API reference
Endpoint explorer

Endpoint explorer

This page is generated from the same OpenAPI 3.1 document that
/assets/hisoka.openapi.json serves, so it cannot drift from the specification or from
the pages beside it.

Use it as a lookup: find the endpoint, read the request and response fields, then copy the
curl. The prose pages explain why; this one lists what.

Prefer a machine-readable copy

Download the raw specification and point any OpenAPI tool at it:

curl https://docs.hisoka.ai/assets/hisoka.openapi.json -o hisoka.openapi.json

Hisoka API

v1.0.0 JSON / YAML

Authentication. Send your key as Authorization: Bearer sk-.... Anthropic clients may send x-api-key instead; the SDKs accept either.

Which endpoint to use. Pick the one your client already speaks. /chat/completions for OpenAI-style clients (Cline, Roo, Continue, aider), /responses for Codex CLI, /messages for Claude Code, Cursor and Zed. There is no fallback in those clients, so the endpoint is not optional.

Billing. Every call settles against your prepaid wallet in micro-USD, priced from the model you asked for. The hisoka block in a response tells you what that call cost and what is left. A model with is_free true settles at zero, but a free call still needs a small standing balance because it consumes upstream capacity.

Errors. Every failure returns the same nested envelope with a stable code, a request_id, and x-should-retry. Branch on the code, never on the message text.

Downloadable spec. This page is generated from /openapi.json. Agents that prefer text can read /llms.txt (one line per operation) or /llms-full.txt (request and response fields with a runnable curl).

GET / - Discover the API

GET /

Discover the API

Answers with the base URL and every endpoint, so a client that only knows the host can find the rest. Safe to poll as a liveness check.

Responses

Status Description

200

The endpoint map.

object

200 body

application/json

Field	Type	Description / Example
`object`	string
`name`	string
`api_version`	string
`base_url`	string
`endpoints`	map[string, string]	Description Absolute URLs, so a client does not have to join paths itself.
`wire_formats`	array[string]
`auth`	object
`docs`	string

GET /models - List models

GET /models

List models

Every model you can call, with its price and capabilities. No key required: this is the same list the public price page shows.

An out-of-stock model is absent rather than listed and failing, so a buyer never pays for a dead pool.

Responses

Status Description

200

The catalogue.

object

200 body

application/json

Field Type Description / Example

object "list"

data

array[object]

Show fields

Field Type Description / Example

id

string

Description

The id you send in a request. This is the only spelling a client needs.

object "model"

owned_by string

label

string

Description

Display name, for a picker.

api_model

string

Description

Upstream id. Informational: send id, not this.

is_free

boolean

Description

A free model settles at zero. It still needs the standing balance floor described in Getting started.

pricing

object

Show fields

Field	Type	Description / Example
`input_per_mtok`	number	Description USD per million input tokens. Exactly 0.0 on a free model, so a client computing its own cost cannot show a charge that never happened.
`output_per_mtok`	number	Description USD per million output tokens.
`currency`	"USD"

capabilities

object

Show fields

Field	Type	Description / Example
`modalities`	array["text" \| "image" \| "video" \| "audio"]	Description What you may send. Sending a modality the model does not list is refused with 400 before it reaches the provider.
`label`	string
`vision`	boolean
`tools`	boolean	Description Whether a tool schema may be sent at all.
`reasoning`	boolean
`prompt_cache`	boolean

multiplier

number

Description

Legacy display coefficient. Ignore it and use pricing.

max_output

integer

Description

Completion ceiling for this model.

context_window

integer

Description

Input and output share this window. Size your own budget from it.

max_input_tokens

integer

Description

Prompt budget. Equal to the window: a completion cap is a ceiling, not a reservation.

GET /models/{model} - Retrieve one model

GET /models/{model}

Retrieve one model

The same row as the list entry. OpenAI SDKs call this from models.retrieve(id); without it the SDK raises NotFoundError on a route that only exists in its own client.

Parameters

Name	In	Type	Description / Example
`model` *	path	string	Description The public model id.

Responses

Status Description

200

One model.

object

200 body

application/json

Field Type Description / Example

id

string

Description

The id you send in a request. This is the only spelling a client needs.

object "model"

owned_by string

label

string

Description

Display name, for a picker.

api_model

string

Description

Upstream id. Informational: send id, not this.

is_free

boolean

Description

A free model settles at zero. It still needs the standing balance floor described in Getting started.

