API Documentation

Returns all boards in the workspace.

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Engineering Sprint",
    "description": "Backend team tasks",
    "createdAt": "2026-01-15T10:30:00Z",
    "isPrivate": false
  }
]

Returns a single board with its statuses, members, labels, and custom fields.

Creates a new board. Requires Owner or Admin role.

curl -X POST https://app.artala.app/api/boards \
  -H "Authorization: Bearer tb_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q3 Roadmap",
    "description": "Product roadmap for Q3 2026",
    "isPrivate": false,
    "sprintsEnabled": true
  }'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Q3 Roadmap",
  "description": "Product roadmap for Q3 2026",
  "createdAt": "2026-05-28T14:22:00Z",
  "isPrivate": false
}

Updates a board's name, description, or privacy. Requires Owner or Admin role.

Archives a board. Requires Owner or Admin role.

Returns a single task with all its details.

Creates a new task on a board.

curl -X POST https://app.artala.app/api/tasks \
  -H "Authorization: Bearer tb_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "boardId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "title": "Implement login flow",
    "description": "OAuth2 + TOTP support",
    "priority": 1,
    "dueDate": "2026-06-15T00:00:00Z",
    "effort": 5,
    "checklistItems": [
      "Design login page",
      "Implement OAuth2",
      "Add TOTP verification"
    ]
  }'

Updates a task's title, description, assignee, priority, dates, or effort.

Changes a task's status (e.g. "To Do" → "In Progress" → "Done").

curl -X PATCH https://app.artala.app/api/tasks/{taskId}/status \
  -H "Authorization: Bearer tb_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "newStatus": "Done" }'

Permanently deletes a task and its checklist items, comments, and time entries.

Moves a task to a different board.

{ "targetBoardId": "guid", "moveToBacklog": false }

Returns all checklist items for a task.

Adds a new checklist item to a task.

{ "title": "Review PR" }

Updates a checklist item's title or completion status.

{ "title": "Review PR", "isComplete": true }

Deletes a checklist item.

Returns all blocking and blocked-by relationships for a task.

Makes {taskId} blocked by {blockingTaskId}. The blocking task must be completed before the blocked task can proceed.

Removes a blocking relationship.

Returns all labels defined in the workspace.

[
  {
    "id": "a1b2c3d4-...",
    "name": "Bug",
    "color": "#f44336",
    "sortOrder": 0
  }
]

Creates a new label, or updates an existing one if id is provided. Requires Owner or Admin role.

Deletes a label. Requires Owner or Admin role. Existing task associations are removed.

Returns labels currently assigned to a task.

Replaces all labels on a task with the provided set. Pass an empty array to clear labels.

curl -X PUT https://app.artala.app/api/labels/task/{taskId} \
  -H "Authorization: Bearer tb_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "labelIds": ["a1b2c3d4-...", "e5f6a7b8-..."] }'

Returns all comments on a task, with replies nested under their parent.

[
  {
    "id": "b2c3d4e5-...",
    "taskId": "a1b2c3d4-...",
    "authorId": "c3d4e5f6-...",
    "authorName": "Sarah Chen",
    "content": "Looks good, merging now.",
    "isEdited": false,
    "createdAt": "2026-05-28T14:30:00Z",
    "replies": []
  }
]

Adds a comment to a task. Include parentCommentId to post a reply. Markdown is supported.

curl -X POST https://app.artala.app/api/comments \
  -H "Authorization: Bearer tb_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "a1b2c3d4-...", "content": "Deployment verified." }'

Edits a comment's content. Members and Commenters can edit their own comments within 24 hours; Admins and Owners can edit any comment.

{ "content": "Updated comment text" }

Deletes a comment and its replies. Members and Commenters can delete their own within 24 hours; Admins and Owners can delete any comment.

Returns all custom field definitions for the workspace. Use the field id when setting values on tasks.

