Agents

REST API

Same base, same auth, for anything that is not an MCP client.

BASE=https://usecotask.com/api/agent
AUTH="Authorization: Bearer pl_your_key"

Method and path	Does
`GET /`	Service info: the MCP URL, the REST base, how to authorize
`GET /tasks`	List tasks — `?status=&project=&priority=&reminder=&query=&limit=`
`POST /tasks`	Create a task (a draft unless you pass `status`)
`GET /tasks/:id`	One task with its attachments
`PATCH /tasks/:id`	Update the fields you pass (`PUT` behaves the same)
`DELETE /tasks/:id`	Delete — drafts only, for agents
`GET /tasks/:id/attachments`	The task's links and files
`POST /tasks/:id/attachments`	Attach a link: `{url, title?}`
`DELETE /tasks/:id/attachments/:attachmentId`	Remove an attachment
`POST /tasks/:id/files`	Attach a file: `{data}` base64 or `{source_url}`
`GET /projects` · `POST /projects`	List · create projects
`GET /preview?url=…`	Resolve a page's title and favicon without attaching it
`POST /uploads`	A signed upload URL for one object — the apps' three-step upload
`PUT /tasks/:id/reminder` · `DELETE /tasks/:id/reminder`	Set when a task rings and how loudly · take the reminder off
`POST /delegate`	Send a task to one of your routes — app session only. See Delegate through the API
`GET /delegations` · `DELETE /delegations/:id`	Scheduled sends (`?status=` — waiting by default, or `all`) · call one off while it waits
`GET /webhooks` · `POST /webhooks`	List · create routes: `{name, url, params?}` for a webhook, `{name, kind: "mac", runner, model?, effort?, params?}` for a Mac route (app session only)
`PATCH /webhooks/:id` · `DELETE /webhooks/:id`	Change · remove a route. `params` replaces the whole set
`POST /webhooks/:id/token` · `PUT /webhooks/:id/secret` · `DELETE /webhooks/:id/token`	A Mac route's inbound token (new or rotated) · a webhook's signing secret · revoke either — app session only, shown once
`POST /inbound/:id` · `GET /inbound/:id/:dispatch`	Queue work for a Mac route · how it went — authorized by the route's `prt_` token, not your key
`POST /storage/gc`	Sweep files no attachment points at — app session only
`DELETE /account`	Delete the account and everything in it — app session only

curl "$BASE/tasks?status=todo" -H "$AUTH"

curl -X POST "$BASE/tasks" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"title":"Review the Q3 plan","project":"Work","due_date":"2026-09-01","priority":"high"}'

curl -X PUT "$BASE/tasks/<id>/reminder" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"remind_at":"2026-09-01T09:00","urgent":true}'   # 9am your time, as an alarm

curl -X PUT "$BASE/tasks/<id>/reminder" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"remind_in":"45m"}'                              # in three quarters of an hour

curl -X PATCH "$BASE/tasks/<id>" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"status":"doing"}'

curl -X POST "$BASE/tasks/<id>/attachments" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"url":"https://www.notion.so/Meeting-notes-…"}'

curl -X POST "$BASE/tasks/<id>/files" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"source_url":"https://example.com/q3.pdf"}'

Responses are JSON: {"task": …}, {"tasks": […]}, {"attachment": …}. Errors are {"error": "…"} with a real status code — 400 bad input, 401 missing or expired credentials (with a WWW-Authenticate header pointing an MCP client at the OAuth flow), 402 a Pro feature, or storage full, on a Free account, 403 something only you may do, 404 not found, 409 a Mac route with nothing to run, 413 a file or a body over the limit, 429 too many requests, 502 a webhook that could not be reached or did not answer 2xx.

Every task comes back with its attachments: id, title, url, kind (link or file), created_by, plus content_type and byte_size on files. url is always fetchable with no credentials.

OAuth endpoints#

Implemented for MCP clients that discover them automatically. You never call these by hand.

Endpoint	Purpose
`GET /.well-known/oauth-protected-resource`	RFC 9728 — points at the authorization server
`GET /.well-known/oauth-authorization-server`	RFC 8414 — endpoints and `S256` PKCE
`POST /register`	RFC 7591 dynamic client registration
`GET /authorize`	Redirects to Cotask's hosted consent screen
`POST /authorize`	Verifies your credentials and mints a single-use code
`POST /token`	`authorization_code` (PKCE-verified) and rotating `refresh_token`

Only SHA-256 hashes of codes and tokens are stored.