Skip to content

Tasks API

The Tasks API works with individual tasks: your personal task overview, reading and updating a task, changing its status (including completion with actual hours), comments, and deletion.

Tasks are created inside a project through POST /api/v1/projects/:id/tasks, not through this API. Project-level scheduling operations (dates, estimates, per-day allocations, and assignees with conflict checks) also live on the Projects API.

Authentication: every endpoint requires an API key. See API Keys & Authentication.

Requests run in the organisation selected for your API key or MCP connection. Another membership, including an owner role or a different primary organisation, does not change that scope. Task changes record the connected user as the author; supplying an actor ID does not change that identity.

Personal task reads require current project and task visibility as well as an active organisation membership. Restricted projects contribute no rows or totals. A direct assigned-task read outside your permitted scope returns 404; an organisation-wide task:view denial returns 403.

Every response uses the standard { "success": true, ... } envelope.

Routine assignment and planning emails are suppressed for draft projects. The task change, audit history and permitted in-app notices still occur. The same behaviour applies through REST and MCP. Explicit messages and approval requests follow their own notification settings. See Messages and Notifications.

Read the connected user’s saved task priorities across permitted projects. This read does not change records or generate a Today summary. It requires active organisation membership, task:view, and access to each project’s tasks.

The only query parameter is optional asOf, a real calendar date in YYYY-MM-DD form. Omit it for today in the organisation timezone. Unknown fields, alternate user or organisation IDs, and invalid dates return 400. The date compares current records, rather than reconstructing a historical snapshot.

GET /api/v1/tasks/my/priorities?asOf=2026-10-12
Authorization: Bearer <your-api-key>

The response includes:

  • source, an opaque revision reference for this dated review;
  • asOf, timezone, observedAt and permitted projectIds;
  • counts: total, shown, review, waiting, pastFinish and undated;
  • rows, up to ten tasks with identity, project, saved status and priority, planned dates, estimated hours, direct dependency counts and waitingReasons;
  • ordering, meaning and short_summary, which explain the review’s limits.

Rows in group: "review" have no recorded waiting condition. Rows in group: "waiting" have a draft, paused or closed project, future planned start, or open or unknown direct dependency. Each group sorts by saved priority, then planned finish. Capacity and other blockers are not assessed. Counts cover the full permitted task set. Missing effort is null; zero remains zero.

Completed/cancelled tasks and deleted/archived projects are excluded. More than 200 candidate projects or 2,000 permitted active tasks returns 400; no partial total is returned. Permission changes apply on every read.

MCP provides the same read through get_my_task_priorities and through call_public_api with method: "GET", path: "/tasks/my/priorities" and the optional date in query. Client-scoped sessions must use the project-specific get_project_task_queue tool. See MCP tools.

Use assignedToIds on task creation, PATCH /api/v1/tasks/:taskId, or PATCH /api/v1/projects/:id/tasks/:taskId/assignee to replace the complete set of assignees. Supply up to 50 user UUIDs. Duplicate IDs are removed, preserving their first occurrence. An empty array unassigns everyone. Do not combine this field with assignedToId; doing so returns 400. The legacy scalar still replaces the assignment with one person, and null unassigns.

{ "assignedToIds": ["<first-user-uuid>", "<second-user-uuid>"] }

The returned task includes assignedToIds, with assignedToId identifying its first person for older clients. Project details also include an assignees list. All assignees must be active members of the credential’s organisation and eligible for that project. Assignment requires task:assign or the project owner/admin override; ordinary task edits retain their existing requirements.

There is one task ID with shared title, description, status, progress, dates and discussion. Each person’s schedule row carries that same taskId; use it when updating the task. Do not use the schedule row’s own id as a task ID. estimatedHours applies to every assignee, so four hours for two people reserves eight person-hours. Each schedule entry identifies the person whose capacity it uses. Removing an assignee removes their allocation; an unscheduled task has no allocations. Auto schedules respect all assignees’ availability, and manual allocations validate each person’s leave and working pattern. Actual time is recorded individually and is never copied to all assignees.

