API reference#

Inference routes use Authorization: Bearer <sgr_live key> and live under /api/v1.

Route	Purpose
`GET /api/v1/models`	Models exposed to the authenticated member.
`POST /api/v1/chat/completions`	OpenAI-style chat, including SSE streaming.
`POST /api/v1/responses`	Stateless Responses-compatible requests.
`POST /api/v1/embeddings`	Embeddings through supported lanes.
`GET /api/v1/quota`	Effective workspace, member and key limits.
`GET /api/v1/usage`	Authenticated usage summary.
`POST /api/v1/router`	Inspect a routing decision without serving a model call.

sugar/conduit invokes task-aware family selection. Naming an exposed direct model bypasses classification. Clients should preserve Sugar's request ID and standard rate-limit headers for diagnostics.

Responses fields#

/v1/responses translates to the chat contract and forwards every field that has a chat equivalent. A field with no equivalent is refused by name with HTTP 400 rather than dropped, so a request whose intent cannot be honoured never returns a plausible 200.

Field	Behaviour
`temperature`, `top_p`	Forwarded. Numbers within 0–2 and 0–1.
`seed`	Forwarded. Must be an integer.
`parallel_tool_calls`	Forwarded, and echoed back in the response envelope. Absent means the API default, `true`.
`user`	Forwarded. A string of at most 256 characters.
`text.format`	Forwarded as chat `response_format`. `text` is the default and sends nothing; `json_object` and `json_schema` are carried, the latter with `name`, `schema` and the optional `description` and `strict`.
`reasoning.effort`	Forwarded as chat `reasoning_effort`: `minimal`, `low`, `medium` or `high`.
`store`	Must be `false`.

These are refused:

Field	Error code
Any unrecognised top-level field	`unsupported_responses_field`
`text.verbosity`, or any other member of `text`	`unsupported_text_field`
`reasoning.summary`, or any other member of `reasoning`	`unsupported_reasoning_field`
`metadata`	`metadata_not_supported`
`truncation` other than `"disabled"`	`truncation_not_supported`
A non-empty `include`	`include_not_supported`
`previous_response_id`	`previous_response_id_not_supported`
`conversation`, `state`	`response_state_not_supported`
`store` other than `false`	`store_not_supported`

The usage block reports the same token splits the gateway records, including input_tokens_details.cached_tokens and output_tokens_details.reasoning_tokens.

Operator metrics#

GET /api/admin/metrics exports Prometheus text exposition behind an admin session or an sgr_admin_ token with the usage:read scope. It is never anonymous. See monitoring.html for the series, the scrape configuration and the query rules.

Verify#

Prerequisites#

A valid member key.
At least one exposed model.

List models, send one non-streaming request, then repeat with stream: true and consume the stream through its terminal marker. Compare reported usage with the portal. Do not automatically retry an ambiguous server failure without checking whether the provider may have served work.