Todo.work API

Everything the Todo.work app does is available over HTTP: tasks, projects, leads, clients, comments, chat, kanban boards, files and time tracking. The same API is also exposed as an MCP server, so an AI agent can use it directly without any glue code.

88 endpoints Base URL https://api.todo.work/api_integrations MCP https://api.todo.work/api_integrations/mcp Get your API key →

Before you start

Create a key under Settings → API keys in the app. A key acts with the permissions of the user it is bound to — it can never do more than that user can.

  • The samples below show YOUR_API_KEY and YOUR_API_SECRET. Replace them with your own, and keep them out of anything you commit or paste.
  • For AI agents: point any MCP-capable client at https://api.todo.work/api_integrations/mcp and authenticate with Authorization: Bearer <api_key>:<api_secret>. The tools are grouped by module and take an { action, params } pair whose action names match the REST paths below.
  • Success bodies are { "response": <payload> }. Check the HTTP status rather than the presence of a response key — the 401 body carries one too, empty.

Authentication

Every request authenticates with a key/secret pair sent as HTTP headers. A key acts with the permissions of the user it is bound to.

Required headers
  • X-API-KEY: YOUR_API_KEY
  • X-API-SECRET: YOUR_API_SECRET
  • Content-Type: application/json
Optional headers
  • User-Token: <token> — override acting user (admin / legacy keys only)
  • User-Timezone: Asia/Jerusalem — defaults to Asia/Jerusalem
Alternative: OAuth 2.1 bearer token (see the OAuth section)
  • Authorization: Bearer tdo_at_… - an access token issued by /oauth_token
  • Content-Type: application/json
Scopes (enforced)
  • write - everything (the default for a key, and for a token unless narrowed)
  • read - lookups only: results, get, lists, reports, exports
  • Two ways in, same API: the key/secret pair (this section) or an OAuth 2.1 bearer access token minted through the consent screen (next section). A bearer token resolves to the key behind it, so everything below applies to both.
  • Scopes are enforced per action. A read-only connection (key marked read-only on the API keys screen, or a token granted scope=read) may call only lookup actions; a write on it answers 403 with WWW-Authenticate: Bearer error="insufficient_scope". The exact allow-list is the READ_ACTIONS constant in api_integrations.php.
  • A missing or refused credential answers 401 with WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/…" so an OAuth-capable client can discover how to log in.
  • Aliases: you may send Api-Token / Api-Secret instead of X-API-KEY / X-API-SECRET.
  • A key bound to a user (acts_as_user_id) runs strictly as that user — it can do nothing the user cannot. Admin / legacy keys may override the acting user with a User-Token header.
  • A disabled key (status = 0) is rejected with 401.
  • Response shapes — there are two, and only two. Success: { "response": <payload> }. Failure: { "status": <http>, "message": "<text>", "response": [] } at the top level, with the same HTTP status. Branch on the HTTP status, then read message.
  • Failure statuses: 400 a rejected parameter or value, 401 unauthorized, 403 the acting user lacks the permission, 404 an unknown action on a real endpoint, 500 internal error. An unknown PATH (wrong controller) is served by the web server and answers HTML, not JSON.
  • A few endpoints (/, /get_users, /get_project_senior_members, /add_lead) wrap their success payload twice, so their data sits at response.response.
  • Older clients may still have handling for a bare "PERMS" string, a bare "method_not_exists." string, or a 200 carrying { "status": false, "error": "…" }. None of those are returned any more — they are 403, 404 and 400 respectively, in the failure envelope above.

GET / Health check

Confirms the key authenticates and a platform resolved. Returns "API is working".

Parameters

No parameters — send the authentication headers only.

Permission

Any valid key

Request
// Health check — verifies your credentials
const response = await fetch('https://api.todo.work/api_integrations/', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  }
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "status": 200,
    "message": "API is working",
    "response": []
  }
}

OAuth 2.1 & Scopes

The standards door for ChatGPT, Claude, Gemini CLI, Zapier-class tools and your own apps: discovery, authorization code + PKCE, short-lived bearer tokens with refresh, dynamic client registration, and two enforced scopes (read / write). The key/secret pair keeps working as before.

Discovery (RFC 9728 / RFC 8414)
  • https://api.todo.work/.well-known/oauth-protected-resource/api_integrations/mcp
  • https://api.todo.work/.well-known/oauth-authorization-server
Endpoints
  • https://app.todo.work/oauth/authorize - the consent screen (workspace admin)
  • https://api.todo.work/api_integrations/oauth_token - code → tokens, refresh
  • https://api.todo.work/api_integrations/oauth_register - RFC 7591 dynamic client registration
  • https://api.todo.work/api_integrations/oauth_revoke - RFC 7009 revocation
Scopes
  • read - lookups only (results, get, lists, reports, exports)
  • write - everything; the default when nothing is requested
  • offline_access - accepted and ignored: a refresh token is always issued
Token lifetimes
  • access_token tdo_at_… - 1 hour
  • refresh_token tdo_rt_… - 90 days, rotated on every refresh (the old one dies)
  • authorization code - 5 minutes, single use
  • MCP clients (ChatGPT connectors, Claude custom connectors, Claude Code, Gemini CLI) need only the MCP URL: they read the discovery documents, register themselves, send the admin to the consent screen and hold a bearer token from then on. Nothing is pasted by hand.
  • The consent screen is where the workspace admin decides everything: which workspace, in whose name the app acts (a bot is a good choice), and whether the connection is read-only. Approving mints (or reuses) an API key for (workspace, app) and a one-time code bound to the PKCE challenge.
  • PKCE (S256) is mandatory for public clients (token_endpoint_auth_method "none") and honoured for everyone. "plain" is not accepted.
  • Client registration: POST /oauth_register with your redirect_uris (https, or http on localhost), or use a Client ID Metadata Document (client_id = the https URL of a JSON document that names itself). Apps registered by Wizzo show as verified on the consent screen; self-registered apps show an "unverified" warning.
  • The token endpoint accepts application/x-www-form-urlencoded and JSON bodies, and client_secret_post, client_secret_basic (HTTP Basic) or no secret (public client + PKCE).
  • Token responses are standard at the top level: access_token, token_type "Bearer", expires_in, refresh_token, scope, plus acts_as_user_id, workspace {id, name, domain}, api_url, brain_url, mcp_url, app_url.
  • Scope narrowing: the app asks (scope=read or nothing), the admin may tick read-only, and a key marked read-only on the API keys screen caps every token minted through it. The effective scope is always the narrower one. On refresh a token may ask for a narrower scope, never a wider one.
  • Disconnecting: the app calls /oauth_revoke with its token (only that pair dies), or the admin disables the key on the API keys screen (every token on it dies at once). A disabled key answers 401 error="invalid_token".

GET /.well-known/oauth-authorization-server Discovery document

Where everything is: authorization, token, registration and revocation endpoints, supported grants, PKCE methods and scopes. No credentials needed. The protected-resource document (…/oauth-protected-resource/api_integrations/mcp) points here.

Parameters

No parameters — send the authentication headers only.

Permission

Public

Request
// Discovery - no credentials; served from the API origin, not under /api_integrations
const response = await fetch('https://api.todo.work/.well-known/oauth-authorization-server');

const data = await response.json();
console.log(data);
Response
{
  "issuer": "https://api.todo.work",
  "authorization_endpoint": "https://app.todo.work/oauth/authorize",
  "token_endpoint": "https://api.todo.work/api_integrations/oauth_token",
  "registration_endpoint": "https://api.todo.work/api_integrations/oauth_register",
  "revocation_endpoint": "https://api.todo.work/api_integrations/oauth_revoke",
  "scopes_supported": ["read", "write", "offline_access"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none", "client_secret_post", "client_secret_basic"],
  "client_id_metadata_document_supported": true
}

POST /oauth_register Register a client (RFC 7591)

Registers your app and returns its client_id (and client_secret unless token_endpoint_auth_method is "none"). Anonymous, rate-limited per address. MCP clients do this by themselves.

Parameters
NameTypeDescription
redirect_uris
required · body
string[] Exact return addresses. https only (http allowed on localhost), no fragments, up to 10.
client_name
optional · body
string Shown on the consent screen. Defaults to the host of the first redirect URI.
token_endpoint_auth_method
optional · body
string "none" (public client, PKCE only), "client_secret_post" or "client_secret_basic" (default).
grant_types
optional · body
string[] authorization_code and/or refresh_token (default: authorization_code).
client_uri
optional · body
string Your app's https address; shown on the consent screen.
logo_uri
optional · body
string https URL of a logo (stored, not yet displayed).
scope
optional · body
string The scope you intend to request: "read" or "write".
Permission

Public (20 registrations per address per hour)

Request
// Register your app once - keep the client_id (and client_secret) it returns.
// No API key: this is how an app that nobody at TODO knows yet introduces itself.
const response = await fetch('https://api.todo.work/api_integrations/oauth_register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    client_name: 'My integration',
    redirect_uris: ['https://my-app.example.com/oauth/callback'],
    token_endpoint_auth_method: 'client_secret_basic',
    grant_types: ['authorization_code', 'refresh_token'],
    client_uri: 'https://my-app.example.com',
    scope: 'read'
  })
});

const data = await response.json();
console.log(data);
Response
{
  "client_id": "dyn_3f9a1c…",
  "client_id_issued_at": 1789761612,
  "client_secret": "…",
  "client_secret_expires_at": 0,
  "client_name": "My integration",
  "redirect_uris": ["https://my-app.example.com/oauth/callback"],
  "token_endpoint_auth_method": "client_secret_basic",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "client_uri": "https://my-app.example.com",
  "scope": "read"
}

GET /oauth/authorize Send the admin to the consent screen

A browser redirect, not an API call: the workspace admin signs in, picks the workspace, chooses in whose name your app acts and whether it is read-only, and is sent back to your redirect_uri with ?code=…&state=…. Lives on the app host, not under /api_integrations.

Parameters
NameTypeDescription
response_type
required · query
string Always "code".
client_id
required · query
string From /oauth_register, or the https URL of your client metadata document.
redirect_uri
required · query
string One of the registered addresses, exactly.
state
required · query
string Your CSRF token; echoed back unchanged.
code_challenge
required · query
string base64url(sha256(code_verifier)). Mandatory for public clients, honoured for all.
code_challenge_method
optional · query
string Only "S256".
scope
optional · query
string "read" for a read-only connection; anything else or nothing = write. The admin can still narrow it.
resource
optional · query
string RFC 8707 resource indicator, e.g. the MCP URL. Recorded on the token.
Permission

A signed-in workspace admin (system.manage)

Request
// Build the address and REDIRECT the admin's browser to it (do not fetch it).
const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));           // keep it for /oauth_token
const challenge = base64url(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier)));

const url = new URL('https://app.todo.work/oauth/authorize');
url.search = new URLSearchParams({
  response_type: 'code',
  client_id: 'dyn_3f9a1c…',
  redirect_uri: 'https://my-app.example.com/oauth/callback',
  state: 'a-random-string-you-verify-on-return',
  code_challenge: challenge,
  code_challenge_method: 'S256',
  scope: 'read',
  resource: 'https://api.todo.work/api_integrations/mcp'
}).toString();

window.location.href = url.toString();
// …the admin approves, and your redirect_uri receives ?code=<64 hex>&state=…
// On refusal: ?error=access_denied&state=…
Response
// Browser lands on:
https://my-app.example.com/oauth/callback?code=9f3c…(64 hex)&state=a-random-string-you-verify-on-return

POST /oauth_token Exchange the code for tokens

grant_type=authorization_code: the code from the redirect plus your PKCE verifier (and client secret for confidential clients) → a bearer access token and a refresh token. Form-encoded or JSON body; client_secret_basic (HTTP Basic) also accepted.