pricing

object

Show fields

Field	Type	Description / Example
`input_per_mtok`	number	Description USD per million input tokens. Exactly 0.0 on a free model, so a client computing its own cost cannot show a charge that never happened.
`output_per_mtok`	number	Description USD per million output tokens.
`currency`	"USD"

capabilities

object

Show fields

Field	Type	Description / Example
`modalities`	array["text" \| "image" \| "video" \| "audio"]	Description What you may send. Sending a modality the model does not list is refused with 400 before it reaches the provider.
`label`	string
`vision`	boolean
`tools`	boolean	Description Whether a tool schema may be sent at all.
`reasoning`	boolean
`prompt_cache`	boolean

multiplier

number

Description

Legacy display coefficient. Ignore it and use pricing.

max_output

integer

Description

Completion ceiling for this model.

context_window

integer

Description

Input and output share this window. Size your own budget from it.

max_input_tokens

integer

Description

Prompt budget. Equal to the window: a completion cap is a ceiling, not a reservation.

404

No such model id.

object

404 body

application/json

Field Type Description / Example

error

object

Show fields

Field	Type	Description / Example
`message`	string	Description Human sentence. The code appears inside it too, because a pasted screenshot carries the sentence and not the field.
`type`	string	Description OpenAI-shaped class: authentication_error, invalid_request_error, rate_limit_error, api_error.
`param`	string \| null
`code`	string	Description Stable machine code. Branch on this, never on the message.
`support`	string	Description Contact address for an account or billing problem.
`docs`	string	Description Where the current reference lives.
`request_id`	string	Description Quote this in any report. It matches the X-Request-Id header.

GET /quota - Read the quota shape

GET /quota

Read the quota shape

Kept for clients that expect a quota object. It mirrors the wallet balance, which is the only limit that applies: there is no separate request allowance.

Responses

Status Description

200

The quota view.

object

200 body

application/json

Field Type Description / Example

object string

balance string

credits

object

Show fields

Field	Type	Description / Example
`remaining`	string
`used`	integer
`limit`	string
`unlimited`	boolean
`window`	string \| null

401

Missing, revoked or expired key.

object

401 body

application/json

Field Type Description / Example

error

object

Show fields

Field	Type	Description / Example
`message`	string	Description Human sentence. The code appears inside it too, because a pasted screenshot carries the sentence and not the field.
`type`	string	Description OpenAI-shaped class: authentication_error, invalid_request_error, rate_limit_error, api_error.
`param`	string \| null
`code`	string	Description Stable machine code. Branch on this, never on the message.
`support`	string	Description Contact address for an account or billing problem.
`docs`	string	Description Where the current reference lives.
`request_id`	string	Description Quote this in any report. It matches the X-Request-Id header.

GET /balance - Read your balance

GET /balance

Read your balance

The same figures the dashboard shows. Reported in dollars and in micro-USD, so a client reconciling cent-level rounding has the exact integer instead of a float.

Responses

Status Description

200

The wallet.

object

200 body

application/json

Field	Type	Description / Example
`object`	"balance"
`currency`	"USD"
`balance_usd`	number
`balance_micro_usd`	integer	Description What the wallet actually holds, as an integer.
`credits`	string	Description The same balance expressed in credits.
`credit_value_usd`	number	Description What one credit is worth, so the two numbers can be reconciled.

401

Missing, revoked or expired key.

object

401 body

application/json

Field Type Description / Example

error

object

Show fields

Field	Type	Description / Example
`message`	string	Description Human sentence. The code appears inside it too, because a pasted screenshot carries the sentence and not the field.
`type`	string	Description OpenAI-shaped class: authentication_error, invalid_request_error, rate_limit_error, api_error.
`param`	string \| null
`code`	string	Description Stable machine code. Branch on this, never on the message.
`support`	string	Description Contact address for an account or billing problem.
`docs`	string	Description Where the current reference lives.
`request_id`	string	Description Quote this in any report. It matches the X-Request-Id header.

GET /transactions - List transactions

GET /transactions

List transactions

Per-call rows from your ledger, newest first. Negative is money out, positive is money in, matching the wallet, so you never have to learn a per-type sign convention.

Parameters

