# Read and reply over the REST API | Busymate AI Source: https://busymate.ai/docs/guides/api Last modified: 2026-09-13T09:04:37+03:00 Busymate AI 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](https://busymate.ai/console/connections), 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. ## 3. List and read conversations `GET /api/v1/conversations` returns recent conversations for the workspace, newest first, and `GET /api/v1/conversations/{id}` returns one conversation's transcript. `GET /api/v1/interventions` lists the human-handoff queue. All three work with a read or a write key. Responses are JSON and rate limited; a call over the limit returns `429` with a `Retry-After` header, so back off and retry rather than looping. ## 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. ### Where do I get the API key? You create it in Connections; it is shown once at creation. Only its prefix is stored, so if you lose it, rotate the key for a new value. ### Do I pass a tenant or account id in requests? No. The key is scoped to one workspace, so it already knows which workspace to act on; a request that names a different tenant is refused. ### What is the difference between a read and a write key? A read key can list and read conversations. A write key can additionally post an operator reply. Choose the narrowest scope your integration needs. ### Is the same key usable with the MCP server? Yes. The key authenticates the existing MCP endpoint, so an MCP client uses it as a Bearer token and reaches the same tenant tools the REST endpoints wrap. ### What happens when I hit the rate limit? The call returns `429` with a `Retry-After` header. Wait the stated time and retry; do not spin in a tight loop.