# Quickstart: Make Your First Taskade API Call

> Make your first Taskade API call in 5 minutes: create a personal access token, list your workspaces, create a project, and add a task with the REST API.

- Source: https://www.taskade.com/docs/getting-started/quickstart
- Section: Getting Started
- Updated: 2026-10-17
- Index of all pages: https://www.taskade.com/docs/llms.txt

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](https://www.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.

```text
  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](https://www.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"
```

```text
┌──────────────────────────────────────────────────────┐
│  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. |
| `"code": "TOO_MANY_REQUESTS"` (HTTP `429`) | You hit a rate limit | Wait for the number of seconds in the `Retry-After` header, then send the request again. |

## Next steps

- [Taskade API overview](https://www.taskade.com/docs/getting-started/api-overview): every API surface, and the path that fits your task.
- [Authentication](https://www.taskade.com/docs/getting-started/authentication): use OAuth 2.0 when your app acts for other Taskade users.
- [REST API reference](https://www.taskade.com/docs/rest): every v1 endpoint, with its parameters and responses.
- [Action API guide](https://www.taskade.com/docs/getting-started/action-api-guide): one verb for each endpoint, a good fit for AI agent tools.
- [Hosted MCP](https://www.taskade.com/docs/mcp/hosted-mcp): connect Claude, Cursor, and other MCP clients to your workspace.