Name	In	Type	Description / Example
`limit`	query	integer minimum: 1maximum: 100	Description Rows per page. Capped at 100.
`page`	query	integer minimum: 1
`type`	query	"usage" \| "grant" \| "topup" \| "adjustment" \| "purchase"	Description An unknown value is ignored rather than refused, so a stale client still gets data.
`model`	query	string	Description Exact model id. Anything else is ignored.
`since`	query	string:date-time
`until`	query	string:date-time

Responses

Status Description

200

A page of ledger rows.

object

200 body

application/json

Field Type Description / Example

object "list"

currency string

data

array[Transaction]

Show fields

Field	Type	Description / Example
`id`	string	Description Public id. Also accepted by the single-transaction endpoint.
`type`	"usage" \| "grant" \| "topup" \| "adjustment" \| "purchase"
`product`	string
`amount_usd`	number	Description Negative is money out.
`amount_micro_usd`	integer	Description The exact integer the wallet moved.
`balance_after_usd`	number
`balance_after_micro_usd`	integer
`created_at`	string:date-time
`model`	string	Description Present on a usage row.
`provider`	string	Description Our own brand. The upstream pool is never named.
`input_tokens`	integer
`output_tokens`	integer
`cached_tokens`	integer

total

integer

Description

Rows matching the filter, not rows on this page.

page integer

limit integer

has_more boolean

401

Missing, revoked or expired key.

object

401 body

application/json

Field Type Description / Example

error

object

Show fields

Field	Type	Description / Example
`message`	string	Description Human sentence. The code appears inside it too, because a pasted screenshot carries the sentence and not the field.
`type`	string	Description OpenAI-shaped class: authentication_error, invalid_request_error, rate_limit_error, api_error.
`param`	string \| null
`code`	string	Description Stable machine code. Branch on this, never on the message.
`support`	string	Description Contact address for an account or billing problem.
`docs`	string	Description Where the current reference lives.
`request_id`	string	Description Quote this in any report. It matches the X-Request-Id header.

GET /transactions/{publicId} - Retrieve one transaction

GET /transactions/{publicId}

Retrieve one transaction

One row, by its public id or its numeric id. Scoped to your own ledger: another account’s id answers 404 rather than 403, so the endpoint cannot be used to probe for ids.

Parameters

Name	In	Type	Description / Example
`publicId` *	path	string

Responses

Status Description

200

One ledger row.

Transaction

200 body

application/json

Field	Type	Description / Example
`id`	string	Description Public id. Also accepted by the single-transaction endpoint.
`type`	"usage" \| "grant" \| "topup" \| "adjustment" \| "purchase"
`product`	string
`amount_usd`	number	Description Negative is money out.
`amount_micro_usd`	integer	Description The exact integer the wallet moved.
`balance_after_usd`	number
`balance_after_micro_usd`	integer
`created_at`	string:date-time
`model`	string	Description Present on a usage row.
`provider`	string	Description Our own brand. The upstream pool is never named.
`input_tokens`	integer
`output_tokens`	integer
`cached_tokens`	integer

401

Missing, revoked or expired key.

object

401 body

application/json

Field Type Description / Example

error

object

Show fields

Field	Type	Description / Example
`message`	string	Description Human sentence. The code appears inside it too, because a pasted screenshot carries the sentence and not the field.
`type`	string	Description OpenAI-shaped class: authentication_error, invalid_request_error, rate_limit_error, api_error.
`param`	string \| null
`code`	string	Description Stable machine code. Branch on this, never on the message.
`support`	string	Description Contact address for an account or billing problem.
`docs`	string	Description Where the current reference lives.
`request_id`	string	Description Quote this in any report. It matches the X-Request-Id header.

404

That id is not in your ledger.

object

404 body

application/json

Field Type Description / Example

error

object

Show fields

Field	Type	Description / Example
`message`	string	Description Human sentence. The code appears inside it too, because a pasted screenshot carries the sentence and not the field.
`type`	string	Description OpenAI-shaped class: authentication_error, invalid_request_error, rate_limit_error, api_error.
`param`	string \| null
`code`	string	Description Stable machine code. Branch on this, never on the message.
`support`	string	Description Contact address for an account or billing problem.
`docs`	string	Description Where the current reference lives.
`request_id`	string	Description Quote this in any report. It matches the X-Request-Id header.

GET /usage/summary - Spend grouped by model

GET /usage/summary

Spend grouped by model

The report you pass through to your own customers: totals for a window, split per model, plus the effective rate.

Parameters

