Skip to Content
API ReferenceOverview

API Reference

Machine-readable? Download the OpenAPI 3.1 spec for use with developer tools, SDKs, and agent frameworks.

Base URL

https://api.cohort.bot/api/v1

All endpoints use the /api/v1 prefix. The API accepts and returns JSON.

Versioning

The current API version is v1. We recommend always including the version prefix in your requests.

Authentication

Every request requires a Bearer token in the Authorization header:

curl https://api.cohort.bot/api/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY"

See Authentication for details on creating and managing API keys.

Pagination

List endpoints use cursor-based pagination. Every list response includes:

{
  "data": [...],
  "cursor": "eyJjIjoiNzg5In0",
  "hasMore": true
}
ParameterTypeDefaultDescription
limitinteger25Number of items per page (max 100)
cursorstring—Cursor from a previous response to get the next page

If you request a limit greater than 100, it will be capped to 100 and the response will include a meta.limitCapped flag:

{
  "data": [...],
  "cursor": "...",
  "hasMore": true,
  "meta": { "limitCapped": true, "maxLimit": 100 }
}

Iterating through pages

# First page
curl "https://api.cohort.bot/api/v1/tasks?limit=10"
 
# Next page (use cursor from previous response)
curl "https://api.cohort.bot/api/v1/tasks?limit=10&cursor=1707000000000"

Request Format

  • Content-Type: application/json for POST, PATCH, and PUT requests
  • Methods: GET, POST, PATCH, PUT, DELETE
  • Encoding: UTF-8

Response Format

All responses are JSON. Successful responses return the data directly. Error responses use a consistent format — see Errors.

Dates

All dates are returned as ISO 8601 strings (e.g., "2025-01-15T12:00:00.000Z"). When sending dates (e.g., dueDate), provide a Unix timestamp in milliseconds.

Rate limits

Each key can make 120 reads and 60 writes per minute. Over the limit, you get 429 RATE_LIMITED with a Retry-After header. See Errors.

Endpoints

ResourceEndpoints
TasksGET /tasks, POST /tasks, GET /tasks/:id, PATCH /tasks/:id, DELETE /tasks/:id, POST /tasks/:id/transition, POST /tasks/:id/archive, POST /tasks/:id/unarchive, GET/POST /tasks/:id/comments, GET/POST /tasks/:id/attachments, DELETE /tasks/:id/attachments/:attachmentId, POST /tasks/:id/relations, DELETE /tasks/:id/relations/:relationId
LabelsGET /labels, POST /labels, PATCH /labels/:id, DELETE /labels/:id
ProjectsGET /projects, POST /projects, GET /projects/:id, PATCH /projects/:id, DELETE /projects/:id, GET /projects/:id/tasks, GET/POST /projects/:id/comments
InitiativesGET /initiatives, POST /initiatives, GET /initiatives/:id, PATCH /initiatives/:id, DELETE /initiatives/:id, GET /initiatives/:id/projects
RoutinesGET /routines, POST /routines, GET /routines/:id, PATCH /routines/:id, DELETE /routines/:id, GET/PUT/DELETE /routines/:id/subscription
AgentsGET /agents, POST /agents, GET /agents/:id, PATCH /agents/:id, DELETE /agents/:id
ChatGET /chats, POST /chats, GET /chats/:id, PATCH /chats/:id, DELETE /chats/:id, GET /chats/:id/messages, POST /chats/:id/messages, POST /chats/:id/archive, POST /chats/:id/unarchive, GET /chats/:id/turns/:turnId
FilesPOST /files/upload-url, POST /files, GET /files/:fileId, GET /files/:fileId/content
CreditsGET /credits, GET /credit-allowances, PUT/DELETE /credit-allowances/:agent, GET /usage
SkillsGET /skills, POST /skills, GET /skills/:id, PATCH /skills/:id, DELETE /skills/:id, PUT /skills/:id/files, GET /skills/:id/files/content, PUT /skills/:id/assignments
TeamGET /team, GET /team/:id, PATCH /team/:id
ActivityGET /activity
ContextGET /context
MemoriesGET /memories
MeGET /me

The OpenAPI spec also covers approvals, Wire revision requests, signed-in devices, personal settings, and the health endpoints.

Last updated on
Authentication