Getting Started

Quickstart: Make Your First API Call

5 min readStart here

Getting Started

Make your first Taskade API call in about five minutes. You create a token, find your workspace, create a project, and add a task to it with the REST API v1.

What you build

At the end, your workspace holds a new project named API quickstart with three tasks. You create all of it from a terminal, and you see it in the Taskade app a second later.

  1. Token       taskade.com/settings/api  →  tskdp_…
  2. Workspace   GET  /workspaces                 →  workspace id
  3. Project     POST /workspaces/{id}/projects   →  project id
  4. Task        POST /projects/{id}/tasks/       →  task id
  5. Check       GET  /projects/{id}/tasks        →  the tasks you made

Before you start

A Taskade account with a verified email address. Taskade does not create a token for an unverified account.
curl in a terminal. macOS and Windows 10 and later include it, and most Linux systems do too.
About five minutes.

1. Create a personal access token

Open taskade.com/settings/api.
Go to Personal access tokens.
Click Create token, type a name, and click Create.
Copy the token. Taskade shows it one time only.
Save the token in your terminal:

Bash

export TASKADE_TOKEN="tskdp_your_token_here"

Keep the token secret. A personal access token has no scopes. It can do everything that your account can do. If a token leaks, revoke it and create a new one.

2. Find your workspace ID

Send your first request. It lists the workspaces that your account can use.

Bash

curl -s https://www.taskade.com/api/v1/workspaces \
  -H "Authorization: Bearer $TASKADE_TOKEN"

The response lists each workspace with its id and name:

Json

{
  "ok": true,
  "items": [
    { "id": "Wk3rT9pLmQ2vXa7c", "name": "My Workspace" }
  ]
}

Copy the id of the workspace that you want to use:

Bash

export WORKSPACE_ID="Wk3rT9pLmQ2vXa7c"

3. Create a project

Send the project as Markdown. The first line, a # heading, becomes the project title. Each list item becomes a task.

Bash

curl -s -X POST "https://www.taskade.com/api/v1/workspaces/$WORKSPACE_ID/projects" \
  -H "Authorization: Bearer $TASKADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"contentType": "text/markdown", "content": "# API quickstart\n\n- Read the quickstart\n- Make the first call"}'

The response holds the new project:

Json

{
  "ok": true,
  "item": { "id": "Pj8sK2nV4wQx6ZbE", "icon": null, "completed": false }
}

Save the project id:

Bash

export PROJECT_ID="Pj8sK2nV4wQx6ZbE"

4. Add a task

Add one more task to the end of the project. The tasks array accepts up to 20 tasks in one request.

Bash

curl -s -X POST "https://www.taskade.com/api/v1/projects/$PROJECT_ID/tasks/" \
  -H "Authorization: Bearer $TASKADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tasks": [{"contentType": "text/plain", "content": "Ship the integration", "placement": "beforeend"}]}'

The response returns each task that you created, with its id:

Json

{
  "ok": true,
  "item": [
    { "id": "Tk5yH1cR7mD3aF9u", "text": "Ship the integration", "completed": false }
  ]
}

5. Check the result

Read the tasks back from the project:

Bash

curl -s "https://www.taskade.com/api/v1/projects/$PROJECT_ID/tasks" \
  -H "Authorization: Bearer $TASKADE_TOKEN"

The items array holds one object for each task, with its id, text, and completed state. The response also carries hasMore and nextCursor. If hasMore is true, send nextCursor as the after query parameter to get the next page.

You are done when the API quickstart project shows in your Taskade workspace with Read the quickstart, Make the first call, and Ship the integration.

Run it as one script

The same five steps in one JavaScript file. It needs Node.js 18 or later, which includes fetch.

// quickstart.mjs: run with node quickstart.mjs
const API = 'https://www.taskade.com/api/v1';
const headers = {
  Authorization: `Bearer ${process.env.TASKADE_TOKEN}`,
  'Content-Type': 'application/json',
};

async function call(method, path, body) {
  const res = await fetch(`${API}${path}`, {
    method,
    headers,
    body: body ? JSON.stringify(body) : undefined,
  });
  const data = await res.json();
  if (!data.ok) throw new Error(`${res.status} ${data.code}: ${data.message}`);
  return data;
}

const { items: workspaces } = await call('GET', '/workspaces');
const workspaceId = workspaces[0].id;

const { item: project } = await call('POST', `/workspaces/${workspaceId}/projects`, {
  contentType: 'text/markdown',
  content: '# API quickstart\n\n- Read the quickstart\n- Make the first call',
});

await call('POST', `/projects/${project.id}/tasks/`, {
  tasks: [{ contentType: 'text/plain', content: 'Ship the integration', placement: 'beforeend' }],
});

const { items: tasks } = await call('GET', `/projects/${project.id}/tasks`);
console.log(tasks.map((task) => task.text));

Fix common errors

What you see	Cause	Fix
`"code": "UNAUTHORIZED"`	The token is missing or wrong	Send `Authorization: Bearer $TASKADE_TOKEN`. Make sure that the variable is set in the same terminal.
You cannot create a token	The account email is not verified	Verify your email address, then create the token again.
`Cannot create more than 5 personal access tokens.`	An account holds 5 tokens maximum	Revoke a token that you do not use.
`429` status	You hit a rate limit	Wait for the number of seconds in the `x-rate-limit-reset` header, then send the request again.

Next steps

Authentication: use OAuth 2.0 when your app acts for other Taskade users.
REST API reference: every v1 endpoint, with its parameters and responses.
Action API guide: one verb for each endpoint, a good fit for AI agent tools.
Webhooks: get an event when data changes, instead of polling.
Hosted MCP: connect Claude, Cursor, and other MCP clients to your workspace.

PreviousDeveloper Overview NextAuthentication