Name	In	Type	Description / Example
`period`	query	"24h" \| "7d" \| "30d" \| "90d"	Description An unrecognised value means all time, which the response reports as `all`.

Responses

Status Description

200

The summary.

object

200 body

application/json

Field Type Description / Example

object "usage_summary"

currency string

period string

requests integer

tokens_in integer

tokens_out integer

tokens integer

usd number

micro_usd integer

usd_per_1k_tokens

number | null

Description

Null when nothing was billed, because a rate over zero tokens is a division by zero dressed as a price.

models

array[object]

Show fields

Field	Type	Description / Example
`model`	string
`requests`	integer
`tokens_in`	integer
`tokens_out`	integer
`usd`	number
`micro_usd`	integer

401

Missing, revoked or expired key.

object

401 body

application/json

Field Type Description / Example

error

object

Show fields

Field	Type	Description / Example
`message`	string	Description Human sentence. The code appears inside it too, because a pasted screenshot carries the sentence and not the field.
`type`	string	Description OpenAI-shaped class: authentication_error, invalid_request_error, rate_limit_error, api_error.
`param`	string \| null
`code`	string	Description Stable machine code. Branch on this, never on the message.
`support`	string	Description Contact address for an account or billing problem.
`docs`	string	Description Where the current reference lives.
`request_id`	string	Description Quote this in any report. It matches the X-Request-Id header.

POST /chat/completions - Create a chat completion

POST /chat/completions

Create a chat completion

The OpenAI chat wire. Most clients use this one.

[!TIP] Leave max_tokens out unless you need a specific ceiling. Input and output share one window, so sending the model ceiling leaves no room for your prompt and the provider answers 400.

[!NOTE] stream: true sends server-sent events. The final frame carries the same hisoka block, so billing is readable on a stream too.

A reasoning model may answer with empty content and finish_reason: stop after spending its whole budget thinking. That is a finished turn, not an outage: check finish_reason before retrying, or you pay twice for an answer already given.

Request Body *

application/json

Field Type Description / Example

model

string

Description

A model id from GET /models. Omit it and the gateway uses the first published model.

messages *

array[object]

minItems: 1

Show fields

Field	Type	Description / Example
`role` *	"system" \| "user" \| "assistant" \| "tool"
`content` *	string \| array[object] Show fields One of: string array[object] Array items: object	Description A string, or an array of content parts for multimodal input.
`tool_calls`	array[object]	Description Assistant turn carrying tool calls. `function.arguments` may be a JSON string or an object; both are accepted.
`tool_call_id`	string	Description On a tool message: the id being answered.
`name`	string

max_tokens

integer

Description

Completion ceiling. Leave it out and the provider applies its own default; sending the model ceiling usually overflows the window.

temperature number

top_p number

stop

any

Description

A string or an array of strings.

stream

boolean

Description

Server-sent events. Our billing frames still apply.

tools

array[object]

Description

Tool schemas. Only send these to a model whose capabilities.tools is true.

tool_choice

any

Description

auto, none, required, or an object naming one function. Omit it and the model decides.

reasoning_effort

string

Description

Level of effort for a reasoning model. Supported values come from the model row and are clipped to what it implements.

Example

{
  "model": "glm-5.3-flash",
  "messages": [
    {
      "role": "system",
      "content": "You are terse."
    },
    {
      "role": "user",
      "content": "Name three prime numbers."
    }
  ],
  "temperature": 0.2
}

Responses

Status Description

200

The completion.

ChatCompletionResponse

200 body

application/json

Field Type Description / Example

id string

object "chat.completion"

created integer

model

string

Description

The public id you asked for.

choices

array[object]

Show fields

Field Type Description / Example

index integer

message

object

Show fields

Field	Type	Description / Example
`role`	string
`content`	string \| null	Description Empty is legitimate on a reasoning model that spent its whole budget thinking. Check `finish_reason` rather than treating an empty body as a failure.
`tool_calls`	array[object]

finish_reason

string

Description

stop, length, or tool_calls. Read length before deciding to continue: an upstream stop on a truncated answer is corrected to length.

usage

object

Show fields

Field	Type	Description / Example
`prompt_tokens`	integer
`completion_tokens`	integer
`total_tokens`	integer

hisoka

object

Show fields

