API Reference

Reference·All endpoints

All endpoints are prefixed with /v1/. Authentication uses the X-API-Key header. Interactive docs are available at http://localhost:8000/docs (Swagger UI) when running locally.

Authentication

request header

X-API-Key: crwl_your_api_key_here

ℹ️

Every endpoint requires a valid API key scoped to the operation. Use scope * for full access during development.

Agents

Method	Path	Description	Scope
GET	/v1/agents	List agents. Query: `status`, `tags`, `limit`, `cursor`	`agents:read`
POST	/v1/agents	Create agent	`agents:write`
GET	/v1/agents/{id}	Get agent by ID	`agents:read`
PATCH	/v1/agents/{id}	Update name, description, tags, config	`agents:write`
DELETE	/v1/agents/{id}	Delete agent and all data	`agents:write`
GET	/v1/agents/{id}/status	Get cached status (Redis, 60s TTL)	`agents:read`
PATCH	/v1/agents/{id}/status	Update status and optional session_id	`agents:write`
GET	/v1/agents/{id}/status/history	Status transition history. Query: `limit` (default 20)	`agents:read`
POST	/v1/agents/{id}/tags	Add tags (`{"tags": ["prod"]}`)	`agents:write`
DELETE	/v1/agents/{id}/tags/{tag}	Remove a tag	`agents:write`
GET	/v1/agents/{id}/relations	List agent relations	`agents:read`
POST	/v1/agents/{id}/relations	Add relation: `type` (supervisor/collaborator/delegate), `related_agent_id`	`agents:write`
DELETE	/v1/agents/{id}/relations/{rel_id}	Remove relation	`agents:write`
GET	/v1/agents/{id}/export	Export agent as streaming JSON (all memories, actions, episodes)	`agents:read`
POST	/v1/agents/import	Import agent from exported JSON. Atomic with savepoint.	`agents:write`

Example: create an agent

curl

curl -X POST http://localhost:8000/v1/agents \
  -H "X-API-Key: crwl_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "sales-agent", "tags": ["production"], "config": {"model": "claude-opus-4-8"}}'

# Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "sales-agent",
  "status": "idle",
  "tags": ["production"],
  "config": {"model": "claude-opus-4-8"},
  "created_at": "2025-06-14T12:00:00Z"
}

Memory

Method	Path	Description
POST	/v1/agents/{id}/memory	Save a long-term memory. Body: `content`, `importance` (0–1), optional `source`, `session_id`
GET	/v1/agents/{id}/memory	List memories. Query: `limit`, `cursor`, `source`
POST	/v1/agents/{id}/memory/recall	Semantic recall. Body: `query`, `limit` (default 10), optional `min_similarity`
DELETE	/v1/agents/{id}/memory/{memory_id}	Delete a specific memory
GET	/v1/agents/{id}/memory/stats	Count by source, average importance, oldest/newest
POST	/v1/agents/{id}/memory/messages	Append short-term message. Body: `session_id`, `role`, `content`
GET	/v1/agents/{id}/memory/messages	Get short-term messages. Query: `session_id`
DELETE	/v1/agents/{id}/memory/messages	Clear short-term memory for a session

Example: semantic recall

curl

curl -X POST http://localhost:8000/v1/agents/$AGENT_ID/memory/recall \
  -H "X-API-Key: crwl_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "user language preferences", "limit": 5}'

# Response
[
  {
    "id": "mem-uuid",
    "content": "User prefers Python over JavaScript",
    "similarity": 0.94,
    "importance": 0.9,
    "source": "extracted",
    "created_at": "2025-06-10T09:00:00Z"
  }
]

Actions

Method	Path	Description
POST	/v1/agents/{id}/actions	Log an action. Body: `tool_name`, `input_params`, `output_result`, `status`, optional `duration_ms`, `session_id`
GET	/v1/agents/{id}/actions	List actions. Query: `tool`, `status`, `limit` (default 50, max 500), `cursor`
GET	/v1/agents/{id}/actions/{action_id}	Get a single action
GET	/v1/agents/{id}/actions/stats	Aggregated stats: counts, error rate, avg duration by tool

