> ## Documentation Index
> Fetch the complete documentation index at: https://guide.beenos-solutions.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Beenos Solutions REST API — Overview and Getting Started

> Overview of the Beenos Solutions REST API: base URL, versioning, request and response formats, error codes, and pagination for all endpoints.

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.

```bash theme={null}
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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```bash theme={null}
# 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.

<Note>
  Before making API requests, you need a valid API key. See the [Authentication](/api-reference/authentication) page to learn how to create and use your API key.
</Note>