Field	Type	Description / Example
`model`	string
`usd_charged`	number	Description What this call cost, in dollars.
`usd_micro_charged`	integer	Description The same figure in micro-USD, the exact integer the wallet moved.
`balance`	string	Description Balance after the call, as the gateway formats it.
`max_tokens`	integer \| null	Description The completion cap actually applied. Read it instead of assuming yours was honoured.
`cap_raised_from`	integer \| null	Description Set when a reasoning model needed a higher floor than you asked for, so a raised cap is visible rather than silent.
`client`	string	Description Detected client family, for support.

Description

Our own additions to the response envelope. Absent on a pure proxy, so treat it as optional.

400

Malformed body, empty messages, a modality the model does not take, or a context that overflows the window.

object

400 body

application/json

Field Type Description / Example

error

object

Show fields

Field	Type	Description / Example
`message`	string	Description Human sentence. The code appears inside it too, because a pasted screenshot carries the sentence and not the field.
`type`	string	Description OpenAI-shaped class: authentication_error, invalid_request_error, rate_limit_error, api_error.
`param`	string \| null
`code`	string	Description Stable machine code. Branch on this, never on the message.
`support`	string	Description Contact address for an account or billing problem.
`docs`	string	Description Where the current reference lives.
`request_id`	string	Description Quote this in any report. It matches the X-Request-Id header.

401

Missing, revoked or expired key.

object

401 body

application/json

Field Type Description / Example

error

object

Show fields

Field	Type	Description / Example
`message`	string	Description Human sentence. The code appears inside it too, because a pasted screenshot carries the sentence and not the field.
`type`	string	Description OpenAI-shaped class: authentication_error, invalid_request_error, rate_limit_error, api_error.
`param`	string \| null
`code`	string	Description Stable machine code. Branch on this, never on the message.
`support`	string	Description Contact address for an account or billing problem.
`docs`	string	Description Where the current reference lives.
`request_id`	string	Description Quote this in any report. It matches the X-Request-Id header.

402

The wallet cannot cover this call, or sits under the free-model floor.

object

402 body

application/json

Field Type Description / Example

error

object

Show fields

Field	Type	Description / Example
`message`	string	Description Human sentence. The code appears inside it too, because a pasted screenshot carries the sentence and not the field.
`type`	string	Description OpenAI-shaped class: authentication_error, invalid_request_error, rate_limit_error, api_error.
`param`	string \| null
`code`	string	Description Stable machine code. Branch on this, never on the message.
`support`	string	Description Contact address for an account or billing problem.
`docs`	string	Description Where the current reference lives.
`request_id`	string	Description Quote this in any report. It matches the X-Request-Id header.

404

That model id is not published.

object

404 body

application/json

Field Type Description / Example

error

object

Show fields

Field	Type	Description / Example
`message`	string	Description Human sentence. The code appears inside it too, because a pasted screenshot carries the sentence and not the field.
`type`	string	Description OpenAI-shaped class: authentication_error, invalid_request_error, rate_limit_error, api_error.
`param`	string \| null
`code`	string	Description Stable machine code. Branch on this, never on the message.
`support`	string	Description Contact address for an account or billing problem.
`docs`	string	Description Where the current reference lives.
`request_id`	string	Description Quote this in any report. It matches the X-Request-Id header.

429

Throttled. Retry-After carries the soonest wait, and x-should-retry is true.

object

429 body

application/json

Field Type Description / Example

error

object

Show fields

Field	Type	Description / Example
`message`	string	Description Human sentence. The code appears inside it too, because a pasted screenshot carries the sentence and not the field.
`type`	string	Description OpenAI-shaped class: authentication_error, invalid_request_error, rate_limit_error, api_error.
`param`	string \| null
`code`	string	Description Stable machine code. Branch on this, never on the message.
`support`	string	Description Contact address for an account or billing problem.
`docs`	string	Description Where the current reference lives.
`request_id`	string	Description Quote this in any report. It matches the X-Request-Id header.

502

The provider failed, or the reply arrived and could not be metered (so it was not billed).

object

502 body

application/json

Field Type Description / Example

error

object

Show fields

Field	Type	Description / Example
`message`	string	Description Human sentence. The code appears inside it too, because a pasted screenshot carries the sentence and not the field.
`type`	string	Description OpenAI-shaped class: authentication_error, invalid_request_error, rate_limit_error, api_error.
`param`	string \| null
`code`	string	Description Stable machine code. Branch on this, never on the message.
`support`	string	Description Contact address for an account or billing problem.
`docs`	string	Description Where the current reference lives.
`request_id`	string	Description Quote this in any report. It matches the X-Request-Id header.

