Read and reply over the REST API

AI Assistant gives each workspace an API key so your own code can read conversations and post replies — over the REST endpoints or straight to the MCP server. This guide creates a key and makes your first authenticated call.

1. Create an API key

In Console → Connections → API keys, open API keys and create one. Give it a label, choose its scope — read, or read and write — and save. The key is shown once, starting with bmai_sk_; copy it now into your server's secret store. Only its prefix is kept afterwards, so it can never be shown again. A read key can list and fetch; a write key can also post an operator reply.

2. Call with the key

Send the key as a Bearer token: Authorization: Bearer bmai_sk_.... The key is bound to one workspace, so you never pass a tenant id — every call acts on the workspace the key belongs to. The same key authenticates the MCP server, so a client that speaks MCP can call the tenant tools directly; the REST endpoints below are a thin convenience over the same reads and the operator reply.

curl -H "Authorization: Bearer bmai_sk_..." https://busymate.ai/api/v1/conversations

Every response is JSON. A successful call is {"ok": true, "data": ...}; an error is {"error": "...", "detail": "..."} with a stable error code (missing_api_key, invalid_api_key, forbidden, bad_request, rate_limited, and so on) you can branch on without parsing prose.

3. List and read conversations

GET /api/v1/conversations returns {"ok": true, "data": [Conversation, ...]} for the workspace, newest first, and GET /api/v1/conversations/{id} returns {"ok": true, "data": <transcript>}. GET /api/v1/interventions lists the human-handoff queue the same way. All three work with a read or a write key. Responses are rate limited; a call over the limit returns 429 with a Retry-After header, so back off and retry rather than looping. When the limiter reports it, the response also carries RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset — the full machine-readable shapes, including which responses carry them, are on the OpenAPI document below.

4. Post an operator reply

POST /api/v1/interventions/{id}/reply with a JSON body carrying your message posts an operator reply into a handed-off conversation, exactly as a teammate reply from the Inbox does — the {id} is an intervention id from the queue above. This needs a write-scoped key; a read key is refused. Every call — read or write — is recorded in your audit trail with the key that made it.

5. Rotate or revoke

Rotate a key to replace it with a fresh one that keeps the same label and scope; the old value stops working the moment you rotate. Revoke a key to stop it immediately with no replacement. Do either from the same card, or with the rotate_api_key and revoke_api_key tools on the MCP server. The full machine-readable description of the REST surface is published as an OpenAPI document at /api/v1/openapi.json, linked from the API keys card.

Verify

1. Confirm the new key is listed with its label, prefix and scope in Connections.
2. Call GET /api/v1/conversations with the key and confirm a JSON list comes back.
3. Read one conversation by id and confirm its transcript.
4. With a write key, post a reply to an intervention and confirm it appears in the Inbox conversation.
5. Rotate the key and confirm the old value now returns an unauthorized error.