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

# API Reference

> Castari REST API documentation

# API Reference

The Castari API lets you programmatically manage agents, deployments, and invocations.

## Base URL

```
https://api.castari.com
```

## Authentication

All API requests require authentication via the `Authorization` header with a Bearer token.

### API Key (Recommended)

Include your API key as a Bearer token:

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

API keys look like: `cast_xxxxxxxx_xxxxxxxxxx`

Generate one in the [Castari Dashboard](https://app.castari.com).

### OAuth Token

You can also use a Clerk JWT token:

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

## Rate Limits

| Endpoint Type                                   | Limit               |
| ----------------------------------------------- | ------------------- |
| CRUD operations (GET, POST, PUT, PATCH, DELETE) | 100 requests/minute |
| Invocations                                     | 10 requests/minute  |

Rate limit headers are included in all responses:

| Header                  | Description                      |
| ----------------------- | -------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed         |
| `X-RateLimit-Remaining` | Requests remaining in window     |
| `X-RateLimit-Reset`     | Unix timestamp when limit resets |

When rate limited, you'll receive a `429 Too Many Requests` response:

```json theme={null}
{
  "detail": "Rate limit exceeded. Try again in 30 seconds."
}
```

## Errors

All errors return JSON with a `detail` field:

```json theme={null}
{
  "detail": "Agent not found"
}
```

### Error Codes

| Status | Meaning                                          |
| ------ | ------------------------------------------------ |
| `400`  | Bad Request — Invalid parameters                 |
| `401`  | Unauthorized — Missing or invalid authentication |
| `403`  | Forbidden — Insufficient permissions             |
| `404`  | Not Found — Resource doesn't exist               |
| `422`  | Validation Error — Invalid request body          |
| `429`  | Rate Limited — Too many requests                 |
| `500`  | Server Error — Something went wrong              |

### Validation Errors

For `422` responses, errors include field-level details:

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "slug"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

## Pagination

List endpoints support pagination:

```bash theme={null}
GET /api/v1/agents?limit=10&offset=0
```

| Parameter | Default | Description                 |
| --------- | ------- | --------------------------- |
| `limit`   | 20      | Max items to return (1-100) |
| `offset`  | 0       | Number of items to skip     |

## Endpoints Overview

### Agents

| Method   | Endpoint                        | Description                     |
| -------- | ------------------------------- | ------------------------------- |
| `GET`    | `/api/v1/agents`                | List all agents                 |
| `POST`   | `/api/v1/agents`                | Create an agent                 |
| `GET`    | `/api/v1/agents/{slug}`         | Get agent details               |
| `PATCH`  | `/api/v1/agents/{slug}`         | Update an agent                 |
| `DELETE` | `/api/v1/agents/{slug}`         | Delete an agent                 |
| `POST`   | `/api/v1/agents/{slug}/deploy`  | Deploy an agent                 |
| `DELETE` | `/api/v1/agents/{slug}/sandbox` | Stop an agent (destroy sandbox) |
| `POST`   | `/api/v1/agents/{slug}/invoke`  | Invoke an agent                 |

### Secrets

| Method   | Endpoint                              | Description     |
| -------- | ------------------------------------- | --------------- |
| `GET`    | `/api/v1/agents/{slug}/secrets`       | List secrets    |
| `POST`   | `/api/v1/agents/{slug}/secrets`       | Set a secret    |
| `DELETE` | `/api/v1/agents/{slug}/secrets/{key}` | Delete a secret |

### Sessions

| Method   | Endpoint                              | Description      |
| -------- | ------------------------------------- | ---------------- |
| `GET`    | `/api/v1/agents/{slug}/sessions`      | List sessions    |
| `DELETE` | `/api/v1/agents/{slug}/sessions/{id}` | Delete a session |

### Invocations

| Method | Endpoint                            | Description             |
| ------ | ----------------------------------- | ----------------------- |
| `GET`  | `/api/v1/agents/{slug}/invocations` | List invocation history |

### API Keys

| Method   | Endpoint                | Description          |
| -------- | ----------------------- | -------------------- |
| `GET`    | `/api/v1/api-keys`      | List all API keys    |
| `POST`   | `/api/v1/api-keys`      | Create a new API key |
| `DELETE` | `/api/v1/api-keys/{id}` | Revoke an API key    |

### Usage

| Method | Endpoint              | Description         |
| ------ | --------------------- | ------------------- |
| `GET`  | `/api/v1/usage`       | Get usage summary   |
| `GET`  | `/api/v1/usage/daily` | Get daily breakdown |

### Storage (Buckets)

| Method   | Endpoint                             | Description            |
| -------- | ------------------------------------ | ---------------------- |
| `GET`    | `/api/v1/buckets`                    | List all buckets       |
| `POST`   | `/api/v1/buckets`                    | Create a bucket        |
| `GET`    | `/api/v1/buckets/{slug}`             | Get bucket details     |
| `PATCH`  | `/api/v1/buckets/{slug}`             | Update a bucket        |
| `DELETE` | `/api/v1/buckets/{slug}`             | Delete a bucket        |
| `POST`   | `/api/v1/buckets/{slug}/credentials` | Set bucket credentials |
| `POST`   | `/api/v1/buckets/{slug}/test`        | Test bucket connection |

### Mounts

| Method   | Endpoint                            | Description              |
| -------- | ----------------------------------- | ------------------------ |
| `GET`    | `/api/v1/agents/{slug}/mounts`      | List mounts for an agent |
| `POST`   | `/api/v1/agents/{slug}/mounts`      | Add a mount              |
| `PATCH`  | `/api/v1/agents/{slug}/mounts/{id}` | Update a mount           |
| `DELETE` | `/api/v1/agents/{slug}/mounts/{id}` | Remove a mount           |

### Files (Managed Storage v2)

| Method   | Endpoint                      | Description          |
| -------- | ----------------------------- | -------------------- |
| `GET`    | `/api/v1/files`               | List files           |
| `POST`   | `/api/v1/files`               | Upload a file        |
| `GET`    | `/api/v1/files/{id}`          | Get file metadata    |
| `PATCH`  | `/api/v1/files/{id}`          | Update file metadata |
| `DELETE` | `/api/v1/files/{id}`          | Delete a file        |
| `GET`    | `/api/v1/files/{id}/download` | Download a file      |
| `GET`    | `/api/v1/files/usage`         | Get storage usage    |

## SDKs

For easier integration, use our official SDKs:

* **TypeScript/JavaScript:** `npm install @castari/sdk`
* **CLI:** `npm install -g @castari/cli`

See the [SDK Reference](/sdk/overview) for details.

## Example: Full Workflow

```bash theme={null}
# 1. Create an agent
curl -X POST https://api.castari.com/api/v1/agents \
  -H "Authorization: Bearer cast_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Agent", "slug": "my-agent"}'

# 2. Deploy the agent
curl -X POST https://api.castari.com/api/v1/agents/my-agent/deploy \
  -H "Authorization: Bearer cast_xxx"

# 3. Invoke the agent
curl -X POST https://api.castari.com/api/v1/agents/my-agent/invoke \
  -H "Authorization: Bearer cast_xxx" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello, world!"}'
```