503

Nothing healthy in the pool, or the catalogue is empty.

object

503 body

application/json

Field Type Description / Example

error

object

Show fields

Field	Type	Description / Example
`message`	string	Description Human sentence. The code appears inside it too, because a pasted screenshot carries the sentence and not the field.
`type`	string	Description OpenAI-shaped class: authentication_error, invalid_request_error, rate_limit_error, api_error.
`param`	string \| null
`code`	string	Description Stable machine code. Branch on this, never on the message.
`support`	string	Description Contact address for an account or billing problem.
`docs`	string	Description Where the current reference lives.
`request_id`	string	Description Quote this in any report. It matches the X-Request-Id header.

POST /responses - Create a response

POST /responses

Create a response

The OpenAI Responses wire, which Codex CLI speaks. Semantics match /chat/completions; only the envelope differs.

Request Body *

application/json

Field Type Description / Example

model

string

Description

A model id from GET /models. Omit it and the gateway uses the first published model.

messages *

array[object]

minItems: 1

Show fields

Field	Type	Description / Example
`role` *	"system" \| "user" \| "assistant" \| "tool"
`content` *	string \| array[object] Show fields One of: string array[object] Array items: object	Description A string, or an array of content parts for multimodal input.
`tool_calls`	array[object]	Description Assistant turn carrying tool calls. `function.arguments` may be a JSON string or an object; both are accepted.
`tool_call_id`	string	Description On a tool message: the id being answered.
`name`	string

max_tokens

integer

Description

Completion ceiling. Leave it out and the provider applies its own default; sending the model ceiling usually overflows the window.

temperature number

top_p number

stop

any

Description

A string or an array of strings.

stream

boolean

Description

Server-sent events. Our billing frames still apply.

tools

array[object]

Description

Tool schemas. Only send these to a model whose capabilities.tools is true.

tool_choice

any

Description

auto, none, required, or an object naming one function. Omit it and the model decides.

reasoning_effort

string

Description

Level of effort for a reasoning model. Supported values come from the model row and are clipped to what it implements.

Example

{
  "model": "deepseek-v4.1-flash-1017",
  "messages": [
    {
      "role": "user",
      "content": "ping"
    }
  ]
}

Responses

Status Description

200

The response object.

object

400

Malformed body or an unsupported parameter.

object

400 body

application/json

Field Type Description / Example

error

object

Show fields

Field	Type	Description / Example
`message`	string	Description Human sentence. The code appears inside it too, because a pasted screenshot carries the sentence and not the field.
`type`	string	Description OpenAI-shaped class: authentication_error, invalid_request_error, rate_limit_error, api_error.
`param`	string \| null
`code`	string	Description Stable machine code. Branch on this, never on the message.
`support`	string	Description Contact address for an account or billing problem.
`docs`	string	Description Where the current reference lives.
`request_id`	string	Description Quote this in any report. It matches the X-Request-Id header.

401

Missing, revoked or expired key.

object

401 body

application/json

Field Type Description / Example

error

object

Show fields

Field	Type	Description / Example
`message`	string	Description Human sentence. The code appears inside it too, because a pasted screenshot carries the sentence and not the field.
`type`	string	Description OpenAI-shaped class: authentication_error, invalid_request_error, rate_limit_error, api_error.
`param`	string \| null
`code`	string	Description Stable machine code. Branch on this, never on the message.
`support`	string	Description Contact address for an account or billing problem.
`docs`	string	Description Where the current reference lives.
`request_id`	string	Description Quote this in any report. It matches the X-Request-Id header.

402

The wallet cannot cover this call.

object

402 body

application/json

Field Type Description / Example

error

object

Show fields

Field	Type	Description / Example
`message`	string	Description Human sentence. The code appears inside it too, because a pasted screenshot carries the sentence and not the field.
`type`	string	Description OpenAI-shaped class: authentication_error, invalid_request_error, rate_limit_error, api_error.
`param`	string \| null
`code`	string	Description Stable machine code. Branch on this, never on the message.
`support`	string	Description Contact address for an account or billing problem.
`docs`	string	Description Where the current reference lives.
`request_id`	string	Description Quote this in any report. It matches the X-Request-Id header.

404

That model id is not published.

object

404 body

application/json

Field Type Description / Example

error

object

Show fields