Parameters
NameTypeDescription
grant_type
required · body
string "authorization_code".
code
required · body
string The 64-hex code from the redirect. Single use, 5 minutes.
client_id
required · body
string Your client id (or in the Basic header).
client_secret
optional · body
string Confidential clients only (or in the Basic header). Public clients omit it.
redirect_uri
required · body
string The same redirect_uri the code was issued for.
code_verifier
optional · body
string The PKCE verifier. Required when the authorization request carried a code_challenge (always, for public clients).
Permission

The registered client (secret and/or PKCE verifier)

Request
// Server side (or the public client itself). No API key - the code + verifier ARE the proof.
const response = await fetch('https://api.todo.work/api_integrations/oauth_token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: '9f3c…',
    client_id: 'dyn_3f9a1c…',
    client_secret: '…',                    // omit for a public client
    redirect_uri: 'https://my-app.example.com/oauth/callback',
    code_verifier: verifier
  })
});

const data = await response.json();
console.log(data.access_token, data.scope);
Response
{
  "access_token": "tdo_at_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "tdo_rt_…",
  "scope": "read",
  "acts_as_user_id": 7,
  "workspace": { "id": 4, "name": "Wizzo", "domain": "wizzo.todo.work" },
  "api_url": "https://api.todo.work/api_integrations",
  "brain_url": "https://api.todo.work/api_brain",
  "mcp_url": "https://api.todo.work/api_integrations/mcp",
  "app_url": "https://wizzo.todo.work"
}
// Failures are RFC 6749 shaped: { "error": "invalid_grant", "error_description": "…" } with 400/401.

POST /oauth_token Refresh the access token

grant_type=refresh_token: a new access token and a NEW refresh token; the one you sent stops working the moment the new pair is issued. A narrower scope may be requested, never a wider one.

Parameters
NameTypeDescription
grant_type
required · body
string "refresh_token".
refresh_token
required · body
string The current tdo_rt_… token.
client_id
required · body
string Your client id.
client_secret
optional · body
string Confidential clients only.
scope
optional · body
string Optional: "read" to narrow a write token.
Permission

The registered client

Request
// When a call answers 401 error="invalid_token" ("access token expired"), refresh and retry.
const response = await fetch('https://api.todo.work/api_integrations/oauth_token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'refresh_token',
    refresh_token: 'tdo_rt_…',
    client_id: 'dyn_3f9a1c…',
    client_secret: '…'                     // omit for a public client
  })
});

const data = await response.json();
// store BOTH: data.access_token and data.refresh_token (the old refresh token is now dead)
Response
{
  "access_token": "tdo_at_…(new)",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "tdo_rt_…(new)",
  "scope": "read",
  "acts_as_user_id": 7,
  "workspace": { "id": 4, "name": "Wizzo", "domain": "wizzo.todo.work" },
  "api_url": "https://api.todo.work/api_integrations",
  "mcp_url": "https://api.todo.work/api_integrations/mcp"
}

GET /whoami Call the API with a bearer token

Any endpoint in this documentation, and the MCP endpoint, accepts Authorization: Bearer tdo_at_… instead of the X-API-KEY / X-API-SECRET pair. Under a read scope, write actions answer 403 insufficient_scope.

Parameters

No parameters — send the authentication headers only.

Permission

The user the connection acts as, within its scope

Request
// Same API, one header instead of two.
const response = await fetch('https://api.todo.work/api_integrations/whoami', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer tdo_at_…',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data.response);
// 401 + WWW-Authenticate: Bearer error="invalid_token"        → refresh (or re-authorize)
// 403 + WWW-Authenticate: Bearer error="insufficient_scope"   → this connection is read-only
Response
{
  "response": {
    "status": 200,
    "message": "OK",
    "response": {
      "user_id": 7,
      "display_name": "…",
      "is_admin": true,
      "platform": { "id": 4, "name": "Wizzo", "domain": "wizzo.todo.work" }
    }
  }
}

POST /oauth_revoke Revoke a token (RFC 7009)

Kills the access/refresh pair the token belongs to; the connection itself (the key) stays, so a fresh authorization is instant. Always 200, idempotent. Confidential clients may instead send api_key to disable the whole connection.

Parameters
NameTypeDescription
token
required · body
string A tdo_at_… or tdo_rt_… token of this client.
client_id
required · body
string Your client id.
client_secret
optional · body
string Confidential clients only.
token_type_hint
optional · body
string Ignored; the prefix says which kind it is.
Permission

The registered client

Request
// The user disconnected on your side - say so here too.
const response = await fetch('https://api.todo.work/api_integrations/oauth_revoke', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    token: 'tdo_rt_…',
    client_id: 'dyn_3f9a1c…',
    client_secret: '…'
  })
});

const data = await response.json();
console.log(data.revoked);
Response
{ "revoked": true }

Projects

List, read and create/update projects. Data is scoped to the key’s platform.

GET /projects/results List projects

Filtered list of projects with calculated metrics (logged hours, open tickets, departments, last update). What it returns depends on the acting user’s permissions — see below.

Parameters
NameTypeDescription
id
optional · query
int A single project id. Overrides is_archive.
client_id
optional · query
int Filter by client.
is_archive
optional · query
bool true = archived/deleted, false = active (default). Accepts true/false, 1/0 and the strings "true"/"false" over a query string.
Permission

Any key (scope depends on tasks.manage / tasks.view_all)

Notes
  • Scope: a user with "ניהול משימות מלא" (tasks.manage) or "צפייה בכל המשימות" (tasks.view_all) gets every project on the platform, full row. Any other user gets only the projects they can see in the app — the ones they are assigned to — and the commercial fields (price, price_hour, calc_by_price_hour, project_estimate_hours, target_monthly_hours, target_monthly_hours_alert, hours) are omitted from those rows.
  • A user with no visible projects gets an empty array — never a refusal.
  • The archived flag on each row is is_deleted, not is_archive — there is no is_archive field in the response.
  • hours is a formatted "HH:MM" string, not a number (managers only).
  • folder resolves the folder_id in place — { id, name, color }, or false when the project is not in a folder. /projects/folders lists them all.
  • Rows also carry the project permission columns (perms_*), notes, folder_id, and the joined client columns cln_name / cln_phone / cln_email. Only the commonly used fields are shown below.
Request
// List active projects for a client
const response = await fetch('https://api.todo.work/api_integrations/projects/results?client_id=5&is_archive=false', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  }
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": [
    {
      "id": 12,
      "name": "Website Redesign",
      "type": "hourly",
      "client_id": 5,
      "color": "#59ce8f",
      "hours": "42:30",
      "open_tickets": 7,
      "is_deleted": 0,
      "last_update": "2026-06-26 14:11:00",
      "departments": [1, 3],
      "cln_name": "Acme Inc.",
      "notes": "",
      "folder_id": 157,
      "folder": { "id": 157, "name": "Retainers", "color": "#59ce8f" }
    }
  ]
}

GET /projects/folders List project folders

The project folders on this platform — the resolver for the folder_id every project carries.

Parameters

No parameters — send the authentication headers only.

Permission

Any key (a member sees only the folders their own projects are in)

Notes
  • Sorted by name. Deleted folders are excluded.
  • Each project in /projects/results already carries the same object inline as folder — call this only when you need the full folder list (e.g. to mirror the sidebar tree).
Request
// List the project folders
const response = await fetch('https://api.todo.work/api_integrations/projects/folders', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  }
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": [
    { "id": 157, "name": "Retainers", "color": "#59ce8f" },
    { "id": 162, "name": "Internal", "color": "" }
  ]
}

GET /projects/get Get a project

A single project by id, enriched with its documents and full department objects.

Parameters
NameTypeDescription
id
required · query
int Project id (must be > 0).
Permission

Any key (same scope as /projects/results)

Notes
  • Returns false for an id the acting user cannot see — same answer as a nonexistent id.
  • A non-manager gets the member column set described under /projects/results.
Request
// Get project 123
const response = await fetch('https://api.todo.work/api_integrations/projects/get?id=123', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  }
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "id": 123,
    "name": "Website Redesign",
    "type": "hourly",
    "departments": [ { "id": 1, "name": "Design" } ],
    "docs": [],
    "docs_token": "…"
  }
}

POST /projects/save Create or update a project

Omit id to create, include it to update. Can auto-create a client and (on create) opens a first ticket.

Parameters
NameTypeDescription
id
optional · body
int Include to update; omit to create.
name
required · body
string Project name.
type
required · body
enum "hourly" (time-tracked) or "fixed" (fixed price).
client_id
optional · body
int | "add" Existing client id, or "add" to create a new client (with client_name / client_email).
price_hour
optional · body
decimal Hourly rate (type=hourly only).
price
optional · body
decimal Fixed price (type=fixed only).
target_monthly_hours
optional · body
decimal Monthly hours target (type=hourly only).
departments
optional · body
array Array of { id } objects or ids.
date_deadline
optional · body
string Any parseable date; stored as Y-m-d.
folder_id
optional · body
int Put the project in a folder — an id from /projects/folders. Omit (or send 0) to leave it where it is.
open_first_ticket
optional · body
bool Open a starter ticket on create (default true).
Permission

Any key (needs tasks.manage)

Notes
  • The id comes back as a number in both directions — create and update. (It used to be a string on create.)
Request
// Create a new hourly project
const response = await fetch('https://api.todo.work/api_integrations/projects/save', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({
    name: 'Website Redesign',
    type: 'hourly',
    client_id: 5,
    price_hour: '50.00',
    target_monthly_hours: '160',
    departments: [{ id: 1 }]
  })
});

const data = await response.json();
console.log(data.response);
Response
// On success the new (or updated) project id:
{ "response": 87 }

POST /projects/update_archive_status Archive or restore a project

Moves a project to the archive, or brings it back. Reversible, and the project keeps all of its tasks, hours and billing history.

Parameters
NameTypeDescription
id
required · body
int Project id.
status
required · body
bool true = archive, false = restore. Must be a real boolean, not "1"/"0".
Permission

Any key (needs tasks.manage)

Notes
  • This is what "delete a project" means in the product — the archive flag is the is_deleted column, and archived projects are listed with is_archive=true on /projects/results.
  • Restoring a project also un-archives its client, if that client was archived.
Request
// Archive a project
const response = await fetch('https://api.todo.work/api_integrations/projects/update_archive_status', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({
    id: 123,
    status: true
  })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": true }

POST /projects/delete Delete a project permanently

Erases a project, all of its tasks and subtasks, its comments, files, chat rooms, kanban lists and links. There is no undo and no archive to recover from — use /projects/update_archive_status unless you really mean destroy.

Parameters
NameTypeDescription
id
required · body
int Project id. Must already be archived.
Permission

Any key (needs tasks.manage)

Notes
  • Two conditions, both refused with 400 and a message that explains itself in the workspace language: (1) the project must already be archived — archive it first, so deleting is always two deliberate steps; (2) it may not carry BILLABLE logged time, meaning an hourly rate above 0 together with time logged on any of its tasks (tasks already deleted and timers running right now included).
  • The time rule is a billing rule, not a safety ritual. Every money figure is hourly rate × logged minutes — the fixed price column never enters it — while payments are recorded against the client, not the project. So a project only becomes undeletable when both halves of that product are non-zero: with a rate of 0 the hours are worth nothing to any balance and the project can be deleted however many were logged, and with no logged time the rate does not matter. Either way, removing it cannot move anyone’s balance.
  • Note that the gate reads the hourly rate, not the pricing type. A project typed "fixed" that still carries a price_hour is billed for its hours by the reports, so it is protected too.
  • Invoices and call recordings are not deleted — they belong to the client and to the people on the call. Their project link is cleared and the records stay.
  • To delete a single task instead, POST /tickets/update with field "is_deleted" and value 1. The same billable-time rule applies there: logged time only blocks the delete when its project has an hourly rate above 0.
Request
// Permanently delete an archived, never-worked-on project
const response = await fetch('https://api.todo.work/api_integrations/projects/delete', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({
    id: 123
  })
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "status": true,
    "deleted": { "project_id": 123, "tickets": 12, "files": 3 }
  }
}

