API Reference

Complete reference for the Alveare REST API. All endpoints accept and return JSON.

Base URL

https://api.alveare.ai

Authentication

All API requests require a Bearer token in the Authorization header. API keys are prefixed with alv_live_ (production) or alv_test_ (sandbox).

Header

Authorization: Bearer alv_live_abc123...

Generate keys from the dashboard. Keep your key secret; do not commit it to version control.

Rate limits

Rate limits are applied per API key and vary by plan.

Plan	Requests / minute	Requests / month
Solo	20	10,000
Starter	100	100,000
Professional	500	500,000
Scale	2,000	2,000,000

When rate-limited you will receive a 429 response with a Retry-After header indicating how many seconds to wait.

POST /v1/chat/completions

OpenAI-compatible chat completions endpoint. Use this if you are migrating from OpenAI or want to use the official OpenAI SDKs with Alveare.

Request body

Parameter	Type	Description
model	string required	Specialist name prefixed with `alveare-`. E.g. `alveare-summarise`, `alveare-classify`, `alveare-extract`, `alveare-qa`, `alveare-chat`, `alveare-code`.
messages	array required	Array of message objects. Each has `role` (`"system"`, `"user"`, or `"assistant"`) and `content` (string).
max_tokens	integer optional	Maximum tokens to generate. Default: 512. Max: 4096.
temperature	number optional	Sampling temperature from 0.0 to 2.0. Default: 0.7. Lower = more deterministic.
top_p	number optional	Nucleus sampling. Default: 1.0.
stream	boolean optional	If true, returns a stream of SSE events. Default: false.

Example request

bash

curl -X POST https://api.alveare.ai/v1/chat/completions \
  -H "Authorization: Bearer alv_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "alveare-summarise",
    "messages": [
      {"role": "user", "content": "Summarise this: The quarterly revenue..."}
    ],
    "max_tokens": 256,
    "temperature": 0.5
  }'

Example response

json

{
  "id": "chatcmpl-abc123def456",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "alveare-summarise",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Revenue grew 23% YoY to $4.2B, driven by..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 142,
    "completion_tokens": 87,
    "total_tokens": 229
  }
}

POST /v1/infer

Native Alveare inference endpoint. Simpler than the chat format -- pass a specialist and prompt directly.

Request body

Parameter	Type	Description
specialist	string required	Specialist name: `classify`, `summarise`, `extract`, `qa`, `chat`, `code`.
prompt	string required	The input text to process.
max_tokens	integer optional	Maximum tokens to generate. Default: 512. Max: 4096.
temperature	number optional	Sampling temperature from 0.0 to 2.0. Default: 0.7.

Example request

bash

curl -X POST https://api.alveare.ai/v1/infer \
  -H "Authorization: Bearer alv_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "specialist": "classify",
    "prompt": "I love this product! Best purchase ever.",
    "max_tokens": 64,
    "temperature": 0.3
  }'

Example response

json

{
  "id": "inf-789xyz",
  "specialist": "classify",
  "result": "positive",
  "tokens_used": 38,
  "latency_ms": 142
}

GET /v1/models

List all available specialists for your account.

Example request

bash

curl https://api.alveare.ai/v1/models \
  -H "Authorization: Bearer alv_live_abc123..."

Example response

json

{
  "object": "list",
  "data": [
    { "id": "alveare-classify", "object": "model", "owned_by": "alveare" },
    { "id": "alveare-summarise", "object": "model", "owned_by": "alveare" },
    { "id": "alveare-extract", "object": "model", "owned_by": "alveare" },
    { "id": "alveare-qa", "object": "model", "owned_by": "alveare" },
    { "id": "alveare-chat", "object": "model", "owned_by": "alveare" },
    { "id": "alveare-code", "object": "model", "owned_by": "alveare" }
  ]
}

GET /v1/usage

Returns usage statistics for the current billing period.

Example request

bash

curl https://api.alveare.ai/v1/usage \
  -H "Authorization: Bearer alv_live_abc123..."

Example response

json

{
  "period_start": "2026-03-01T00:00:00Z",
  "period_end": "2026-03-31T23:59:59Z",
  "requests_used": 42370,
  "requests_limit": 100000,
  "tokens_used": 8420156,
  "by_specialist": {
    "classify": 18200,
    "summarise": 15830,
    "extract": 8340
  }
}

GET /health

Public health check endpoint. No authentication required.

Example request

bash

curl https://api.alveare.ai/health

Example response

json

{
  "status": "ok",
  "version": "1.4.2",
  "uptime_seconds": 2592000
}

Error handling

All errors return a JSON body with a consistent structure.

Error response format

json

{
  "error": {
    "message": "Invalid API key provided.",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

HTTP status codes

Code	Meaning	Description
400	Bad Request	Missing or invalid parameters. Check the `message` field for details.
401	Unauthorized	Missing or invalid API key. Check your `Authorization` header.
403	Forbidden	Your plan does not include the requested specialist or feature.
429	Rate Limited	Too many requests. The `Retry-After` header tells you how many seconds to wait. SDKs handle this automatically with exponential backoff.
500	Server Error	Something went wrong on our end. Retry with backoff or check status.alveare.ai.

When you receive a 429, always respect the Retry-After header. Ignoring it and retrying immediately may result in extended rate limiting.