API reference

Chat completions API

LineMod is a security gateway with agent behavior observability—guardrails at the edge, harness diagnostics across runs, and policy routing when you need it. This page is the chat completions API reference for that gateway. LineMod exposes an OpenAI-compatible surface on https://api.linemod.ai/v1 with gateway policy headers on every request and response.

Endpoints

Public gateway surface

Authenticate with Authorization: Bearer <api_key>.

POST/v1/chat/completions

Primary chat endpoint. Set model to a concrete ID or an auto:* alias. Supports stream: true for SSE chunks.

GET/v1/models

List models available to your org and region. Catalog rows come from the platform model registry.

Request body (chat)

Field	Type	Required	Notes
`model`	string	yes	Concrete model ID or `auto:balanced`, `auto:cost`, etc.
`messages`	array	yes	OpenAI-compatible role/content messages.
`stream`	boolean	no	When true, returns SSE `data:` chunks ending with `[DONE]`.
`temperature`	number	no	Passed through when supported by the routed model.
`max_tokens`	integer	no	Completion token cap for the upstream call.

Headers

Gateway request headers

Optional per-request overrides. Org defaults and API key settings apply when a header is omitted.

Header	Values	Purpose
`X-LineMod-Security`	`strict` \| `standard` \| `relaxed` \| `off`	Override security template for this request.
`X-LineMod-Budget-Max`	USD float	Per-request spend cap hint.
`X-LineMod-Fallback`	comma-separated models	Custom fallback chain for this request.
`X-LineMod-Tag`	string	Cost attribution label for usage reports.
`X-LineMod-Cost-Quality`	0–10	Cost-quality dial for supported `auto:*` templates.
`X-LineMod-Session-Id`	string	Sticky routing context across related turns.
`X-LineMod-No-Failover`	`true`	Fail fast instead of rerouting to fallbacks.
`X-LineMod-Run-Id`	string (UUID)	Attach gateway calls to an agent run waterfall. Reuse the same ID across every step in a multi-turn agent loop.
`X-LineMod-Client`	registry id	Declare the calling agent or IDE client type (for example `cursor`, `claude_code`). Must match a published registry id when your org enforces client identification.
`X-LineMod-Tool-Approval`	token	Approve a gated agent tool call (agent security flows).

Transparency

Response headers

Log these headers with your application request ID for support, billing reconciliation, and audit review.

Header	Description
`X-LineMod-Request-Id`	Unique request identifier for audit correlation.
`X-LineMod-Model-Used`	Concrete model ID that served the request.
`X-LineMod-Route-Reason`	Human-readable routing decision summary.
`X-LineMod-Route-Confidence`	Routing confidence score when learned routes apply.
`X-LineMod-Route-Excluded`	Truncated list of models filtered out of consideration.
`X-LineMod-Cost`	Estimated request cost in USD.
`X-LineMod-Saved`	Savings percentage vs a reference model (when configured).
`X-LineMod-Credential-Source`	`platform` \| `org_byok` \| `platform_fallback`
`X-LineMod-CrossBorder`	`true` when the call crossed region boundaries.
`X-LineMod-Security-Risk`	Input risk level: `low` \| `medium` \| `high` \| `critical`
`X-LineMod-Output-Risk`	Output risk tags when scanners flag content.
`X-LineMod-Run-Id`	Agent run ID when agent mode is active (echoed when supplied on the request).
`X-LineMod-Client-Profile`	Resolved client profile id used for Agent insights and harness baselines.
`X-LineMod-Client-Profile-Source`	How the profile was resolved: `api_key`, `header`, `user_agent`, or `unknown`.
`X-LineMod-Run-Cost` / `X-LineMod-Run-Steps`	Aggregated agent run cost and step count.
`X-LineMod-Schema-Valid` / `X-LineMod-Schema-Errors`	Structured output validation results from the routing executor.

Streaming

SSE stream format

Streaming responses use standard OpenAI chunk objects. Upstream interruption may append an error event.

SSEchat.completion.chunk

data: {"object":"chat.completion.chunk","model":"deepseek-v3",
"choices":[{"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"object":"chat.completion.chunk",
"choices":[{"delta":{},"finish_reason":"stop"}],
"usage":{"prompt_tokens":10,"completion_tokens":20,"total_tokens":30}}

data: [DONE]

Errors

Common status codes

Errors use a unified envelope: { "error": { "code", "message", "type" } }.

Status	Typical cause	What to check
`401`	Invalid or revoked API key	Bearer token, key scope, and org membership.
`402`	Insufficient platform credits	Wallet balance or BYOK subscription status.
`403`	Blocked by security policy	Template level, tool permission, or output scanner verdict.
`429`	Rate limited	Org, key, or upstream provider throughput.
`503`	No routable model available	Catalog, cooldown state, region filter, or failover chain.