// Refused (HTTP 400):
{
  "status": 400,
  "message": "Cannot delete: this project has logged work time (42:30 across 7 task(s))…",
  "response": []
}

Tickets

The core task object. Create, read, update, run timers and manage handlers. Results are limited to projects the acting key can access.

  • scheduled_date is read/written in the caller’s timezone (User-Timezone header) and stored as UTC.
  • Update changes ONE field per call using the field / value pattern.
  • Dates: prefer ISO — "2026-10-01 09:00" or "2026-10-02T09:00:00". Slash format is read as DD/MM/YYYY, so 03/10/2026 is 3 October. A value that cannot be parsed is rejected; it never clears the stored date.
  • handlers_uid comes back as a pipe-delimited string ("|7|12|"), not an array. Send handlers (array of { id }) to change it.

POST /tickets/results List tickets

Paginated ticket list with rich filtering by project, handler, status, custom fields, date range and full-text search.

Parameters
NameTypeDescription
filter_by
optional · body
enum pending | finished | my | all | search.
project_id
optional · body
int | array | "all" One id, a list, or "all" accessible projects.
handler
optional · body
int | array | "none" Filter by handler; "none" = unassigned.
q
optional · body
string Search text (min 3 chars, with filter_by=search).
page
optional · body
int 1-indexed page (default 1).
limit
optional · body
int Per page (default 100).
order
optional · body
string date_updated (default) | date_created | scheduled_date | handler.
order_dir
optional · body
enum ASC | DESC (default DESC).
Permission

Any key

Notes
  • The response always carries a projects array alongside tickets.
  • project_totals, total_results and next_token are returned ONLY when project_id is sent. Without it the response is just { tickets, projects } — so paginate by sending project_id.
Request
// Pending tickets in projects 1 and 2 handled by user 5
const response = await fetch('https://api.todo.work/api_integrations/tickets/results', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({
    filter_by: 'pending',
    project_id: [1, 2],
    handler: 5,
    page: 1,
    limit: 50,
    order: 'date_updated',
    order_dir: 'DESC'
  })
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "tickets": [
      {
        "id": 123,
        "subject": "Fix login bug",
        "project_id": 5,
        "handlers": [ { "id": 7, "display_name": "Dana" } ],
        "handlers_uid": "|7|",
        "is_completed": 0,
        "scheduled_date": "2026-07-15 14:30:00",
        "duration": 90
      }
    ],
    "projects": [ { "id": 5, "name": "Website Redesign" } ],
    "total_results": 1,
    "next_token": "…"
  }
}

POST /tickets/get Get a ticket

A single ticket with comments, subtasks, handlers, custom fields and a share url.

Parameters
NameTypeDescription
id
required · body
int Ticket id.
Permission

Any key (must have access to the ticket)

Request
// Get ticket 456
const response = await fetch('https://api.todo.work/api_integrations/tickets/get', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ id: 456 })
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "id": 456,
    "subject": "Fix login bug",
    "project_id": 5,
    "handlers": [ { "id": 7, "display_name": "Dana" } ],
    "is_completed": 0,
    "custom_filters": { "42": "101" },
    "comments": [],
    "subtasks_list": [],
    "share_url": "https://…"
  }
}

POST /tickets/add Create a ticket

Creates a task (or lead). Handlers are auto-enrolled into the project.

Parameters
NameTypeDescription
subject
required · body
string Ticket title.
project_id
optional · body
int Target project (auto-selects first if omitted).
scheduled_date
optional · body
string Datetime in your timezone.
handlers_uid
optional · body
array[int] Handler user ids.
duration_limit
optional · body
int Time budget in minutes.
list_id
optional · body
int Kanban list to place it on.
type
optional · body
enum task (default) | lead.
Permission

Any key

Notes
  • The response also carries ticket_id alongside ticket.id — ticket_id is a string, ticket.id is a number. Prefer ticket.id.
Request
// Create a ticket in project 123
const response = await fetch('https://api.todo.work/api_integrations/tickets/add', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({
    subject: 'Fix login bug',
    project_id: 123,
    handlers_uid: [7, 12],
    scheduled_date: '2026-07-15 14:30',
    duration_limit: 240
  })
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "status": true,
    "ticket_id": "988",
    "ticket": { "id": 988, "subject": "Fix login bug", "project_id": 123 }
  }
}

POST /tickets/update Update a ticket field

Updates one field per call. Side effects fire automatically (timers stop on completion, handlers enroll into the project, reminders schedule).

Parameters
NameTypeDescription
id
required · body
int Ticket id.
field
required · body
string subject | scheduled_date | handlers | is_completed | project_id | duration_limit | custom_field.
value
required · body
mixed Format depends on field (see notes). handlers = array of { id }. Must be present — omitting the key is an error, not an empty value.
custom_field_id
optional · body
int Required when field = "custom_field" (see Custom Fields).
Permission

Any key (edit access to the ticket’s project)

Notes
  • is_completed accepts true/false, 1/0 and the strings "1"/"0"/"true"/"false". Anything else is rejected with a message rather than being coerced.
  • A bare { "response": false } means one thing only: nothing changed, because the value sent already equals the stored one. Every rejection answers { "status": false, "error": "…" } instead, so an idempotent re-run is distinguishable from a refusal.
  • Sending an id that does not exist answers { "status": false, "error": "Ticket not found" }.
Request
// Set the handlers of ticket 456
const response = await fetch('https://api.todo.work/api_integrations/tickets/update', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({
    id: 456,
    field: 'handlers',
    value: [{ id: 7 }, { id: 12 }]
  })
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "status": "success",
    "ticket": { "id": 456, "handlers": [ { "id": 7 }, { "id": 12 } ] }
  }
}

POST /tickets/create_subtask Create a subtask

Creates a subtask under a parent ticket; it inherits the parent’s project.

Parameters
NameTypeDescription
parent_id
required · body
int Parent ticket id.
subject
required · body
string Subtask title.
handlers_uid
optional · body
array[int] Handler user ids.
Permission

Any key (access to the parent ticket)

Request
// Add a subtask to ticket 456
const response = await fetch('https://api.todo.work/api_integrations/tickets/create_subtask', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({
    parent_id: 456,
    subject: 'Test the login page',
    handlers_uid: [8]
  })
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": { "status": true, "ticket": { "id": 991, "parent_id": 456 } }
}

POST /tickets/add_handler Add a handler

Adds a single handler without replacing the others (idempotent).

Parameters
NameTypeDescription
tid
required · body
int Ticket id.
handler_id
required · body
int User id to add.
Permission

Any key (edit access)

Request
// Add handler 7 to ticket 456
const response = await fetch('https://api.todo.work/api_integrations/tickets/add_handler', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ tid: 456, handler_id: 7 })
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "status": "success",
    "ticket": { "id": 456, "handlers_uid": "|7|", "handlers": [ { "id": 7, "display_name": "Dana" } ] }
  }
}

POST /tickets/remove_handler Remove a handler

Removes a single handler (idempotent).

Parameters
NameTypeDescription
tid
required · body
int Ticket id.
handler_id
required · body
int User id to remove.
Permission

Any key (edit access)

Request
// Remove handler 7 from ticket 456
const response = await fetch('https://api.todo.work/api_integrations/tickets/remove_handler', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ tid: 456, handler_id: 7 })
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "status": "success",
    "ticket": { "id": 456, "handlers_uid": "||", "handlers": [] }
  }
}

POST /tickets/start_handling Start a timer

Starts a duration timer on a ticket. Time-threshold warnings (ticket duration limit / project monthly hours) are a UI-only confirmation dialog — over the API the timer always just starts, so "confirm" is never returned here.

Parameters
NameTypeDescription
tid
required · body
int Ticket id.
handler_uid
optional · body
int Defaults to the acting user.
Permission

Any key (acting user must be a team member)

Request
// Start the timer on ticket 456
const response = await fetch('https://api.todo.work/api_integrations/tickets/start_handling', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ tid: 456 })
});

const data = await response.json();
console.log(data.response);
Response
// true on start, false if a timer is already running for this handler:
{ "response": true }

POST /tickets/stop_handling Stop a timer

Stops the active timer and records the elapsed minutes.

Parameters
NameTypeDescription
tid
required · body
int Ticket id.
Permission

Any key (acting user must be a team member)

Request
// Stop the timer on ticket 456
const response = await fetch('https://api.todo.work/api_integrations/tickets/stop_handling', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ tid: 456 })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": true }

POST /tickets/report_duration Report worked time

Records a completed block of work directly, without a start/stop clock — useful for billing or reported work.

Parameters
NameTypeDescription
tid
required · body
int Ticket id.
duration
required · body
int Minutes worked (> 0).
handler_uid
optional · body
int Defaults to the acting user.
date
optional · body
string Work datetime in your timezone (defaults to now).
description
optional · body
string What was done in this block of work (max 500 chars).
Permission

Any key (acting user must be a team member)

