Tasks API

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

Generated from the product on Nov 17, 2026

Base URL: https://workspace.brokerandagent.com/api/public/v1. Every call needs an API key or OAuth token.

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.
Shell
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 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
Shell
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 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
Shell
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 we’ll fix it.