Tasks API
Tasks and entries: the queue, workflow actions, refile and archive
GET /orgs/{org}/entries/{ref}
Any entry (a heading or an inline task).
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
ref required | path | string | The entry's short ID or UUID. |
Responses
200- OK. EntryView
application/json
GET /orgs/{org}/tasks
Tasks you can read that match, ranked (§7.10) unless the query sorts.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
q | query | string | A query (§9.1). |
match | query | string | Org match syntax (+work-someday/TODO). |
status | query | string | A queue status: ready, blocked, claimed, review, … |
owner | query | string | An owner handle, me or none. |
limit | query | integer (int32) | Page size. |
cursor | query | string | Cursor. |
tz | query | string | The viewer's IANA zone for floating times and relative dates (default: the account's). |
Responses
200- OK. Paged_TaskView
application/json 422- Invalid. ProblemBody
application/json
POST /orgs/{org}/tasks
Creates a task: on the named page (and heading, or date tree), else in the owner's inbox, else yours (§7.3).
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
Request body
application/json, TaskInput.
| Field | Type | Description |
|---|---|---|
body | string | null | Body (Markdown). |
created | string (date-time) | null | The original creation time (created::). |
deadline | string | null | deadline:: |
depends | string[] | depends:: short IDs. |
effort | string | null | Effort (30m, 1:30). |
external_id | string | null | external_id::, unique per source. |
keyword | string | null | The TODO keyword (default: the first of the page's first sequence; "" for none). |
owner | string | null | owner:: handle. |
priority | string | null | Priority letter. |
properties | map of string | Other properties. |
scheduled | string | null | scheduled:: (a timestamp, date or RFC 3339 instant). |
source | string | null | Import provenance (source::), for upserts. |
tags | string[] | Tags. |
target | null | TargetInput | |
title required | string | Title. |
Responses
201- Created. TaskView
application/json 404- Not found. ProblemBody
application/json
GET /orgs/{org}/tasks/{ref}
A task.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
ref required | path | string | The task's short ID or UUID. |
Responses
200- OK. TaskView
application/json 404- Not found. ProblemBody
application/json
PATCH /orgs/{org}/tasks/{ref}
Edits a task's fields. Contract fields are locked while a live claim holds them (409 contract_locked).
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
ref required | path | string | The task's short ID or UUID. |
If-Match | header | string | null | The task's containing page's strong ETag. If supplied, it must match the current revision; a mismatch returns 409 revision_conflict. |
Request body
application/json, PatchTask.
| Field | Type | Description |
|---|---|---|
acceptance | string | null | acceptance:: |
base_revision | integer (int64) | null | The revision the edit was based on. |
body | string | null | Body. |
deadline | string | null | deadline:: |
depends | string[] | null | depends:: short IDs. |
effort | string | null | Effort (30m; "" clears). |
owner | string | null | owner:: |
priority | string | null | Priority letter. |
properties | map of string | null | Other properties (null removes). |
scheduled | string | null | scheduled:: |
tags | string[] | null | Tags. |
title | string | null | Title. |
Responses
200- OK. TaskView
application/json 409- Conflict. ProblemBody
application/json
POST /orgs/{org}/tasks/{ref}/actions/{action}
Runs a workflow action (§7.5–§7.8): the text, task_coord and events commit together.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
ref required | path | string | The task. |
action required | path | string | claim, renew, release, submit, approve, reject, cancel, reopen, complete, set_state, clock_in, clock_out or note. |
If-Match | header | string | null | The task's containing page's strong ETag. If supplied, it must match the current revision independently of base_revision; a mismatch returns 409 revision_conflict. |
Request body
application/json, ActionBody.
| Field | Type | Description |
|---|---|---|
base_revision | integer (int64) | null | The page revision the action was based on. |
claim_id | string (uuid) | null | The claim (claims are idempotent per claim_id; one is minted if absent). |
completion_source | CompletionSource | Completion attribution (complete, or set_state to done); defaults to performed. |
evidence | string | null | Evidence (submit, approve, reject). |
keyword | string | null | The keyword (set_state). |
lease_minutes | integer (int32) | null | Lease length (1–240 minutes). |
note | string | null | A note (release, complete, set_state, note), or the reason (cancel, reopen). |
override_claim | boolean | A human overriding someone else's claim. |
reason | string | null | The reason (cancel, reopen). |
Responses
200- OK. ActionResponse
application/json 409- Conflict. ProblemBody
application/json
POST /orgs/{org}/tasks/{ref}/archive
Archives a task (§7.12): to the page's archive: target (created on demand) with the archive_* metadata, else archived:: true in place.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
ref required | path | string | The task's short ID or UUID. |
Responses
200- OK. TaskView
application/json
GET /orgs/{org}/tasks/{ref}/context
The context packet (§15.4): the task, its ancestors, linked pages, backlinks, decisions, attachments and secret names.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
ref required | path | string | The task's short ID or UUID. |
detail | query | Detail | summary (default) or full. |
Responses
200- OK. ContextPacket
application/json
POST /orgs/{org}/tasks/{ref}/refile
Moves a task's subtree (children, id::s and logbook included) under a heading or to the end of a page, atomically across both pages.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
ref required | path | string | The task's short ID or UUID. |
Request body
application/json, RefileBody.
| Field | Type | Description |
|---|---|---|
base_revision | integer (int64) | null | The revision of the task's page the move was based on. |
heading | string | null | A heading on it (default: the end of the page). |
page required | string | The target page (short ID, id or title). |
Responses
200- OK. TaskView
application/json
POST /orgs/{org}/tasks:batch
Creates or upserts up to 500 tasks in one transaction (§23.2).
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
Request body
application/json, BatchBody.
| Field | Type | Description |
|---|---|---|
dry_run | boolean | Report what would happen, writing nothing. |
import_id | string (uuid) | null | Record the items in this import (so it can be undone as a unit). |
items required | TaskInput[] | The tasks. Items with source and external_id upsert. |
source | string | null | The default source for items. |
Responses
200- OK. BatchResult
application/json