Beenos Solutions REST API — Overview and Getting Started

The Beenos Solutions REST API gives you programmatic access to every capability of the platform — from ingesting content into your knowledge base to deploying and chatting with AI agents. All requests and responses use JSON, follow predictable resource-oriented URLs, and return standard HTTP response codes. You can use any HTTP client, scripting language, or integration tool that supports HTTPS to interact with the API.

Base URL

Every API request targets the following base URL. Include this prefix before all endpoint paths shown in this reference.

https://api.beenossolutions.com/v1

Request Format

Send all request bodies as JSON and include the Content-Type: application/json header on every request that carries a body. Requests that upload files (such as document sources) use multipart/form-data instead — those endpoints note the difference explicitly.

curl -X POST https://api.beenossolutions.com/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Support Bot", "knowledge_base_ids": ["kb_abc123"] }'

Response Format

Every successful response returns a JSON object with a top-level data key containing the requested resource or list of resources, and a meta key with request tracing information. Use the request_id when contacting support about a specific API call.

{
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Error Format

When a request fails, the API returns an error object in place of data. The code field is a machine-readable string you can use for programmatic error handling, while message provides a human-readable explanation. The request_id matches the failed request for traceability.

{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found.",
    "request_id": "req_abc123"
  }
}

Common error codes and their corresponding HTTP status codes are listed below.

HTTP Status	Error Code	Meaning
`400`	`invalid_request`	The request body is malformed or missing required fields
`401`	`unauthorized`	No API key provided or the key is invalid
`403`	`forbidden`	Your API key does not have permission for this action
`404`	`not_found`	The requested resource does not exist
`422`	`unprocessable_entity`	The request is well-formed but contains invalid values
`429`	`rate_limited`	You have exceeded the request rate limit
`500`	`internal_error`	An unexpected error occurred on our servers

Pagination

List endpoints use cursor-based pagination, which is stable and efficient even as your data changes between requests. Pass a limit query parameter to control how many records are returned per page (default 20, maximum 100). When more records are available, the response includes a next_cursor value under meta — pass that value as the cursor query parameter in your next request to retrieve the following page.

# First page
curl "https://api.beenossolutions.com/v1/knowledge-base/sources?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Next page using the cursor from the previous response
curl "https://api.beenossolutions.com/v1/knowledge-base/sources?limit=20&cursor=cur_xyz789" \
  -H "Authorization: Bearer YOUR_API_KEY"

When next_cursor is absent from a response, you have reached the last page of results.

Versioning

The API version is embedded directly in the URL path (for example, /v1/). This means breaking changes will always be introduced under a new version path, and your existing integrations continue to work without modification until you choose to migrate. The current stable version is v1. When a new version is released, Beenos Solutions will publish a migration guide and provide a deprecation window before retiring older versions.

Before making API requests, you need a valid API key. See the Authentication page to learn how to create and use your API key.

​Base URL

​Request Format

​Response Format

​Error Format

​Pagination

​Versioning

Base URL

Request Format

Response Format

Error Format

Pagination

Versioning