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:

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.

OAuth Token

You can also use a Clerk JWT token:

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:

{
  "detail": "Rate limit exceeded. Try again in 30 seconds."
}

Errors

All errors return JSON with a detail field:

{
  "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:

{
  "detail": [
    {
      "loc": ["body", "slug"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Pagination

List endpoints support pagination:

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 for details.

Example: Full Workflow

# 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!"}'

​API Reference

​Base URL

​Authentication

​API Key (Recommended)

​OAuth Token

​Rate Limits

​Errors

​Error Codes

​Validation Errors

​Pagination

​Endpoints Overview

​Agents

​Secrets

​Sessions

​Invocations

​API Keys

​Usage

​Storage (Buckets)

​Mounts

​Files (Managed Storage v2)

​SDKs

​Example: Full Workflow