Request
// Log 2 hours on ticket 456
const response = await fetch('https://api.todo.work/api_integrations/tickets/report_duration', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({
    tid: 456,
    duration: 120,
    handler_uid: 7,
    date: '2026-06-27 14:00',
    description: 'Migrated the export job to the new queue'
  })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": true }

POST /tickets/set_duration_description Describe a time entry

Sets the free-text description on a treatment-log entry — what was actually done. Target a specific entry by id, or pass tid to hit the acting user's latest entry on that ticket (the one just closed by stop_handling, or the currently open one).

Parameters
NameTypeDescription
description
required · body
string What was done (max 500 chars).
id
optional · body
int Duration-log entry id. Takes precedence over tid.
tid
optional · body
int Ticket id — targets the acting user's latest entry on it. Required when id is omitted.
Permission

Any key (acting user must be a team member)

Request
// Describe the work just stopped on ticket 456
const response = await fetch('https://api.todo.work/api_integrations/tickets/set_duration_description', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({
    tid: 456,
    description: 'Fixed the webhook retries and added logging'
  })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": { "status": true, "id": 8317 } }

POST /tickets/edit_duration Correct a time entry

Sets the minutes of a closed treatment-log entry — and optionally its date and description. This is how a clock that ran longer (or shorter) than the work it stood for is brought to the right number after stop_handling. Target a specific entry by id, or pass tid to hit the acting user's latest entry on that ticket. A key may only correct entries of the user it acts as; an admin key may correct any entry.

Parameters
NameTypeDescription
duration
required · body
int Minutes the entry should say (0 or more).
id
optional · body
int Duration-log entry id. Takes precedence over tid.
tid
optional · body
int Ticket id — targets the acting user's latest entry on it. Required when id is omitted.
date
optional · body
string Move the entry to this datetime (your timezone). Untouched when omitted.
description
optional · body
string Replace the entry's description (max 500 chars). Untouched when omitted.
Permission

Any key (own entries; admin keys: any entry)

Request
// The clock ran 47 minutes, the work was 30
const response = await fetch('https://api.todo.work/api_integrations/tickets/edit_duration', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({
    tid: 456,
    duration: 30,
    description: 'Fixed the webhook retries and added logging'
  })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": { "status": true, "id": 8317, "tid": 456, "duration": 30 } }

Leads (webhook)

One request creates a lead, fills its contact fields and posts the incoming text as its first note — built to be dropped straight into a form / lead-ad / Zapier webhook field.

  • Field names are matched loosely and case-insensitively: name / full_name / first_name+last_name, phone / mobile / tel, message / note / body / description …
  • Select fields (source, status) accept the option NAME or its id. A value matching no option is reported in "warnings" instead of failing the call.
  • Anything the mapping did not consume (utm_*, landing page, extra form questions) is appended to the note, so a webhook never loses data. Send append_unmapped: false to drop it instead.
  • This endpoint also accepts its credentials in the body (api_key + api_secret) or as Authorization: Bearer key:secret — for senders that cannot set custom headers. Prefer the headers when you can.
  • If the key is bound to a non-admin user, send project_id (or handlers_uid) so that user can read the lead — otherwise the lead is created but the note is refused, and you get a warning saying so.

POST /add_lead Create a lead + note

Creates the lead (default lead status, automations fire), fills phone / email / contact name / company / source / status, then posts content as the first comment. Replaces the old tickets/add → filters/get_all → add_filter_to_ticket → comments/add_comment chain.

Parameters
NameTypeDescription
content
optional · body
string The note. Plain text is fine — line breaks are kept. Aliases: message, note, body, description…
subject
optional · body
string Board title. Defaults to the contact name / company / phone / email.
contact_name
optional · body
string Person’s name. Aliases: name, full_name, first_name + last_name.
phone
optional · body
string Aliases: mobile, tel, telephone, whatsapp…
email
optional · body
string Aliases: mail, email_address.
company
optional · body
string Aliases: company_name, organization, business.
source
optional · body
string Lead source — option name or id.
status
optional · body
string Lead status — option name or id. Defaults to the workspace default.
handlers_uid
optional · body
array[int] Assign to these users. Accepts [7], [{id:7}] or "7,12".
project_id
optional · body
int Optional — leads normally live outside projects.
scheduled_date
optional · body
string Follow-up datetime in your timezone.
fields
optional · body
object Any other custom field: { "<system_key | id | name>": value }.
append_unmapped
optional · body
bool Append unrecognised payload keys to the note. Default true.
Permission

Any key with leads.manage (admins always)

Notes
  • Requires the workspace to have lead statuses configured. If it does not, the call is refused with a message — open the Leads screen in the TODO app once to create the defaults, then retry.
Request
// Website form → lead + note, in one call
const response = await fetch('https://api.todo.work/api_integrations/add_lead', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({
    name: 'Israel Israeli',
    phone: '050-1234567',
    email: 'israel@example.com',
    company: 'Acme Ltd.',
    source: 'טופס אתר',
    message: 'Interested in the large package.\nBudget around 5,000.',
    utm_campaign: 'summer-2026'
  })
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "status": 200,
    "message": "Lead created",
    "response": {
      "lead_id": 76924,
      "subject": "Israel Israeli",
      "comment_id": 92933,
      "fields_set": {
        "lead_contact_name": "Israel Israeli",
        "lead_phone": "050-1234567",
        "lead_email": "israel@example.com",
        "lead_company": "Acme Ltd.",
        "lead_source": "549"
      },
      "warnings": [],
      "lead": { "id": 76924, "type": "lead", "subject": "Israel Israeli" }
    }
  }
}

Expenses & supplier invoices

The expenses module (הוצאות) for an external process: the rows of a period, what is still missing for the month, and — the useful part — filing a supplier invoice: the document is read by the same AI reader the screen uses, matched to the row of that month and attached, or opened as a new pending row.

  • Every call runs with the expense permissions of the user the key acts as: expenses.manage sees and edits everything, expenses.view sees everything, a budget member sees their budgets. A key whose user has none of these gets 403.
  • Amounts are returned as strings with two decimals ("64.07") so nothing is lost in JSON. Dates are YYYY-MM-DD.
  • file_document never invents data: a document it could not read an amount AND a date from is not turned into a row — the answer says needs_decision and what was read, and you decide.
  • Reading a document costs one AI credit of the workspace, like the screen upload does.

POST /expenses/results List expenses

The expense rows of a period, with supplier, status, paid flag and the attached documents. compact: true returns one short row per expense.

Parameters
NameTypeDescription
date_from
optional · body
string YYYY-MM-DD
date_to
optional · body
string YYYY-MM-DD
supplier_id
optional · body
int One supplier only.
status
optional · body
string pending | approved | rejected
payment_status
optional · body
string paid | not_paid
q
optional · body
string Free text (title, supplier, receipt number).
limit
optional · body
int Default 500, max 2000.
compact
optional · body
bool true = {id, title, amount, expense_date, supplier_id, supplier_name, status, is_paid, has_document, documents, receipt_number, recurring_expense_id} per row.
Permission

Any key whose user can view expenses

Request
// August rows, short form
const response = await fetch('https://api.todo.work/api_integrations/expenses/results', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({
    date_from: '2026-08-01',
    date_to: '2026-08-31',
    compact: true
  })
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "success": true,
    "data": [
      { "id": 2883, "title": "Open AI מנוי משרד", "amount": "64.07", "expense_date": "2026-08-13",
        "supplier_id": 4168, "supplier_name": "Open AI", "status": "approved", "is_paid": 0,
        "has_document": false, "documents": 0, "receipt_number": "", "recurring_expense_id": 904 }
    ]
  }
}

POST /expenses/gaps What is missing for a month

The 1st-of-month check: rows of the month without a document, active recurring templates that produced no row in it, and rows not marked paid — plus the workspace’s require_document setting.

Parameters
NameTypeDescription
month
optional · body
string YYYY-MM. Default: the current month.
Permission

Any key whose user can view expenses

Request
// Is August closed?
const response = await fetch('https://api.todo.work/api_integrations/expenses/gaps', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ month: '2026-08' })
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "month": "2026-08", "rows": 22, "total_amount": "32900.08", "require_document": false,
    "missing_document": [ { "id": 2700, "title": "GOOGLE WORKSPACE WIZZO", "amount": "215.00", "expense_date": "2026-08-01", "supplier_name": "GOOGLE WORKSPACE", "has_document": false } ],
    "templates_without_row": [ { "recurring_expense_id": 896, "title": "...", "amount": "215.00", "supplier_name": "...", "next_run_date": "2026-09-01" } ],
    "unpaid": [ ... ]
  }
}

POST /expenses/file_document File a supplier invoice

Send the document (base64). It is read (supplier, amount, date, receipt number), the supplier is matched by registration number or name, and then: a row of the same supplier, month and amount (also ex-VAT) without a document → the file is attached to it; the receipt number already filed → duplicate, nothing attached; a matching row that already has a document → needs_decision (call again with expense_id to attach anyway); no row → a new pending row is opened from the document, the supplier created when unknown (create: false to skip that step). expense_id set → attach straight to that row, no matching.

Parameters
NameTypeDescription
file_base64
required · body
string The file — a data URI or bare base64. pdf / jpg / png / gif / webp, up to 10MB.
storage_id
optional · body
string Instead of the file: the match.storage_id a needs_decision answer returned. The second call (with on_similar or expense_id) then decides without uploading the same file again.
file_name
required · body
string Original file name, the extension decides the type.
expense_id
optional · body
int Attach to this row and stop.
create
optional · body
bool Default true. false = when no row matches, answer no_match instead of opening a row.
on_similar
optional · body
string What to do when the month already has a matching row WITH a document. 'ask' (default) = answer needs_decision; 'create' = open a new row for this document anyway (a second charge of the same supplier and amount in one month); 'attach' = add it to that row anyway (a receipt of an invoice already filed).
Permission

A key whose user can add expenses (for a bot: the "expenses" scope must be open)

Request
// An invoice PDF that arrived by mail
const response = await fetch('https://api.todo.work/api_integrations/expenses/file_document', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({
    file_name: 'openai_invoice_august.pdf',
    file_base64: 'JVBERi0xLjQK...'
  })
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "success": true,
    "action": "attached",            // attached | created | duplicate | needs_decision | no_match | already_attached
    "expense_id": 2883,
    "match": {
      "storage_id": "f4c87776-...", "file_name": "openai_invoice_august.pdf",
      "extracted": { "title": "מנוי ChatGPT Plus", "amount": "64.07", "date": "2026-08-13", "supplier_name": "Open AI", "receipt_number": "A1B2C3D4-0008" },
      "supplier": { "id": 4168, "name": "Open AI" },
      "similar_expense": { "id": 2883, "amount": "64.07", "expense_date": "2026-08-13", "has_document": false }
    },
    "expense": { "id": 2883, "has_document": true, "documents": 1, "receipt_number": "A1B2C3D4-0008" }
  }
}

POST /expenses/attach_document Attach a stored file to a row

Attach a file that is already in storage (a storage_id from an earlier file_document answer) to an expense row.

Parameters
NameTypeDescription
id
required · body
int The expense row.
storage_id
required · body
string The file uuid.
Permission

A key whose user can add expenses

Request
// After a needs_decision answer
const response = await fetch('https://api.todo.work/api_integrations/expenses/attach_document', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ id: 2883, storage_id: 'f4c87776-...' })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": { "success": true, "action": "attached", "expense_id": 2883, "expense": { ... } } }

POST /expenses/remove_document Take a document off a row

Detach a document from an expense row — the screen's own delete. The file itself is deleted only when no other row or recurring template still holds it. save never touches documents; this and attach_document do.

Parameters
NameTypeDescription
id
required · body
int The expense row.
storage_id
required · body
string The file uuid — documents[].file_uuid of GET /expenses/get.
Permission

A key whose user can add expenses (the row must be editable by them)

Request
// A receipt filed on the wrong row
const response = await fetch('https://api.todo.work/api_integrations/expenses/remove_document', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ id: 3333, storage_id: '1fefd732-...' })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": { "success": true, "expense_id": 3333, "expense": { "id": 3333, "has_document": true, "documents": 2 } } }

POST /expenses/delete Delete a row

Send an expense row to the archive (is_deleted = 1) — the screen's own delete, under the acting user's delete permission. A paid or locked row is refused with the same message the screen shows.

Parameters
NameTypeDescription
id
required · body
int The expense row.
Permission

A key whose user can delete that row (their own, or expenses.manage)

Request
// A row opened by mistake
const response = await fetch('https://api.todo.work/api_integrations/expenses/delete', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ id: 3342 })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": { "success": true, "expense_id": 3342, "message": "ההוצאה נמחקה בהצלחה" } }

POST /expenses/find_similar Find the row of the month

The row of a supplier in the month of the date with an amount within 5% / 50 — the same matching file_document uses. Useful when the amount comes from a bank charge rather than a document.

Parameters
NameTypeDescription
supplier_id
required · body
int
amount
required · body
number
date
optional · body
string YYYY-MM-DD, default today.
Permission

Any key whose user can view expenses

Request
// A bank charge of 64.07 on Aug 13
const response = await fetch('https://api.todo.work/api_integrations/expenses/find_similar', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ supplier_id: 4168, amount: 64.07, date: '2026-08-13' })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": { "success": true, "data": { "id": 2883, "title": "Open AI מנוי משרד", "amount": "64.07", "has_document": false } } }

POST /expenses/save Create or update a row

Insert an expense row (status pending), or update one when id is set. Same rules as the screen: budget limits, the earliest allowed date, approvers.

Parameters
NameTypeDescription
title
required · body
string
amount
required · body
number
expense_date
required · body
string YYYY-MM-DD
supplier_id
optional · body
int
category_id
optional · body
int
budget_id
optional · body
int
receipt_number
optional · body
string
description
optional · body
string
id
optional · body
int Set = update that row.
temp_storage_ids
optional · body
array[string] Storage uuids to attach.
Permission

A key whose user can add expenses (edit: their own rows, or expenses.manage)

Request
// A row typed by hand
const response = await fetch('https://api.todo.work/api_integrations/expenses/save', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({
    title: 'Hetzner — servers, August',
    amount: 1531.5,
    expense_date: '2026-08-31',
    supplier_id: 4171
  })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": { "success": true, "data": 2910 } }   // data = the expense id

POST /expenses/mark_as_paid Mark paid / unpaid

Flip the paid flag of a row; the change is logged on the row.

Parameters
NameTypeDescription
id
required · body
int
is_paid
optional · body
bool Default true.
Permission

expenses.manage

Request
// Paid
const response = await fetch('https://api.todo.work/api_integrations/expenses/mark_as_paid', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ id: 2883, is_paid: true })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": { "success": true } }