Field	Type	Description / Example
`message`	string	Description Human sentence. The code appears inside it too, because a pasted screenshot carries the sentence and not the field.
`type`	string	Description OpenAI-shaped class: authentication_error, invalid_request_error, rate_limit_error, api_error.
`param`	string \| null
`code`	string	Description Stable machine code. Branch on this, never on the message.
`support`	string	Description Contact address for an account or billing problem.
`docs`	string	Description Where the current reference lives.
`request_id`	string	Description Quote this in any report. It matches the X-Request-Id header.

429

Throttled.

object

429 body

application/json

Field Type Description / Example

error

object

Show fields

Field	Type	Description / Example
`message`	string	Description Human sentence. The code appears inside it too, because a pasted screenshot carries the sentence and not the field.
`type`	string	Description OpenAI-shaped class: authentication_error, invalid_request_error, rate_limit_error, api_error.
`param`	string \| null
`code`	string	Description Stable machine code. Branch on this, never on the message.
`support`	string	Description Contact address for an account or billing problem.
`docs`	string	Description Where the current reference lives.
`request_id`	string	Description Quote this in any report. It matches the X-Request-Id header.

502

The provider failed.

object

502 body

application/json

Field Type Description / Example

error

object

Show fields

Field	Type	Description / Example
`message`	string	Description Human sentence. The code appears inside it too, because a pasted screenshot carries the sentence and not the field.
`type`	string	Description OpenAI-shaped class: authentication_error, invalid_request_error, rate_limit_error, api_error.
`param`	string \| null
`code`	string	Description Stable machine code. Branch on this, never on the message.
`support`	string	Description Contact address for an account or billing problem.
`docs`	string	Description Where the current reference lives.
`request_id`	string	Description Quote this in any report. It matches the X-Request-Id header.

POST /messages - Create a message

POST /messages

Create a message

The Anthropic Messages wire, which Claude Code, Cursor and Zed speak. Auth accepts x-api-key as well as a bearer token.

[!WARNING] Set your base URL to the host root, not to this path. The SDKs append their own /v1, so https://hisoka.ai/api/v1 reaches this endpoint correctly while also using it twice breaks the path. The gateway collapses a repeated version segment but will never strip a single one.

Errors use the Anthropic envelope: {"type": "error", "error": {...}} with an Anthropic error.type beside our own code.

tool_choice left unspecified stays unspecified. It is never rewritten to required, which would force a tool call forever and make an agent loop on 200 responses.

Request Body *

application/json

Field	Type	Description / Example
`model` *	string
`max_tokens` *	integer	Description Required by this wire.
`messages` *	array[object]	Description Anthropic message objects.
`system`	any	Description A string, or an array of content blocks.
`stream`	boolean
`tools`	array[object]
`tool_choice`	object	Description Left alone when omitted.

Example

{
  "model": "glm-5.3-flash",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "ping"
    }
  ]
}

Responses

Status Description

200

The message object.

object

400

Malformed body or an unsupported parameter.

object

400 body

application/json

Field Type Description / Example

error

object

Show fields

Field	Type	Description / Example
`message`	string	Description Human sentence. The code appears inside it too, because a pasted screenshot carries the sentence and not the field.
`type`	string	Description OpenAI-shaped class: authentication_error, invalid_request_error, rate_limit_error, api_error.
`param`	string \| null
`code`	string	Description Stable machine code. Branch on this, never on the message.
`support`	string	Description Contact address for an account or billing problem.
`docs`	string	Description Where the current reference lives.
`request_id`	string	Description Quote this in any report. It matches the X-Request-Id header.

401

Missing, revoked or expired key.

object

401 body

application/json

Field Type Description / Example

error

object

Show fields

Field	Type	Description / Example
`message`	string	Description Human sentence. The code appears inside it too, because a pasted screenshot carries the sentence and not the field.
`type`	string	Description OpenAI-shaped class: authentication_error, invalid_request_error, rate_limit_error, api_error.
`param`	string \| null
`code`	string	Description Stable machine code. Branch on this, never on the message.
`support`	string	Description Contact address for an account or billing problem.
`docs`	string	Description Where the current reference lives.
`request_id`	string	Description Quote this in any report. It matches the X-Request-Id header.

402

The wallet cannot cover this call.

object

402 body

application/json

Field Type Description / Example

error

object

Show fields

