The One Bear Public API lets your own systems read and update the data in your One Bear workspace: conversations, messages, customers, orders and products. Webhooks push events to you; see the Webhooks page.Base URL#
Every path is relative to it and starts with /api/v1/companies/{companyId}/.... Your companyId is the workspace id shown in Settings > Developer.1. Create an API key#
In One Bear go to Settings > Developer > API keys > Create key. Give the key a name and pick only the scopes it needs. The full key (ob_live_...) is shown once - copy it now; One Bear stores only a hash. You can create several keys with different scopes and revoke any of them at any time (revocation is immediate).2. Authenticate#
Send the key as a Bearer token on every request:Scopes#
| Scope | Grants |
|---|
chat:read | list/get rooms and messages |
customers:read | list/get customers |
customers:write | create and update customers (includes read) |
orders:read | list/get orders |
products:read | list/get products |
A request outside the key's scopes returns 403. A companyId that is not the key's own workspace also returns 403.List endpoints accept pageSize (default 20, max 100) and continuationToken.{ "data": [ ... ], "continuationToken": "...", "hasMore": true }
continuationToken back unchanged to fetch the next page; stop when hasMore is false.Errors#
| Status | Meaning |
|---|
| 400 | validation failed - body { "code", "message" } |
| 401 | missing, malformed or revoked key |
| 403 | scope or workspace mismatch |
| 404 | resource not found in this workspace |
| 409 | conflict, e.g. duplicate |
| 429 | rate limited - retry after the Retry-After header |
Every response carries an X-Correlation-Id header. Quote it when you contact support.Good to know#
Timestamps are ISO-8601 UTC strings or Unix milliseconds (*Timestamp fields).
Internal notes written by agents are never returned by the messages endpoints.
Sending messages through the API is not available yet.
Keep keys on your server. Never ship an ob_live_ key in a browser or mobile app.
Modified at 2026-09-16 07:22:25
