Skip to main content

​
Base URL

https://api.cuadra.ai/v1

​
Authentication

Include your access token in the Authorization header: 
Authorization: Bearer YOUR_TOKEN
MethodUse Case
JWT SessionsFrontend apps (from Stytch B2B auth)
M2M OAuth 2.0Backend services (client credentials flow)
See Authentication for setup details.

​
Request Format

All requests use JSON: 
curl -X POST https://api.cuadra.ai/v1/chats \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"modelId": "model_abc", "messages": [{"role": "user", "content": "Hello"}]}'

​
Idempotency

For POST requests, include Idempotency-Key to safely retry without duplicates: 
Idempotency-Key: unique-request-id-123

​
Response Format

​
Success

{
  "id": "chat_xyz789",
  "message": {
    "role": "assistant",
    "content": "Hello! How can I help?"
  },
  "usage": {
    "inputTokens": 15,
    "outputTokens": 8,
    "totalTokens": 23
  }
}

​
Error (RFC 7807)

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or expired token."
}

​
Rate Limits

ScopeLimit
Per organization300 requests/minute
Per user60 requests/minute
Rate-limited requests return HTTP 429 with a Retry-After header.

​
Pagination

List endpoints use cursor-based pagination: 
GET /v1/models?limit=20

{
  "data": [...],
  "nextCursor": "cursor_abc123",
  "hasMore": true
}

​
Endpoints

EndpointDescription
POST /v1/chatsCreate chat completion
GET /v1/modelsList models
POST /v1/modelsCreate model
GET /v1/datasetsList datasets
POST /v1/datasetsCreate dataset
GET /v1/usageGet usage metrics

Chat API

Completions with streaming

Authentication

JWT and M2M setup

​
FAQ

​
Is the API RESTful?

Yes. The Cuadra AI API follows REST conventions with resource-based URLs, standard HTTP methods (GET, POST, PATCH, DELETE), and JSON payloads.

​
What’s the latency?

Depends on the LLM provider and response length. Typical first-token latency is 200-500ms. Use stream: true for perceived faster responses.

​
Is there a sandbox environment?

No separate sandbox. Use the Free plan for testing.

​
How do I handle rate limits?

Implement exponential backoff. Check the Retry-After header on 429 responses. See Errors for retry logic examples.