Chat Completions

Generate conversational and tool-using completions with sage-2-4-actus, sage-2-5-celer, and sage-oss.

POST https://api.sagea.space/v1/chat/completions

Authentication

Send Authorization: Bearer $SAGEA_API_KEY on every request. Get a key

Parameters

Send a JSON body with the following fields.

Parameter	Type	Required	Description
`model`	`string`	Yes	One of `sage-2-4-actus`, `sage-2-5-celer`, or `sage-oss`.
`messages`	`array`	Yes	Ordered list of `system`, `user`, `assistant`, or `tool` messages.
`temperature`	`number`	No	Sampling randomness from 0 to 2. Default is `0.7`.
`max_tokens`	`integer`	No	Maximum tokens to generate. Defaults to the model context limit.
`stream`	`boolean`	No	Set to `true` for server-sent event streaming. Default is `false`.
`tools`	`array`	No	Functions the model may call, such as Kathmandu weather lookup.
`response_format`	`object`	No	Use type `json_object` object to force valid JSON output.

Example request

Kathmandu weather tool call with SAGE 2.4 Actus.

curl -X POST https://api.sagea.space/v1/chat/completions \
  -H "Authorization: Bearer $SAGEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sage-2-4-actus",
    "messages": [
      {"role": "system", "content": "You are SAGEA, a helpful assistant."},
      {"role": "user", "content": "What is the weather in Kathmandu today?"}
    ],
    "temperature": 0.7,
    "max_tokens": 500,
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {"city": {"type": "string"}},
          "required": ["city"]
        }
      }
    }]
  }'

Response

A successful call returns the assistant message plus usage.

{
  "id": "chatcmpl_9kathmandu42",
  "object": "chat.completion",
  "created": 1736459200,
  "model": "sage-2-4-actus",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "It is 18C and clear in Kathmandu today.",
        "tool_calls": [{"id": "call_ktm01", "type": "function"}]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {"prompt_tokens": 84, "completion_tokens": 22, "total_tokens": 106}
}

Errors

Status	Code	Fix
`400`	`invalid_request`	Validate `messages` roles and required `model` field.
`401`	`unauthorized`	Re-export a valid `SAGEA_API_KEY` value.
`404`	`session_not_found`	Retry without a stale `session_id` value.
`429`	`rate_limit_exceeded`	Back off and retry with exponential delay.
`500`	`internal_error`	Retry once, then contact support with request ID.

Limits

Actus allows 60 requests per minute on Starter and 1000 per minute on Pro, while Celer allows 120 per minute on Starter and 2000 per minute on Pro.