The named MCP tools create_task and update_task accept the same field. create_task also supports unscheduled tasks within a client-scoped connection; omit plannedStartDate and dependsOn. Updates and scheduled creation require an unscoped user-generated connection. call_public_api provides the same operations for unscoped connections and requires confirm: true for writes. See MCP task tools.

Use assignments on POST /api/v1/projects/:id/tasks to create one task with one entry per person needed. Supply assignedToId for a known person, roleId for an unfilled reservation, or both to fill that role at creation. Each entry requires at least one valid UUID. The maximum is 50 entries; a person cannot appear twice. Repeated roles are allowed.

{
"name": "Campaign concepts",
"estimatedHours": 4,
"assignments": [
{ "roleId": "<designer-role-uuid>", "assignedToId": "<person-uuid>" },
{ "roleId": "<writer-role-uuid>", "assignedToId": null }
]
}

This plans eight hours on one task. Filling the second role keeps eight hours. Legacy roleIds, assignedToIds and assignedToId remain supported, but cannot be combined with assignments. Conflicting formats return 400 before creation. The following legacy example reserves unfilled roles.

{
"name": "Campaign delivery",
"estimatedHours": 4,
"assignedToIds": [
"<producer-user-uuid>"
],
"roleIds": [
"<designer-role-uuid>",
"<designer-role-uuid>",
"<writer-role-uuid>"
]
}

This plans 16 hours: four hours for each named person or unfilled place. Filling a reserved place keeps that total; do not add a second place for the person filling it. The task retains one status, schedule and discussion.

OperationMethod and path
Available role IDs and namesGET /api/v1/projects/:id/task-role-options
Read places and revisionGET /api/v1/projects/:id/tasks/:taskId/role-assignments
Replace the complete role listPUT /api/v1/projects/:id/tasks/:taskId/role-assignments
Read unfilled demandGET /api/v1/projects/role-demand?projectId=<uuid>

Read the role list before writing it. The response contains roleAssignments, revision, assignedToIds, availableRoles and canAssign. The revision covers both roles and people. Each public place has id, roleId, roleName and nullable assignedToId. It contains no financial rates.

{
"revision": "<revision-from-read>",
"roles": [
{ "id": "<existing-place-uuid>", "roleId": "<role-uuid>", "assignedToId": "<person-uuid>" },
{ "roleId": "<role-uuid>", "assignedToId": null }
]
}

To replace the direct-person assignments in the same write, also send directAssigneeIds. Omit it to preserve the current direct assignments. If a person already directly assigned is chosen for a role, they move into that role and count once. Send an empty list to clear direct assignments. Role changes still require the complete roles list and its current revision.

Omit id for a new place. Retain it when staffing or reopening an existing place. Omit a place from the array to remove it. A person can occupy one place per task; the combined maximum is 50 named people and unfilled places. Invalid IDs, inactive or ineligible people, duplicate people and submitted price fields return 400. Stale revisions return 409 with no partial write.

Assignment authority or the project owner/admin override is required. Scheduled staffing changes also require schedule management authority. A person whose working pattern, leave or closures cannot accommodate the saved hours is refused with 409. Other-task overlaps return 409 with code: ROLE_SCHEDULE_CONFLICT and conflicts. After review, resubmit with allowScheduleConflicts: true to accept overlaps. This cannot override unavailable working hours.

Filling a place transfers demand to the person and retains the saved role rate. Removing a person reopens their role. A one-for-one person handover transfers the role. Estimates, details, dates and status remain shared on the central task. Unfilled demand rows identify the task, project, place, role and segment hours; unscheduled rows have null segment times and hours plus estimatedHours. Completed/cancelled tasks and closed projects are excluded.

Financial readers can use GET /api/v1/projects/:id/task-costs; its plannedSnapshots map includes each place once at its saved rate. A missing required FX rate leaves planned cost unknown. Ordinary role reads do not grant financial access.