Field	Type	Description / Example
`message`	string	Description Human sentence. The code appears inside it too, because a pasted screenshot carries the sentence and not the field.
`type`	string	Description OpenAI-shaped class: authentication_error, invalid_request_error, rate_limit_error, api_error.
`param`	string \| null
`code`	string	Description Stable machine code. Branch on this, never on the message.
`support`	string	Description Contact address for an account or billing problem.
`docs`	string	Description Where the current reference lives.
`request_id`	string	Description Quote this in any report. It matches the X-Request-Id header.

404

That model id is not published.

object

404 body

application/json

Field Type Description / Example

error

object

Show fields

Field	Type	Description / Example
`message`	string	Description Human sentence. The code appears inside it too, because a pasted screenshot carries the sentence and not the field.
`type`	string	Description OpenAI-shaped class: authentication_error, invalid_request_error, rate_limit_error, api_error.
`param`	string \| null
`code`	string	Description Stable machine code. Branch on this, never on the message.
`support`	string	Description Contact address for an account or billing problem.
`docs`	string	Description Where the current reference lives.
`request_id`	string	Description Quote this in any report. It matches the X-Request-Id header.

429

Throttled. Retry-After carries the soonest wait.

object

429 body

application/json

Field Type Description / Example

error

object

Show fields

Field	Type	Description / Example
`message`	string	Description Human sentence. The code appears inside it too, because a pasted screenshot carries the sentence and not the field.
`type`	string	Description OpenAI-shaped class: authentication_error, invalid_request_error, rate_limit_error, api_error.
`param`	string \| null
`code`	string	Description Stable machine code. Branch on this, never on the message.
`support`	string	Description Contact address for an account or billing problem.
`docs`	string	Description Where the current reference lives.
`request_id`	string	Description Quote this in any report. It matches the X-Request-Id header.

502

The provider failed.

object

502 body

application/json

Field Type Description / Example

error

object

Show fields

Field	Type	Description / Example
`message`	string	Description Human sentence. The code appears inside it too, because a pasted screenshot carries the sentence and not the field.
`type`	string	Description OpenAI-shaped class: authentication_error, invalid_request_error, rate_limit_error, api_error.
`param`	string \| null
`code`	string	Description Stable machine code. Branch on this, never on the message.
`support`	string	Description Contact address for an account or billing problem.
`docs`	string	Description Where the current reference lives.
`request_id`	string	Description Quote this in any report. It matches the X-Request-Id header.

POST /messages/count_tokens - Count tokens

POST /messages/count_tokens

Count tokens

Answered locally rather than proxied, so a client that calls it before every turn does not double the upstream request count.

[!NOTE] This is an estimate. It is the right shape for budgeting a context window, not a figure to bill against.

Request Body *

application/json

Field	Type	Description / Example
`system`	any	Description A string or content blocks.
`messages`	array[object]
`tools`	array[object]

Example

{
  "messages": [
    {
      "role": "user",
      "content": "ping"
    }
  ]
}

Responses

Status Description

200

The estimate.

object

200 body

application/json

Field	Type	Description / Example
`input_tokens`	integer

401

Missing, revoked or expired key.

object

401 body

application/json

Field Type Description / Example

error

object

Show fields

Field	Type	Description / Example
`message`	string	Description Human sentence. The code appears inside it too, because a pasted screenshot carries the sentence and not the field.
`type`	string	Description OpenAI-shaped class: authentication_error, invalid_request_error, rate_limit_error, api_error.
`param`	string \| null
`code`	string	Description Stable machine code. Branch on this, never on the message.
`support`	string	Description Contact address for an account or billing problem.
`docs`	string	Description Where the current reference lives.
`request_id`	string	Description Quote this in any report. It matches the X-Request-Id header.

Endpoint explorer

Endpoint explorer

Hisoka API

GET / - Discover the API

Responses

GET /models - List models

Responses

GET /models/{model} - Retrieve one model

Parameters

Responses

GET /quota - Read the quota shape

Responses

GET /balance - Read your balance

Responses

GET /transactions - List transactions

Parameters

Responses

GET /transactions/{publicId} - Retrieve one transaction

Parameters

Responses

GET /usage/summary - Spend grouped by model

Parameters

Responses

POST /chat/completions - Create a chat completion

Request Body *

Example

Responses

POST /responses - Create a response

Request Body *

Example

Responses

POST /messages - Create a message

Request Body *

Example

Responses

POST /messages/count_tokens - Count tokens

Request Body *

Example

Responses

On This Page