Build

Chat completions

The request and response of POST /v1/chat/completions, the OpenAI contract with a few Paranine specifics.

Endpoint

POST https://sovereign.paranine.com/v1/chat/completions
Authorization: Bearer sk_p9_…
Content-Type: application/json

The request and response follow OpenAI's chat completions API. Every OpenAI chat completions parameter is accepted and passed to the model; whether a model honours a given one (for example tools or response_format) depends on the model.

Request

Field	Type	Notes
`model`	string	A model id from the catalogue, verbatim.
`messages`	array	The conversation in order, with roles `system`, `user`, `assistant` and `tool`. `content` is a string, or an array of parts that can include images.
`stream`	boolean	`true` to receive server-sent events; see Streaming. Default `false`.
`max_tokens`	integer	The longest reply you'll accept. Without it, the reply is capped at the model's default length.
`n`	integer	Must be `1`: Paranine returns one choice per request.
`temperature`, `top_p`, `stop`, `tools`, `tool_choice`, `response_format`, …		Passed to the model as sent.

A parameter that isn't part of OpenAI's chat completions API (for example top_k) is refused with 400 (unknown_parameter), naming it in param.

{
  "model": "paranine/gpt-oss-120b(Global)",
  "messages": [
    {"role": "system", "content": "You are a concise assistant."},
    {"role": "user", "content": "What is a token?"}
  ],
  "max_tokens": 200,
  "temperature": 0.3
}

Response

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "created": 1787578888,
  "model": "paranine/gpt-oss-120b(Global)",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "A token is…"},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 27, "completion_tokens": 64, "total_tokens": 91}
}

finish_reason is stop when the model finished, length when the reply reached max_tokens (or the default length), and tool_calls when the model called a tool. usage is what you're billed on.

Request ids

Every response carries an X-Request-Id header, which is also the request's id in your request logs. To use your own id, send X-Request-ID with 1 to 128 letters, digits or . _ : + / = -. Quote the id when you contact us.

Tagging requests

Any header that starts with X-P9-Meta- is stored with the request and searchable in your request logs. Use tags to attribute usage to your own users, features or tenants without changing the request body:

X-P9-Meta-user_tag: emp-4092
X-P9-Meta-feature_tag: ticket_summary

Tags are never sent to the model. Tag names are lowercased, and a request's tags can total up to 4 KB.

Safe retries

A retried request that succeeds runs, and is charged, again. To make retries safe, send an Idempotency-Key header of 1 to 255 printable characters: a second request with the same key within 24 hours answers 409 (duplicate_idempotency_key) instead of running again.

Limits

Size: a request can be up to 2 MB. A larger one answers 413 (request_too_large).
Duration: a request can run for up to five minutes.
Rate: 60 requests per minute per key, unless the key was given another limit.

Other endpoints

Endpoint	For
`POST /v1/embeddings`	Embeddings
`POST /v1/systemone`	Decisions
`POST /v1/messages`	Anthropic's Messages API, with your own Anthropic key

A model sent to an endpoint that doesn't serve it answers 400 (endpoint_not_supported). GET /v1/models, /v1/completions and /v1/responses are not available.

Something unclear or wrong on this page? Tell us. Machine-readable copies: llms.txt.