get_task_roles and set_task_roles provide named MCP access. The latter requires confirm: true; call_public_api covers all these operations. Role operations stay bound to the credential’s organisation. The named role tools require an unscoped user-generated credential; restricted job/client/tool sessions cannot use their API bridge.

Task endpoints return a task with usage metadata:

{
"id": "4be2d871-...",
"name": "Draft homepage copy",
"description": "First pass for internal review.",
"status": "in_progress",
"priority": "high",
"projectId": "1f0e9a52-...",
"projectName": "Winter Launch",
"budgetLineId": null,
"clientName": "Northwind",
"estimatedHours": 6,
"actualHours": 5.5,
"trackedHours": 4.25,
"progress": 60,
"plannedStartDate": "2026-07-13T00:00:00.000Z",
"plannedEndDate": "2026-07-14T00:00:00.000Z",
"actualStartDate": "2026-07-13T01:12:44.000Z",
"actualEndDate": null,
"completionNotes": null,
"commentCount": 3,
"tags": ["copy", "homepage"],
"metadata": {},
"dueCategory": "today",
"dueInDays": 1,
"createdAt": "2026-07-10T00:05:31.000Z",
"updatedAt": "2026-07-13T02:41:12.000Z"
}
  • budgetLineId is the saved budget line UUID, or null when unmapped. It is included in task detail, personal task lists and project task readbacks. Unrelated task updates preserve it. Use the Finance mapping endpoints to set or clear it; the ID does not grant access to budget amounts.
  • status is one of pending, scheduled, in_progress, completed, cancelled.
  • priority is one of low, medium, high, critical.
  • dueCategory is one of overdue, today, upcoming, unscheduled, computed from the planned dates. Completed tasks report upcoming.
  • dueInDays is the number of days until the planned end date (negative when overdue), or null when the task has no planned end date.
  • trackedHours is the total of the task’s time entries. actualHours is the figure recorded when the task was completed.
  • description, clientName, estimatedHours, actualHours, the date fields, completionNotes, and tags can be null or absent.

Get an overview of the tasks assigned to you: a summary of counts and hours, plus the full task list grouped for due-date display. Cancelled tasks and all tasks in draft projects are excluded, including their counts and hours. This covers custom workflow stages in the draft category, such as Planning. Assignment and scheduling alone do not make draft work actionable.

Project activation makes assigned work visible here, including unscheduled backlog tasks. Returning the project to draft hides it again. Authorised task detail and project reads remain available throughout planning. The same behaviour applies through MCP using call_public_api with GET /tasks/my.

Any organisation member can call this. It only ever returns your own tasks.

Example request

Terminal window
curl https://api.runnit.io/api/v1/tasks/my \
-H 'Authorization: Bearer rnk_your_key'

Response

{
"success": true,
"data": {
"summary": {
"total": 12,
"overdue": 1,
"dueToday": 2,
"upcoming": 6,
"completed": 3,
"inProgress": 2,
"scheduledHours": 64.5,
"trackedHours": 38.25
},
"tasks": [ { "id": "4be2d871-...", "name": "Draft homepage copy", "dueCategory": "today" } ]
}
}

tasks contains full task objects as described above, ordered by due date with completed tasks last. The overdue, dueToday, and upcoming counts only include tasks that are not completed.

Errors

  • 400 if no active organisation can be resolved for your account.

Get one of your assigned tasks by ID.

Any organisation member can call this, but it only resolves tasks assigned to you. A task assigned to someone else (or to nobody) returns 404.

Cancelled tasks and tasks in draft projects remain readable here even though GET /tasks/my omits them. Current project and task permissions still apply. The same read is available through MCP with call_public_api and GET /tasks/:taskId.

Path parameters

NameTypeRequiredDescription
taskIdUUIDYesTask ID. Must be assigned to you.

Example request

