Quickstart
Create an API key, choose a plan, and test with curl or n8n.
On this page
This quickstart takes you from zero to a successful authenticated chat completion. Base URL for production is https://api.caedral.com. All examples use the OpenAI-compatible /v1 surface.
1. Create an account and API key
- Sign up at https://caedral.com/signup and verify your email
- Open Dashboard → API Keys (https://caedral.com/dashboard/api-keys)
- Click Generate key, give it a label (for example production-n8n), and copy the secret immediately — Caedral shows the full key only once
- Store it as CAEDRAL_API_KEY in your environment or secrets manager
export CAEDRAL_API_KEY="cd_live_xxxxxxxxxxxxxxxx"2. Choose a subscription plan
Plans are defined in one canonical configuration (config/plans.json). Each plan includes two monthly usage pools: Caedral Models for Caedral-hosted products, and External models for third-party catalog models.
| Plan | Price | Caedral Models pool | External models pool |
|---|---|---|---|
| Hobby | Free | $200/mo | — |
| Pro | $20/mo | $500/mo | $20/mo |
| Pro+ | $60/mo | $2,500/mo | $70/mo |
| Ultra | $200/mo | $10,000/mo | $400/mo |
| Teams Standard | $40/seat/mo | $2,000/seat/mo | $40/seat/mo |
| Teams Premium | $120/seat/mo | $6,000/seat/mo | $120/seat/mo |
- Caedral-hosted Embed and native Voice draw from the Caedral Models pool; hosted rerank draws from External Models
- Third-party models draw from the external models pool (Pro or higher)
- At zero included quota, enable on-demand or upgrade — otherwise HTTP 402
- Annual billing is charged yearly at a discount, but quota cycles stay monthly — pools still reset every month
3. Authentication
Every authenticated route expects an Authorization Bearer header. Keys use the cd_live_ prefix in production.
Authorization: Bearer $CAEDRAL_API_KEYContent-Type: application/json4. First chat request (cURL)
Send a standard OpenAI-compatible chat completion. Use any live catalog model ID — deepseek/deepseek-v4-flash is a strong production default. List everything with GET /v1/models or browse the catalog on caedral.com/models.
curl https://api.caedral.com/v1/chat/completions \ -H "Authorization: Bearer $CAEDRAL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "deepseek/deepseek-v4-flash", "messages": [ { "role": "system", "content": "You are an operations assistant. Be concise." }, { "role": "user", "content": "Summarize this support ticket in two bullets." } ], "temperature": 0.2, "max_tokens": 400 }'Successful response shape
{ "id": "cd_req_...", "object": "chat.completion", "created": 1722268800, "model": "deepseek/deepseek-v4-flash", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "• Customer cannot sync invoices\n• Escalate to billing ops" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 48, "completion_tokens": 26, "total_tokens": 74 }}5. List models
curl https://api.caedral.com/v1/models \ -H "Authorization: Bearer $CAEDRAL_API_KEY"6. Check subscription usage
curl https://api.caedral.com/v1/usage \ -H "Authorization: Bearer $CAEDRAL_API_KEY"{ "accountStatus": "active", "plan": { "id": "pro", "name": "Pro", "interval": "monthly", "status": "active" }, "billingPeriod": { "start": "...", "end": "..." }, "pools": { "caedral": { "usedFormatted": "$12.50", "limitFormatted": "$500.00", "percentUsed": 3 }, "external": { "usedFormatted": "$0.00", "limitFormatted": "$20.00", "percentUsed": 0 } }, "onDemand": { "mode": "disabled", "allowed": true, "blocked": false }}7. Common errors
| HTTP | type | Fix |
|---|---|---|
| 400 | invalid_request | Check model ID, messages array, and JSON shape |
| 401 | invalid_api_key | Missing/revoked key — regenerate in the dashboard |
| 402 | insufficient_balance | Included pools exhausted — upgrade or enable on-demand |
| 429 | rate_limit_exceeded | Backoff and retry; split high-volume clients |
Next steps
- Wire the same request in n8n — see n8n integration
- Read full parameter tables in API reference
- Install TypeScript/Python/Go SDKs when you leave curl behind