GeezerVison

The Action API v2 is an action-based API. Each operation sends a JSON body with POST to a named endpoint.

It is not RESTful. It has no GET /workspaces or PUT /tasks/{id} endpoints.

Media downloads, bundle downloads, and webhook registration are the REST-style exceptions.

The live OpenAPI spec is published at taskade.com/api/documentation/v2.

Before you start

• A Taskade account with a verified email address.

• A personal access token from taskade.com/settings/api, or an OAuth 2.0 access token. See Authentication.

• curl in a terminal. The tabbed examples also show Python 3 with requests and TypeScript on Node.js 18 or later.

Save the token in your terminal. Every example on this page reads it from TASKADE_TOKEN:

export TASKADE_TOKEN="tskdp_your_token_here"

Choose an API

Taskade ships two public HTTP APIs. They share the same authentication.

The v2 task operations are createTask, updateTask, deleteTask and moveTask, plus assignTask, setTaskDate, setTaskNote, setTaskFieldValue and more.

Use v2 for LLM tools, agent prompts, or webhook registration. One verb per endpoint maps directly to a tool definition.

Use v1 for its longer stability record. Also use v1 to read one task, date, note, or field directly, with GET /projects/{projectId}/tasks/{taskId} and its /date, /note and /fields/{fieldId} sub-paths.

Every row in this table is checkable. Each row comes from the two live OpenAPI documents. The generated Action API reference and REST API reference are built from those same specs.

Base URL and authentication

All v2 operations live under:

Send a personal access token, or an OAuth 2.0 access token for apps that act for other users, in the Authorization header:

See the Authentication guide for personal tokens and OAuth 2.0 with PKCE.

Calling convention

Every v2 call sends a JSON body with POST to an operation name. The API returns JSON.

A successful response has "ok": true. A list operation adds an items array, and a single-item operation adds an item object.

Here is a single Action API v2 call, from authentication to JSON response.

The call below lists the projects that your account can open. It needs no IDs:

Endpoints

The examples below read IDs from shell variables. Save each ID when a response gives it to you:

List spaces (workspaces)

POST /listSpaces is every integration's entry point. Send a JSON body. Every field in it is optional, so send {} when you do not filter.

Response:

Filter with { "filterBy": { "name": { "operator": "contains", "value": "Marketing" } } }.

List folders in a space

POST /listFolders returns { ok, items: [{ id, name }] }.

List projects in a space

POST /listProjects takes { spaceId, completed? } and returns { ok, items: [{ id, name?, icon?, completed?, archived?, color?, tags? }] }. Set completed to false to list only open projects, or to true to list only completed projects. Leave it out to list both. Archived projects are not in the list.

Get a project

POST /getProject returns { ok, item: { id, name?, icon?, completed?, archived?, color?, tags? } }.

Create a project

POST /createProject seeds a project from Markdown.

Response:

List tasks

POST /listTasks is paginated with after / before cursors. Each task is { id, text, parentId?, completed }. Set completed to false to list only open tasks, or to true to list only completed tasks. The cursors and limit apply to the filtered list.

Response:

If Google Calendar is connected on an eligible workspace, dates set with setTaskDate can sync the same way as dates set in Taskade.

Prompt an agent

POST /promptAgent sends a single prompt to a workspace agent. The endpoint returns a synchronous text response. This capability is v2-only.

Each call uses the workspace's AI credits, the same as an agent chat in the app. If the workspace has no AI credits left, the call fails before the agent runs.

Response:

If the agent is not in that space, the call returns 404:

To list past conversations, use POST /listConversations with { agentId, limit?, page? }.

To read one, use POST /getConversation with { agentId, convoId, includeTranscript? }.

Pass "includeTranscript": true to add a Markdown transcript field to the response.

Manage agents

Attach knowledge to an agent

POST /addKnowledgeProject grounds an agent in a project. (removeKnowledgeProject, addKnowledgeMedia, removeKnowledgeMedia mirror it.)

The response returns the updated agent as { ok, item: { id, name, space_id, data } }.

Export / import a bundle

POST /exportBundle returns a portable Taskade Genesis app bundle. POST /importBundle installs one. Export needs the Pro plan or higher.

See Bundles & App Kits for the full schema, the binary .tsk variants, and the plan errors.

The response is { "ok": true, "item": { "version": "1", "items": { ... } } }.

Full operation list

• Workspaces & structure: listSpaces, listFolders, listMyProjects, listTemplates, listMedia.

• Projects: listProjects, getProject, createProject, createProjectFromTemplate, copyProject, completeProject, restoreProject, archiveProject, renameProject, exportProject, listBlocks, listFields, listProjectMembers, getShareLink, enableShareLink.

• Tasks, content: listTasks, createTask, updateTask, deleteTask, moveTask, completeTask, uncompleteTask.

• Tasks, metadata: assignTask, unassignTask, setTaskDate, deleteTaskDate, setTaskNote, deleteTaskNote, setTaskFieldValue, deleteTaskFieldValue.

• Agents, lifecycle: listAgents, getAgent, createAgent, updateAgent, deleteAgent, promptAgent, generateAgent.

• Agents, conversations: listConversations, getConversation.

• Agents, knowledge: addKnowledgeProject, removeKnowledgeProject, addKnowledgeMedia, removeKnowledgeMedia.

• Agents, public access: enablePublicAgentAccess, getPublicAgent, updatePublicAgent.

• Media: uploadMedia, getMedia, deleteMedia, plus GET /media/{mediaId}/content and GET /media/spaces/{spaceId}/content for downloads.

• Bundles: exportBundle, importBundle, importBundleZip, plus GET /bundles/{spaceId}/export/zip.

• Webhooks: POST /webhooks, GET /webhooks, GET /webhooks/{id}, DELETE /webhooks/{id}. See Webhooks. subscribeWebhook and unsubscribeWebhook are deprecated.

The authoritative, always-current list is the live v2 spec.

Pagination

listTasks and listBlocks use cursor pagination with after and before. listProjectMembers, listConversations, listMyProjects, listMedia, and listTemplates use page pagination with page and limit.

Rate limits

Every rate-limited response carries the current budget in two sets of headers. Header names are case-insensitive:

v2 operations share the public API's per-IP budget with every other public request. The budget is 40 requests per 60 seconds for each IP address, as the live v2 spec states. Taskade can change it without a docs release, so read the headers for the live values.

A 429 response carries Retry-After, in whole seconds. Wait that number of seconds before you retry. Earlier retries are also rejected.

For sustained throughput, batch operations such as /createTask, which takes a tasks array. Reduce polling frequency. Stagger scheduled jobs.

Errors

Every error response carries ok: false, message, code, and statusMessage. A missing or wrong token returns 401:

A schema validation failure returns 400 with code: "FST_ERR_VALIDATION" and the same four fields. Its message names each field that failed, then the reason.

Branch on ok and code. Do not parse the human-readable message.

Fix common errors

Security best practices

• Never commit tokens. Use environment variables or a secret manager.

• Use OAuth, not personal tokens, for multi-user applications.

• Rotate personal tokens periodically. You can hold up to 5 at a time.

• Encrypt refresh tokens at rest. They are long-lived.

Next steps

• Action API reference: every v2 operation, with its body and response.

• REST API guide: the v1 API, which reads a single task.

• Authentication: OAuth 2.0 for apps that act for other users.

• Webhooks: register a signed webhook with POST /api/v2/webhooks.

• Bundles and App Kits: export and import a Taskade Genesis app.

This page is also published at taskade.com/docs/getting-started/action-api-guide.