Authentication
Every request is authenticated with a workspace API key sent as Authorization: Bearer YOUR_API_KEY. Responses use the envelope { status, message, data }.
- Open Setting → API keys in your workspace and create a key.
- Pick the scopes the key needs. Leave out what it should not do.
- Copy the key. It is shown only once; only its hash is stored.
Request
curl -X GET "https://www.beamvia.com/api/v1/channel" \
-H "Authorization: Bearer YOUR_API_KEY"Scopes
| Scope | Grants |
|---|---|
| message:send | Send messages on any channel |
| conversation:read | List conversations and read their messages |
| conversation:write | Change conversation status and handler |
| contact:read | List and read contacts |
| contact:write | Create and update contacts |
| channel:read | List channels and their status |
| webhook:manage | Create and delete webhooks |
| event:write | Send events to the AI agent |
| plugin:read | Call plugin actions that read (e.g. list orders) |
| plugin:write | Call plugin actions that change data (e.g. create an order) |
Limits
Requests count against your plan's daily API quota per channel type, and sent messages against the daily message quota. Over the limit, requests return 429 until the next day (UTC).
Errors
Errors use the same envelope with status false and a readable message.
| Code | Meaning |
|---|---|
| 400 | Invalid request body or parameters |
| 401 | Missing, invalid or revoked API key |
| 402 | Your plan does not include this feature |
| 403 | The key lacks the required scope, or the channel is locked |
| 404 | Resource not found in this workspace |
| 409 | Conflict, for example the identity already belongs to another contact |
| 429 | Daily quota reached |
Response
{
"status": false,
"message": "Daily API request quota exceeded",
"data": null
}