API Documentation - ChaozCode

Authentication

All API requests require authentication using a Bearer token. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Getting Your API Key

Log in to your dashboard at chaozcode.com/app/dashboard
Navigate to Settings → API Keys
Click "Generate New Key"
Copy and securely store your key

API Key Types

Type	Scope	Use Case
`development`	Full access, rate limited	Local development & testing
`production`	Full access, higher limits	Production applications
`readonly`	GET requests only	Analytics, reporting
`restricted`	Specific endpoints only	Third-party integrations

Example Request

curl -X GET "https://api.chaozcode.com/v2/user/me" \
  -H "Authorization: Bearer cc_live_abc123..." \
  -H "Content-Type: application/json"

Rate Limits

API requests are rate limited based on your plan. Limits are applied per API key.

Plan	Requests/Min	Requests/Day	Burst Limit
Free	10	100	20
Pro	60	10,000	100
Team	300	100,000	500
Enterprise	1,000+	Unlimited	Custom

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1706652000
X-RateLimit-RetryAfter: 30

Handling Rate Limits

When rate limited, you'll receive a 429 Too Many Requests response. Implement exponential backoff:

async function apiCallWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429) {
        const delay = Math.pow(2, i) * 1000;
        await new Promise(r => setTimeout(r, delay));
      } else throw error;
    }
  }
}

Error Handling

All errors return a consistent JSON structure:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request body is missing required field 'prompt'",
    "details": {
      "field": "prompt",
      "reason": "required"
    },
    "requestId": "req_abc123"
  }
}

Error Codes

HTTP	Code	Description
400	`INVALID_REQUEST`	Malformed request or missing parameters
401	`UNAUTHORIZED`	Invalid or missing API key
403	`FORBIDDEN`	API key lacks required permissions
404	`NOT_FOUND`	Resource doesn't exist
409	`CONFLICT`	Resource already exists
422	`VALIDATION_ERROR`	Request validation failed
429	`RATE_LIMITED`	Too many requests
500	`INTERNAL_ERROR`	Server error (retry safe)
503	`SERVICE_UNAVAILABLE`	Temporary outage

AI Query Endpoints

Core endpoints for AI-powered queries and completions.

POST /query

Send a prompt to the AI and receive a completion. Supports multiple models and customization options.

Parameter	Type	Required	Description
`prompt`	string	Yes	The input prompt (max 100,000 chars)
`model`	string	No	Model ID: gpt-4, claude-3-sonnet, gemini-pro
`systemPrompt`	string	No	System instructions for the AI
`temperature`	number	No	Creativity (0.0-2.0, default: 0.7)
`maxTokens`	integer	No	Maximum response tokens (default: 4096)
`topP`	number	No	Nucleus sampling (0.0-1.0)
`stop`	array	No	Stop sequences
`stream`	boolean	No	Enable streaming response
`context`	object	No	Additional context from Memory Spine

Request Example

curl -X POST "https://api.chaozcode.com/v2/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Explain the difference between REST and GraphQL",
    "model": "gpt-4",
    "temperature": 0.7,
    "maxTokens": 1000
  }'

200 Success Response

{
  "id": "query_abc123",
  "text": "REST and GraphQL are both API architectures...",
  "model": "gpt-4",
  "usage": {
    "promptTokens": 15,
    "completionTokens": 487,
    "totalTokens": 502
  },
  "finishReason": "stop",
  "createdAt": "2026-01-30T12:00:00Z"
}

POST /query/stream

Stream AI responses using Server-Sent Events (SSE). Same parameters as /query.

Stream Response Format

data: {"type":"start","id":"query_abc123"}

data: {"type":"delta","content":"REST "}

data: {"type":"delta","content":"and "}

data: {"type":"delta","content":"GraphQL..."}

data: {"type":"done","usage":{"totalTokens":502}}

POST /query/chat

Multi-turn chat completion with message history.

Parameter	Type	Required	Description
`messages`	array	Yes	Array of message objects with role and content
`model`	string	No	Model ID (default: gpt-4)
`conversationId`	string	No	Resume existing conversation

Request Example

