# Tasks API

> Tasks in the Broker & Agent API: list tasks; create a task; check off, reopen or move a task.

Base URL: `https://workspace.brokerandagent.com/api/public/v1`. Every call needs an [API key or OAuth token](https://brokerandagent.com/developers/api/authentication).

- [List tasks](#list-tasks): `GET /tasks`
- [Create a task](#create-a-task): `POST /tasks`
- [Check off, reopen or move a task](#check-off-reopen-or-move-a-task): `PATCH /tasks/{id}`

## List tasks

`GET /tasks`

The open tasks the credential's person can see, high priority first, then soonest due, 200 to a page unless `limit` says otherwise.

Scope: `crm.read`

**Parameters**

| Name | In | Type | |
|---|---|---|---|
| `contactId` | query | string or null | Only this contact's tasks. Cut to 64 characters. |
| `limit` | query | integer | How many to answer with, 1 to 200. Default `200`. |
| `cursor` | query | string or null | The `nextCursor` of the page before; absent for the first page. Cut to 200 characters. |

```bash
curl https://workspace.brokerandagent.com/api/public/v1/tasks \
  -H "Authorization: Bearer bak_YOUR_KEY"
```

**Responses**

| Status | | Returns |
|---|---|---|
| `200` | A page of tasks. | { `tasks`: array of [Task](https://brokerandagent.com/developers/api/reference/objects#task), `nextCursor`: string or null } |
| `401` | No credential, or one that's unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended). |  |
| `403` | The credential lacks the scope (insufficient_scope, naming it in `scope`), the record isn't the person's to change (forbidden), the connection wasn't granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant's tools (wrong_audience). |  |
| `422` | A field is the wrong kind or breaks a rule, named in the message (validation); or the Idempotency-Key was used for a different request (idempotency_key_reused). |  |
| `429` | Too many requests for this credential; wait for Retry-After (rate_limited). |  |

## Create a task

`POST /tasks`

`due` defaults to now. A time without a zone (`2026-10-14T17:00`) is on the clock of the person the key belongs to, and a date alone is 10 a.m. that day there; a `Z` or an offset is honored. An unassigned task goes to the contact's owner, as in the app.

Scope: `crm.write` · Role: transaction-coordinator or above

**Body**

| Field | Type | |
|---|---|---|
| `title` (required) | string | Cut to 300 characters. |
| `detail` | string or null | Cut to 2000 characters. |
| `contactId` | string or null | Cut to 64 characters. |
| `kind` | `call`, `sms`, `email`, `todo` | An unknown value is ignored, not refused. |
| `due` | string or null |  |

```bash
curl -X POST https://workspace.brokerandagent.com/api/public/v1/tasks \
  -H "Authorization: Bearer bak_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Call Dana back"}'
```

**Responses**

| Status | | Returns |
|---|---|---|
| `201` | The task. | { `task`: [Task](https://brokerandagent.com/developers/api/reference/objects#task) } |
| `400` | The body isn't a JSON object (bad_json), or the Idempotency-Key is malformed (bad_idempotency_key). |  |
| `401` | No credential, or one that's unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended). |  |
| `403` | The credential lacks the scope (insufficient_scope, naming it in `scope`), the record isn't the person's to change (forbidden), the connection wasn't granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant's tools (wrong_audience). |  |
| `404` | No such record, or one the credential's person can't see (not_found). |  |
| `409` | A request with this Idempotency-Key is still being handled (idempotency_in_progress, with Retry-After), or the call conflicts with the record's state (flow_off, in_progress). |  |
| `422` | A field is the wrong kind or breaks a rule, named in the message (validation); or the Idempotency-Key was used for a different request (idempotency_key_reused). |  |
| `429` | Too many requests for this credential; wait for Retry-After (rate_limited). |  |

## Check off, reopen or move a task

`PATCH /tasks/{id}`

`done: true` checks it off as Today does (one on a contact leaves its Done line on their timeline); `false` opens it again and takes that line back. `due` moves it, read as in `POST /tasks`, and `allDay: true` with it makes it a day with no time. The same request again changes nothing more. A task's words and who it's for change in the app.

Scope: `crm.write` · Role: transaction-coordinator or above

**Parameters**

| Name | In | Type | |
|---|---|---|---|
| `id` (required) | path | string |  |

**Body**

| Field | Type | |
|---|---|---|
| `done` | boolean |  |
| `due` | string |  |
| `allDay` | boolean |  |

```bash
curl -X PATCH https://workspace.brokerandagent.com/api/public/v1/tasks/ID \
  -H "Authorization: Bearer bak_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"done":true,"due":"…"}'
```

**Responses**

| Status | | Returns |
|---|---|---|
| `200` | The task as it now stands. | { `task`: [Task](https://brokerandagent.com/developers/api/reference/objects#task) } |
| `400` | The body isn't a JSON object (bad_json), or the Idempotency-Key is malformed (bad_idempotency_key). |  |
| `401` | No credential, or one that's unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended). |  |
| `403` | The credential lacks the scope (insufficient_scope, naming it in `scope`), the record isn't the person's to change (forbidden), the connection wasn't granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant's tools (wrong_audience). |  |
| `404` | No such record, or one the credential's person can't see (not_found). |  |
| `422` | A field is the wrong kind or breaks a rule, named in the message (validation); or the Idempotency-Key was used for a different request (idempotency_key_reused). |  |
| `429` | Too many requests for this credential; wait for Retry-After (rate_limited). |  |

---

Source: https://brokerandagent.com/developers/api/reference/tasks
