Skip to main content

​
Base URL

http://localhost:8000/api/v1

​
Authentication

Agent Chassis supports multiple authentication methods:

​
API Key (Simple)

Include the API key in the X-API-Key header: 
curl -H "X-API-Key: your-api-key" ...
Configuration: Set CHASSIS_API_KEY in your .env file to enable API key authentication.

​
JWT Bearer Token (User Auth)

Include the JWT token in the Authorization header: 
curl -H "Authorization: Bearer your-jwt-token" ...
Getting a token:
  1. Register: POST /auth/register
  2. Verify email: POST /auth/verify-email
  3. Login: POST /auth/login (returns access_token)
See Authentication Guide for details.

​
Endpoints

​
Agent Endpoints

MethodEndpointDescription
POST/agent/completionRun agent loop with tool calling
GET/agent/session/{session_id}Get session information
PATCH/agent/session/{session_id}/accessUpdate session access settings
DELETE/agent/session/{session_id}Delete a session

​
Authentication Endpoints

MethodEndpointDescription
POST/auth/registerRegister new user account
POST/auth/verify-emailVerify email with code
POST/auth/resend-verificationResend verification email
POST/auth/loginLogin with email/password
POST/auth/refreshRefresh access token
POST/auth/googleGoogle OAuth login/register
POST/auth/password-resetRequest password reset
POST/auth/password-reset/confirmConfirm password reset
GET/auth/meGet current user info

​
Health Check

MethodEndpointDescription
GET/healthHealth check endpoint

​
Response Format

​
Success Response

All endpoints return JSON: 
{
  "role": "assistant",
  "content": "Response content",
  "session_id": "abc-123"
}

​
Error Response

Error responses follow this format: 
{
  "detail": "Error message describing what went wrong"
}
Common HTTP Status Codes:
  • 200 - Success
  • 201 - Created
  • 400 - Bad Request (invalid input)
  • 401 - Unauthorized (missing/invalid auth)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not Found
  • 500 - Internal Server Error
  • 503 - Service Unavailable (feature disabled)

​
Rate Limiting

​
Login Endpoints

Login endpoints are rate-limited to prevent brute force attacks:
  • 5 attempts per 15 minutes per IP address
  • Exceeded attempts return 429 Too Many Requests

​
Email Verification

Verification email sending is rate-limited:
  • 1 email per minute per email address
  • Prevents email spam

​
Request Size Limits

  • Message content: Maximum 100,000 characters (~100KB)
  • Metadata: Maximum 10KB
  • Messages per request: Maximum 100 (client-side mode)

​
Streaming Responses

For endpoints that support streaming (e.g., /agent/completion), set "stream": true in the request body. The response will be a text/event-stream with JSON chunks: 
data: {"type": "content", "content": "Hello"}
data: {"type": "content", "content": " world"}
data: {"type": "done"}

​
OpenAPI Specification

Agent Chassis automatically generates an OpenAPI specification at: 
http://localhost:8000/api/v1/openapi.json
You can view interactive API documentation at: 
http://localhost:8000/docs

​
Examples

​
Basic Agent Request

curl -X POST http://localhost:8000/api/v1/agent/completion \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "messages": [
      {"role": "user", "content": "What is 2+2?"}
    ],
    "model": "kimi-k2-thinking",
    "allowed_tools": ["calculate"]
  }'

​
Server-Side Session

# Create session
curl -X POST http://localhost:8000/api/v1/agent/completion \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "message": "Hello!",
    "model": "kimi-k2-thinking"
  }'

# Continue session
curl -X POST http://localhost:8000/api/v1/agent/completion \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "session_id": "abc-123",
    "message": "Continue the conversation",
    "model": "kimi-k2-thinking"
  }'

​
User Registration

curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123",
    "display_name": "John Doe"
  }'

​
Next Steps