{
  "messages": [
    {"role": "system", "content": "You are a helpful coding assistant."},
    {"role": "user", "content": "How do I create a React hook?"},
    {"role": "assistant", "content": "Here's how to create a custom React hook..."},
    {"role": "user", "content": "Can you show an example with useState?"}
  ],
  "model": "gpt-4"
}

GET /models

List all available AI models with their capabilities and pricing.

200 Response

{
  "models": [
    {
      "id": "gpt-4",
      "name": "GPT-4",
      "provider": "openai",
      "contextWindow": 128000,
      "inputPrice": 0.03,
      "outputPrice": 0.06,
      "capabilities": ["chat", "code", "analysis"]
    },
    {
      "id": "claude-3-sonnet",
      "name": "Claude 3 Sonnet",
      "provider": "anthropic",
      "contextWindow": 200000,
      "inputPrice": 0.003,
      "outputPrice": 0.015,
      "capabilities": ["chat", "code", "vision"]
    }
  ]
}

Memory Endpoints

Memory Spine API for persistent context and knowledge management. See Memory Spine API for the complete 62-tool MCP reference.

POST /memory/store

Store a new memory with content, tags, and metadata.

Parameter	Type	Required	Description
`id`	string	Yes	Unique memory identifier
`content`	string	Yes	Memory content (text, JSON, markdown)
`tags`	array	No	Categorization tags
`importance`	string	No	low, medium, high, critical
`metadata`	object	No	Additional key-value pairs

201 Success

{
  "ok": true,
  "id": "project-auth-v2",
  "vectorId": "vec_abc123",
  "createdAt": "2026-01-30T12:00:00Z"
}

POST /memory/search

Semantic search for relevant memories.

Parameter	Type	Required	Description
`query`	string	Yes	Natural language search query
`limit`	integer	No	Max results (default: 10, max: 100)
`tags`	array	No	Filter by tags
`minScore`	number	No	Minimum similarity (0.0-1.0)

200 Success

{
  "results": [
    {
      "id": "auth-implementation",
      "content": "Implemented OAuth2 with PKCE...",
      "score": 0.92,
      "tags": ["auth", "security"],
      "createdAt": "2026-01-29T10:00:00Z"
    }
  ],
  "total": 1,
  "took": 23
}

GET /memory/{id}

Retrieve a specific memory by ID.

PUT /memory/{id}

Update an existing memory. Creates a new version.

DELETE /memory/{id}

Soft delete a memory. Recoverable within 30 days.

GET /memory/stats

Get Memory Spine statistics.

200 Response

{
  "vectorCount": 5234,
  "storageBytes": 52428800,
  "version": "0.4.0",
  "avgResponseMs": 8,
  "status": "healthy"
}

POST /memory/context

Build an optimized context window for LLM queries.

Parameter	Type	Required	Description
`query`	string	Yes	Task or question
`maxTokens`	integer	No	Max context size (default: 4000)

Codebase Endpoints

Code analysis and generation endpoints.

POST /codebase/analyze

Analyze codebase structure, dependencies, and patterns.

Parameter	Type	Required	Description
`files`	array	Yes	Array of {path, content} objects
`language`	string	No	Primary language (auto-detected)
`depth`	string	No	basic, standard, deep (default: standard)

200 Success

{
  "summary": {
    "totalFiles": 45,
    "totalLines": 8234,
    "languages": {"typescript": 80, "css": 15, "json": 5}
  },
  "structure": {
    "components": 12,
    "hooks": 5,
    "utils": 8,
    "tests": 20
  },
  "dependencies": [...],
  "suggestions": [...]
}

POST /codebase/generate

Generate code based on context and task description.

Parameter	Type	Required	Description
`task`	string	Yes	What to generate
`context`	array	No	Relevant code files for context
`language`	string	No	Target language
`style`	object	No	Code style preferences

POST /codebase/review

AI code review with suggestions and issue detection.

Parameter	Type	Required	Description
`code`	string	Yes	Code to review
`language`	string	No	Programming language
`focus`	array	No	Focus areas: security, performance, style, bugs

POST /codebase/fix

Get AI-powered fix suggestions for code issues.

