Skip to main content
POST
Create a message

Headers

x-workload
string

The workload the request is for, which ambral/auto serves from its primary model and whose traces record it. A model suffix (ambral/auto:<workload>) names it too, and the two must agree. A request that names none and carries the x-ambral-eval header is for its eval's workload.

x-ambral-upstream
string

The upstream that serves the request, at that upstream's price, for debugging. Otherwise Ambral chooses. A model it doesn't serve is a 400.

Minimum string length: 1
x-ambral-eval
string

<run>; workload=<workload>; model=<model>: the request is a call of an eval run, which Ambral's SDKs set. A request that names no workload (no x-workload, no model suffix) is for the run's. A request for the run's workload is served the run's model, one of the workload's pool, and a request for another workload that workload's primary. Either way it is recorded as an eval trace of the run, never as production. It needs a session, and a value that doesn't parse is a 400.

x-session-id
string

The session the request belongs to: the same id on every request of a session, 8–128 characters of A-Z a-z 0-9 _ -; any other value is ignored. The body's session_id or an x-<vendor>-session-id header names it too. Without one, each request is a session.

x-ambral-end-user
string

Your own id for the person the request serves, recorded on its session's trace: 1–128 characters of A-Z a-z 0-9 . _ : @ + -; any other value is ignored. Without it, the body's safety_identifier, user or metadata.user_id names them. A session keeps the first one it is sent.

x-ambral-labels
string

Labels on the request's session, key=value or a bare tag, comma-separated: up to 16. A key is lowercase letters, digits, ., _ and -, starting with a letter or digit, at most 63 characters. A value is letters, digits, spaces and . _ : / @ + -, at most 128 characters; spaces around it are dropped. A session's labels gather every request's, a later value replacing an earlier one's; once a session holds 16, a later request's new keys are dropped. Invalid labels are ignored, all of them, and the response says why in its own x-ambral-labels header.

anthropic-version
string

The API version, sent on to the provider. Without one, 2023-06-01.

anthropic-beta
string

The betas to turn on, comma-separated, sent on to the provider, which may support only some.

Body

application/json
model
string
required
Required string length: 1 - 256
max_tokens
integer
required
Required range: 0 <= x <= 9007199254740991
messages
object[]
required
system
tools
object[]
stream
boolean
session_id
any
{key}
any

Response

The provider's answer: one message, or a stream of events.

The message, or the error envelope when Ambral couldn't read the provider's answer.

id
string
required
type
enum<string>
required
Available options:
message
role
enum<string>
required
Available options:
assistant
content
object[]
required
model
string
required
Required string length: 1 - 256
stop_reason
string | null
required
usage
object
required
container
unknown
stop_details
unknown
stop_sequence
string | null
context_management
unknown