POST /expenses/suppliers_search Suppliers · search / quick create

suppliers_search {q, limit} lists suppliers by name; supplier_quick_create {name, business_number?, contact_email?, contact_phone?} adds one (returns the existing id when the name already exists).

Parameters
NameTypeDescription
q
optional · body
string Name fragment.
limit
optional · body
int Default 20.
Permission

Any key whose user can view expenses (create: can add expenses)

Request
// Who is "cursor"?
const response = await fetch('https://api.todo.work/api_integrations/expenses/suppliers_search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ q: 'cursor' })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": { "success": true, "data": [ { "id": 4182, "name": "cursor", "business_number": "" } ] } }

POST /expenses/recurring_expenses_results Recurring templates

The recurring-expense templates (what is expected every month), with interval, next run date and supplier.

Parameters
NameTypeDescription
q
optional · body
string
status
optional · body
string active | paused
Permission

Any key whose user can view expenses

Request
// The active templates
const response = await fetch('https://api.todo.work/api_integrations/expenses/recurring_expenses_results', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ status: 'active' })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": { "success": true, "data": [ { "id": 904, "title": "Open AI מנוי משרד", "amount": "64.07", "supplier_id": 4168, "next_run_date": "2026-09-13" } ] } }

POST /expenses/export_documents_zip ZIP of the period’s documents

The same ZIP the reports screen downloads: every attached document of the rows in the filter, named date_title_file.ext. Returns a download URL.

Parameters
NameTypeDescription
date_from
optional · body
string YYYY-MM-DD
date_to
optional · body
string YYYY-MM-DD
supplier_id
optional · body
int
expense_ids
optional · body
array[int] Only these rows (other filters ignored).
download_mode
optional · body
string all (default) | main_only — skip files held in rule fields.
Permission

Any key whose user can view expenses

Request
// July + August for the bookkeeper
const response = await fetch('https://api.todo.work/api_integrations/expenses/export_documents_zip', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ date_from: '2026-07-01', date_to: '2026-08-31' })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": { "success": true, "download_url": "https://api.todo.work/media/System/temp/expenses_zip/expenses_documents_....zip", "filename": "...", "file_count": 41, "expenses_count": 44 } }

Calendar meetings

The meetings of the TODO calendar (פגישות ביומן): list them, read one, create, move, change and cancel them, see who can be invited and when everyone is free. The same code as the app's "פגישה חדשה" form: the same organizer rule, the same TALK room, the same reminders and the same invites.

  • The user the key acts as is the ORGANIZER of every meeting it creates, and only the organizer may update or delete a meeting (403 otherwise).
  • Notifications are exactly the app form's: every user attendee gets a bell notification and a push, every attendee with an address gets an email with an ICS invite (Google Calendar and Outlook add it), and the invite carries the TALK join link. A meeting with no attendees notifies nobody; only the organizer's own reminders apply.
  • Times are ISO 8601. start_at / end_at come back with the offset (2026-10-14T10:00:00+03:00). A time sent without an offset is read in the company's timezone (Israel time for an Israeli workspace); a time with an offset or Z is converted.
  • "me" is accepted wherever a user id is (attendees_uid, attendee_uid, user_ids).
  • Meetings carry no project or client: project_id / client_id are ignored and the answer says so in warnings.
  • delete is the app's delete: the meeting is cancelled (status cancelled) and every attendee gets the cancellation by the same channels.
  • The same actions are the "events" tool of the MCP endpoint, with {action, params}.

POST /events/results List meetings

The meetings of a date range that the user may see in the app calendar (the workspace's meetings, and the private ones they take part in). Cancelled meetings are left out.

Parameters
NameTypeDescription
date_from
optional · body
string YYYY-MM-DD. Default: today.
date_to
optional · body
string YYYY-MM-DD. Default: date_from + 7 days (the coming week). At most 62 days.
attendee_uid
optional · body
int | "me" | array Only meetings this user organizes or attends.
q
optional · body
string Text in the subject, description or place.
limit
optional · body
int Default 200, max 500.
Permission

Any key

Request
// My meetings this week
const response = await fetch('https://api.todo.work/api_integrations/events/results', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ attendee_uid: 'me' })
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "date_from": "2026-10-13", "date_to": "2026-10-20", "timezone": "Asia/Jerusalem", "count": 1,
    "events": [
      { "id": 812, "subject": "סקירת ספרינט", "start_at": "2026-10-14T10:00:00+03:00", "end_at": "2026-10-14T10:30:00+03:00",
        "all_day": false, "date": "2026-10-14", "when_text": "יום ד' 14.10.2026 · 10:00-10:30",
        "description": "", "location": "", "organizer": { "user_id": 7, "name": "..." }, "is_organizer": true,
        "my_rsvp": "accepted", "attendees": [ { "user_id": 12, "email": "", "name": "...", "rsvp": "needs_action" } ],
        "visibility": "platform", "join_url": "https://app.todo.work/call/..." }
    ]
  }
}

POST /events/get Get a meeting

One meeting with its status (confirmed | cancelled), attendees and their answers, reminders and join link.

Parameters
NameTypeDescription
id
required · body
int Meeting id.
Permission

Any key that may see the meeting

Request
// Read meeting 812
const response = await fetch('https://api.todo.work/api_integrations/events/get', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ id: 812 })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": { "id": 812, "subject": "סקירת ספרינט", "start_at": "2026-10-14T10:00:00+03:00", "end_at": "2026-10-14T10:30:00+03:00", "status": "confirmed", "attendees": [ ... ], "reminders": [ { "channel": "app", "min_before": 10 }, { "channel": "email", "min_before": 1440 } ], "join_url": "..." } }

POST /events/add Create a meeting

Creates the meeting with the key's user as organizer, opens its TALK room and invites the attendees exactly as the app form does.

Parameters
NameTypeDescription
subject
required · body
string The meeting title.
start_at
required · body
string ISO date-time: 2026-10-14T10:00 (company time) or 2026-10-14T10:00:00+03:00.
end_at
optional · body
string ISO date-time, 5 minutes to 24 hours after start_at. Or duration_min. Default: 30 minutes.
duration_min
optional · body
int Instead of end_at, 5 to 1440.
description
optional · body
string
location
optional · body
string A place, shown under the title and in the invite.
attendees_uid
optional · body
array[int] | string Users of the workspace (ids, "me", or "12,15"). See invitees. Empty = nobody is notified.
attendee_emails
optional · body
array People outside the workspace: addresses, or [{email, name}]. They get the email invite with the ICS.
reminder
optional · body
int | array | "none" Omitted = the app's defaults (in the app 10 minutes before, email 1 day before). 0 or "none" = none. Minutes before, a list of minutes, or [{channel: "app" | "email", min_before}].
visibility
optional · body
string platform (default, the workspace sees it) | busy (only participants see the details).
with_room
optional · body
bool Default true: a TALK room and its join link.
request_id
optional · body
string Up to 36 characters. The same request_id twice returns the first meeting instead of creating a second one.
Permission

Any key

Request
// A half-hour meeting tomorrow at 10:00
const response = await fetch('https://api.todo.work/api_integrations/events/add', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({
    subject: 'סקירת ספרינט',
    start_at: '2026-10-14T10:00',
    end_at: '2026-10-14T10:30',
    attendees_uid: [12, 15]
  })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": { "id": 812, "subject": "סקירת ספרינט", "start_at": "2026-10-14T10:00:00+03:00", "end_at": "2026-10-14T10:30:00+03:00", "status": "confirmed", "join_url": "...", "attendees": [ ... ], "created": true, "notified": "the attendees were invited exactly as from the app form ..." } }

POST /events/update Update a meeting

Changes one field (field + value) or several (the fields themselves). A new time, place, subject or attendee list sends the attendees the update, as the app does.

Parameters
NameTypeDescription
id
required · body
int Meeting id.
field
optional · body
string subject | description | location | start_at | end_at | duration_min | attendees_uid | attendee_emails | reminder | visibility
value
optional · body
any The new value of field.
start_at
optional · body
string A new start; the length stays.
end_at
optional · body
string A new end; the start stays.
attendees_uid
optional · body
array[int] REPLACES the user attendees (the outside addresses stay unless attendee_emails is sent too). A removed attendee gets a cancellation.
Permission

The organizer only

Request
// Move meeting 812 to 11:00
const response = await fetch('https://api.todo.work/api_integrations/events/update', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ id: 812, field: 'start_at', value: '2026-10-14T11:00' })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": { "id": 812, "start_at": "2026-10-14T11:00:00+03:00", "end_at": "2026-10-14T11:30:00+03:00", "updated": true, ... } }

POST /events/delete Cancel a meeting

The app's delete: the meeting is cancelled and every attendee gets the cancellation (app and email).

Parameters
NameTypeDescription
id
required · body
int Meeting id.
Permission

The organizer only

Request
// Cancel meeting 812
const response = await fetch('https://api.todo.work/api_integrations/events/delete', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ id: 812 })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": { "success": true, "id": 812, "status": "cancelled", "already_cancelled": false, "attendees_notified": 2 } }

POST /events/invitees Who can be invited

Every active user of the workspace a meeting can invite (team members and client users), with their email.

Parameters
NameTypeDescription
q
optional · body
string Text in the name or email.
Permission

Any key

Request
// Find Dana
const response = await fetch('https://api.todo.work/api_integrations/events/invitees', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ q: 'dana' })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": { "count": 1, "users": [ { "user_id": 12, "name": "Dana", "email": "dana@example.com", "is_team": true } ] } }

POST /events/free_slots When everyone is free

For each day, the windows of at least duration_min in which ALL the given users are free, and each one's busy ranges. Busy counts meetings, appointment bookings, their synced Google Calendar and reported absences; nothing earlier than now is offered.

Parameters
NameTypeDescription
user_ids
required · body
array[int] | string Up to 30 users; "me" for yourself.
date_from
optional · body
string YYYY-MM-DD. Default: today.
date_to
optional · body
string YYYY-MM-DD. Default: date_from. Up to 14 days.
duration_min
optional · body
int Default 30.
day_start
optional · body
string HH:MM, default 08:00.
day_end
optional · body
string HH:MM, default 20:00.
exclude_event_id
optional · body
int A meeting being moved: its own time is not counted as busy.
Permission

Any key

Request
// An hour with Dana this week
const response = await fetch('https://api.todo.work/api_integrations/events/free_slots', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ user_ids: ['me', 12], date_to: '2026-10-17', duration_min: 60 })
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "duration_min": 60, "day_start": "08:00", "day_end": "20:00", "timezone": "Asia/Jerusalem",
    "days": [
      { "date": "2026-10-14", "weekday": "Wednesday",
        "free": [ { "start": "08:00", "end": "10:00", "start_at": "2026-10-14T08:00:00+03:00", "end_at": "2026-10-14T10:00:00+03:00" } ],
        "busy": { "7": [ ["10:00", "10:30"] ], "12": [] } }
    ]
  }
}

Custom Fields

Read your platform’s custom field definitions, then set their values on tickets through the ticket update endpoint.

  • Read current values from a ticket via /tickets/get (the custom_filters map).
  • Always look up the field id and type from /filters/get_all before writing.
  • A key that acts as a workspace admin can also create and update the field definitions themselves with /filters/save.

GET /filters/get_all List custom field definitions

Every custom field on the platform with its id, type and (for select fields) its option values.

Parameters
NameTypeDescription
target
optional · query
enum task (default) | lead | expense. Note: expense currently returns 0 fields.
project_id
optional · query
int Restrict to fields available on this project.
Permission

Any key

Notes
  • Select fields return their options twice: values as full objects, and selectValues as { key, val } pairs. They carry the same options in two shapes.
  • On user_approval fields the selectValues key is a state string such as "idle", not an option id.