[
  {
    "id": "d4e5f6a7-...",
    "name": "Environment",
    "fieldType": "Choice",
    "choiceOptions": "[\"Staging\",\"Production\",\"Development\"]",
    "isRequired": false,
    "sortOrder": 0
  }
]

Returns custom field values set on a task, including the field definition details.

[
  {
    "fieldId": "d4e5f6a7-...",
    "name": "Environment",
    "fieldType": "Choice",
    "choiceOptions": "[\"Staging\",\"Production\",\"Development\"]",
    "isRequired": false,
    "value": "Production"
  }
]

Sets or updates a single custom field value on a task. Send one request per field.

curl -X POST https://app.artala.app/api/fields/task/{taskId} \
  -H "Authorization: Bearer tb_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "fieldId": "d4e5f6a7-...", "value": "Production" }'

Returns all valid task statuses for the workspace. Use these names when creating or updating tasks. Workspaces can use built-in statuses (To Do, In Progress, Done) or define custom statuses.

[
  {
    "id": "e5f6a7b8-...",
    "name": "To Do",
    "color": "#9E9E9E",
    "isDefault": true,
    "isDone": false,
    "sortOrder": 0
  }
]

Returns all members in the workspace. Use the member id as assigneeId when creating or updating tasks.

[
  {
    "id": "c3d4e5f6-...",
    "fullName": "Sarah Chen",
    "email": "sarah@example.com",
    "role": "Admin",
    "isActive": true
  }
]

Logs time against a task. Owner/Admin keys can log time for any user by specifying targetUserId.

curl -X POST https://app.artala.app/api/timesheets \
  -H "Authorization: Bearer tb_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "taskId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "loggedDate": "2026-05-28",
    "hours": 2.5,
    "note": "Backend implementation"
  }'

Submits a week for review. The week is identified by any date inside it. Owner/Admin keys can submit on behalf of another user with targetUserId. Returns the week with its new status and total hours.

curl -X POST https://app.artala.app/api/timesheets/week/submit \
  -H "Authorization: Bearer tb_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "dateInWeek": "2026-06-15" }'

Returns the status of a single week. Query parameters: dateInWeek (any date in the week; defaults to the current week) and optional targetUserId.

Lists the caller's own week statuses over a range. Optional from and to query parameters (default: the last 8 weeks).

Returns the submitted weeks awaiting the caller's review — weeks routed to them plus, for Owners/Admins, the unrouted pool. Each row includes the owner, week dates, and total hours.

Returns recently approved and rejected weeks the caller can reopen or correct.

Approves a submitted week. The week becomes locked. Fires timesheet.week.approved.

Rejects a submitted week with a note explaining what needs to change. The member can edit and resubmit. Fires timesheet.week.rejected.

curl -X POST https://app.artala.app/api/timesheets/weeks/3fa85f64-5717-4562-b3fc-2c963f66afa6/reject \
  -H "Authorization: Bearer tb_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "note": "Please move the Friday hours to the correct task." }'

Reopens an approved week back to draft (subject to separation-of-duties rules). Fires timesheet.week.reopened.

Retracts a still-pending submitted week back to draft so it can be edited again.

Enables or disables the approval workflow for the workspace (Owner/Admin). Enabling records a grandfather date so earlier weeks aren't pulled in.

Sets the day each approval week begins (Owner/Admin). A change takes effect from a future boundary so existing weeks are not re-sliced.

All active tasks across all boards.

Columns: Id, BoardId, BoardName, Title, Description, Status, Priority, PriorityName, AssigneeId, AssigneeName, DueDate, IsOverdue, IsBacklog, IsArchived, CompletedAt, CreatedAt, UpdatedAt, Effort, ExternalId, ExternalSource, and more.

# High priority overdue tasks
/odata/Tasks?$filter=IsOverdue eq true and Priority eq 3&$orderby=DueDate

# Completed this month
/odata/Tasks?$filter=CompletedAt ge 2026-05-01T00:00:00Z&$orderby=CompletedAt desc

# Tasks with effort estimates
/odata/Tasks?$filter=Effort ne null&$orderby=Effort desc

