Skip to main content

​
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. 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 TypeLimit
CRUD operations (GET, POST, PUT, PATCH, DELETE)100 requests/minute
Invocations10 requests/minute
Rate limit headers are included in all responses:
HeaderDescription
X-RateLimit-LimitMaximum requests allowed
X-RateLimit-RemainingRequests remaining in window
X-RateLimit-ResetUnix 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

StatusMeaning
400Bad Request — Invalid parameters
401Unauthorized — Missing or invalid authentication
403Forbidden — Insufficient permissions
404Not Found — Resource doesn’t exist
422Validation Error — Invalid request body
429Rate Limited — Too many requests
500Server 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
ParameterDefaultDescription
limit20Max items to return (1-100)
offset0Number of items to skip

​
Endpoints Overview

​
Agents

MethodEndpointDescription
GET/api/v1/agentsList all agents
POST/api/v1/agentsCreate 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}/deployDeploy an agent
DELETE/api/v1/agents/{slug}/sandboxStop an agent (destroy sandbox)
POST/api/v1/agents/{slug}/invokeInvoke an agent

​
Secrets

MethodEndpointDescription
GET/api/v1/agents/{slug}/secretsList secrets
POST/api/v1/agents/{slug}/secretsSet a secret
DELETE/api/v1/agents/{slug}/secrets/{key}Delete a secret

​
Sessions

MethodEndpointDescription
GET/api/v1/agents/{slug}/sessionsList sessions
DELETE/api/v1/agents/{slug}/sessions/{id}Delete a session

​
Invocations

MethodEndpointDescription
GET/api/v1/agents/{slug}/invocationsList invocation history

​
API Keys

MethodEndpointDescription
GET/api/v1/api-keysList all API keys
POST/api/v1/api-keysCreate a new API key
DELETE/api/v1/api-keys/{id}Revoke an API key

​
Usage

MethodEndpointDescription
GET/api/v1/usageGet usage summary
GET/api/v1/usage/dailyGet daily breakdown

​
Storage (Buckets)

MethodEndpointDescription
GET/api/v1/bucketsList all buckets
POST/api/v1/bucketsCreate 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}/credentialsSet bucket credentials
POST/api/v1/buckets/{slug}/testTest bucket connection

​
Mounts

MethodEndpointDescription
GET/api/v1/agents/{slug}/mountsList mounts for an agent
POST/api/v1/agents/{slug}/mountsAdd 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)

MethodEndpointDescription
GET/api/v1/filesList files
POST/api/v1/filesUpload 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}/downloadDownload a file
GET/api/v1/files/usageGet 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!"}'