Request
// List custom field definitions
const response = await fetch('https://api.todo.work/api_integrations/filters/get_all', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  }
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": [
    {
      "id": 42,
      "name": "Status",
      "type": "select",
      "values": [
        { "id": 101, "name": "Open" },
        { "id": 102, "name": "In progress" },
        { "id": 103, "name": "Done" }
      ],
      "selectValues": [
        { "key": "101", "val": "Open" },
        { "key": "102", "val": "In progress" }
      ]
    },
    { "id": 43, "name": "Due date", "type": "date" },
    { "id": 44, "name": "Notes", "type": "free_text" }
  ]
}

POST /filters/save Create or update a custom field

Creates a custom field, or updates the one named by id. Nothing is ever deleted here: on an update the options you send are added to the options the field already has.

Parameters
NameTypeDescription
id
optional · body
int The field to update. Omit it to create a new field.
name
optional · body
string The label of the field. Required when creating.
type
optional · body
enum Required when creating, cannot be changed later: dropdown (a list of options) | free_text | rich_text | link | date | time | switch | users_list | user_approval | duration | duration_limit | scheduled_date | date_created | date_updated | task_creator.
values
optional · body
array The options of a dropdown field (required when creating one): names, or objects { name, color?, id? }. On an update they are added to the existing options; an id renames or recolours that option.
applies_to
optional · body
array[enum] task | lead | expense. Default: ["task"].
project_ids
optional · body
array[int] Show the field only in these projects. Omitted or empty: every project.
exclude_project_ids
optional · body
array[int] Projects a global field is hidden from.
is_global
optional · body
bool true returns a project-specific field to every project.
placeholder
optional · body
string Hint text of a text or link field.
show_table
optional · body
bool A column in the tasks table. Default true.
show_ticket
optional · body
bool Shown inside the task. Default true.
show_search
optional · body
bool Offered in the search filters. Default true.
show_subtasks
optional · body
bool Also shown on subtasks. Default false.
allow_duplicate
optional · body
bool Create the field even though one with the same name exists (refused otherwise).
Permission

Key of a workspace admin

Notes
  • The type of an existing field cannot be changed: the values tasks already hold are stored for that type.
  • Deleting a field or one of its options is done in the fields screen of the app, not through the API.
  • To set the new field on a ticket use /tickets/update with field: "custom_field"; a dropdown field takes the option id from filter.values.
  • A dropdown is stored and returned as type "select"; send "dropdown" when creating one.
Request
// Create a dropdown field that shows in one project
const response = await fetch('https://api.todo.work/api_integrations/filters/save', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({
    name: 'Region',
    type: 'dropdown',
    values: ['North', 'Center', 'South'],
    project_ids: [123]
  })
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "id": 57,
    "created": true,
    "filter": {
      "id": 57,
      "name": "Region",
      "type": "select",
      "is_global": false,
      "project_ids_array": [123],
      "values": [
        { "id": 301, "name": "North", "color": "#59CE8F" },
        { "id": 302, "name": "Center", "color": "#3498db" },
        { "id": 303, "name": "South", "color": "#f0c419" }
      ]
    }
  }
}

POST /filters/add_to_project Show a custom field in a project

Makes an existing field show in one more project. The reverse is /filters/exclude_from_project with the same parameters: the field stops showing in that project, and the values tasks hold stay.

Parameters
NameTypeDescription
filter_id
required · body
int The field id from /filters/get_all.
project_id
required · body
int The project.
Permission

Key of a workspace admin

Request
// Show field 57 in a project
const response = await fetch('https://api.todo.work/api_integrations/filters/add_to_project', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({
    filter_id: 57,
    project_id: 123
  })
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": { "id": 57, "project_id": 123, "filter": { "id": 57, "name": "Region", "type": "select" } }
}

POST /tickets/update Set a custom field on a ticket

Validated write: stores the value, logs it, and fires automation. The value format depends on the field type.

Parameters
NameTypeDescription
id
required · body
int Ticket id.
field
required · body
string Must be the literal "custom_field".
custom_field_id
required · body
int The field id from /filters/get_all.
value
required · body
mixed Per type (see below). null clears the value.
Permission

Any key (edit access to the ticket)

Request
// Each field type takes its own value format.
// Use field: 'custom_field' and custom_field_id to target the field.

// SELECT — value is the option id
await fetch('https://api.todo.work/api_integrations/tickets/update', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ id: 456, field: 'custom_field', custom_field_id: 42, value: 101 })
});

// DATE — value is 'YYYY-MM-DD'
await fetch('https://api.todo.work/api_integrations/tickets/update', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ id: 456, field: 'custom_field', custom_field_id: 43, value: '2026-03-15' })
});

// TEXT / FREE_TEXT — value is any string
await fetch('https://api.todo.work/api_integrations/tickets/update', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ id: 456, field: 'custom_field', custom_field_id: 44, value: 'Any text' })
});

// USERS_LIST — value is an array of user ids
await fetch('https://api.todo.work/api_integrations/tickets/update', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ id: 456, field: 'custom_field', custom_field_id: 45, value: [1, 2, 3] })
});

// USER_APPROVAL — value is 'idle' | 'pending' | 'approved' | 'rejected'
await fetch('https://api.todo.work/api_integrations/tickets/update', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ id: 456, field: 'custom_field', custom_field_id: 46, value: 'approved' })
});

// SWITCH — value is '1' (on) or '0' (off)
await fetch('https://api.todo.work/api_integrations/tickets/update', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ id: 456, field: 'custom_field', custom_field_id: 47, value: '1' })
});

console.log('Custom field examples — copy and adapt as needed');
Response
{
  "response": {
    "status": "success",
    "ticket": { "id": 456, "custom_filters": { "42": "101" } }
  }
}

Clients

Read the clients and projects the key can access.

GET /get_clients List clients

Flat array of the clients this key can see. Despite the endpoint name it returns clients only — there is no companion projects array and no full_name field. Use /projects/results for projects.

Parameters

No parameters — send the authentication headers only.

Permission

Any key (respects the acting user’s access)

Request
// List clients
const response = await fetch('https://api.todo.work/api_integrations/get_clients', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  }
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": [
    { "id": 5, "name": "Acme Inc.", "phone": "03-1234567", "email": "hi@acme.com" }
  ]
}

Comments

Add or edit comments on tickets and expenses, with @mentions and replies.

POST /comments/add_comment Add or edit a comment

Creates a comment (or edits one when comment_id is sent). Supports @mentions, nested replies and file attachments. Send visibility: "internal" for a staff-only internal note: clients and external users never see it (not in the thread, not in search, not in notifications or Ask Todo). Only a staff key (type user, or an admin) may write one; a client key gets internal_not_allowed. audience narrows who on the staff side sees it: staff (default), handlers (the task handlers, the managers above them, and admins) or admins. A reply always inherits its parent’s visibility and audience, and an edit never changes them.

Parameters
NameTypeDescription
tid
required · body
int Ticket (or expense) id.
content
required · body
string HTML text (a safe tag subset is allowed). May be empty when blocks are sent: the plain-text fallback is then derived from them.
blocks
optional · body
array Structured content rendered under the text: the SAME block schema as Chat → "Send a structured message" (header, text, facts, table, callout, chart, divider, context, actions). Prefer it over HTML tables. Stored canonically; an invalid payload is rejected with the reason.
object_type
optional · body
enum ticket (default) | expense.
mentions
optional · body
string Comma-separated user ids, e.g. "5,12".
reply_to
optional · body
int Parent comment id for a reply. The reply inherits the parent’s visibility.
visibility
optional · body
enum public (default) | internal. internal = staff-only note, hidden from client/external users. Staff keys only; ignored on edits.
audience
optional · body
enum Internal notes only. staff (default) = everyone on the team; handlers = the task handlers, the managers above them in the org tree, and admins; admins = system admins only. A reply inherits it; ignored on edits.
comment_id
optional · body
int Send to edit an existing comment.
Permission

Any key (access to the ticket/expense; edits are author or admin only)

Request
// Comment on ticket 456 and mention two users
const response = await fetch('https://api.todo.work/api_integrations/comments/add_comment', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({
    tid: 456,
    object_type: 'ticket',
    content: '<p>Fixed the alignment.</p>',
    mentions: '5,12',
    reply_to: 0
  })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": { "success": true, "comment_id": 4567 } }

Users & Team

List platform users and find the senior members of a project.

  • A non-admin key only sees users at its own permission level and below — it can never obtain an admin’s token.
  • The returned token is scoped to this integrations API and expires after 48 hours. It is not an app session token and will not authenticate anywhere else — re-fetch it when it expires rather than storing it long-term.

GET /whoami Who am I

The user this key acts as. Every other endpoint is already scoped to that user, but nothing else tells you who it is — call this before anything phrased as “me”/“my”. Wherever a user id is expected you may also pass the literal string "me".

Parameters

No parameters — send the authentication headers only.

Permission

Any key

Notes
  • core_id is the same person across every workspace, while user_id is only valid inside this one. You need it to receive incoming calls: the push channel is core_user:<core_id>. Bots have no core row, so theirs is 0.
Request
// The identity this key acts as
const response = await fetch('https://api.todo.work/api_integrations/whoami', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  }
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "status": 200,
    "message": "OK",
    "response": {
      "user_id": 7,
      "core_id": 794,
      "display_name": "Dana",
      "type": "user",
      "permissions": 2,
      "is_admin": false,
      "platform": { "id": 4, "name": "Wizzo", "domain": "wizzo.todo.work" },
      "timezone": "Asia/Jerusalem"
    }
  }
}

GET /get_users List users

All active platform users. Each carries a freshly-minted token, scoped to this API and valid for 48 hours — use it as a User-Token header on later requests (if the key permits).

Parameters

No parameters — send the authentication headers only.

Permission

Any key (results filtered by the key’s permission level)

Request
// List platform users
const response = await fetch('https://api.todo.work/api_integrations/get_users', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  }
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "status": 200,
    "message": "Users fetched successfully",
    "response": [
      { "id": 7, "display_name": "Dana", "type": "user", "is_me": true, "token": "…" }
    ]
  }
}

GET /get_project_senior_members Get project senior members

The highest-permission team members on a project (up to 5), for @-mentioning senior staff. Falls back to platform admins.

Parameters
NameTypeDescription
project_id
required · query
int Project id.
exclude_user_id
optional · query
int A user to leave out (e.g. yourself).
Permission

Any key

Request
// Senior members of project 123
const response = await fetch('https://api.todo.work/api_integrations/get_project_senior_members?project_id=123&exclude_user_id=7', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  }
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "status": 200,
    "message": "Senior members fetched successfully",
    "response": [
      { "id": 3, "display_name": "Denis", "permission": 1, "pic_parsed": "https://…" }
    ]
  }
}

Files & Briefs

Attach a brief (text + reference/material files) to a project, and add users to it.

  • These endpoints use multipart/form-data — do not set Content-Type, let the browser set the boundary.

POST /add_files Add a brief & files to a project

Creates a project brief: a description plus image rows for each reference and material file.

Parameters
NameTypeDescription
project_id
required · formdata
int Target project.
description
required · formdata
string Brief text.
reference_files[]
optional · formdata
file[] Reference images.
material_files[]
optional · formdata
file[] Working-material files.
Permission

Any key (scoped to the platform)

Request
// Add a brief to a project (multipart/form-data — no Content-Type header)
const formData = new FormData();
formData.append('project_id', 123);
formData.append('description', 'Brief description');
// formData.append('reference_files[]', file1);
// formData.append('material_files[]', file2);

const response = await fetch('https://api.todo.work/api_integrations/add_files', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: formData
});

const data = await response.json();
console.log(data.response);
Response
{ "response": true }

POST /attach_users Attach a user to a project

Prefixes the project name with its id and (optionally) attaches a user as a viewer.

