API Reference
Chat Completions
POST /v1/chat/completions
POST /v1/chat/completionsOpenAI-compatible chat completions. Supports streaming via stream: true.
Request
Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer sk-... |
Content-Type | Yes | application/json |
X-Carrot-Trace | No | Set to "true" to capture a trace |
Body
{
"model": "my-custom-model",
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello!"}
],
"stream": false,
"temperature": 0.7,
"max_tokens": 1024
}| Field | Type | Required | Description |
|---|---|---|---|
model | string | Yes | Your Carrot model name |
messages | array | Yes | Array of message objects with role and content |
stream | boolean | No | Stream response as SSE. Default: false |
temperature | number | No | Sampling temperature (0-2) |
max_tokens | integer | No | Maximum tokens to generate |
Response
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Hello! How can I help you today?"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 20,
"completion_tokens": 10,
"total_tokens": 30
}
}Streaming
When stream: true, the response is a stream of SSE events:
data: {"id":"chatcmpl-abc123","choices":[{"delta":{"role":"assistant"},"index":0}]}
data: {"id":"chatcmpl-abc123","choices":[{"delta":{"content":"Hello"},"index":0}]}
data: [DONE]Example
curl https://api.carrotlabs.ai/v1/chat/completions \
-H "Authorization: Bearer sk-..." \
-H "Content-Type: application/json" \
-d '{
"model": "my-custom-model",
"messages": [{"role": "user", "content": "What is 2+2?"}]
}'Errors
| Status | Meaning |
|---|---|
401 | Invalid or missing API key |
404 | Model not found |
502 | Inference provider temporarily unavailable |