Tasks from the global backlog (Idea / Planned / Ready).

# Ready for sprint
/odata/BacklogTasks?$filter=Status eq 'Ready'&$orderby=Priority desc,SortOrder

Board list with task and member counts.

Columns: Id, Name, Description, IsPublic, IsBacklogBoard, TaskCount, MemberCount, CreatedAt, UpdatedAt.

Workspace user list with roles.

Columns: Id, FullName, Email, Role, IsActive, TotpEnabled, LastLoginAt, CreatedAt.

# Active members without 2FA
/odata/Members?$filter=IsActive eq true and TotpEnabled eq false&$select=FullName,Email,Role

Sprint list with task counts and effort totals.

Columns: Id, BoardId, BoardName, Name, Goal, StartDate, EndDate, Status, TotalTasks, CompletedTasks, TotalEffort, CompletedEffort, CompletedAt, CreatedAt.

# Velocity by sprint
/odata/Sprints?$filter=Status eq 'Completed'&$select=Name,BoardName,TotalEffort,CompletedEffort&$orderby=StartDate

One row per task-sprint pair. Use for sprint-level reporting and burndown analysis.

# Incomplete tasks in active sprints
/odata/SprintTasks?$filter=SprintStatus eq 'Active' and CompletedAt eq null

Full audit trail of task field changes. Use for cycle time, lead time, and flow analysis.

Columns: Id, TaskId, TaskTitle, BoardId, BoardName, FieldChanged, OldValue, NewValue, ChangedById, ChangedBy, ChangedAt.

# Status changes only
/odata/TaskHistory?$filter=FieldChanged eq 'Status'&$orderby=ChangedAt desc

One row per label per task. Use for grouping and filtering by label.

Columns: TaskId, TaskTitle, BoardId, BoardName, LabelName, Color.

Custom field values — one row per field per task.

Columns: TaskId, TaskTitle, FieldId, FieldName, FieldType, Value.

Blocking relationships between tasks. BlockedTask is waiting on BlockingTask to finish.

# Active blockers
/odata/TaskBlockers?$filter=BlockingTaskIsDone eq false&$orderby=BlockedTaskTitle

Time entries — one row per entry. Available when time tracking is enabled.

Columns: Id, TaskId, TaskTitle, BoardId, BoardName, UserId, UserName, LoggedDate, Hours, Note, WeekStatus, CreatedAt. WeekStatus is the approval status of the entry's timesheet week (Draft, Submitted, Approved, or Rejected) when approvals are enabled, otherwise null — filter on it to report only approved time.

# Total hours per task
/odata/TimeEntries?$apply=groupby((TaskId,TaskTitle),aggregate(Hours with sum as TotalHours))

# Approved hours only (for payroll)
/odata/TimeEntries?$filter=WeekStatus eq 'Approved'

Timesheet approval weeks — one row per submitted, approved, or rejected week. Available when timesheets are enabled; Owners/Admins see all weeks, other users see only their own.

Columns: Id, UserId, UserName, WeekStartDate, WeekEndDate, WeekStartDay, Status, TotalHours, SubmittedAt, ApproverId, ApproverName, ActionedByUserId, ActionedByName, ActionedAt, RejectNote, CreatedAt.

# Weeks awaiting approval
/odata/TimesheetWeeks?$filter=Status eq 'Submitted'

# Approved hours per person this quarter
/odata/TimesheetWeeks?$apply=filter(Status eq 'Approved')/groupby((UserName),aggregate(TotalHours with sum as Hours))

Returns all webhooks configured in the workspace.

Creates a new webhook, or updates an existing one if id is provided. Requires Owner or Admin role.

curl -X POST https://app.artala.app/api/webhooks \
  -H "Authorization: Bearer tb_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slack notifications",
    "url": "https://hooks.example.com/artala",
    "secret": "my-signing-secret",
    "events": "task.created,task.completed"
  }'

Deletes a webhook. Requires Owner or Admin role.