Parameters
NameTypeDescription
project_id
required · body
int Target project.
user_id
optional · body
int User to attach (omit to only rename).
rename
optional · body
bool Default true. Send false to attach the user without touching the project name.
Permission

Any key (scoped to the platform)

Notes
  • The rename writes the project name as "<id> - <name>". It is applied at most once — calling repeatedly no longer stacks the prefix.
  • Send rename: false if you only want to attach the user.
Request
// Attach user 7 to project 123
const response = await fetch('https://api.todo.work/api_integrations/attach_users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ project_id: 123, user_id: 7 })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": true }

Chat

Conversations, group management and messaging. Access is scoped to the conversations you participate in.

GET /chat/get_conversations List conversations

The acting user’s conversations, pinned-first then most recent, with participants and last message.

Parameters
NameTypeDescription
limit
optional · query
int Default 50.
offset
optional · query
int Default 0.
Permission

Any key

Request
// List conversations
const response = await fetch('https://api.todo.work/api_integrations/chat/get_conversations?limit=50&offset=0', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  }
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "status": true,
    "conversations": [
      { "id": 5, "type": "private", "name": "Dana", "unread_count": 2, "last_message": { } }
    ],
    "has_more": false
  }
}

GET /chat/get_messages Get messages

Messages in a conversation, in chronological order, paginated with a before_id cursor.

Parameters
NameTypeDescription
conversation_id
required · query
int Conversation id.
before_id
optional · query
int Cursor: fetch messages older than this id.
limit
optional · query
int Default 50.
Permission

Any key (participant)

Request
// Get the latest messages of conversation 5
const response = await fetch('https://api.todo.work/api_integrations/chat/get_messages?conversation_id=5&limit=50', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  }
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "status": true,
    "messages": [
      { "id": 900, "content": "Hi!", "message_type": "text", "sender": { "id": 7, "display_name": "Dana" } }
    ],
    "has_more": true
  }
}

GET /chat/get_visible_users List who you can message

Users the acting user can start a 1:1 chat with, with an optional name search.

Parameters
NameTypeDescription
search
optional · query
string Case-insensitive match on display name.
limit
optional · query
int Default 50.
Permission

Any key

Request
// List users you can chat with
const response = await fetch('https://api.todo.work/api_integrations/chat/get_visible_users?limit=50', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  }
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "status": true,
    "users": [ { "id": 7, "display_name": "Dana", "type": "user" } ]
  }
}

POST /chat/get_or_create_private Open a 1:1 conversation

Gets the existing private conversation with a user, or creates it.

Parameters
NameTypeDescription
user_id
required · body
int The other user (must be visible to you).
Permission

Any key

Request
// Open a chat with user 7
const response = await fetch('https://api.todo.work/api_integrations/chat/get_or_create_private', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ user_id: 7 })
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": { "status": true, "conversation": { "id": 5, "type": "private" }, "created": false }
}

POST /chat/create_group Create a group

Creates a group; you become its admin. Unreachable participants are skipped.

Parameters
NameTypeDescription
name
required · body
string Group name.
participants
optional · body
array[int] User ids to add.
image
optional · body
string Storage id of a group image.
Permission

Any key

Request
// Create a group with three members
const response = await fetch('https://api.todo.work/api_integrations/chat/create_group', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({
    name: 'New project',
    participants: [5, 12, 18]
  })
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "status": true,
    "conversation": { "id": 200, "type": "group", "name": "New project", "my_role": "admin" }
  }
}

POST /chat/send_message Send a message

Sends a text message. Supports @[Name](userId) and #[Title](ticketId) mentions; URLs auto-expand into link/ticket cards. For structured content (numbers, lists, tables) pass `blocks` — see "Send a structured message" below.

Parameters
NameTypeDescription
conversation_id
required · body
int Target conversation.
content
required · body
string Message text (mention syntax supported). With `blocks`, this is the plain-text fallback.
blocks
optional · body
array Structured message blocks (schema below). When present the message is stored as message_type "blocks".
reply_to_id
optional · body
int Message being replied to.
temp_id
optional · body
string Client id echoed back for optimistic UI.
Permission

Any key (participant)

Request
// Send a message with a mention
const response = await fetch('https://api.todo.work/api_integrations/chat/send_message', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({
    conversation_id: 5,
    content: 'Hi @[Dana](7), see #[Ticket](456)',
    temp_id: 'client_123'
  })
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "status": true,
    "message": { "id": 901, "content": "Hi @Dana, see #Ticket", "message_type": "text" }
  }
}

POST /chat/send_message Send a structured message

