Getting Started

Quickstart: Make Your First Taskade API Call

7 min readStart hereView as Markdown
Getting Started

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

Page type: Tutorial. Follow the steps in order for a first working result.

TL;DR: Create a token at taskade.com/settings/api, export TASKADE_TOKEN=…, then curl -s https://www.taskade.com/api/v1/workspaces -H "Authorization: Bearer $TASKADE_TOKEN". The rest of this page creates a project and a task.

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

You need an account, a terminal, and five minutes.

Requirement Details
Taskade account Any plan, Free included. The email address must be verified.
Terminal curl. macOS, Windows 10 and later, and most Linux systems include it.
Optional runtime Node.js 18 or later, or Python 3 with requests, for the script tabs
Time About five minutes

1. Create a personal access token

A personal access token lets your terminal act as you.

Warning: Keep the token out of source code, chat, and the browser. A personal access token has no scopes. It can do everything that your account can do.

  1. Open taskade.com/settings/api.
  2. Under Personal access tokens, click Create token.
  3. In Token name, type a name, for example quickstart. Click Create.
  4. Under Your new token, click Copy. Taskade shows the token one time only.
  5. Save the token in your terminal:
Bash
export TASKADE_TOKEN="tskdp_your_token_here"

┌──────────────────────────────────────────────────────┐
│  Create Personal Access Token                        │
├──────────────────────────────────────────────────────┤
│  Token name                                          │
│  ┌────────────────────────────────────────────────┐  │
│  │ quickstart                                     │  │
│  └────────────────────────────────────────────────┘  │
│                               [ Cancel ] [ Create ]  │
└──────────────────────────────────────────────────────┘

2. Find your workspace ID

Your first request lists the workspaces that your account can use. It only reads data, so it is safe to repeat.

cURL

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

JavaScript

Node.js 18 or later, which includes fetch. Save as workspaces.mjs, then run node workspaces.mjs.

Js
const res = await fetch('https://www.taskade.com/api/v1/workspaces', {
  headers: { Authorization: `Bearer ${process.env.TASKADE_TOKEN}` },
});
const data = await res.json();
if (!data.ok) throw new Error(`${res.status} ${data.code}`);
console.log(data.items);

Python

Python 3 with the requests package.

Python
import os
import requests

res = requests.get(
    'https://www.taskade.com/api/v1/workspaces',
    headers={'Authorization': f"Bearer {os.environ['TASKADE_TOKEN']}"},
)
data = res.json()
if not data['ok']:
    raise RuntimeError(f"{res.status_code} {data['code']}")
print(data['items'])

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

One POST request creates a project from 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

One POST request adds a 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

One GET request reads 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. A task under another task also carries parentId. The IDs below are examples:

Json
{
  "ok": true,
  "items": [
    { "id": "Tk1aQ4wE8rT2yU6i", "text": "Read the quickstart", "completed": false },
    { "id": "Tk3sD7fG1hJ5kL9z", "text": "Make the first call", "completed": false },
    { "id": "Tk5yH1cR7mD3aF9u", "text": "Ship the integration", "completed": false }
  ],
  "hasMore": false,
  "nextCursor": null
}

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

One JavaScript file repeats steps 2 to 5. It needs Node.js 18 or later, which includes fetch.

Js
// 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.
Verify your email before creating tokens. You did not open the link in the email that Taskade sent at sign-up Open that email from Taskade and click its link. Then create the token.
Cannot create more than 5 personal access tokens. An account holds 5 active tokens maximum Revoke a token that you do not use.
"code": "NOT_FOUND" The workspace ID or project ID is wrong Copy the id again from the response of step 2 or step 3.
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

PreviousDeveloper OverviewNextAuthentication