Sessions

Method	Path	Description
POST	/v1/agents/{id}/sessions	Create session. Body: optional `episode_id`, `metadata`
GET	/v1/agents/{id}/sessions	List sessions for agent
GET	/v1/sessions/{session_id}	Get session details
POST	/v1/sessions/{session_id}/close	Close session and extract memories from conversation using Claude

Episodes

Method	Path	Description
POST	/v1/agents/{id}/episodes	Create episode. Body: `title`, optional `description`
GET	/v1/agents/{id}/episodes	List episodes
GET	/v1/agents/{id}/episodes/{episode_id}	Get episode with session list
POST	/v1/agents/{id}/episodes/{episode_id}/complete	Mark episode complete
POST	/v1/agents/{id}/episodes/{episode_id}/recall	Semantic recall scoped to this episode's memories

Context (Blackboard)

Method	Path	Description
GET	/v1/context/{namespace}	List all keys in namespace
GET	/v1/context/{namespace}/{key}	Read value (current version)
PUT	/v1/context/{namespace}/{key}	Write value. Body: `{"value": any}`. Increments version.
DELETE	/v1/context/{namespace}/{key}	Delete key
GET	/v1/context/{namespace}/{key}/history	Version history for a key
POST	/v1/context/{namespace}/{key}/rollback	Rollback to a specific version. Body: `{"version": 3}`
GET	/v1/context/{namespace}/subscribe	SSE stream. Emits events when any key in the namespace changes.

Evaluations

Method	Path	Description
POST	/v1/agents/{id}/evaluations	Create evaluation. Body: `prompt`, `response`, optional `expected`, `session_id`, `variant`
GET	/v1/agents/{id}/evaluations	List evaluations. Query: `variant`, `limit`, `cursor`
GET	/v1/agents/{id}/evaluations/summary	A/B summary: avg score per variant, anomaly counts

Prompts

Method	Path	Description
POST	/v1/agents/{id}/prompts	Create prompt version. Body: `name`, `content`, optional `description`
GET	/v1/agents/{id}/prompts	List all versions
GET	/v1/agents/{id}/prompts/{version_id}	Get specific version with diff from previous
POST	/v1/agents/{id}/prompts/{version_id}/activate	Mark version as active

Webhooks

Method	Path	Description
POST	/v1/webhooks	Register webhook. Body: `url`, `events` (array), optional `secret`
GET	/v1/webhooks	List webhooks
DELETE	/v1/webhooks/{webhook_id}	Delete webhook

Webhook events include: agent.status_changed, memory.extracted, action.error, anomaly.detected.

Auth / API Keys

Method	Path	Description
POST	/v1/auth/keys	Create API key. Body: `name`, `scopes`, optional `expires_at`, `rate_limit`
GET	/v1/auth/keys	List API keys (values are never returned after creation)
DELETE	/v1/auth/keys/{key_id}	Revoke API key immediately

Other Endpoints

Method	Path	Description
GET	/v1/audit	Read-only audit log of all API operations. Query: `agent_id`, `action`, `limit`
GET	/v1/usage	Resource usage counts for the current tenant
GET	/metrics	Prometheus metrics. Requires `Authorization: Bearer METRICS_TOKEN` from non-localhost
GET	/health	Health check: DB + Redis status

Available Scopes

Scope	Access
`*`	All operations (superkey)
`agents:read`	Read agents and status
`agents:write`	Create, update, delete agents
`memory:read`	Read and recall memories
`memory:write`	Save and delete memories
`actions:read`	Read action log
`actions:write`	Log new actions
`context:read`	Read blackboard values
`context:write`	Write blackboard values

← Previous Core Concepts Next → Python SDK