> ## Documentation Index
> Fetch the complete documentation index at: https://docs.versuno.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Guide

> Authentication, quick start examples, error handling, and key endpoints for the Versuno Public API.

## Authentication

Every request must include your API key as a Bearer token in the `Authorization` header.

```
Authorization: Bearer YOUR_API_KEY
```

Get your API key at [versuno.ai](https://versuno.ai/).

<Warning>
  Store your API key in an environment variable or secret manager, never in source code. Rotate it immediately if compromised.
</Warning>

## Base URL

```
https://versuno.ai/api/public
```

All endpoints are relative to this base URL.

## Quick Start

### List your assets

```bash theme={null}
curl https://versuno.ai/api/public/assets \
  -H "Authorization: Bearer $VERSUNO_API_KEY"
```

### Create an asset

```bash theme={null}
curl -X POST https://versuno.ai/api/public/assets \
  -H "Authorization: Bearer $VERSUNO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Customer support persona",
    "assetType": "persona",
    "content": "You are a friendly and concise customer support agent..."
  }'
```

### Save a version checkpoint

```bash theme={null}
curl -X POST https://versuno.ai/api/public/assets/{assetId}/versions \
  -H "Authorization: Bearer $VERSUNO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Improved tone" }'
```

### Revert to a previous version

```bash theme={null}
curl -X POST https://versuno.ai/api/public/assets/{assetId}/versions/{versionId}/revert \
  -H "Authorization: Bearer $VERSUNO_API_KEY"
```

### Query a brain

List the public brains, then run a semantic query against one:

```bash theme={null}
curl https://versuno.ai/api/public/brains/public \
  -H "Authorization: Bearer $VERSUNO_API_KEY"

curl -X POST https://versuno.ai/api/public/brains/BRAIN_ID/query \
  -H "Authorization: Bearer $VERSUNO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "How do I get started?" }'
```

Brain queries return HTTP `200` with a `{ success, error, data }` envelope, so check `success` rather than the status code. The brain-level query is metered. See [Brains](/brains/overview) for the full model.

## Rate Limits

The Public API enforces a limit of **50 requests per minute** per API key.

When you exceed the limit, the API returns `429`:

```json theme={null}
{
  "error": "Rate limit exceeded"
}
```

Rate limit state is included in every response header:

| Header                  | Description                                |
| ----------------------- | ------------------------------------------ |
| `X-RateLimit-Limit`     | Maximum requests allowed per window (50)   |
| `X-RateLimit-Remaining` | Requests remaining in the current window   |
| `X-RateLimit-Reset`     | Unix timestamp (ms) when the window resets |

## Error Handling

The API uses standard HTTP status codes.

| Status | Meaning      | What to do                                                            |
| ------ | ------------ | --------------------------------------------------------------------- |
| `200`  | Success      | Process the response normally                                         |
| `400`  | Bad Request  | Check request body: a required field is missing or invalid            |
| `401`  | Unauthorized | Verify your API key is correct and not suspended                      |
| `404`  | Not Found    | The resource doesn't exist or belongs to another user                 |
| `409`  | Conflict     | The operation conflicts with the current state (e.g. already trashed) |
| `500`  | Server Error | Retry with backoff, contact support if persistent                     |

### Error response format

All errors return a JSON body with a single `error` field:

```json theme={null}
{
  "error": "Invalid API key"
}
```

## Key Endpoints

| Method   | Endpoint                                        | Description                           |
| -------- | ----------------------------------------------- | ------------------------------------- |
| `GET`    | `/assets`                                       | List all assets with optional filters |
| `POST`   | `/assets`                                       | Create a new asset                    |
| `GET`    | `/assets/{assetId}`                             | Get a single asset                    |
| `PATCH`  | `/assets/{assetId}/update`                      | Update an asset                       |
| `POST`   | `/assets/{assetId}/trash`                       | Move an asset to trash                |
| `PUT`    | `/assets/{assetId}/trash`                       | Restore an asset from trash           |
| `DELETE` | `/assets/{assetId}/trash`                       | Permanently delete a trashed asset    |
| `GET`    | `/projects`                                     | List all projects                     |
| `POST`   | `/projects`                                     | Create a project                      |
| `GET`    | `/assets/{assetId}/versions`                    | List version history for an asset     |
| `POST`   | `/assets/{assetId}/versions`                    | Save a version checkpoint             |
| `POST`   | `/assets/{assetId}/versions/{versionId}/revert` | Revert to a version                   |
| `GET`    | `/brains/public`                                | List public brains                    |
| `GET`    | `/brains/{id}`                                  | Get a brain                           |
| `GET`    | `/brains/{id}/containers`                       | List a brain's containers             |
| `GET`    | `/brains/{id}/nodes/{nodeId}`                   | Get a single node                     |
| `POST`   | `/brains/{id}/query`                            | Semantic query over a brain (metered) |

<Note>
  Check the [API Reference](/api-reference/assets/list-all-assets) for complete endpoint documentation with interactive examples, full request/response schemas, and parameter descriptions.
</Note>