Skip to main content
POST
Create a chat completion

Authorizations

Authorization
string
header
required

A workspace API key in an Authorization: Bearer header. A missing header, a scheme other than Bearer, a key of the wrong shape, and a key we reject are all 401.

Body

application/json

An OpenAI chat completion request. Fields beyond the ones named here are forwarded to the provider unchanged rather than refused for being unfamiliar.

model
string
required

The model to call, in one of exactly two forms. A provider-pinned id, "{provider}/{that provider's own id}", is split once on the FIRST slash: the part before it names one of the provider accounts this platform serves, and everything after it is that provider's own id for the model, passed on verbatim, slashes included. A workspace routing-profile slug, "profile/{identifier}", is the other form: the platform then tries that profile's models in the customer's own order, and the usage record and the charge name whichever model actually served. A bare model id is refused with 400 and the code "model_id_not_pinned". GET /v1/models lists the exact strings this key can call, one per model and provider that serves it. A third string is accepted alongside them: "hopscotch/auto", which names whichever routing profile the workspace made its default. It is a fixed id every workspace can send, so a client is configured once and the route behind it is changed later on the Routing screen without touching the calling code. It resolves through the same path a profile slug takes, so the usage record and the charge name whichever model actually served, and a workspace with no default route set is refused 404 "model_not_available" saying exactly that.

Example:

"openai/gpt-4o-mini"

messages
object[]
required
max_tokens
integer

The most output tokens the reply may use. Optional, as it is on OpenAI. Left out, it is filled in for the providers whose own API refuses a request that does not carry one, and the figure used is the model's published max_output_tokens, which GET /v1/models/{model} reports and which is what credit is held for on a request naming no ceiling. Every other provider is sent the request unchanged. max_completion_tokens counts as this field being given.

Example:

256

stream
boolean

Response

The completion. A response that is not streamed carries the provider's token counts in its own usage object. Its model field echoes the slug you asked for rather than the provider's internal name, except in three cases that are returned as the provider sent them: a streamed reply, whose frames are passed through unchanged; a request naming a routing profile, which names a chain rather than one model; and a successful body carrying no string model field at all.

When stream is true the body is text/event-stream instead, and the counts arrive on a :x-hopscotch-usage comment line immediately before data: [DONE]; the server-sent events specification requires parsers to ignore comment lines, so an SDK never sees it.

An OpenAI chat completion, as the provider produced it.

id
string
object
string
Example:

"chat.completion"

created
integer
model
string
choices
object[]
usage
object