API Reference

Complete reference for the BimpeAI Console REST API — authentication, response envelopes, pagination, rate limiting, and error codes.

The BimpeAI Console API is a REST API served from https://api.bimpe.ai. All paths are prefixed with /api/v1/console.

Authentication

Every request must carry a secret API key in one of two headers:

Authorization: Bearer sk_...

X-Api-Key: sk_...

Keys are scope-restricted. Calling an endpoint your key does not have access to returns a 403 insufficient_scope error.

Response envelopes

Single-resource responses wrap the payload in data:

{ "message": "Agent retrieved.", "data": { ... } }

List responses add a meta object:

{
  "message": "Agents retrieved.",
  "data": [ ... ],
  "meta": {
    "total_count": 42,
    "page_count": 3,
    "current_page": 1,
    "limit": 20,
    "has_next_page": true,
    "has_previous_page": false
  }
}

Pagination

List endpoints accept the following query parameters:

Parameter	Default	Notes
`page`	`1`	Page number
`limit`	`20`	Results per page; maximum `100`
`search`	—	Text filter (endpoint-specific)
`sort`	—	Field name; prefix with `-` for descending order

The meta field in every list response is a PaginationMeta object with total_count, page_count, current_page, limit, has_next_page, and has_previous_page.

Rate limiting

The API returns rate-limit state on every response:

Header	Description
`X-RateLimit-Limit`	Requests allowed per window
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

A 429 response also includes Retry-After (seconds to wait before retrying).

Idempotency

Write requests accept an Idempotency-Key header. Submitting the same key twice within the idempotency window returns the original response without re-executing the operation.

Request correlation

Send an X-Request-Id header on any request; the API echoes it back in the response. Useful for correlating logs across systems.

Error codes

All error responses carry a code field:

Code	Meaning
`validation_error`	Request body or params failed validation
`bad_request`	Malformed request
`unauthorized`	No credentials supplied
`api_key_missing`	`Authorization` / `X-Api-Key` header absent
`api_key_invalid`	Key does not exist or has been revoked
`api_key_expired`	Key has passed its expiry date
`insufficient_scope`	Key lacks the required scope for this endpoint
`forbidden`	Authenticated but not permitted
`not_found`	Resource does not exist
`conflict`	State conflict (e.g., duplicate resource)
`rate_limited`	Synonym for `too_many_requests` in some paths
`too_many_requests`	Rate limit exceeded
`not_implemented`	Endpoint exists but is not yet active
`agent_limit_reached`	Account agent quota exhausted
`internal_error`	Unexpected server-side failure

Known limitations

GET /api/v1/console/calls currently returns not_implemented. Call listing is coming soon.

Conversation message streams use Server-Sent Events. Because SSE does not support request headers, the API issues a single-use ?ticket= token from the stream-ticket endpoint. Pass that token as a query parameter when opening the event stream; it expires after first use.

Sections

Agents — create and manage agents, knowledge bases, channels, integrations, and conversation flows
Workflows — build and manage automation workflows
Conversations — list conversations, send messages, and stream replies
Calls — call history (coming soon)
CORS and the playground — required CORS configuration for the interactive try-it UI