Do you like cookies?

octo.do has no tracking and no analytics. Your choice only switches the chat assistant: accept, and it can open; decline, and it stays off.

Skip to content

API Documentation

Integrate your octo.do tasks with any tool, automation, or custom workflow.

Authentication

All requests require a personal API key. Generate one from Settings → API Keys in the app.

curl -H "Authorization: Bearer octodo_YOUR_KEY" \
  https://api.octo.do/public/v1/tasks

Base URL

https://api.octo.do/public/v1

Tasks

GET
/tasks

List all tasks. Supports ?status=unchecked|in_progress|checked&category=UUID&limit=100&offset=0

curl -H "Authorization: Bearer octodo_YOUR_KEY" \
  "https://api.octo.do/public/v1/tasks?status=unchecked&limit=8"
GET
/tasks/:id

Get a single task by ID.

POST
/tasks

Create a new task.

curl -X POST \
  -H "Authorization: Bearer octodo_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Ship feature X", "location": "backlog", "business_value": 8, "time_criticality": 5, "risk_reduction": 3, "job_size": 5}' \
  https://api.octo.do/public/v1/tasks
FieldTypeRequiredDescription
titlestringrequiredTask title (max 500 chars)
locationstringoptionaltoday, next, someday, or backlog (default)
descriptionstringoptionalTask description (max 5000 chars)
categoryuuidoptionalCategory ID
business_valuenumberoptional1–10 (default 1)
time_criticalitynumberoptional1–10 (default 1)
risk_reductionnumberoptional1–10 (default 1)
job_sizenumberoptional≥1 (default 1)
PATCH
/tasks/:id

Update a task. Send only the fields you want to change.

curl -X PATCH \
  -H "Authorization: Bearer octodo_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"location": "done"}' \
  https://api.octo.do/public/v1/tasks/TASK_UUID
DELETE
/tasks/:id

Delete a task permanently.

Categories

GET
/categories

List all categories.

POST
/categories

Create a category.

curl -X POST \
  -H "Authorization: Bearer octodo_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Work", "icon": "💼"}' \
  https://api.octo.do/public/v1/categories
FieldTypeRequiredDescription
namestringrequiredCategory name (max 100 chars)
iconstringoptionalEmoji icon
parent_iduuidoptionalParent category for nesting
PATCH
/categories/:id

Update a category.

DELETE
/categories/:id

Delete a category.

Profile

GET
/profile

Get your profile and preferences.

PATCH
/profile

Update preferences.

curl -X PATCH \
  -H "Authorization: Bearer octodo_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"max_today": 6, "theme": "dark"}' \
  https://api.octo.do/public/v1/profile

Errors

All errors return a JSON object with an error field.

StatusDescription
401Invalid or missing API key
400Invalid request body or parameters
404Resource not found
500Internal server error

Rate Limits

The API is rate-limited to 100 requests per minute per API key. If you hit the limit, wait a moment and retry.