API introduction

The Brandless API lets you read and manage your workspace from your own systems: list agents and clients, pull call logs with full transcripts, check usage, create clients, assign agents, and place outbound calls. It’s a plain REST API over HTTPS. Every response is JSON.

Availability

The API is a plan feature:

Growth — read access (list agents, clients, conversations, usage, phone numbers).
Scale — read and write access (create clients, assign agents, place calls).
Starter / Free — no API access.

Access is checked on your current plan for every request, so if you upgrade or downgrade it takes effect immediately — you never need to re-issue keys.

Base URL

https://intent-weasel-655.eu-west-1.convex.site/api/v1

You can always copy your exact base URL from API in your dashboard sidebar.

Authentication

Every request is authenticated with an API key sent as a Bearer token:

Authorization: Bearer bl_live_xxxxxxxxxxxxxxxx

Create a key

Open the API page

In your dashboard, click API in the sidebar. (If you don’t see it, your plan doesn’t include API access yet.)

Create a key

Click Create key, give it a name (for example, “Production” or “Zapier”), and click Create key.

Copy the secret now

Your full key is shown once. Copy it and store it somewhere safe — for your security, we never show it again. If you lose it, revoke the key and create a new one.

Your API key grants full access to your workspace. Treat it like a password: keep it server-side, never commit it to source control, and never put it in browser or mobile code. If a key leaks, revoke it from the API page immediately.

Your first request

curl https://intent-weasel-655.eu-west-1.convex.site/api/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "agency": {
    "id": "j57...",
    "name": "Acme Agency",
    "slug": "acme",
    "plan": "scale"
  },
  "apiTier": "advanced"
}

Rate limits

Each key is limited to 120 requests per minute. If you exceed it, you get a 429 response with a Retry-After header (in seconds):

{ "error": { "code": "rate_limited", "message": "Too many requests. Slow down." } }

Errors

Errors return a non-2xx status and a JSON body with a stable code and a human-readable message:

{ "error": { "code": "invalid_api_key", "message": "This API key is not valid." } }

Status	Code	Meaning
400	`invalid_request`	A required field is missing or a value is invalid.
401	`missing_api_key`	No `Authorization: Bearer` header was sent.
401	`invalid_api_key`	The key is wrong or has been revoked.
402	`insufficient_credits`	The workspace is out of credits (for placing calls).
403	`plan_required`	Your plan doesn’t include API access.
403	`write_forbidden`	Writes require the Scale plan.
404	`not_found`	The endpoint or resource doesn’t exist.
429	`rate_limited`	You’ve exceeded the rate limit.
502	`provider_error`	An upstream provider (e.g. the voice provider) failed.

Pagination

List endpoints that can be large — currently conversations — use cursor pagination. The response includes nextCursor and hasMore:

{ "data": [ ... ], "nextCursor": "abc123", "hasMore": true }

To get the next page, pass the cursor back:

GET /conversations?cursor=abc123

Keep following nextCursor until hasMore is false. A page can occasionally come back with an empty data array while hasMore is still true — that’s expected, just request the next page.

Account

Your agency profile and current usage.

Agents

List agents and assign them to clients.

Clients

List and create client workspaces.

Conversations

Pull call logs and transcripts.

Calls

Place outbound calls from an agent.

Getting started

Your brand

Clients

Building agents

Chat & embedding

Calendar

API

Billing your clients

Account & billing

Availability

Base URL

Authentication

Create a key

Your first request

Rate limits

Errors

Next

Account

Agents

Clients

Conversations

Calls

​Availability

​Base URL

​Authentication

​Create a key

​Your first request

​Rate limits

​Errors

​Pagination

​Next

Account

Agents

Clients

Conversations

Calls

Availability

Base URL

Authentication

Create a key

Your first request

Rate limits

Errors

Pagination

Next