Parameter	Type	Required	Description
`code`	string	Yes	Code with issues
`error`	string	No	Error message or description
`context`	string	No	Additional context

Agent Endpoints

AI agent orchestration and task management.

POST /agents/spawn

Spawn a specialized AI agent for a task.

Parameter	Type	Required	Description
`type`	string	Yes	Agent type: explore, task, code-review, general-purpose
`prompt`	string	Yes	Task description
`model`	string	No	Override default model
`timeout`	integer	No	Timeout in seconds (default: 300)

202 Accepted

{
  "agentId": "agent_abc123",
  "type": "explore",
  "status": "running",
  "createdAt": "2026-01-30T12:00:00Z"
}

GET /agents/{agentId}

Get agent status and results.

200 Response

{
  "agentId": "agent_abc123",
  "type": "explore",
  "status": "completed",
  "result": {
    "summary": "Found 5 authentication-related files...",
    "files": [...],
    "confidence": 0.92
  },
  "usage": {"tokens": 1523, "cost": 0.045},
  "duration": 3.2
}

GET /agents/types

List available agent types and their capabilities.

DELETE /agents/{agentId}

Cancel a running agent.

Project Endpoints

Manage projects and their configurations.

GET /projects

List all projects for the authenticated user.

POST /projects

Create a new project.

Parameter	Type	Required	Description
`name`	string	Yes	Project name
`description`	string	No	Project description
`settings`	object	No	Project configuration

GET /projects/{projectId}

Get project details.

PATCH /projects/{projectId}

Update project settings.

DELETE /projects/{projectId}

Delete a project and all associated data.

User Endpoints

User account and settings management.

GET /user/me

Get current user profile.

200 Response

{
  "id": "user_abc123",
  "email": "developer@example.com",
  "name": "Jane Developer",
  "plan": "pro",
  "usage": {
    "apiCalls": 4523,
    "limit": 10000,
    "resetAt": "2026-02-01T00:00:00Z"
  },
  "createdAt": "2025-06-15T10:00:00Z"
}

PATCH /user/me

Update user profile.

GET /user/usage

Get detailed usage statistics.

GET /user/api-keys

List all API keys (masked).

POST /user/api-keys

Generate a new API key.

DELETE /user/api-keys/{keyId}

Revoke an API key.

Webhook Endpoints

Configure webhooks to receive real-time event notifications.

GET /webhooks

List configured webhooks.

POST /webhooks

Create a new webhook.

Parameter	Type	Required	Description
`url`	string	Yes	Webhook endpoint URL (HTTPS)
`events`	array	Yes	Events to subscribe to
`secret`	string	No	Signing secret (auto-generated if omitted)

Available Events

memory.stored - New memory created
memory.updated - Memory modified
memory.deleted - Memory removed
agent.started - Agent began processing
agent.completed - Agent finished
agent.failed - Agent encountered error
project.updated - Project settings changed
usage.threshold - Usage threshold reached

DELETE /webhooks/{webhookId}

Delete a webhook.

POST /webhooks/{webhookId}/test

Send a test event to verify webhook configuration.

Webhook Payload Format

{
  "id": "evt_abc123",
  "type": "memory.stored",
  "createdAt": "2026-01-30T12:00:00Z",
  "data": {
    "memoryId": "project-update",
    "tags": ["project", "update"],
    "importance": "high"
  }
}

Verifying Webhook Signatures

All webhooks include a signature header for verification:

X-ChaozCode-Signature: sha256=abc123...

// Verify in Node.js
const crypto = require('crypto');
const signature = crypto
  .createHmac('sha256', webhookSecret)
  .update(rawBody)
  .digest('hex');

if (signature === receivedSignature) {
  // Valid webhook
}

API Reference v2.0

📑 Quick Navigation

Authentication

Getting Your API Key

API Key Types

Example Request

Rate Limits

Rate Limit Headers

Handling Rate Limits

Error Handling

Error Codes

AI Query Endpoints

Memory Endpoints

Codebase Endpoints

Agent Endpoints

Project Endpoints

User Endpoints

Webhook Endpoints

Available Events

Webhook Payload Format

Verifying Webhook Signatures