Terminal window
curl https://api.runnit.io/api/v1/tasks/<task-id> \
-H 'Authorization: Bearer rnk_your_key'

Response

{ "success": true, "task": { "id": "4be2d871-...", "name": "Draft homepage copy", "status": "in_progress" } }

Errors

  • 404 if the task does not exist, is deleted, is in another organisation, or is not assigned to you.

Update a task’s fields. Send only the fields you want to change. Project owners and project admins have a local override. Organisation capabilities apply on every accessible project, even when the caller is not listed on its team.

Path parameters

NameTypeRequiredDescription
taskIdUUIDYesTask ID.

Request body (all optional)

NameTypeRequiredDescription
namestringNoNew name, 1 to 255 Unicode characters after trimming surrounding spaces.
descriptionstringNoTask description.
prioritystringNolow, medium, high, or critical.
progressintegerNo0 to 100.
estimatedHoursnumberNo0 to 1000. On a dated task with a day-by-day breakdown, keeps the planned window and rescales the daily hours when the new total fits it; otherwise rebuilds from the start. On an undated task, saves the estimate without creating dates.
plannedStartDateISO 8601 dateNoPlanned start. Rebuilds the task schedule and recalculates planned end.
dependsOnUUID[]NoReplace the task’s finish-to-start dependency list (max 25 task ids from the same project; cycles rejected). Requires task-wide update and schedule-management access. The response includes a cascade summary when downstream tasks were rescheduled.
plannedEndDateISO 8601 dateNoCalculated output. A value supplied with start or estimate is ignored for backwards compatibility. Sending only this field returns 400.
tagsarray of stringsNoReplaces the full tag list.
assignedToIdstring or nullNoNew assignee’s user ID. Null unassigns the task. The user must be an active organisation member. On a client project they must be on the client staffing list or the explicit project team.

A start update creates or rebuilds the same working-day schedule used by the project dates endpoint, and moves a pending backlog task to scheduled. An estimate-only update on a dated task follows the same manual-aware rule as the project estimate endpoint: a manual day-by-day plan keeps its window and rescales when the new total fits, and rebuilds from the start when it does not. It never invents a start date for backlog work. Changing the assignee also updates the owner on any existing schedule segments.

General fields require task-wide update access, assigned-task access for the current assignee, or a project override. Assignment requires task:assign. Schedule fields and dependencies require both task:update:any and schedule:manage. A project’s target date is not a write boundary: segments after its organisation calendar day are marked overdue but remain editable. Finishing on the target day is on time; days overdue count working days after it.

Example request

Terminal window
curl -X PATCH https://api.runnit.io/api/v1/tasks/<task-id> \
-H 'Authorization: Bearer rnk_your_key' \
-H 'Content-Type: application/json' \
-d '{ "priority": "critical", "progress": 75 }'

Response

{ "success": true, "task": { "id": "4be2d871-...", "priority": "critical", "progress": 75 } }

Errors

  • 400 if a field fails validation (empty or overlong name, progress outside 0 to 100, estimated hours outside 0 to 1000, invalid priority or date), if the new assignee is not an active organisation member, or if the new assignee is neither on the client staffing list nor the explicit project team, or if plannedEndDate is sent without a start or estimate.
  • 404 if the task does not exist, is deleted, or is in another organisation.
  • 403 when the caller lacks the capability required for the fields being changed.

Change a task’s status and optional progress together. Completing a task can also record the actual hours spent and a completion note.

The task’s assignee or project owner can call this. Users with organisation-wide task update access can also update the task. Assignment changes still use the Projects API.

Path parameters

NameTypeRequiredDescription
taskIdUUIDYesTask ID.

Request body

NameTypeRequiredDescription
statusstringYesOne of pending, scheduled, in_progress, completed, cancelled.
progressintegerNoWhole percentage from 0 to 100.
actualHoursnumberNo0 to 1000. Recorded with completion.
completionNotesstringNoUp to 2000 characters.

