Requests, errors and limits

The conventions every API call follows, including JSON, times and dates, pagination, errors, plan limits and the rate limit.

Updated Nov 11, 2026

Format#

  • JSON in, JSON out. Send Content-Type: application/json with a body.
  • Dates are ISO 8601 strings, like 2026-10-02T15:00:00Z. Date-only fields use YYYY-MM-DD.
  • Text is trimmed and cut to the field’s length rather than refused.
  • An unknown choice, like an intent or a task kind we don’t have, is ignored rather than refused.
  • In a PATCH, a field you leave out is left alone, and null clears it.
  • Custom field values arrive as text (numbers and true/false are converted), at most 50 per request.

Times and time zones#

  • A time without a zone is read on the clock of the person behind the credential. 2026-10-14T17:00 is 5 PM where they are.
  • A date alone, where a time is expected, is 10 AM that day on their clock.
  • A from or to that’s a date alone covers that whole day.
  • Days, like a deal’s contract and closing dates, are sent as that day’s UTC midnight. Read them as a date, not a moment.

Pagination#

Lists that can grow long page by cursor. Pass limit, then pass the answer’s nextCursor as cursor to get the next page. A null nextCursor means you’ve reached the end.

Shell
curl "https://workspace.brokerandagent.com/api/public/v1/contacts?limit=25&cursor=ct_…" \
  -H "Authorization: Bearer bak_YOUR_KEY"
  • Paged by cursor: /contacts, /inbox/threads, /documents, /smart-lists/{id}/members, /tasks, /appointments and /envelopes.
  • Paged only when you pass limit: /transactions and /tours. Without limit they answer with everything.
  • Page sizes differ. The default is 25 for contacts, 50 for threads and 200 for tasks.
  • A limit above the call’s maximum is treated as that maximum, and one below 1 as 1.

A cursor for a record that has since been deleted answers 422; start again from the first page.

Errors#

Every error has the same shape:

JSON
{ "error": { "code": "validation", "message": "email: Not a valid email address" } }

Branch on code, never on the wording of message, which can change.

Status Code Meaning
400 bad_json The body isn’t a JSON object
400 bad_idempotency_key The Idempotency-Key is malformed. See Retrying safely
401 unauthorized, workspace_suspended See Authentication
402 upgrade_required The workspace’s plan doesn’t include this, or the workspace is at a plan limit. The reason is in message
403 insufficient_scope, insufficient_access, forbidden, workspace_not_granted, wrong_audience, ip_not_allowed, ai_apps_off, awaiting_approval The credential can’t do this, or can’t reach this record or workspace. See Authentication
404 not_found No such record, or none the credential can see
409 idempotency_in_progress A request with the same Idempotency-Key is still running. Retry after Retry-After
409 flow_off The automation you tried to start is switched off
409 in_progress A copy of the same request is still being handled
422 validation A field is the wrong kind; the message names it
422 idempotency_key_reused The same Idempotency-Key came with a different body or path
429 rate_limited Too many requests; see below
500 internal Something went wrong on our side
503 unavailable Briefly unavailable. Retry shortly

Rate limits#

Each key or connection can make 120 requests a minute, and each IP address gets 10 tries a minute with a bad credential. Over either, calls answer 429 rate_limited with a Retry-After: 60 header. Wait, then retry. Spreading requests out works better than bursts.

There are no RateLimit-* headers yet, and the count is approximate, since it’s kept per Cloudflare location.

Plan limits#

The API is on every Workspace plan, Free included. A workspace at a plan limit answers 402 upgrade_required, with the reason in message.

Today one call can meet a limit: POST /contacts, when a Free workspace already holds its 100,000 contacts, plus 25,000 for each extra login. Leads always land: lead-capture keys, POST /events and POST /site-leads are never refused for a limit.

Some answers follow the workspace’s add-ons rather than refusing. Without the collaboration add-on, GET /reports covers the credential’s own person, and calendar attendees are left off a booking.

Answers that wait for a person#

A connected app (OAuth) can be set to ask its person first. Then starting an automation or removing a tour stop answers 202 with a proposal, and nothing runs until the person approves it in the app. API keys never ask first. See Build an app with OAuth.

Build for change#

Within v1 the API only grows: new calls, new fields, new values. Ignore fields and values you don’t recognize, and your integration keeps working. See Versioning and changes.

Something missing or wrong? Email support@brokerandagent.com and we’ll fix it.