API Documentation
Automate OKiDO from scripts, integrations, and AI agents.
Overview
The OKiDO API is a JSON REST API. Everything you can do in the app — projects, tasks, SOP runs, documents, templates — is available programmatically. All requests use the base URL:
https://app.okido.io/apiRequest and response bodies are JSON (Content-Type: application/json).
Authentication
Personal access tokens
The recommended way to call the API is with a personal access token (PAT). Create one in the app under Settings → Security → Personal access tokens. Tokens start with dit_pat_, act with your permissions in every organization you belong to, and can be set to expire after 7 days, 1 month, 3 months, 6 months, 1 year — or never. The token is shown once at creation; store it securely.
Send it in the Authorization header on every request:
curl https://app.okido.io/api/projects \
-H "Authorization: Bearer dit_pat_..." \
-H "X-Org-Id: <your-org-id>"For safety, a personal access token cannot manage tokens, change your password, or manage sessions — those actions require an interactive session and return 403 SESSION_AUTH_REQUIRED.
Organization API tokens
Organization-scoped API tokens (prefix dit_, created by org owners/admins under organization settings) authenticate the MCP endpoint only. They carry granular scopes and are bound to a single organization — use them when you want a credential that is not tied to a person.
Selecting an organization
Your account can belong to several organizations, so every REST request must say which organization it targets via the X-Org-Id header. You must be an active member of the organization; otherwise the API responds 403.
X-Org-Id: org-id
# or several at once (reads only):
X-Org-Id: org-id-1,org-id-2When multiple IDs are provided, list endpoints return results across all of them, and write operations target the first ID.
Errors
Errors share a single shape:
{
"message": "Human-readable description",
"code": "MACHINE_READABLE_CODE"
}| Status | Code | Meaning |
|---|---|---|
| 400 | VALIDATION_ERROR | Missing or invalid request fields |
| 400 | ORG_ID_REQUIRED | The X-Org-Id header is missing |
| 401 | UNAUTHORIZED | Missing, invalid, or expired token |
| 403 | FORBIDDEN | Not a member of the organization, or insufficient role |
| 403 | SESSION_AUTH_REQUIRED | Action not allowed with a personal access token |
| 404 | NOT_FOUND | Resource does not exist (or belongs to another organization) |
| 429 | RATE_LIMITED | Too many requests — retry later |
| 500 | INTERNAL_ERROR | Something went wrong on our side |
Resources
The tables below list the most-used endpoints per resource. All of them require the Authorization and X-Org-Id headers described above. List responses wrap results in a named array, e.g. { "projects": [...] }.
Projects
| Method | Endpoint | Description |
|---|---|---|
GET | /projects | List projects |
POST | /projects | Create a project |
GET | /projects/:id | Get a project |
PATCH | /projects/:id | Update a project |
DELETE | /projects/:id | Delete a project |
GET | /projects/:id/tasks | List tasks in a project |
GET | /projects/:id/stages | List workflow stages |
POST | /projects/:id/members | Add a member (private projects) |
Tasks
| Method | Endpoint | Description |
|---|---|---|
POST | /tasks | Create a task |
GET | /tasks/search?q=... | Search tasks in the organization |
GET | /tasks/:id | Get a task |
PATCH | /tasks/:id | Update a task (status, assignee, due date, ...) |
DELETE | /tasks/:id | Delete a task |
POST | /tasks/:id/comments | Add a comment |
POST | /tasks/:id/subtasks | Create a subtask |
POST | /tasks/:id/time-entries | Log time on a task |
SOP runs
| Method | Endpoint | Description |
|---|---|---|
GET | /runs | List runs (filter with ?status=... or ?templateId=...) |
POST | /runs | Start a run from a template |
GET | /runs/:id | Get a run with its steps |
PATCH | /runs/:id | Update a run |
DELETE | /runs/:id | Delete a run |
POST | /runs/:id/steps/:stepId/complete | Complete a step |
PATCH | /runs/:id/steps/:stepId | Update a step (status, assignee) |
POST | /runs/:id/variable-values | Set a run variable value |
Documents
| Method | Endpoint | Description |
|---|---|---|
GET | /documents | List documents (filter with ?processId=...) |
POST | /documents | Create a document |
GET | /documents/:id | Get a document |
PATCH | /documents/:id | Update a document |
DELETE | /documents/:id | Delete a document |
POST | /documents/:id/publish | Publish (new version) |
GET | /documents/:id/versions | List version history |
SOP templates
| Method | Endpoint | Description |
|---|---|---|
GET | /sop-templates | List templates |
POST | /sop-templates | Create a template |
GET | /sop-templates/:id | Get a template |
PATCH | /sop-templates/:id | Update a template |
DELETE | /sop-templates/:id | Delete a template |
POST | /sop-templates/:id/steps | Add a step |
POST | /sop-templates/:id/publish | Publish a version snapshot |
MCP endpoint for AI agents
OKiDO exposes a Model Context Protocol endpoint so AI clients such as Claude can work with your projects, tasks, runs, and documents through tools instead of raw HTTP:
https://app.okido.io/mcpAuthenticate with a personal access token, an organization API token, or OAuth. With a personal access token the AI client can act across all your organizations; an organization token limits it to one organization with the scopes you selected.
Quickstart
# 1. Create a personal access token in Settings → Security
# 2. List your projects
curl https://app.okido.io/api/projects \
-H "Authorization: Bearer dit_pat_..." \
-H "X-Org-Id: <your-org-id>"
# 3. Create a task
curl -X POST https://app.okido.io/api/tasks \
-H "Authorization: Bearer dit_pat_..." \
-H "X-Org-Id: <your-org-id>" \
-H "Content-Type: application/json" \
-d '{"title": "My first API task", "projectId": "<project-id>"}'Questions or missing endpoints? Contact us — we're expanding this reference continuously.