Completing a task sets its progress to 100 and records the work in your portfolio history. If you supply actualHours with completion, Runnit also records and submits only that completion time entry. Automatic approval updates budget usage immediately. Required approval and applicable organisation policy stages leave the entry submitted for review.

Completion hours are task effort, including totals above 24 hours up to the 1000-hour limit. A new entry posts on the saved completion date in the organisation timezone. Retrying an editable entry preserves its posting date. Use dated time entries for a daily breakdown; do not log the same hours twice. If recording is refused after the task completes, the result contains timeEntry.outcome: "blocked", reason and code. Read the receipt before reporting that hours were recorded.

Submission uses the same time permissions as the timesheet: one of time:log, time:approve or time:manage_locked, plus time:approve when acting for another person. A submission refusal preserves the recorded draft and returns timeEntry.submissionBlocked: true, status, reason and code. A successful receipt includes timeEntry.status (submitted or approved). Check this receipt even when the task update succeeded. Other draft entries are not submitted. Already submitted, approved or invoiced completion hours require the normal timesheet correction workflow. Zero hours creates no entry.

The endpoint applies these work-state rules:

  • Progress from 1 to 99 changes pending or scheduled work to in_progress.
  • Progress at 100 changes the status to completed.
  • completed always stores progress at 100.
  • pending and scheduled store progress at 0 when progress is omitted or 0.
  • cancelled preserves the stored progress.
  • Reopening completed work as in_progress defaults to 95 when progress is omitted.

Example request

Terminal window
curl -X PATCH https://api.runnit.io/api/v1/tasks/<task-id>/status \
-H 'Authorization: Bearer rnk_your_key' \
-H 'Content-Type: application/json' \
-d '{
"status": "completed",
"progress": 100,
"actualHours": 5.5,
"completionNotes": "Copy approved by the internal review."
}'

Response

{ "success": true, "task": { "id": "4be2d871-...", "status": "completed", "progress": 100, "actualHours": 5.5 } }

Errors

  • 400 if status is missing or invalid, progress is not a whole number from 0 to 100, actualHours is out of range, or completionNotes exceeds 2000 characters.
  • 404 if the task does not exist, is deleted, or is in another organisation.
  • 403 if you are not the task’s assignee or project owner and do not have organisation-wide task update access.

For a count without loading the discussion, use tasks[].commentCount in project details. It includes all non-deleted comments and replies, including those beyond the first page. The same response includes unreadCommentCount for the caller. These reads do not mark comments as read.

List a task’s comments, including who wrote each one. This is the same discussion opened from the project table’s Comments column and task details. Comments are the messages in the task’s chat thread, so entries created by replying or mentioning someone in the app appear here too. A comment may include a replyToId referencing the comment it replies to.

Any organisation member can call this for tasks in their organisation.

Path parameters

NameTypeRequiredDescription
taskIdUUIDYesTask ID.

Example request

Terminal window
curl https://api.runnit.io/api/v1/tasks/<task-id>/comments \
-H 'Authorization: Bearer rnk_your_key'

Response

{
"success": true,
"comments": [
{
"id": "b7e13f90-...",
"taskId": "4be2d871-...",
"userId": "d3a6f0c1-...",
"commentText": "First draft is up for review.",
"metadata": {},
"createdAt": "2026-07-13T02:41:12.000Z",
"updatedAt": "2026-07-13T02:41:12.000Z",
"user": { "id": "d3a6f0c1-...", "name": "Alex Chen", "email": "alex@example.com" }
}
]
}

metadata and the user’s avatarUrl can be absent. userId and user are null for system-generated entries. replyToId is present on replies. Up to 500 comments are returned.

Errors

  • 404 if the task does not exist, is deleted, or is in another organisation.

Add a comment to a task. The comment posts into the task’s chat thread: the task’s assignee, the project owner, and other thread participants are notified in the app and can reply there.

Requires task-comment access for tasks in your organisation.

