Build

API reference

CostIQ v1 exposes model discovery, native OpenAI Responses, and Chat Completions. All public requests use HTTPS and bearer authentication.

Base URL

https://inference.costiq.xyz/v1

Append /models, /responses, or /chat/completions. Do not append another /v1.

Authentication

Send the key in the standard bearer header on every request.

HTTP header

Authorization: Bearer $COSTIQ_API_KEY

Missing, invalid, expired, or revoked credentials return 401.

GET/v1/models

List models

Returns only the stable model aliases allowed for the supplied key.

Example response

{
  "object": "list",
  "data": [
    {
      "id": "general-fast",
      "object": "model"
    }
  ]
}

POST/v1/responses

Create a response

Use the native Responses shape for coding agents, function tools, and new SDK integrations. CostIQ forwards it as Responses API traffic; it does not translate the request through Chat Completions.

Field	Type	Required	Description
`model`	string	Yes	Use `general-fast`.
`input`	string or array	Yes	Text or typed input items.
`tools`	array	No	Function tools supported by the selected model.
`store`	boolean	No	Use `false`; CostIQ clients should carry their own conversation state.
`stream`	boolean	No	Streams typed SSE events when true.

Request body

{
  "model": "general-fast",
  "input": "What is CostIQ?",
  "store": false,
  "stream": false
}

Representative response

{
  "id": "resp_...",
  "object": "response",
  "status": "completed",
  "model": "general-fast",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {"type": "output_text", "text": "..."}
      ]
    }
  ],
  "usage": {
    "input_tokens": 24,
    "output_tokens": 18,
    "total_tokens": 42,
    "cost": 0.00006
  }
}

POST/v1/chat/completions

Create a chat completion

Send a JSON object with a permitted model alias and a conversation.

Field	Type	Required	Description
`model`	string	Yes	Use `general-fast`.
`messages`	array	Yes	Ordered role and content messages.
`stream`	boolean	No	Streams SSE when true.

Request body

{
  "model": "general-fast",
  "messages": [
    {"role": "system", "content": "Be concise."},
    {"role": "user", "content": "What is CostIQ?"}
  ],
  "stream": false
}

Representative response

{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 18,
    "total_tokens": 42,
    "cost": 0.00006
  }
}

Token values and optional fields vary by response. Treat usage fields as accounting metadata, not a billing invoice.

Streaming

With stream: true, the response content type is text/event-stream. Responses API streams use typed events and end with response.completed or an error event. Chat Completions streams end with [DONE]. A concurrency slot remains occupied until either stream closes.

Usage and prompt caching

When token usage is available, CostIQ adds usage.cost as a USD estimate calculated from the deployment rate card. It is operational metadata, not an invoice. Provider-supplied cost values are preserved.

Prompt caching is automatic when the model route can reuse input. There is no request-side switch to enable it. Native Responses streams report cache-read tokens in input_tokens_details when the route reuses a prefix.

Protected policy fields

Routing, fallback, retry, provider, identity, tags, and metadata controls are owned by CostIQ. Requests that attempt to override them return 400.

Limits and errorsBuild safe failure handling.SecurityReview the public trust boundary.