Tasks API
Tasks in the Broker & Agent API: list tasks; create a task; check off, reopen or
Base URL: https://workspace.brokerandagent.com/api/public/v1. Every call needs an API key or OAuth token.
- List tasks:
GET /tasks - Create a task:
POST /tasks - 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. |
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, 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
Scope: crm.write · Role:
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 |
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 } |
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
Scope: crm.write · Role:
Parameters
| Name | In | Type | |
|---|---|---|---|
id (required) |
path | string |
Body
| Field | Type | |
|---|---|---|
done |
boolean | |
due |
string | |
allDay |
boolean |
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 } |
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). |
Something missing or wrong? Email support@brokerandagent.com and