Tasks API

The Tasks API is available under /apis/v1/tasks and requires a Ration bearer token. Tasks are tenant-scoped and can be visible through ownership, assignment, delegation, or sharing.

Authorization: Bearer <ration_access_token>
Content-Type: application/json

Task model

Task responses are wrapped as { "task": { ... } }. Core fields include:

Field	Type	Description
id, title, description	String	Task identity and content. title is required on create.
completed, completed_at	Boolean, date-time	Completion state and time.
date, start_date, reminder_at, reminder_tz	String	Due, start, and reminder scheduling.
priority, complexity, sensitivity, blocked	String/Boolean	Planning and access state.
labels, references, attachments	Array	Categorization, source links, and attached files.
assignees, delegates, followers	Array	Collaboration members.
subtasks, comments, activity	Array	Work breakdown, discussion, and audit activity.
dependencies	String array	Tasks that must complete before this task can be completed.
recurrence	Object or null	Recurrence definition. Completing a recurring task creates the next instance.
space_slug, group	String	Workspace and grouping context.
role	String	Caller’s access role when returned.

Task CRUD

List tasks

GET /apis/v1/tasks

Response: { "tasks": [Task] }.

Use assigned=me to limit the result to work assigned to the authenticated user. Other supported list options are passed to Ration’s task query for filtering and ordering.

Create a task

POST /apis/v1/tasks

{
  "title": "Prepare launch brief",
  "description": "Include the final rollout checklist.",
  "date": "2026-08-14",
  "priority": "high",
  "assignees": [{ "id": "user-id", "email": "sam@example.com" }],
  "labels": ["launch"],
  "dependencies": ["blocking-task-id"]
}

Useful create fields include group, space_slug, start_date, completed, sensitivity, complexity, my_day, labels, assignees, delegates, followers, subtasks, references, attachments, recurrence, blocked, dependencies, reminder_at, and reminder_tz.

Response: 201 { "task": Task }. A forbidden workspace returns 403 { "error": "workspace_forbidden" }.

Read, update, or delete

Method	Path	Response
GET	/apis/v1/tasks/:id	{ "task": Task, "role": "…" }; shared tasks also include shared: true.
PATCH or PUT	/apis/v1/tasks/:id	Updated { "task": Task }.
DELETE	/apis/v1/tasks/:id	Deleted { "task": Task }.

Set { "completed": true } to complete a task. Ration returns 409 { "error": "blocked_by_dependency" } if incomplete dependencies prevent completion. A successful completion may create the next recurring instance automatically.

Subtasks and progress

Method	Path	Request	Response
POST	/:task_id/subtasks	Required title; optional completed.	201 { "task": Task }
PUT	/:task_id/subtasks/:id	title and/or completed.	{ "task": Task }
DELETE	/:task_id/subtasks/:id	—	{ "task": Task }

Paths in this table are relative to /apis/v1/tasks.

Use the returned task.subtasks array to render progress: completed subtasks divided by total subtasks. Updating a subtask’s completion returns the parent task immediately, so no additional read is required to refresh the tracker.

Comments and attachments

Add a comment

POST /apis/v1/tasks/:task_id/comments

{ "body": "The legal review is complete." }

body is required. Ration sets author_id and author_name from the authenticated user and returns { "task": Task }.

Attach a file

POST /apis/v1/tasks/:task_id/attachments

Send multipart/form-data with one required file part and Accept: application/json. The effective upload limit is 20 MB.

Response: 201 { "task": Task }; the task attachment includes secure_id, url, filename, content_type, and size.

DELETE /apis/v1/tasks/:task_id/attachments/:id removes the attachment and returns the updated task.

Panels, folders, and search

Task action panel

GET /apis/v1/tasks/:id/panel

Returns { "panel": { ... } } with compact task data and permissions for a task action panel: title, description, status, priority, dates, recurrence, assignee summary, and can_edit, can_undo, and can_open flags.

Task folders

Task folders use /apis/v1/task_folders:

Method	Path	Operation
GET, POST	/task_folders	List or create folders.
PATCH, PUT, DELETE	/task_folders/:id	Update or delete a folder.

Search tasks

GET /apis/v1/search/tasks

Search is bearer-authenticated and applies the same tenant and shared-task visibility rules as task listing. Supply the query and supported search filters as query parameters. The response is the task search result from Ration’s search index.

Permissions and errors

Status	Error / meaning
401	Missing or invalid bearer authentication.
403	forbidden or workspace_forbidden; caller lacks the required task capability.
404	Task not found or not visible to the caller.
409	blocked_by_dependency or another conflict.
422	Invalid ID, missing required fields such as title/body, no changes, file too large, or invalid task state.

Owners and delegates can edit task structure. Assignees may update progress and comment where permitted; view-only collaborators cannot mutate the task.