The same endpoint with a `blocks` array: the message is rendered as real UI (headline, key figures, table, callout, chart, buttons) instead of a wall of text. The very same `blocks` schema is accepted by /comments/add_comment (rendered under the comment text) — one parser, one renderer, everywhere long structured text appears. Alternative for LLM-driven senders: end `content` with a ```blocks fence holding the same JSON array; the API extracts and validates it server-side (chat and comments alike), and the remaining text becomes the fallback. An invalid fence is left as plain text. This follows the convention of Slack Block Kit / Teams Adaptive Cards: a JSON array of semantic blocks plus an independent plain-text fallback (`content`) shown in push notifications, previews and older clients. Block types: header {text} · text {text, supports **bold**, *italic*, `code`} · facts {items:[{label, value, tone?}]} (up to 12) · table {columns:[{label, kind?: "number"|"date", align?}], rows:[[cell, ...]], footer?} (up to 100 rows × 8 columns; a "number" column is end-aligned and coloured by sign, so pass "+1,200 ₪" / "-350 ₪") · callout {tone, title?, text} · chart {kind: "line"|"bar", title?, points:[{x, y}], markers?:[{y, label, tone?}], unit?} · divider {} · context {text} · actions {items:[{label, kind: "url"|"reply", url?, value?}]} (up to 4; url must be http/https; "reply" sends `value` back to the conversation as the reader). gallery {title?, items:[{file|url, label, kind?: "desktop"|"mobile", caption?}]} (up to 12) — screens shown as a presentation: a card per screen, click opens a full-width viewer that scrolls the page, toggles desktop/mobile and moves between screens; `file` names a file attached to the same comment/message, items sharing a `label` are one screen on two devices. tone is neutral | success | warning | danger. Up to 50 blocks, 60 KB. Unknown keys are dropped; an invalid payload is rejected with the exact reason in `error`.

Parameters
NameTypeDescription
conversation_id
required · body
int Target conversation.
content
optional · body
string Plain-text fallback. Write it yourself (a short summary); if omitted it is derived from the blocks.
blocks
required · body
array Array of block objects, each with a `type` (see description).
reply_to_id
optional · body
int Message being replied to.
Permission

Any key (participant)

Request
// Send a cash-flow update as blocks
const response = await fetch('https://api.todo.work/api_integrations/chat/send_message', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({
    conversation_id: 5,
    content: 'Cash-flow update: balance 2,998 ₪, forecast low -30,070 ₪ on 09/10, collect at least 50,070 ₪.',
    blocks: [
      { type: 'header', text: 'Cash-flow update, next 30 days' },
      { type: 'text', text: 'One decision is needed **before 09/10**.' },
      { type: 'facts', items: [
        { label: 'Balance', value: '2,998 ₪' },
        { label: 'Forecast low', value: '-30,070 ₪', tone: 'danger' },
        { label: 'To collect', value: '50,070 ₪', tone: 'success' }
      ]},
      { type: 'table',
        columns: [{ label: 'Date', kind: 'date' }, { label: 'Movement' }, { label: 'Amount', kind: 'number' }],
        rows: [
          ['10/09/2026', 'Payme Ltd', '+33,988 ₪'],
          ['15/09/2026', 'Diners 7704', '-25,207 ₪'],
          ['09/10/2026', 'Payroll 09/2026 (4 people)', '-67,798 ₪']
        ],
        footer: '3 movements in the forecast' },
      { type: 'chart', kind: 'line', title: 'Balance', unit: '₪',
        points: [{ x: '09/09', y: 2998 }, { x: '10/09', y: 36986 }, { x: '15/09', y: 11779 }, { x: '09/10', y: -56019 }],
        markers: [{ y: 20000, label: 'Alert floor' }] },
      { type: 'callout', tone: 'danger', title: 'Forecast low', text: '-30,070 ₪ on 09/10/2026, below the 20,000 ₪ floor.' },
      { type: 'context', text: 'Source: checking account, as of 09/09/2026.' },
      { type: 'actions', items: [
        { label: 'Open full report', kind: 'url', url: 'https://app.todo.work/reports' },
        { label: 'Ask Sara', kind: 'reply', value: 'What should I collect first?' }
      ]}
    ]
  })
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "status": true,
    "message": {
      "id": 902,
      "message_type": "blocks",
      "content": "Cash-flow update: balance 2,998 ₪, ...",
      "widget_data": { "blocks": [ { "type": "header", "text": "Cash-flow update, next 30 days" }, "..." ] }
    }
  }
}

// Validation failure (HTTP 200, status false):
{ "response": { "status": false, "error": "blocks: block #3 (table): rows is required" } }

POST /chat/mark_read Mark a conversation read

Marks every message in a conversation as read and resets the unread count.

Parameters
NameTypeDescription
conversation_id
required · body
int Conversation id.
Permission

Any key (participant)

Request
// Mark conversation 5 read
const response = await fetch('https://api.todo.work/api_integrations/chat/mark_read', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ conversation_id: 5 })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": { "status": true } }

Kanban

Build and maintain boards: lists (columns) and the ticket cards on them.

POST /kanban/boards List boards

Boards owned by or shared with the acting user, most recently updated first.

Parameters
NameTypeDescription
id
optional · body
int A specific board id.
limit
optional · body
int Default 50.
page
optional · body
int 0-indexed; page 0 includes the total count.
Permission

Any key

Request
// List my boards
const response = await fetch('https://api.todo.work/api_integrations/kanban/boards', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ limit: 10, page: 0 })
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "items": [ { "id": 42, "name": "Daily — Dana", "color": "#59ce8f", "users": [] } ],
    "num": 1
  }
}

POST /kanban/lists List columns

The lists (columns) of a board, in order.

Parameters
NameTypeDescription
kanban_id
required · body
int Board id.
limit
optional · body
int Default 50.
page
optional · body
int 0-indexed.
Permission

Any key (board access)

Request
// List the columns of board 42
const response = await fetch('https://api.todo.work/api_integrations/kanban/lists', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ kanban_id: 42, page: 0 })
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "items": [ { "id": 101, "kanban_id": 42, "name": "To do", "ord": 0, "tickets": [] } ],
    "num": 1
  }
}

POST /kanban/get_tickets Get board cards

Every active ticket card on a board, with its list and order.

Parameters
NameTypeDescription
kanban_id
required · body
int Board id.
Permission

Any key (board access)

Request
// Get the cards on board 42
const response = await fetch('https://api.todo.work/api_integrations/kanban/get_tickets', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ kanban_id: 42 })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": [ { "id": 789, "list_id": 101, "ord": 0, "project_id": 5 } ] }

POST /kanban/add_board Create a board

Creates a board (you are added as a participant); optionally shares it with another user.

Parameters
NameTypeDescription
name
required · body
string Board name.
share_user_id
optional · body
int Share the board with this user.
Permission

Any key

Request
// Create a shared board
const response = await fetch('https://api.todo.work/api_integrations/kanban/add_board', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ name: 'Daily — Dana', share_user_id: 7 })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": { "board": { "id": 43, "name": "Daily — Dana" } } }

POST /kanban/add_list Add or update a column

Creates a list (column), or updates it when id is sent.

Parameters
NameTypeDescription
kanban_id
required · body
int Board id.
name
required · body
string List name.
id
optional · body
int Send to update an existing list.
project_id
optional · body
int Link the column to a project (auto-populated).
Permission

Any key (board access)

Request
// Add a column to board 42
const response = await fetch('https://api.todo.work/api_integrations/kanban/add_list', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ kanban_id: 42, name: 'June 27 — Thursday' })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": { "list": { "id": 102, "kanban_id": 42, "name": "June 27 — Thursday" } } }

POST /kanban/move_ticket Place a card

Places or moves a ticket card onto a list.

Parameters
NameTypeDescription
ticket_id
required · body
int Ticket id.
list_id
required · body
int Target list id.
Permission

Any key (board access)

Request
// Move a card onto a list
const response = await fetch('https://api.todo.work/api_integrations/kanban/move_ticket', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ ticket_id: 789, list_id: 102 })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": true }

POST /kanban/remove_ticket Remove a card

Removes a ticket card from a list (the ticket itself is untouched).

Parameters
NameTypeDescription
ticket_id
required · body
int Ticket id.
list_id
required · body
int List id.
Permission

Any key (board access)

Request
// Remove a card from a list
const response = await fetch('https://api.todo.work/api_integrations/kanban/remove_ticket', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ ticket_id: 789, list_id: 102 })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": true }

POST /kanban/remove_list Delete a column

Deletes a list (column) and its card placements.

Parameters
NameTypeDescription
id
required · body
int List id.
Permission

Any key (board access)

Request
// Delete a column
const response = await fetch('https://api.todo.work/api_integrations/kanban/remove_list', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ id: 102 })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": true }

POST /kanban/remove_board Delete a board

Deletes a board with all its lists and card placements.

Parameters
NameTypeDescription
id
required · body
int Board id.
Permission

Any key (board ownership)

Request
// Delete a board
const response = await fetch('https://api.todo.work/api_integrations/kanban/remove_board', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ id: 42 })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": true }

POST /kanban/find_shared_board Find a shared board admin only

Finds a board shared between two specific users.

Parameters
NameTypeDescription
user_a
required · body
int First user id.
user_b
required · body
int Second user id.
Permission

Key with tracking.view_all / tracking.manage (admins always)

Request
// Find the board shared between two users
const response = await fetch('https://api.todo.work/api_integrations/kanban/find_shared_board', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({ user_a: 5, user_b: 12 })
});

const data = await response.json();
console.log(data.response);
Response
{ "response": { "id": 42, "name": "Daily — Dana", "users": [] } }
// or { "response": false } when none exists

Team Insights

Read-only presence, time-tracking, call transcripts and daily-target progress. Built for an AI office-manager integration.

  • The /tracking endpoints read platform-wide presence, so they need the time-tracking permission: “ניהול מעקב שעות מלא” (tracking.manage) or “צפייה בכל השעות” (tracking.view_all). Admin keys always pass. A key whose user has neither gets 403 naming the missing permission.

GET /tracking/get_active_shifts Who is clocked in admin only

Everyone with an open shift right now.

Parameters

No parameters — send the authentication headers only.

Permission

Key with tracking.view_all / tracking.manage (admins always)

Request
// Who is currently clocked in
const response = await fetch('https://api.todo.work/api_integrations/tracking/get_active_shifts', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  }
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": [ { "user_id": 7, "date_start": "2026-06-27T08:02:00Z", "absence_type": null } ]
}

GET /tracking/get_active_handlings Who is on a timer admin only

Everyone with an open task-timer right now.

Parameters

No parameters — send the authentication headers only.

Permission

Key with tracking.view_all / tracking.manage (admins always)

Request
// Who is currently working a ticket
const response = await fetch('https://api.todo.work/api_integrations/tracking/get_active_handlings', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  }
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": [ { "handler_uid": 7, "tid": 123, "due_date": "2026-06-27T10:15:00Z" } ]
}

GET /tracking/get_today_handlings Today’s logged work admin only

Task-timers that closed today.

Parameters
NameTypeDescription
date
optional · query
string Y-m-d (defaults to today).
Permission

Key with tracking.view_all / tracking.manage (admins always)

Request
// Work logged today
const response = await fetch('https://api.todo.work/api_integrations/tracking/get_today_handlings?date=2026-06-27', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  }
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": [ { "handler_uid": 7, "tid": 123, "duration": 45, "ended_at": "2026-06-27T11:00:00Z" } ]
}

GET /voice/get_calls_for_user Get call transcripts

Completed voice-call transcripts a user took part in.

Parameters
NameTypeDescription
user_id
required · query
int Whose calls to fetch.
from_date
optional · query
string Inclusive lower bound (Y-m-d).
limit
optional · query
int Default 100, max 200.
Permission

Any key

Request
// Recent call transcripts for user 7
const response = await fetch('https://api.todo.work/api_integrations/voice/get_calls_for_user?user_id=7&from_date=2026-06-01&limit=50', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  }
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "calls": [
      {
        "call_id": "call_abc",
        "initiator_id": 7,
        "participants": [7, 12],
        "started_at": "2026-06-27T09:00:00Z",
        "duration_seconds": 83,
        "summary": "…",
        "full_text": "…"
      }
    ]
  }
}

POST /voice_signal Ring, answer or hang up

Sends a call signal as the user this key acts as — this is how an integration places, answers or ends a call rather than only reading transcripts afterwards. The matching endpoint on the app API rejects integration tokens on purpose, so calls belong here.

Parameters
NameTypeDescription
type
required · body
string call_invite, call_accept, call_decline, call_leave, call_cancel, call_answered_elsewhere or call_declined_elsewhere.
callId
required · body
string Your id for the call — reuse the same one for every signal in it.
participants
optional · body
array User ids to signal. Required in practice for call_invite.
isVideo
optional · body
bool call_invite: place it as a video call.
reason
optional · body
string call_decline: busy or unavailable — drives the caller’s “user is busy” indicator.
Permission

Any key, on a platform with the walkie-talkie service

Notes
  • Signalling only: it rings the other side and carries the answer/hang-up. Audio itself is WebRTC — pair it with /voice/turn_credentials, and open and close the call record with /voice/history_start and /voice/history_end.
  • The browser-tab coordination signals (walkie_tab_*) are deliberately not reachable here — they are about which tab owns the microphone, which has no meaning for an integration.
Request
// Ring a user
const response = await fetch('https://api.todo.work/api_integrations/voice_signal', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify([object Object])
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": { "status": true, "message": "Signal sent", "channel": "core_user:794" }
}

POST /voice/turn_credentials ICE / TURN servers

Short-lived STUN/TURN credentials for the WebRTC leg of a call, ready to hand to an RTCPeerConnection.

Parameters

No parameters — send the authentication headers only.

Permission

Any key

Request
// ICE servers for a call
const response = await fetch('https://api.todo.work/api_integrations/voice/turn_credentials', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify(undefined)
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": { "status": true, "username": "…", "credential": "…", "ttl": 86400, "uris": ["stun:…", "turn:…"] }
}

POST /voice/history_start · /voice/history_end Open and close the call record

Puts the call on the timeline the way an app call appears: history_start when it connects, history_end when it is over. Without them the call happens but leaves no trace anyone can see.

Parameters
NameTypeDescription
call_id
required · body
string The same id used for the signals.
participants
required · body
array User ids on the call.
duration_seconds
optional · body
int history_end: how long it lasted.
status
optional · body
string history_end: completed, missed, declined…
Permission

Any key

Request
// Close the call record
const response = await fetch('https://api.todo.work/api_integrations/voice/history_end', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify([object Object])
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": { "status": true }
}

POST /voice/upload_chunk · /voice/end_recording Upload call audio (accepted, not transcribed)

The transcript of a call comes from the call itself: everyone in the room is transcribed there, and the result is readable through get_transcription and get_calls_for_user. These two calls are kept so that older clients keep working: an uploaded chunk is accepted and answered with status true, and it is not stored, not transcribed, not added to the transcript and not charged. end_recording answers with status true and starts nothing.

Parameters
NameTypeDescription
chunk
required · body
file upload_chunk: audio part (multipart/form-data). Accepted and dropped.
call_id
required · body
string The call.
user_id
required · body
int Whose audio this is.
chunk_index
required · body
int upload_chunk: 0-based order.
absolute_start_ms
optional · body
int upload_chunk: no longer read.
duration_ms
required · body
int upload_chunk: length of this chunk.
Permission

Any key

Request
// This participant is done recording
const response = await fetch('https://api.todo.work/api_integrations/voice/end_recording', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify([object Object])
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": { "status": true }
}

POST /voice/get_transcription Get one call’s transcript

The merged transcript of a single call, once recording has finished on every side.

Parameters
NameTypeDescription
call_id
required · body
string The call.
Permission

Any key

Request
// Transcript of one call
const response = await fetch('https://api.todo.work/api_integrations/voice/get_transcription', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: JSON.stringify([object Object])
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": { "status": true, "full_text": "…", "segments": [ { "user_id": 7, "start_ms": 0, "text": "…" } ] }
}

GET /panels/daily_target_for_user Daily target progress

One user’s daily-target progress — the same numbers as the dashboard target widget.

Parameters
NameTypeDescription
user_id
required · query
int The user.
date
optional · query
string Y-m-d (defaults to today).
Permission

Any key

Notes
  • user_id is genuinely required — without it the endpoint answers a bare false.
  • The response carries about 26 fields; the common ones are shown below. It also includes target / target_type, which are aliases of daily_target / daily_target_type.
Request
// Daily target progress for user 7
const response = await fetch('https://api.todo.work/api_integrations/panels/daily_target_for_user?user_id=7&date=2026-06-27', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  }
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "user_id": 7,
    "display_name": "Dana",
    "date": "2026-06-27",
    "daily_target": 8,
    "daily_target_type": "hours",
    "perc": 62.5,
    "ttl_hours_parsed": "05:00"
  }
}

Media Gallery

List, upload and delete project media (images, video and files).

GET /media_gallery/results List media

Media for a project and its tickets, paginated.

Parameters
NameTypeDescription
project_id
required · query
int Project to scope media to.
limit
optional · query
int Default 50.
page
optional · query
int 0-indexed; page 0 includes the total count.
q
optional · query
string Free-text filter on the file name and the owning ticket subject.
Permission

Any key

Notes
  • project_id is required — calling without it answers 400.
  • Deleting requires POST; a GET to /media_gallery/delete is refused with 405.
Request
// List media in project 123
const response = await fetch('https://api.todo.work/api_integrations/media_gallery/results?project_id=123&limit=10&page=0', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  }
});

const data = await response.json();
console.log(data.response);
Response
{
  "response": {
    "num": 1,
    "items": [
      {
        "id": 5,
        "name": "logo.png",
        "url": "https://…",
        "type": "image",
        "project_id": 123,
        "ticket_id": false,
        "subject": false,
        "date_created": false
      }
    ]
  }
}

POST /media_gallery/upload Upload media

Uploads media files to a project (multipart/form-data).

Parameters
NameTypeDescription
project_id
required · formdata
int Target project.
files
required · formdata
file[] The files to upload.
Permission

Any key (needs project access)

Request
// Upload media (multipart/form-data — no Content-Type header)
const formData = new FormData();
formData.append('project_id', 123);
// formData.append('files[]', file1);

const response = await fetch('https://api.todo.work/api_integrations/media_gallery/upload', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  },
  body: formData
});

const data = await response.json();
console.log(data.response);
Response
{ "response": true }

GET /media_gallery/delete Delete media

Deletes a single media file by its storage id.

Parameters
NameTypeDescription
media_id
required · query
int The storage id to delete.
Permission

Any key (needs project access)

Request
// Delete a media file
const response = await fetch('https://api.todo.work/api_integrations/media_gallery/delete?media_id=5', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY',
    'X-API-SECRET': 'YOUR_API_SECRET'
  }
});

const data = await response.json();
console.log(data.response);
Response
{ "response": { "success": true } }
// or { "response": { "success": false, "message": "Media item not found" } }