Path parameters

NameTypeRequiredDescription
taskIdUUIDYesTask ID.

Request body

NameTypeRequiredDescription
commentTextstringYesComment body. Must not be empty.
replyToIdUUIDNoID of an existing comment on the same task to reply to.
mentionsarrayNoStructured mentions, e.g. [{ "targetType": "user", "targetId": "<user-id>" }]. Mentioned users must be active organisation members; they are notified directly.
metadataobjectNoFree-form metadata stored with the comment.

Example request

Terminal window
curl -X POST https://api.runnit.io/api/v1/tasks/<task-id>/comments \
-H 'Authorization: Bearer rnk_your_key' \
-H 'Content-Type: application/json' \
-d '{ "commentText": "First draft is up for review." }'

Response

Returns 201 with the task’s full comment list, including the new comment, in the same shape as the list endpoint above.

Errors

  • 400 if commentText is missing or empty, or no active organisation can be resolved for your account.
  • 404 if the task does not exist, is deleted, or is in another organisation.

Delete a task. Runnit also removes the task’s schedule entries, including schedule entries for subtasks deleted with the parent. The task no longer appears in task, dashboard, schedule, or capacity results.

The task’s assignee or the project owner can call this.

Path parameters

NameTypeRequiredDescription
taskIdUUIDYesTask ID.

Example request

Terminal window
curl -X DELETE https://api.runnit.io/api/v1/tasks/<task-id> \
-H 'Authorization: Bearer rnk_your_key'

Response

{ "success": true, "message": "Task deleted successfully" }

Errors

  • 404 if the task does not exist, is already deleted, or is in another organisation.
  • 403 if you are neither the task’s assignee nor the project owner (“Only the task assignee or project owner can delete tasks”).

A typical task lifecycle, end to end. Replace the placeholders with real IDs.

  1. Create the task in its project (tasks always belong to a project):
Terminal window
curl -X POST https://api.runnit.io/api/v1/projects/<project-id>/tasks \
-H 'Authorization: Bearer rnk_your_key' \
-H 'Content-Type: application/json' \
-d '{ "name": "Draft homepage copy", "priority": "high", "estimatedHours": 6 }'
  1. Assign it (use the assignee options endpoint to find valid assignees first):
Terminal window
curl -X PATCH https://api.runnit.io/api/v1/projects/<project-id>/tasks/<task-id>/assignee \
-H 'Authorization: Bearer rnk_your_key' \
-H 'Content-Type: application/json' \
-d '{ "assignedToId": "<user-uuid>" }'
  1. Move its dates when the plan changes (this rebuilds the working-day schedule):
Terminal window
curl -X PATCH https://api.runnit.io/api/v1/projects/<project-id>/tasks/<task-id>/dates \
-H 'Authorization: Bearer rnk_your_key' \
-H 'Content-Type: application/json' \
-d '{ "plannedStartDate": "2026-07-20" }'
  1. Mark it complete with actual hours (as the assignee):
Terminal window
curl -X PATCH https://api.runnit.io/api/v1/tasks/<task-id>/status \
-H 'Authorization: Bearer rnk_your_key' \
-H 'Content-Type: application/json' \
-d '{ "status": "completed", "actualHours": 5.5 }'
  1. Comment on the outcome:
Terminal window
curl -X POST https://api.runnit.io/api/v1/tasks/<task-id>/comments \
-H 'Authorization: Bearer rnk_your_key' \
-H 'Content-Type: application/json' \
-d '{ "commentText": "Done. Final copy is in the shared collection." }'

Create and schedule tasks through the Projects API, or read team schedules through the Scheduling API.

Role reservations and unfilled demand follow your current project-view and client staffing access. A project filter cannot widen it. Organisation owners and admins retain visibility across their organisation; other people retain access through eligible clients or their active project membership. A refused request changes no roles or bookings. Conflicts from projects you cannot see show the date and reason without their task name or link.