Skip to main content
The Beenos Solutions REST API gives you complete programmatic control over your workspace. You can use it to create and update knowledge bases, upload source documents, send messages to agents, and retrieve conversation history — all from your own application or automation pipeline. The API follows standard REST conventions and returns JSON for every response, making it straightforward to integrate with any language or framework.

​
Getting your API key

Before you can make any API requests, you need an API key associated with your workspace.
1

Open API Keys settings

In your workspace, navigate to Settings and click API Keys in the left sidebar.
2

Create a new key

Click Create Key, give the key a descriptive name (for example, production-backend or staging-tests), and optionally set an expiry date.
3

Copy your key

Click Create to generate the key. Copy the key value immediately — for security reasons, it is only shown once. Store it in a secure location such as an environment variable or secrets manager.

​
Base URL and authentication

All API requests are sent to the following base URL:
Authenticate every request by including your API key in the Authorization header as a Bearer token:
Here is a simple example that lists all agents in your workspace:
Never include your API key directly in client-side JavaScript or publicly accessible code. Always make API calls from a server-side environment where the key remains private.

​
Rate limits

API requests are subject to rate limits based on your current plan. If you exceed the limit, the API returns a 429 Too Many Requests response. Wait until the next rate limit window resets before retrying. If you consistently approach your plan’s rate limit, consider upgrading your plan or batching requests to reduce call frequency.

​
Error codes

The API uses standard HTTP status codes to indicate the outcome of a request. The table below covers the most common error responses you may encounter. All error responses include a JSON body with a message field that provides a human-readable explanation of the problem.
This page covers authentication and general API usage. For a full reference of every available endpoint — including request parameters, response schemas, and code examples — visit the REST API Reference.