> ## 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.

# Use the Beenos Solutions REST API in Your Application

> Use the Beenos Solutions REST API to manage knowledge bases, run queries, and chat with agents programmatically from any application.

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.

<Steps>
  <Step title="Open API Keys settings">
    In your workspace, navigate to **Settings** and click **API Keys** in the left sidebar.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Base URL and authentication

All API requests are sent to the following base URL:

```
https://api.beenossolutions.com/v1
```

Authenticate every request by including your API key in the `Authorization` header as a Bearer token:

```
Authorization: Bearer YOUR_API_KEY
```

Here is a simple example that lists all agents in your workspace:

```bash theme={null}
curl https://api.beenossolutions.com/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY"
```

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.

| Plan       | Rate Limit             |
| ---------- | ---------------------- |
| Free       | 60 requests / minute   |
| Pro        | 300 requests / minute  |
| Enterprise | Custom — contact sales |

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.

| Status Code | Name                  | Description                                                                                                               |
| ----------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `401`       | Unauthorized          | The API key is missing or invalid. Check that your `Authorization` header is correctly formatted.                         |
| `403`       | Forbidden             | The API key does not have permission to perform the requested action. Check the key's scope and workspace access.         |
| `404`       | Not Found             | The requested resource does not exist. Verify the resource ID or URL path is correct.                                     |
| `429`       | Rate Limit Exceeded   | You have sent too many requests in the current time window. Slow down your request rate and retry after the reset period. |
| `500`       | Internal Server Error | An unexpected error occurred on the Beenos Solutions side. If this persists, contact support.                             |

All error responses include a JSON body with a `message` field that provides a human-readable explanation of the problem.

<Note>
  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](/api-reference/introduction).
</Note>