API reference

v0.1.0 · 247 operations
Base URLhttps://api.opennozzle.com
AuthenticationAuthorization: Bearer pk_live_…Each operation names the scope it needs.
RetriesIdempotency-Key: <uuid>Required where marked; a retry replays, never repeats.
The error envelope every failure uses
errorobjectrequired
codestringrequired
Stable machine-readable code, e.g. `auth.missing_scope`, `request.invalid`, `upstream.rate_limited`.
detailsobject
Optional structured context — the offending parameter, the unsupported fields, the upstream's own error code.
messagestringrequired
Human-facing explanation.
request_idstring
UUIDv7 for this request; quote it in support requests.
trace_idstring
W3C trace id, for correlating across services.

Inference

17 operations
post/anthropic/v1/messages

Anthropic Messages API drop-in — translated to the one chat pipeline. A filtered reply ends `stop_reason: refusal` and names the filter in the Nozzle extension `finish_detail` (chat completions' vocabulary) beside it, on the message and on the stream's `message_delta.delta`.

inference:call

Parameters

· string
· string

Request body

object

Response · 200

object

curl -X POST https://api.opennozzle.com/anthropic/v1/messages \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
post/v1/audio/speech

OpenAI-compatible text-to-speech: model, input, voice, optional response_format, speed and instructions (style direction, on models that take it). Audio bytes out. Bills per input character, per reported token or per estimated minute, whichever the model is priced in (pricing.billing_unit).

inference:call

Request body

object

Response · 200

object

curl -X POST https://api.opennozzle.com/v1/audio/speech \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
post/v1/audio/transcriptions

OpenAI-compatible transcription (multipart). Bills by reported duration.

inference:call

Request body

object

Response · 200

object

curl -X POST https://api.opennozzle.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
post/v1/audio/translations

OpenAI-compatible speech translation to English (multipart). Bills by reported duration.

inference:call

Request body

object

Response · 200

object

curl -X POST https://api.opennozzle.com/v1/audio/translations \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
post/v1/chat/completions

OpenAI-compatible chat completion. Routes through model_registry. Nozzle extension: a choice a provider's filter blocked ends `finish_reason: content_filter` as on OpenAI and names the filter in `finish_detail`, the provider's own reason lowercased: `recitation`, `safety`, `blocklist`, `prohibited_content`, `spii` (Gemini), `refusal` (Anthropic), `guardrail_intervened` (Bedrock), `error_toxic` (Cohere). Absent on every other choice, and when the provider names no filter. A stream carries it on the chunk that finishes the choice. A prompt Gemini refuses outright is 400 `request.invalid` with `details.upstream_error_code: inference.content_policy_violation` and the same name at `details.upstream_details.finish_detail`.

inference:call

Parameters

· string
· string

Request body

object

Response · 200

object

curl -X POST https://api.opennozzle.com/v1/chat/completions \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
post/v1/classify

Classify inputs. Bills per classification.

inference:call

Request body

object

Response · 200

object

curl -X POST https://api.opennozzle.com/v1/classify \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
post/v1/completions

OpenAI-compatible legacy text completion. Adapts onto the chat pipeline; a filtered choice carries the chat pipeline's `finish_detail` beside `finish_reason`.

inference:call

Parameters

· string
· string

Request body

object

Response · 200

object

curl -X POST https://api.opennozzle.com/v1/completions \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
post/v1/embeddings

OpenAI-compatible embeddings. Routes through model_registry.

inference:call

Request body

object

Response · 200

object

curl -X POST https://api.opennozzle.com/v1/embeddings \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
post/v1/images/edits

OpenAI-compatible image edits (multipart: reference images + prompt). gpt-image dialect only; bills from token usage.

inference:call

Request body

object

Response · 200

object

curl -X POST https://api.opennozzle.com/v1/images/edits \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
post/v1/images/generations

OpenAI-compatible image generation. Bills per image at the quality-multiplied baseline, or from token usage on the gpt-image dialect.

inference:call

Request body

object

Response · 200

object

curl -X POST https://api.opennozzle.com/v1/images/generations \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
get/v1/models

OpenAI-compatible model list — drop-in for OpenAI SDK clients.

catalog:read

Response · 200

dataOpenAiModel[]required
createdinteger · int64required
idstringrequired
limitsCallerLimitsrequired
What the caller is held to when it calls this model. Additive to the OpenAI shape, which SDKs ignore.
requests_per_minuteinteger · uint32
This key's requests per minute, counted separately on every endpoint path: `/v1/chat/completions` and `/v1/embeddings` are two windows. `null` when the key carries no cap (the default): the gateway does not limit it, and the provider's own limits are the only bound.
tenant_requests_per_dayinteger · int64
The plan's requests per day, shared the same way (a rolling 24 hours).
tenant_requests_per_minuteinteger · int64
The plan's requests per minute, shared by every key of the tenant across every inference call.
tokens_per_minuteinteger · uint32
This key's tokens per minute across every inference call, charged at an upper-bound estimate before the call and settled after it.
objectstringrequired
owned_bystringrequired
objectstringrequired
curl -X GET https://api.opennozzle.com/v1/models \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/models/{id}

OpenAI-compatible model retrieve — one callable model by name.

catalog:read

Parameters

idpath · stringrequired

Response · 200

createdinteger · int64required
idstringrequired
limitsCallerLimitsrequired
What the caller is held to when it calls this model. Additive to the OpenAI shape, which SDKs ignore.
requests_per_minuteinteger · uint32
This key's requests per minute, counted separately on every endpoint path: `/v1/chat/completions` and `/v1/embeddings` are two windows. `null` when the key carries no cap (the default): the gateway does not limit it, and the provider's own limits are the only bound.
tenant_requests_per_dayinteger · int64
The plan's requests per day, shared the same way (a rolling 24 hours).
tenant_requests_per_minuteinteger · int64
The plan's requests per minute, shared by every key of the tenant across every inference call.
tokens_per_minuteinteger · uint32
This key's tokens per minute across every inference call, charged at an upper-bound estimate before the call and settled after it.
objectstringrequired
owned_bystringrequired
curl -X GET https://api.opennozzle.com/v1/models/<id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/models/{id}/capabilities

Per-wire capability declaration for a model — the same truths the router refuses on.

catalog:read

Parameters

idpath · stringrequired

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/models/<id>/capabilities \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/models/{id}/health

What this model's serving lane did last: healthy, degraded, dead or unknown, with the evidence.

catalog:read

Parameters

idpath · stringrequired

Response · 200

binding_idstring · uuidrequired
consecutive_failuresinteger · int32required
kindstringrequired
last_failure_atstring · date-time
last_failure_codestring
last_failure_statusinteger · int16
last_success_atstring · date-time
modelstringrequired
providerstring
statusstringrequired
curl -X GET https://api.opennozzle.com/v1/models/<id>/health \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/moderations

OpenAI-compatible content moderation. Flat per-call rate.

inference:call

Request body

object

Response · 200

object

curl -X POST https://api.opennozzle.com/v1/moderations \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
post/v1/rerank

Rerank documents against a query. Bills in search units.

inference:call

Request body

object

Response · 200

object

curl -X POST https://api.opennozzle.com/v1/rerank \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
post/v1/responses

OpenAI Responses API — reasoning items and function tools together, streamed as Responses events, billed like chat.

inference:call

Parameters

· string

Request body

object

Response · 200

object

curl -X POST https://api.opennozzle.com/v1/responses \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Models & catalog

8 operations
get/v1/catalog

Nested Model → Variants browse surface for the dashboard catalog page.

catalog:read

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/catalog \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/catalog/health

Health of every platform-served model lane: healthy, degraded, dead or unknown. Public; no tenant data.

no auth

Response · 200

consecutive_failuresinteger · int32required
kindstringrequired
last_failure_atstring · date-time
last_failure_codestring
last_success_atstring · date-time
modelstringrequired
providerstring
statusstringrequired
curl -X GET https://api.opennozzle.com/v1/catalog/health \
  -s
get/v1/catalog/models

List the catalog. With neither `bound` nor `deployability` given it lists the models THIS caller can call, each under the id it sends as `model`; `deployability=all` lists the whole registry, callable rows first. Each row carries context_window, max_output_tokens, pricing, deployability, and what the caller resolves to: `bound`, `provider`, `upstream_model`, `kind` and `wire_capabilities` (the booleans `/v1/models/{id}/capabilities` answers). Optional query filters, all AND-ed: `provider`, `modality`, `q` (substring of id or display name), `min_context`, `max_input_cents_per_mtok`, `bound` (true|false), `deployability` (callable|launchable|blueprint_no_gpu|no_blueprint|all), `limit` (1-500, default 100), `offset`.

no auth

Response · 200

activebooleanrequired
boundbooleanrequired
Whether the caller can call this model right now: a global active binding, or a binding in the caller's own tenant. Unlike `active` (any tenant's binding counts) and `deployability.status == callable` (same), this is answered for the caller who asked.
capabilitiesstring[]required
context_windowinteger · int32
created_atstring · date-timerequired
deployabilityDeployabilityrequired
How (and whether) this model can be served — see [`Deployability`].
blueprintsstring[]required
Names of the Blueprints that can launch this model's family.
est_hourly_centsinteger · int64
Floor hourly cost of a self-hosted launch, integer cents. Present only when a Blueprint AND a priced GPU both exist.
gpu_requiredbooleanrequired
Whether serving this model needs a GPU launch (i.e. it has a Blueprint) versus being callable through an existing binding.
statusDeployabilityStatusrequired
Deployability tiers, in descending readiness. The wire strings are the `?deployability=` filter values.
display_namestringrequired
familystringrequired
hf_repostring
idstringrequired
kindstring
The binding kind — which inference surface serves it (`openai_chat`, `openai_embed`, `openai_transcription`, `openai_image`, …); `null` when `bound` is false.
licensestring
max_output_tokensinteger · int32
The most tokens one reply may carry, as the provider states it. `None` ⇒ unpublished; a consumer must not guess it.
modalitystringrequired
params_total_bnumber · double
pricingPricingrequired
The list price, every dimension the cost writer bills on. The three cache rates are published so a consumer that mirrors this catalog and estimates its own spend (Lighthouse does) prices a cache read and a cache write with the SAME numbers the ledger uses, instead of guessing a multiplier and drifting from the bill. Absent when the model has no such rate.
billing_unitBillingUnit | null
The unit the ledger charges this model in, for the binding the caller resolves to — derived by `model_registry::billing_unit`, the same decision the cost writers take. Null when the caller has no binding for this model (nothing it could be charged for).
cache_creation_1hr_cents_per_mtoknumber · double
cache_creation_cents_per_mtoknumber · double
cached_input_cents_per_mtoknumber · double
cents_per_audio_minutenumber · double
Per minute of audio (speech generation and transcription). Null when unset.
cents_per_classificationnumber · double
Per input classified. Null when unset.
cents_per_image_baselinenumber · double
Per generated image at baseline quality. Null when unset.
cents_per_mcharnumber · double
Per million input characters synthesized (character-priced speech). Null when unset.
cents_per_requestnumber · double
Per request (moderation, fixed-cost custom endpoints). Null when unset.
cents_per_search_unitnumber · double
Per rerank search unit. Null when unset.
cents_per_video_secondnumber · double
Per generated second of video. Null when unset.
currencystringrequired
image_input_cents_per_mtoknumber · double
Rate for input tokens that are images (gpt-image edits' reference images). Absent means image input bills at `input_cents_per_mtok`.
input_cents_per_mtoknumber · double
long_contextLongContextRates | null
The provider's long-prompt tier: once a prompt exceeds `above_prompt_tokens` the whole call bills at these rates. Absent when the model has one rate at every length.
output_cents_per_mtoknumber · double
tiersTierRatesrequired
The rate tiers a call to this model can be billed at through Nozzle, in permille of the standard rate: `flex_permille` / `priority_permille` (ask with `service_tier`), `batch_permille` (lines of a `/v1/batches` batch), and an `off_peak` clock (`{permille, peak_utc}`: every hour outside the peak windows is billed at permille). Null means the tier is not available for this model.
batch_permilleinteger · uint16
flex_permilleinteger · uint16
off_peakOffPeak | null
priority_permilleinteger · uint16
providerstring
The upstream provider the caller's resolving binding routes to; `null` when `bound` is false.
reasoning_effort_maparray
The same efforts, each with the request fragment it becomes upstream (`{"reasoning_effort": "low"}`, `{"output_config": {"effort": "low"}}`, `{"thinkingConfig": {"thinkingBudget": 0}}`) and the operator's note where the word alone would mislead.
reasoning_effortsarray
The `reasoning_effort` values the router accepts for the caller's resolving binding, least thinking first, read from the same row the router validates against. `[]` when the model takes none (a value is refused by name). `null` when `bound` is false, or when Nozzle forwards the word verbatim and the upstream decides, so there is no list Nozzle can vouch for.
reasoning_visibleReasoningVisibility | null
What readable reasoning a stream carries as `delta.reasoning_content`: `summary` (a provider-written summary, which Nozzle requests), `full` (the provider returns the reasoning text itself) or `none`. Never encrypted or redacted reasoning. `null` when `bound` is false.
updated_atstring · date-timerequired
upstream_modelstring
The model id on that provider's wire; `null` when `bound` is false.
wire_capabilitiesWireCapabilities | null
The parameter support the router enforces for the caller's resolving binding — the same booleans `GET /v1/models/{id}/capabilities` answers, computed the same way (wire family, narrowed by the provider row, the model's own profile and the binding kind). `null` when `bound` is false: there is no binding to answer for. Distinct from `capabilities`, which is the curated tag list a discovered model carries before any binding exists.
curl -X GET https://api.opennozzle.com/v1/catalog/models \
  -s
get/v1/catalog/models/{id}

Get a single catalog model by id (typed flat shape — legacy).

no auth

Parameters

idpath · stringrequired

Response · 200

activebooleanrequired
boundbooleanrequired
Whether the caller can call this model right now: a global active binding, or a binding in the caller's own tenant. Unlike `active` (any tenant's binding counts) and `deployability.status == callable` (same), this is answered for the caller who asked.
capabilitiesstring[]required
context_windowinteger · int32
created_atstring · date-timerequired
deployabilityDeployabilityrequired
How (and whether) this model can be served — see [`Deployability`].
blueprintsstring[]required
Names of the Blueprints that can launch this model's family.
est_hourly_centsinteger · int64
Floor hourly cost of a self-hosted launch, integer cents. Present only when a Blueprint AND a priced GPU both exist.
gpu_requiredbooleanrequired
Whether serving this model needs a GPU launch (i.e. it has a Blueprint) versus being callable through an existing binding.
statusDeployabilityStatusrequired
Deployability tiers, in descending readiness. The wire strings are the `?deployability=` filter values.
display_namestringrequired
familystringrequired
hf_repostring
idstringrequired
kindstring
The binding kind — which inference surface serves it (`openai_chat`, `openai_embed`, `openai_transcription`, `openai_image`, …); `null` when `bound` is false.
licensestring
max_output_tokensinteger · int32
The most tokens one reply may carry, as the provider states it. `None` ⇒ unpublished; a consumer must not guess it.
modalitystringrequired
params_total_bnumber · double
pricingPricingrequired
The list price, every dimension the cost writer bills on. The three cache rates are published so a consumer that mirrors this catalog and estimates its own spend (Lighthouse does) prices a cache read and a cache write with the SAME numbers the ledger uses, instead of guessing a multiplier and drifting from the bill. Absent when the model has no such rate.
billing_unitBillingUnit | null
The unit the ledger charges this model in, for the binding the caller resolves to — derived by `model_registry::billing_unit`, the same decision the cost writers take. Null when the caller has no binding for this model (nothing it could be charged for).
cache_creation_1hr_cents_per_mtoknumber · double
cache_creation_cents_per_mtoknumber · double
cached_input_cents_per_mtoknumber · double
cents_per_audio_minutenumber · double
Per minute of audio (speech generation and transcription). Null when unset.
cents_per_classificationnumber · double
Per input classified. Null when unset.
cents_per_image_baselinenumber · double
Per generated image at baseline quality. Null when unset.
cents_per_mcharnumber · double
Per million input characters synthesized (character-priced speech). Null when unset.
cents_per_requestnumber · double
Per request (moderation, fixed-cost custom endpoints). Null when unset.
cents_per_search_unitnumber · double
Per rerank search unit. Null when unset.
cents_per_video_secondnumber · double
Per generated second of video. Null when unset.
currencystringrequired
image_input_cents_per_mtoknumber · double
Rate for input tokens that are images (gpt-image edits' reference images). Absent means image input bills at `input_cents_per_mtok`.
input_cents_per_mtoknumber · double
long_contextLongContextRates | null
The provider's long-prompt tier: once a prompt exceeds `above_prompt_tokens` the whole call bills at these rates. Absent when the model has one rate at every length.
output_cents_per_mtoknumber · double
tiersTierRatesrequired
The rate tiers a call to this model can be billed at through Nozzle, in permille of the standard rate: `flex_permille` / `priority_permille` (ask with `service_tier`), `batch_permille` (lines of a `/v1/batches` batch), and an `off_peak` clock (`{permille, peak_utc}`: every hour outside the peak windows is billed at permille). Null means the tier is not available for this model.
batch_permilleinteger · uint16
flex_permilleinteger · uint16
off_peakOffPeak | null
priority_permilleinteger · uint16
providerstring
The upstream provider the caller's resolving binding routes to; `null` when `bound` is false.
reasoning_effort_maparray
The same efforts, each with the request fragment it becomes upstream (`{"reasoning_effort": "low"}`, `{"output_config": {"effort": "low"}}`, `{"thinkingConfig": {"thinkingBudget": 0}}`) and the operator's note where the word alone would mislead.
reasoning_effortsarray
The `reasoning_effort` values the router accepts for the caller's resolving binding, least thinking first, read from the same row the router validates against. `[]` when the model takes none (a value is refused by name). `null` when `bound` is false, or when Nozzle forwards the word verbatim and the upstream decides, so there is no list Nozzle can vouch for.
reasoning_visibleReasoningVisibility | null
What readable reasoning a stream carries as `delta.reasoning_content`: `summary` (a provider-written summary, which Nozzle requests), `full` (the provider returns the reasoning text itself) or `none`. Never encrypted or redacted reasoning. `null` when `bound` is false.
updated_atstring · date-timerequired
upstream_modelstring
The model id on that provider's wire; `null` when `bound` is false.
wire_capabilitiesWireCapabilities | null
The parameter support the router enforces for the caller's resolving binding — the same booleans `GET /v1/models/{id}/capabilities` answers, computed the same way (wire family, narrowed by the provider row, the model's own profile and the binding kind). `null` when `bound` is false: there is no binding to answer for. Distinct from `capabilities`, which is the curated tag list a discovered model carries before any binding exists.
curl -X GET https://api.opennozzle.com/v1/catalog/models/<id> \
  -s
post/v1/models

Register a model your project can call, served by a named provider.

catalog:readcatalog:writeIdempotency-Keyemits model.promoted

Request body

cents_per_audio_minutenumber · double
Cost per minute of audio, in cents — the unit an audio model bills in. Required for `modality: "audio"` unless the catalog already prices it.
input_cents_per_mtoknumber · double
Cost per million input tokens, in cents. Required only when the catalog does not already price this model under this provider, and only for a token-billed modality.
modalitystring
What the model serves, and therefore which surface it answers on: `text` (the default) for `/v1/chat/completions`, `embedding` for `/v1/embeddings`, `audio` for `/v1/audio/transcriptions`. The binding kind is derived from it by the same mapping a self-hosted pod uses, so there is one vocabulary for "what is this model", not two. One of `text`, `embedding`, `audio`. Sent as a string because the vocabulary belongs to the registry crate, which has no business deriving a JSON schema; an unknown value is refused by name.
namestringrequired
The name you will send in `{"model": "..."}`. Any string you like — an alias you invent, or an existing catalog name you are re-pointing at your own provider account.
output_cents_per_mtoknumber · double
Cost per million output tokens, in cents.
providerstringrequired
Which upstream serves it. Must be enabled; `GET /v1/providers` lists the ones available to you.
upstream_modelstringrequired
The provider's own name for the model. Routinely differs from `name` (`Qwen/Qwen3.8-27B` at DeepInfra vs `qwen3.8-27b` at Groq), which is exactly why both exist.

Response · 200

idstringrequired
modalitystringrequired
What it serves, echoed back so a client can see which surface to call.
namestringrequired
providerstringrequired
scopestringrequired
Always `"tenant"`. Stated rather than implied so a client can tell a model it registered from one the platform published.
upstream_modelstringrequired
curl -X POST https://api.opennozzle.com/v1/models \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "cents_per_audio_minute": null,
  "input_cents_per_mtok": null,
  "modality": null,
  "name": "string",
  "output_cents_per_mtok": null,
  "provider": "string",
  "upstream_model": "string"
}'
delete/v1/models/{id}

Stop serving a model you registered; platform models are unaffected.

catalog:readcatalog:writeIdempotency-Key

Parameters

idpath · stringrequired

Response · 204

Success. No response body.

curl -X DELETE https://api.opennozzle.com/v1/models/<id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s
get/v1/providers

List providers you can register a model against.

catalog:read

Response · 200

credentialstringrequired
`"platform"` when Nozzle holds the credential and bills you for tokens; `"byok"` when you must supply your own via `POST /v1/byok/credentials`; `"self_hosted"` for pods we run.
namestringrequired
wire_familystringrequired
curl -X GET https://api.opennozzle.com/v1/providers \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/registrations

List the models you registered, as opposed to the platform catalog.

catalog:read

Response · 200

idstringrequired
modalitystringrequired
What it serves, echoed back so a client can see which surface to call.
namestringrequired
providerstringrequired
scopestringrequired
Always `"tenant"`. Stated rather than implied so a client can tell a model it registered from one the platform published.
upstream_modelstringrequired
curl -X GET https://api.opennozzle.com/v1/registrations \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s

API keys & service accounts

12 operations
get/v1/keys/{key_id}

Get a virtual key's metadata (no token returned).

keys:read

Parameters

key_idpath · stringrequired

Response · 200

created_atstring · date-timerequired
created_byUserId | null
environmentKeyEnvironmentrequired
expires_atstring · date-time
idVirtualKeyIdrequired
A customer-facing programmatic key (pk_live_* / pk_test_*).
last_used_atstring · date-time
namestringrequired
previewstringrequired
Suffix of the token (e.g. `…aB3xQ`) for UI identification.
project_idProjectIdrequired
Project within an organization — the unit virtual keys belong to.
restrictionsKeyRestrictionsrequired
The restrictions a key carries beyond its scopes. Enforced at the dispatch seam (`keys::enforce`), by the rate-limit layer for `rpm_limit`, and at authentication for `ip_allowlist`; settable at mint and by PATCH. Every field is optional data: `null` means no restriction, so a key with no `rpm_limit` / `tpm_limit` is not throttled by the gateway at all.
blocked_modelsarray
Refused even when `models` admits them.
ip_allowlistarray
CIDR blocks (or bare addresses) this key may be used from.
model_access_groupsarray
Named model access groups; their models are added to `models`.
modelsarray
Models this key may call. `null` = every model the tenant reaches.
rpm_limitinteger · uint32
Requests per minute on each endpoint path. `null` = no gateway cap.
tpm_limitinteger · uint32
Tokens per minute, prompt + completion. `null` = no gateway cap.
revoked_atstring · date-time
scopesScope[]required
service_account_idstring · uuid
spend_capSpendCap | null
The spend ceiling this key carries, or `null` when it is uncapped. Readable because it is settable: a cap you cannot see is a cap you cannot audit.
statusKeyStatusrequired
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
curl -X GET https://api.opennozzle.com/v1/keys/<key_id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
patch/v1/keys/{key_id}

Update a virtual key (name, scopes-reduction, rate limit, expiry).

keys:writeIdempotency-Keyemits virtual_key.updated

Parameters

key_idpath · stringrequired

Request body

expires_atstring · date-time
Setting to `None` clears the expiry (no-op for never-expiring keys).
namestring
restrictionsKeyRestrictions | null
Replace the key's restrictions wholesale. Omit to leave them; send `{}` (every field null) to lift them all. Whole-object rather than per-field so a console editing the restrictions form sends exactly what it shows, and "absent" never has to mean two things.
scopesarray
Reducing the scope set is allowed; expanding requires a remint.
spend_capSpendCap | null
The most this key may spend, over which window. Both halves arrive together because the type carries both: a ceiling with no window never enforces and a window with no ceiling means nothing, which is what the `virtual_keys_budget_coherent` CHECK says in the database. Omitting it leaves the existing cap alone, as every other field here does. Removing a cap is deliberately not expressible for the same reason clearing an expiry is not: one PATCH body cannot distinguish "absent" from "set to nothing" without a second nesting level, and a silent uncapping is the wrong thing to guess.

Response · 200

created_atstring · date-timerequired
created_byUserId | null
environmentKeyEnvironmentrequired
expires_atstring · date-time
idVirtualKeyIdrequired
A customer-facing programmatic key (pk_live_* / pk_test_*).
last_used_atstring · date-time
namestringrequired
previewstringrequired
Suffix of the token (e.g. `…aB3xQ`) for UI identification.
project_idProjectIdrequired
Project within an organization — the unit virtual keys belong to.
restrictionsKeyRestrictionsrequired
The restrictions a key carries beyond its scopes. Enforced at the dispatch seam (`keys::enforce`), by the rate-limit layer for `rpm_limit`, and at authentication for `ip_allowlist`; settable at mint and by PATCH. Every field is optional data: `null` means no restriction, so a key with no `rpm_limit` / `tpm_limit` is not throttled by the gateway at all.
blocked_modelsarray
Refused even when `models` admits them.
ip_allowlistarray
CIDR blocks (or bare addresses) this key may be used from.
model_access_groupsarray
Named model access groups; their models are added to `models`.
modelsarray
Models this key may call. `null` = every model the tenant reaches.
rpm_limitinteger · uint32
Requests per minute on each endpoint path. `null` = no gateway cap.
tpm_limitinteger · uint32
Tokens per minute, prompt + completion. `null` = no gateway cap.
revoked_atstring · date-time
scopesScope[]required
service_account_idstring · uuid
spend_capSpendCap | null
The spend ceiling this key carries, or `null` when it is uncapped. Readable because it is settable: a cap you cannot see is a cap you cannot audit.
statusKeyStatusrequired
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
curl -X PATCH https://api.opennozzle.com/v1/keys/<key_id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "expires_at": "2026-09-22T12:00:00Z",
  "name": null,
  "restrictions": null,
  "scopes": null,
  "spend_cap": null
}'
delete/v1/keys/{key_id}

Revoke a virtual key (immediate, no grace window).

keys:writeIdempotency-Keyemits virtual_key.revoked

Parameters

key_idpath · stringrequired

Response · 204

Success. No response body.

curl -X DELETE https://api.opennozzle.com/v1/keys/<key_id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s
post/v1/keys/{key_id}/rotate

Rotate a virtual key, optionally with a grace window.

keys:writeIdempotency-Keyemits virtual_key.rotated

Parameters

key_idpath · stringrequired

Request body

grace_period_secondsinteger · uint32
Seconds during which the *old* token remains valid after rotation. Defaults to 0 (immediate cutover). Bounded by `MAX_ROTATION_GRACE_SECS`.

Response · 200

grace_expires_atstring · date-timerequired
When the previous token stops accepting requests.
keyVirtualKeyPublicrequired
created_atstring · date-timerequired
created_byUserId | null
environmentKeyEnvironmentrequired
expires_atstring · date-time
idVirtualKeyIdrequired
A customer-facing programmatic key (pk_live_* / pk_test_*).
last_used_atstring · date-time
namestringrequired
previewstringrequired
Suffix of the token (e.g. `…aB3xQ`) for UI identification.
project_idProjectIdrequired
Project within an organization — the unit virtual keys belong to.
restrictionsKeyRestrictionsrequired
The restrictions a key carries beyond its scopes. Enforced at the dispatch seam (`keys::enforce`), by the rate-limit layer for `rpm_limit`, and at authentication for `ip_allowlist`; settable at mint and by PATCH. Every field is optional data: `null` means no restriction, so a key with no `rpm_limit` / `tpm_limit` is not throttled by the gateway at all.
blocked_modelsarray
Refused even when `models` admits them.
ip_allowlistarray
CIDR blocks (or bare addresses) this key may be used from.
model_access_groupsarray
Named model access groups; their models are added to `models`.
modelsarray
Models this key may call. `null` = every model the tenant reaches.
rpm_limitinteger · uint32
Requests per minute on each endpoint path. `null` = no gateway cap.
tpm_limitinteger · uint32
Tokens per minute, prompt + completion. `null` = no gateway cap.
revoked_atstring · date-time
scopesScope[]required
service_account_idstring · uuid
spend_capSpendCap | null
The spend ceiling this key carries, or `null` when it is uncapped. Readable because it is settable: a cap you cannot see is a cap you cannot audit.
statusKeyStatusrequired
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
tokenstringrequired
The new plaintext token. Display once.
curl -X POST https://api.opennozzle.com/v1/keys/<key_id>/rotate \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "grace_period_seconds": 0
}'
get/v1/organizations/{organization_id}/service-accounts

List service accounts in a organization.

keys:read

Parameters

organization_idpath · stringrequired

Response · 200

activebooleanrequired
created_atstring · date-timerequired
created_byUserId | null
descriptionstring
disabled_atstring · date-time
idstring · uuidrequired
max_scopesScope[]required
namestringrequired
organization_idOrganizationIdrequired
Organization within a tenant.
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
curl -X GET https://api.opennozzle.com/v1/organizations/<organization_id>/service-accounts \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/organizations/{organization_id}/service-accounts

Create a service account (a non-human principal that owns keys).

keys:writeIdempotency-Keyemits service_account.created

Parameters

organization_idpath · stringrequired

Request body

descriptionstring
max_scopesScope[]required
The scope ceiling for every key this account mints.
namestringrequired

Response · 201

activebooleanrequired
created_atstring · date-timerequired
created_byUserId | null
descriptionstring
disabled_atstring · date-time
idstring · uuidrequired
max_scopesScope[]required
namestringrequired
organization_idOrganizationIdrequired
Organization within a tenant.
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
curl -X POST https://api.opennozzle.com/v1/organizations/<organization_id>/service-accounts \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "description": null,
  "max_scopes": [
    "catalog:read"
  ],
  "name": "string"
}'
get/v1/projects/{project_id}/keys

List virtual keys for a project.

keys:read

Parameters

project_idpath · stringrequired

Response · 200

created_atstring · date-timerequired
created_byUserId | null
environmentKeyEnvironmentrequired
expires_atstring · date-time
idVirtualKeyIdrequired
A customer-facing programmatic key (pk_live_* / pk_test_*).
last_used_atstring · date-time
namestringrequired
previewstringrequired
Suffix of the token (e.g. `…aB3xQ`) for UI identification.
project_idProjectIdrequired
Project within an organization — the unit virtual keys belong to.
restrictionsKeyRestrictionsrequired
The restrictions a key carries beyond its scopes. Enforced at the dispatch seam (`keys::enforce`), by the rate-limit layer for `rpm_limit`, and at authentication for `ip_allowlist`; settable at mint and by PATCH. Every field is optional data: `null` means no restriction, so a key with no `rpm_limit` / `tpm_limit` is not throttled by the gateway at all.
blocked_modelsarray
Refused even when `models` admits them.
ip_allowlistarray
CIDR blocks (or bare addresses) this key may be used from.
model_access_groupsarray
Named model access groups; their models are added to `models`.
modelsarray
Models this key may call. `null` = every model the tenant reaches.
rpm_limitinteger · uint32
Requests per minute on each endpoint path. `null` = no gateway cap.
tpm_limitinteger · uint32
Tokens per minute, prompt + completion. `null` = no gateway cap.
revoked_atstring · date-time
scopesScope[]required
service_account_idstring · uuid
spend_capSpendCap | null
The spend ceiling this key carries, or `null` when it is uncapped. Readable because it is settable: a cap you cannot see is a cap you cannot audit.
statusKeyStatusrequired
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
curl -X GET https://api.opennozzle.com/v1/projects/<project_id>/keys \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/projects/{project_id}/keys

Mint a new virtual API key in a project.

keys:writeIdempotency-Keyemits virtual_key.created

Parameters

project_idpath · stringrequired

Request body

environmentKeyEnvironmentrequired
expires_atstring · date-time
Optional absolute expiry. When `None`, the key never expires (revocation is the only way to disable it).
namestringrequired
restrictionsKeyRestrictions | null
Model, throughput and network restrictions; omit for none.
scopesScope[]required
service_account_idstring · uuid
Mint the key FOR a service account in this project's organization. Its scopes are clipped to the account's ceiling, and the account is the owner of record (the minting human stays `created_by`).
spend_capSpendCap | null
A spend ceiling from birth; omit for uncapped.

Response · 201

keyVirtualKeyPublicrequired
created_atstring · date-timerequired
created_byUserId | null
environmentKeyEnvironmentrequired
expires_atstring · date-time
idVirtualKeyIdrequired
A customer-facing programmatic key (pk_live_* / pk_test_*).
last_used_atstring · date-time
namestringrequired
previewstringrequired
Suffix of the token (e.g. `…aB3xQ`) for UI identification.
project_idProjectIdrequired
Project within an organization — the unit virtual keys belong to.
restrictionsKeyRestrictionsrequired
The restrictions a key carries beyond its scopes. Enforced at the dispatch seam (`keys::enforce`), by the rate-limit layer for `rpm_limit`, and at authentication for `ip_allowlist`; settable at mint and by PATCH. Every field is optional data: `null` means no restriction, so a key with no `rpm_limit` / `tpm_limit` is not throttled by the gateway at all.
blocked_modelsarray
Refused even when `models` admits them.
ip_allowlistarray
CIDR blocks (or bare addresses) this key may be used from.
model_access_groupsarray
Named model access groups; their models are added to `models`.
modelsarray
Models this key may call. `null` = every model the tenant reaches.
rpm_limitinteger · uint32
Requests per minute on each endpoint path. `null` = no gateway cap.
tpm_limitinteger · uint32
Tokens per minute, prompt + completion. `null` = no gateway cap.
revoked_atstring · date-time
scopesScope[]required
service_account_idstring · uuid
spend_capSpendCap | null
The spend ceiling this key carries, or `null` when it is uncapped. Readable because it is settable: a cap you cannot see is a cap you cannot audit.
statusKeyStatusrequired
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
tokenstringrequired
Full plaintext token. Display once; never returned again.
curl -X POST https://api.opennozzle.com/v1/projects/<project_id>/keys \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "environment": "live",
  "expires_at": null,
  "name": "string",
  "restrictions": null,
  "scopes": [
    "catalog:read"
  ],
  "service_account_id": null,
  "spend_cap": null
}'
get/v1/service-accounts/{service_account_id}

Get a service account.

keys:read

Parameters

service_account_idpath · stringrequired

Response · 200

activebooleanrequired
created_atstring · date-timerequired
created_byUserId | null
descriptionstring
disabled_atstring · date-time
idstring · uuidrequired
max_scopesScope[]required
namestringrequired
organization_idOrganizationIdrequired
Organization within a tenant.
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
curl -X GET https://api.opennozzle.com/v1/service-accounts/<service_account_id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
patch/v1/service-accounts/{service_account_id}

Rename a service account, change its description, or narrow its scope ceiling.

keys:writeIdempotency-Keyemits service_account.updated

Parameters

service_account_idpath · stringrequired

Request body

descriptionstring
max_scopesarray
Narrow the ceiling. Must be a subset of the current one.
namestring

Response · 200

activebooleanrequired
created_atstring · date-timerequired
created_byUserId | null
descriptionstring
disabled_atstring · date-time
idstring · uuidrequired
max_scopesScope[]required
namestringrequired
organization_idOrganizationIdrequired
Organization within a tenant.
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
curl -X PATCH https://api.opennozzle.com/v1/service-accounts/<service_account_id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "description": null,
  "max_scopes": null,
  "name": null
}'
delete/v1/service-accounts/{service_account_id}

Disable a service account (keys it owns keep their attribution).

keys:writeIdempotency-Keyemits service_account.disabled

Parameters

service_account_idpath · stringrequired

Response · 204

Success. No response body.

curl -X DELETE https://api.opennozzle.com/v1/service-accounts/<service_account_id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s
get/v1/service-accounts/{service_account_id}/keys

List the keys a service account owns.

keys:read

Parameters

service_account_idpath · stringrequired

Response · 200

created_atstring · date-timerequired
created_byUserId | null
environmentKeyEnvironmentrequired
expires_atstring · date-time
idVirtualKeyIdrequired
A customer-facing programmatic key (pk_live_* / pk_test_*).
last_used_atstring · date-time
namestringrequired
previewstringrequired
Suffix of the token (e.g. `…aB3xQ`) for UI identification.
project_idProjectIdrequired
Project within an organization — the unit virtual keys belong to.
restrictionsKeyRestrictionsrequired
The restrictions a key carries beyond its scopes. Enforced at the dispatch seam (`keys::enforce`), by the rate-limit layer for `rpm_limit`, and at authentication for `ip_allowlist`; settable at mint and by PATCH. Every field is optional data: `null` means no restriction, so a key with no `rpm_limit` / `tpm_limit` is not throttled by the gateway at all.
blocked_modelsarray
Refused even when `models` admits them.
ip_allowlistarray
CIDR blocks (or bare addresses) this key may be used from.
model_access_groupsarray
Named model access groups; their models are added to `models`.
modelsarray
Models this key may call. `null` = every model the tenant reaches.
rpm_limitinteger · uint32
Requests per minute on each endpoint path. `null` = no gateway cap.
tpm_limitinteger · uint32
Tokens per minute, prompt + completion. `null` = no gateway cap.
revoked_atstring · date-time
scopesScope[]required
service_account_idstring · uuid
spend_capSpendCap | null
The spend ceiling this key carries, or `null` when it is uncapped. Readable because it is settable: a cap you cannot see is a cap you cannot audit.
statusKeyStatusrequired
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
curl -X GET https://api.opennozzle.com/v1/service-accounts/<service_account_id>/keys \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s

Billing & costs

15 operations
get/v1/billing/balance

Read your own prepaid credit balance.

billing:read

Response · 200

balance_centsinteger · int64required
currencystringrequired
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
curl -X GET https://api.opennozzle.com/v1/billing/balance \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/billing/costs

Page through your own cost ledger, newest first, with filters.

billing:read

Parameters

cursorquery · string
Opaque cursor from a previous page's `X-Nozzle-Next-Cursor` header.
fromquery · date-time
Inclusive lower bound on `occurred_at` (RFC 3339).
key_idquery · uuid
Virtual key that incurred the cost.
kindquery · string
Ledger kind, e.g. `inference.chat`, `inference.embed`, `instance_tick`.
limitquery · uint32
Rows per page, 1–1000. Default 200, the size this route always answered.
modelquery · string
Model the row was billed for.
project_idquery · uuid
Project the cost was attributed to.
providerquery · string
Provider that served the call (rows written from 2026-09-22 on).
toquery · date-time
Exclusive upper bound on `occurred_at` (RFC 3339).

Response · 200

cached_tokensinteger · int64
completion_tokensinteger · int64
cost_centsinteger · int64required
Whole cents, rounded once at the edge. Kept because it shipped; a typical inference call is well under one cent and reads `0` here, so reconcile on `cost_micro_cents`.
cost_micro_centsinteger · int64required
The exact figure — the same integer the `X-Nozzle-Cost-Micro-Cents` response header carried for `request_id`.
currencystringrequired
estimatedbooleanrequired
`true` when the token counts were counted locally because the upstream returned no usage block; the amount is then an estimate.
idstring · uuidrequired
kindstringrequired
occurred_atstring · date-timerequired
project_idProjectId | null
prompt_tokensinteger · int64
providerstring
The provider that served the call — the same value the call's `X-Nozzle-Provider` header carried. `null` on rows written before 2026-09-22 and on charges no provider served.
ref_idstring
ref_typestring
request_idstring
The `X-Request-Id` of the call that produced this row; `null` on rows that are not one call (a GPU-hour tick).
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
virtual_key_idstring · uuid
The virtual key that incurred this cost; `null` for dashboard-session calls and for charges no caller made (a GPU-hour tick).
X-Nozzle-Next-Cursor
Opaque cursor for the next page; send it back as `cursor`. Absent on the last page.
curl -X GET https://api.opennozzle.com/v1/billing/costs \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/billing/costs/{request_id}

What one of your calls cost, by its X-Request-Id.

billing:read

Parameters

request_idpath · stringrequired

Response · 200

cached_tokensinteger · int64
completion_tokensinteger · int64
cost_centsinteger · int64required
Whole cents, rounded once at the edge. Kept because it shipped; a typical inference call is well under one cent and reads `0` here, so reconcile on `cost_micro_cents`.
cost_micro_centsinteger · int64required
The exact figure — the same integer the `X-Nozzle-Cost-Micro-Cents` response header carried for `request_id`.
currencystringrequired
estimatedbooleanrequired
`true` when the token counts were counted locally because the upstream returned no usage block; the amount is then an estimate.
idstring · uuidrequired
kindstringrequired
occurred_atstring · date-timerequired
project_idProjectId | null
prompt_tokensinteger · int64
providerstring
The provider that served the call — the same value the call's `X-Nozzle-Provider` header carried. `null` on rows written before 2026-09-22 and on charges no provider served.
ref_idstring
ref_typestring
request_idstring
The `X-Request-Id` of the call that produced this row; `null` on rows that are not one call (a GPU-hour tick).
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
virtual_key_idstring · uuid
The virtual key that incurred this cost; `null` for dashboard-session calls and for charges no caller made (a GPU-hour tick).
curl -X GET https://api.opennozzle.com/v1/billing/costs/<request_id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/billing/credits

List your own credit ledger entries.

billing:read

Response · 200

has_morebooleanrequired
itemsCreditEntryPublic[]required
currencystringrequired
delta_centsinteger · int64required
idstring · uuidrequired
occurred_atstring · date-timerequired
reasonstringrequired
ref_idstring
ref_typestring
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
next_cursorstring
curl -X GET https://api.opennozzle.com/v1/billing/credits \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/billing/entitlement

Read your own plan entitlement.

billing:read

Response · 200

custom_overridesobjectrequired
planPlanrequired
activebooleanrequired
created_atstring · date-timerequired
currencystringrequired
custom_pricingbooleanrequired
True when the price is negotiated per customer (Enterprise): there is no list price, and `price_cents_monthly` is 0 only because the column needs a value. Render "Custom" and sort it last; never show the 0.
featuresobjectrequired
idstringrequired
max_concurrent_instancesinteger · int32required
max_model_params_bnumber · doublerequired
monthly_credits_centsinteger · int64required
namestringrequired
per_day_limitinteger · int32
per_minute_limitinteger · int32
G13 — burst protection ceilings. `None` means "unlimited" (the `effective_ceiling` short-circuit returns Some(v) from the custom_override JSON before falling through to these, so the operator can still tighten an enterprise tenant via override). Stock plans seed values per tier in migration 0014b.
price_cents_monthlyinteger · int64required
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
valid_fromstring · date-timerequired
valid_tostring · date-time
curl -X GET https://api.opennozzle.com/v1/billing/entitlement \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/billing/plans

List available billing plans.

no auth

Response · 200

activebooleanrequired
created_atstring · date-timerequired
currencystringrequired
custom_pricingbooleanrequired
True when the price is negotiated per customer (Enterprise): there is no list price, and `price_cents_monthly` is 0 only because the column needs a value. Render "Custom" and sort it last; never show the 0.
featuresobjectrequired
idstringrequired
max_concurrent_instancesinteger · int32required
max_model_params_bnumber · doublerequired
monthly_credits_centsinteger · int64required
namestringrequired
per_day_limitinteger · int32
per_minute_limitinteger · int32
G13 — burst protection ceilings. `None` means "unlimited" (the `effective_ceiling` short-circuit returns Some(v) from the custom_override JSON before falling through to these, so the operator can still tighten an enterprise tenant via override). Stock plans seed values per tier in migration 0014b.
price_cents_monthlyinteger · int64required
curl -X GET https://api.opennozzle.com/v1/billing/plans \
  -s
post/v1/billing/reconcile

Re-apply recent Stripe events to the credit ledger (idempotent).

admin:billing:manageIdempotency-Key

Request body

object

Response · 200

object

curl -X POST https://api.opennozzle.com/v1/billing/reconcile \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
get/v1/tenants/{tenant_id}/billing/balance

Current credit balance for the tenant.

billing:read

Parameters

tenant_idpath · stringrequired

Response · 200

balance_centsinteger · int64required
currencystringrequired
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
curl -X GET https://api.opennozzle.com/v1/tenants/<tenant_id>/billing/balance \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/tenants/{tenant_id}/billing/checkout

Open a Stripe Checkout session for a plan.

billing:writeIdempotency-Key

Parameters

tenant_idpath · stringrequired

Request body

cancel_urlstringrequired
plan_idstringrequired
success_urlstringrequired

Response · 200

session_urlstringrequired
curl -X POST https://api.opennozzle.com/v1/tenants/<tenant_id>/billing/checkout \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "cancel_url": "string",
  "plan_id": "string",
  "success_url": "string"
}'
get/v1/tenants/{tenant_id}/billing/costs

Page through the tenant's cost ledger, newest first, with filters.

billing:read

Parameters

tenant_idpath · stringrequired
cursorquery · string
Opaque cursor from a previous page's `X-Nozzle-Next-Cursor` header.
fromquery · date-time
Inclusive lower bound on `occurred_at` (RFC 3339).
key_idquery · uuid
Virtual key that incurred the cost.
kindquery · string
Ledger kind, e.g. `inference.chat`, `inference.embed`, `instance_tick`.
limitquery · uint32
Rows per page, 1–1000. Default 200, the size this route always answered.
modelquery · string
Model the row was billed for.
project_idquery · uuid
Project the cost was attributed to.
providerquery · string
Provider that served the call (rows written from 2026-09-22 on).
toquery · date-time
Exclusive upper bound on `occurred_at` (RFC 3339).

Response · 200

cached_tokensinteger · int64
completion_tokensinteger · int64
cost_centsinteger · int64required
Whole cents, rounded once at the edge. Kept because it shipped; a typical inference call is well under one cent and reads `0` here, so reconcile on `cost_micro_cents`.
cost_micro_centsinteger · int64required
The exact figure — the same integer the `X-Nozzle-Cost-Micro-Cents` response header carried for `request_id`.
currencystringrequired
estimatedbooleanrequired
`true` when the token counts were counted locally because the upstream returned no usage block; the amount is then an estimate.
idstring · uuidrequired
kindstringrequired
occurred_atstring · date-timerequired
project_idProjectId | null
prompt_tokensinteger · int64
providerstring
The provider that served the call — the same value the call's `X-Nozzle-Provider` header carried. `null` on rows written before 2026-09-22 and on charges no provider served.
ref_idstring
ref_typestring
request_idstring
The `X-Request-Id` of the call that produced this row; `null` on rows that are not one call (a GPU-hour tick).
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
virtual_key_idstring · uuid
The virtual key that incurred this cost; `null` for dashboard-session calls and for charges no caller made (a GPU-hour tick).
X-Nozzle-Next-Cursor
Opaque cursor for the next page; send it back as `cursor`. Absent on the last page.
curl -X GET https://api.opennozzle.com/v1/tenants/<tenant_id>/billing/costs \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/tenants/{tenant_id}/billing/costs/{request_id}

Every ledger row one call produced, by its X-Request-Id.

billing:read

Parameters

tenant_idpath · stringrequired
request_idpath · stringrequired

Response · 200

cached_tokensinteger · int64
completion_tokensinteger · int64
cost_centsinteger · int64required
Whole cents, rounded once at the edge. Kept because it shipped; a typical inference call is well under one cent and reads `0` here, so reconcile on `cost_micro_cents`.
cost_micro_centsinteger · int64required
The exact figure — the same integer the `X-Nozzle-Cost-Micro-Cents` response header carried for `request_id`.
currencystringrequired
estimatedbooleanrequired
`true` when the token counts were counted locally because the upstream returned no usage block; the amount is then an estimate.
idstring · uuidrequired
kindstringrequired
occurred_atstring · date-timerequired
project_idProjectId | null
prompt_tokensinteger · int64
providerstring
The provider that served the call — the same value the call's `X-Nozzle-Provider` header carried. `null` on rows written before 2026-09-22 and on charges no provider served.
ref_idstring
ref_typestring
request_idstring
The `X-Request-Id` of the call that produced this row; `null` on rows that are not one call (a GPU-hour tick).
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
virtual_key_idstring · uuid
The virtual key that incurred this cost; `null` for dashboard-session calls and for charges no caller made (a GPU-hour tick).
curl -X GET https://api.opennozzle.com/v1/tenants/<tenant_id>/billing/costs/<request_id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/tenants/{tenant_id}/billing/credits

Paginated credits ledger for the tenant.

billing:read

Parameters

tenant_idpath · stringrequired

Response · 200

has_morebooleanrequired
itemsCreditEntryPublic[]required
currencystringrequired
delta_centsinteger · int64required
idstring · uuidrequired
occurred_atstring · date-timerequired
reasonstringrequired
ref_idstring
ref_typestring
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
next_cursorstring
curl -X GET https://api.opennozzle.com/v1/tenants/<tenant_id>/billing/credits \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/tenants/{tenant_id}/billing/entitlement

Get the tenant's active entitlement (plan + overrides).

billing:read

Parameters

tenant_idpath · stringrequired

Response · 200

custom_overridesobjectrequired
planPlanrequired
activebooleanrequired
created_atstring · date-timerequired
currencystringrequired
custom_pricingbooleanrequired
True when the price is negotiated per customer (Enterprise): there is no list price, and `price_cents_monthly` is 0 only because the column needs a value. Render "Custom" and sort it last; never show the 0.
featuresobjectrequired
idstringrequired
max_concurrent_instancesinteger · int32required
max_model_params_bnumber · doublerequired
monthly_credits_centsinteger · int64required
namestringrequired
per_day_limitinteger · int32
per_minute_limitinteger · int32
G13 — burst protection ceilings. `None` means "unlimited" (the `effective_ceiling` short-circuit returns Some(v) from the custom_override JSON before falling through to these, so the operator can still tighten an enterprise tenant via override). Stock plans seed values per tier in migration 0014b.
price_cents_monthlyinteger · int64required
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
valid_fromstring · date-timerequired
valid_tostring · date-time
curl -X GET https://api.opennozzle.com/v1/tenants/<tenant_id>/billing/entitlement \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/tenants/{tenant_id}/billing/entitlement/change-plan

Switch the tenant to a different plan.

billing:writeIdempotency-Key

Parameters

tenant_idpath · stringrequired

Request body

plan_idstringrequired

Response · 200

custom_overridesobjectrequired
planPlanrequired
activebooleanrequired
created_atstring · date-timerequired
currencystringrequired
custom_pricingbooleanrequired
True when the price is negotiated per customer (Enterprise): there is no list price, and `price_cents_monthly` is 0 only because the column needs a value. Render "Custom" and sort it last; never show the 0.
featuresobjectrequired
idstringrequired
max_concurrent_instancesinteger · int32required
max_model_params_bnumber · doublerequired
monthly_credits_centsinteger · int64required
namestringrequired
per_day_limitinteger · int32
per_minute_limitinteger · int32
G13 — burst protection ceilings. `None` means "unlimited" (the `effective_ceiling` short-circuit returns Some(v) from the custom_override JSON before falling through to these, so the operator can still tighten an enterprise tenant via override). Stock plans seed values per tier in migration 0014b.
price_cents_monthlyinteger · int64required
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
valid_fromstring · date-timerequired
valid_tostring · date-time
curl -X POST https://api.opennozzle.com/v1/tenants/<tenant_id>/billing/entitlement/change-plan \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "plan_id": "string"
}'

Quotas

2 operations
get/v1/quotas

Read your own quota usage and ceilings.

billing:read

Response · 200

plan_idstringrequired
slotsQuotaSlot[]required
ceilinginteger · int64
The ceiling in `unit`. `null` when — and only when — `unlimited`.
enforcedbooleanrequired
`true` when at least one declared operation enforces this kind. A kind no route declares is reported, not hidden, and this says it is inert.
kindstringrequired
measureQuotaMeasurerequired
What `value` measures. A spend is summed from the ledger, a gauge is counted live, a counter is incremented per event, and `ceiling_only` says the kind bounds a request property rather than accumulating anything — its `value` is always zero and is not a measurement.
period_keystringrequired
sourcestringrequired
The table or gauge `value` is read from — the same one the enforcer reads, by construction.
unitQuotaUnitrequired
The unit a slot's `value` and `ceiling` are BOTH denominated in. Stated on the wire because the 2026-09-19 digest compared a request count against a cents ceiling inside one slot; a reader could not tell. A slot now carries one unit and both numbers are in it.
unlimitedbooleanrequired
`true` when no ceiling applies (plan column NULL or an explicit `null` override). Stated rather than left to be inferred from a null `ceiling`, so "unlimited" and "unknown" can never be confused.
updated_atstring · date-timerequired
valueinteger · int64required
Current usage in `unit`. Zero and not a measurement when `measure` is `ceiling_only`.
tenant_idstring · uuidrequired
curl -X GET https://api.opennozzle.com/v1/quotas \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/tenants/{tenant_id}/quotas

Read the tenant's current quota usage and ceilings.

billing:read

Parameters

tenant_idpath · stringrequired

Response · 200

plan_idstringrequired
slotsQuotaSlot[]required
ceilinginteger · int64
The ceiling in `unit`. `null` when — and only when — `unlimited`.
enforcedbooleanrequired
`true` when at least one declared operation enforces this kind. A kind no route declares is reported, not hidden, and this says it is inert.
kindstringrequired
measureQuotaMeasurerequired
What `value` measures. A spend is summed from the ledger, a gauge is counted live, a counter is incremented per event, and `ceiling_only` says the kind bounds a request property rather than accumulating anything — its `value` is always zero and is not a measurement.
period_keystringrequired
sourcestringrequired
The table or gauge `value` is read from — the same one the enforcer reads, by construction.
unitQuotaUnitrequired
The unit a slot's `value` and `ceiling` are BOTH denominated in. Stated on the wire because the 2026-09-19 digest compared a request count against a cents ceiling inside one slot; a reader could not tell. A slot now carries one unit and both numbers are in it.
unlimitedbooleanrequired
`true` when no ceiling applies (plan column NULL or an explicit `null` override). Stated rather than left to be inferred from a null `ceiling`, so "unlimited" and "unknown" can never be confused.
updated_atstring · date-timerequired
valueinteger · int64required
Current usage in `unit`. Zero and not a measurement when `measure` is `ceiling_only`.
tenant_idstring · uuidrequired
curl -X GET https://api.opennozzle.com/v1/tenants/<tenant_id>/quotas \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s

Analytics

8 operations
get/v1/analytics/cost

Your own cost per day.

usage:read

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/analytics/cost \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/analytics/instances

Your own instance lifetime rollups.

usage:read

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/analytics/instances \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/analytics/margin

Your own margin per day.

usage:read

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/analytics/margin \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/analytics/usage

Traffic grouped by time and/or model, provider, key, project or kind, for the caller's tenant.

usage:read

Parameters

fromquery · date-time
group_byquery · string
intervalquery · string
key_idquery · uuid
kindquery · string
modelquery · string
project_idquery · uuid
providerquery · string
toquery · date-time

Response · 200

fromstring · date-timerequired
group_by"model" | "provider" | "key" | "project" | "kind" | null
interval"hour" | "day" | null
rowsUsageRow[]required
billedinteger · int64required
Rows written to the money ledger (billed events).
bucketstring · date-time
Start of the bucket (UTC) when `interval` was given, else absent.
cached_tokensinteger · int64required
callsinteger · int64required
Metered calls, served or refused (call log).
completion_tokensinteger · int64required
cost_micro_centsinteger · int64required
error_countinteger · int64required
Calls that ended with an error status (>= 400).
keystring
The group's value when `group_by` was given (a model name, key id, …); `null` for traffic with no value on that axis (e.g. no project).
p50_latency_msinteger · int32
Time to response head: the whole call when buffered, time to first byte when streamed. `null` when the bucket has no logged calls.
p95_latency_msinteger · int32
prompt_tokensinteger · int64required
tostring · date-timerequired
totalsUsageRowrequired
The whole window, ungrouped — the same numbers the rows sum to (latency percentiles are over the window, not an average of the rows').
billedinteger · int64required
Rows written to the money ledger (billed events).
bucketstring · date-time
Start of the bucket (UTC) when `interval` was given, else absent.
cached_tokensinteger · int64required
callsinteger · int64required
Metered calls, served or refused (call log).
completion_tokensinteger · int64required
cost_micro_centsinteger · int64required
error_countinteger · int64required
Calls that ended with an error status (>= 400).
keystring
The group's value when `group_by` was given (a model name, key id, …); `null` for traffic with no value on that axis (e.g. no project).
p50_latency_msinteger · int32
Time to response head: the whole call when buffered, time to first byte when streamed. `null` when the bucket has no logged calls.
p95_latency_msinteger · int32
prompt_tokensinteger · int64required
truncatedbooleanrequired
True when `rows` hit the cap and smaller groups were omitted.
curl -X GET https://api.opennozzle.com/v1/analytics/usage \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/tenants/{tenant_id}/analytics/cost

Daily cost breakdown (inference / instance / training) for a tenant.

usage:read

Parameters

tenant_idpath · stringrequired

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/tenants/<tenant_id>/analytics/cost \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/tenants/{tenant_id}/analytics/instances

Per-Instance lifetime and spend for a tenant.

usage:read

Parameters

tenant_idpath · stringrequired

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/tenants/<tenant_id>/analytics/instances \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/tenants/{tenant_id}/analytics/margin

Daily inference-versus-compute margin series for a tenant.

usage:read

Parameters

tenant_idpath · stringrequired

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/tenants/<tenant_id>/analytics/margin \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/tenants/{tenant_id}/analytics/usage

Traffic grouped by time and/or model, provider, key, project or kind: calls, errors, tokens, cost, latency.

usage:read

Parameters

tenant_idpath · stringrequired
fromquery · date-time
group_byquery · string
intervalquery · string
key_idquery · uuid
kindquery · string
modelquery · string
project_idquery · uuid
providerquery · string
toquery · date-time

Response · 200

fromstring · date-timerequired
group_by"model" | "provider" | "key" | "project" | "kind" | null
interval"hour" | "day" | null
rowsUsageRow[]required
billedinteger · int64required
Rows written to the money ledger (billed events).
bucketstring · date-time
Start of the bucket (UTC) when `interval` was given, else absent.
cached_tokensinteger · int64required
callsinteger · int64required
Metered calls, served or refused (call log).
completion_tokensinteger · int64required
cost_micro_centsinteger · int64required
error_countinteger · int64required
Calls that ended with an error status (>= 400).
keystring
The group's value when `group_by` was given (a model name, key id, …); `null` for traffic with no value on that axis (e.g. no project).
p50_latency_msinteger · int32
Time to response head: the whole call when buffered, time to first byte when streamed. `null` when the bucket has no logged calls.
p95_latency_msinteger · int32
prompt_tokensinteger · int64required
tostring · date-timerequired
totalsUsageRowrequired
The whole window, ungrouped — the same numbers the rows sum to (latency percentiles are over the window, not an average of the rows').
billedinteger · int64required
Rows written to the money ledger (billed events).
bucketstring · date-time
Start of the bucket (UTC) when `interval` was given, else absent.
cached_tokensinteger · int64required
callsinteger · int64required
Metered calls, served or refused (call log).
completion_tokensinteger · int64required
cost_micro_centsinteger · int64required
error_countinteger · int64required
Calls that ended with an error status (>= 400).
keystring
The group's value when `group_by` was given (a model name, key id, …); `null` for traffic with no value on that axis (e.g. no project).
p50_latency_msinteger · int32
Time to response head: the whole call when buffered, time to first byte when streamed. `null` when the bucket has no logged calls.
p95_latency_msinteger · int32
prompt_tokensinteger · int64required
truncatedbooleanrequired
True when `rows` hit the cap and smaller groups were omitted.
curl -X GET https://api.opennozzle.com/v1/tenants/<tenant_id>/analytics/usage \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s

Playground

7 operations
get/v1/playground/prompts

List saved playground prompts, newest edit first. Filters: project_id, mode, limit.

inference:call

Response · 200

bodyobjectrequired
The request exactly as the playground would send it (messages, parameters, the model list for a compare).
created_atstring · date-timerequired
created_by_user_idstring · uuid
idstring · uuidrequired
modePlaygroundModerequired
The console surface a prompt or run belongs to. Closed so the console can branch on it and the database CHECK can mirror it exactly.
modelstring
namestringrequired
project_idstring · uuid
updated_atstring · date-timerequired
curl -X GET https://api.opennozzle.com/v1/playground/prompts \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/playground/prompts

Save a playground prompt (the request body as the playground would send it).

inference:callIdempotency-Key

Request body

bodyobjectrequired
modePlaygroundModerequired
The console surface a prompt or run belongs to. Closed so the console can branch on it and the database CHECK can mirror it exactly.
modelstring
namestringrequired
project_idstring · uuid

Response · 201

bodyobjectrequired
The request exactly as the playground would send it (messages, parameters, the model list for a compare).
created_atstring · date-timerequired
created_by_user_idstring · uuid
idstring · uuidrequired
modePlaygroundModerequired
The console surface a prompt or run belongs to. Closed so the console can branch on it and the database CHECK can mirror it exactly.
modelstring
namestringrequired
project_idstring · uuid
updated_atstring · date-timerequired
curl -X POST https://api.opennozzle.com/v1/playground/prompts \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "body": {},
  "mode": "chat",
  "model": null,
  "name": "string",
  "project_id": null
}'
get/v1/playground/prompts/{id}

Read one saved playground prompt.

inference:call

Parameters

idpath · stringrequired

Response · 200

bodyobjectrequired
The request exactly as the playground would send it (messages, parameters, the model list for a compare).
created_atstring · date-timerequired
created_by_user_idstring · uuid
idstring · uuidrequired
modePlaygroundModerequired
The console surface a prompt or run belongs to. Closed so the console can branch on it and the database CHECK can mirror it exactly.
modelstring
namestringrequired
project_idstring · uuid
updated_atstring · date-timerequired
curl -X GET https://api.opennozzle.com/v1/playground/prompts/<id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
patch/v1/playground/prompts/{id}

Rename a saved prompt or replace its model or body.

inference:callIdempotency-Key

Parameters

idpath · stringrequired

Request body

bodyobject
modelstring
namestring

Response · 200

bodyobjectrequired
The request exactly as the playground would send it (messages, parameters, the model list for a compare).
created_atstring · date-timerequired
created_by_user_idstring · uuid
idstring · uuidrequired
modePlaygroundModerequired
The console surface a prompt or run belongs to. Closed so the console can branch on it and the database CHECK can mirror it exactly.
modelstring
namestringrequired
project_idstring · uuid
updated_atstring · date-timerequired
curl -X PATCH https://api.opennozzle.com/v1/playground/prompts/<id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "body": null,
  "model": null,
  "name": null
}'
delete/v1/playground/prompts/{id}

Delete a saved playground prompt; runs that used it keep their record.

inference:callIdempotency-Key

Parameters

idpath · stringrequired

Response · 204

Success. No response body.

curl -X DELETE https://api.opennozzle.com/v1/playground/prompts/<id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s
get/v1/playground/runs

List playground runs, newest first. Filters: project_id, mode, limit, before (keyset).

inference:call

Response · 200

created_atstring · date-timerequired
created_by_user_idstring · uuid
idstring · uuidrequired
modePlaygroundModerequired
The console surface a prompt or run belongs to. Closed so the console can branch on it and the database CHECK can mirror it exactly.
outcomesRunOutcome[]required
cost_micro_centsinteger · int64
error_codestring
first_token_msinteger · uint64
latency_msinteger · uint64
modelstringrequired
previewstring
The first few hundred characters of the answer, for the history list.
request_idstring
winnerboolean
project_idstring · uuid
prompt_idstring · uuid
requestobjectrequired
curl -X GET https://api.opennozzle.com/v1/playground/runs \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/playground/runs

Record a playground run: the request and what each model returned, keyed by request id.

inference:callIdempotency-Key

Request body

modePlaygroundModerequired
The console surface a prompt or run belongs to. Closed so the console can branch on it and the database CHECK can mirror it exactly.
outcomesRunOutcome[]required
cost_micro_centsinteger · int64
error_codestring
first_token_msinteger · uint64
latency_msinteger · uint64
modelstringrequired
previewstring
The first few hundred characters of the answer, for the history list.
request_idstring
winnerboolean
project_idstring · uuid
prompt_idstring · uuid
requestobjectrequired

Response · 200

created_atstring · date-timerequired
created_by_user_idstring · uuid
idstring · uuidrequired
modePlaygroundModerequired
The console surface a prompt or run belongs to. Closed so the console can branch on it and the database CHECK can mirror it exactly.
outcomesRunOutcome[]required
cost_micro_centsinteger · int64
error_codestring
first_token_msinteger · uint64
latency_msinteger · uint64
modelstringrequired
previewstring
The first few hundred characters of the answer, for the history list.
request_idstring
winnerboolean
project_idstring · uuid
prompt_idstring · uuid
requestobjectrequired
curl -X POST https://api.opennozzle.com/v1/playground/runs \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "chat",
  "outcomes": [
    {
      "model": "string"
    }
  ],
  "project_id": null,
  "prompt_id": null,
  "request": {}
}'

Compute

11 operations
get/v1/blueprints

List the deployable Blueprints and the hardware each requires.

catalog:read

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/blueprints \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/blueprints/{name}

Read one deployable Blueprint by name.

catalog:read

Parameters

namepath · stringrequired

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/blueprints/<name> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/gpu-offerings

Every GPU Nozzle can rent across RunPod, Shadeform's clouds, Prime Intellect and Vast: model, count, interconnect, region, availability and live hourly price, cheapest per GPU first.

catalog:read

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/gpu-offerings \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/instances

List the caller's compute Instances.

instances:read

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/instances \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/instances

Enqueue a new compute Instance launch.

instances:writeIdempotency-Keyemits instance.create_requested

Request body

object

Response · 201

object

curl -X POST https://api.opennozzle.com/v1/instances \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
get/v1/instances/{id}

Read one compute Instance.

instances:read

Parameters

idpath · stringrequired

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/instances/<id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
delete/v1/instances/{id}

Hard terminate a compute Instance (no drain).

instances:writeemits instance.terminate_requested

Parameters

idpath · stringrequired

Request body

object

Response · 200

object

curl -X DELETE https://api.opennozzle.com/v1/instances/<id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
get/v1/instances/{id}/diagnostics

Get typed diagnostic envelope for a compute Instance.

instances:read

Parameters

idpath · stringrequired

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/instances/<id>/diagnostics \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/instances/{id}/logs

Get the launch/lifecycle log timeline for a compute Instance.

instances:read

Parameters

idpath · stringrequired

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/instances/<id>/logs \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/instances/{id}/stop

Graceful drain → stop on a running Instance.

instances:writeemits instance.stop_requested

Parameters

idpath · stringrequired

Request body

object

Response · 200

object

curl -X POST https://api.opennozzle.com/v1/instances/<id>/stop \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
get/v1/launch-estimate

Hourly cost and measured cold-start for a Blueprint on a given GPU.

catalog:read

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/launch-estimate \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s

Workspaces, orgs & projects

23 operations
delete/v1/invitations/{invitation_id}

Revoke a pending invitation.

tenancy:writeIdempotency-Keyemits invitation.revoked

Parameters

invitation_idpath · stringrequired

Response · 204

Success. No response body.

curl -X DELETE https://api.opennozzle.com/v1/invitations/<invitation_id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s
post/v1/invitations/accept

Accept an invitation token and join the target organization.

identity:writeIdempotency-Keyemits invitation.accepted

Request body

tokenstringrequired

Response · 200

avatar_urlstring
display_namestring
emailstring
The person, on the members list. Absent where a membership is returned on its own (accepting an invitation).
joined_atstring · date-timerequired
organization_idOrganizationIdrequired
Organization within a tenant.
roleRolerequired
Organization member role. Ordered by privilege: `Owner` ≥ `Admin` ≥ `Developer` ≥ `Viewer`. The ordering is what enables checks like `role >= Role::Admin`.
user_idUserIdrequired
End-user identifier (dashboard login).
curl -X POST https://api.opennozzle.com/v1/invitations/accept \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "string"
}'
get/v1/me/organizations

List organizations the authenticated user belongs to.

identity:read

Response · 200

organizationOrganizationPublicrequired
created_atstring · date-timerequired
idOrganizationIdrequired
Organization within a tenant.
namestringrequired
owner_user_idUserIdrequired
End-user identifier (dashboard login).
slugSlugrequired
A URL-safe identifier: lowercase alphanumerics and single dashes, 1–64 characters, no leading/trailing dash and no double dash. A small set of reserved words is additionally refused at runtime.
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
roleRolerequired
Organization member role. Ordered by privilege: `Owner` ≥ `Admin` ≥ `Developer` ≥ `Viewer`. The ordering is what enables checks like `role >= Role::Admin`.
curl -X GET https://api.opennozzle.com/v1/me/organizations \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/organizations/{organization_id}

Get an organization by id.

identity:read

Parameters

organization_idpath · stringrequired

Response · 200

created_atstring · date-timerequired
idOrganizationIdrequired
Organization within a tenant.
namestringrequired
owner_user_idUserIdrequired
End-user identifier (dashboard login).
slugSlugrequired
A URL-safe identifier: lowercase alphanumerics and single dashes, 1–64 characters, no leading/trailing dash and no double dash. A small set of reserved words is additionally refused at runtime.
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
curl -X GET https://api.opennozzle.com/v1/organizations/<organization_id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
patch/v1/organizations/{organization_id}

Rename an organization. Its slug never changes.

tenancy:writeIdempotency-Keyemits organization.renamed

Parameters

organization_idpath · stringrequired

Request body

namestringrequired

Response · 200

created_atstring · date-timerequired
idOrganizationIdrequired
Organization within a tenant.
namestringrequired
owner_user_idUserIdrequired
End-user identifier (dashboard login).
slugSlugrequired
A URL-safe identifier: lowercase alphanumerics and single dashes, 1–64 characters, no leading/trailing dash and no double dash. A small set of reserved words is additionally refused at runtime.
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
curl -X PATCH https://api.opennozzle.com/v1/organizations/<organization_id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string"
}'
get/v1/organizations/{organization_id}/invitations

List pending invitations for an organization.

identity:read

Parameters

organization_idpath · stringrequired

Response · 200

created_atstring · date-timerequired
emailstringrequired
email_deliveryDelivery | null
Whether the invitation email went out — present on create only.
expires_atstring · date-timerequired
idstring · uuidrequired
invited_byUserIdrequired
End-user identifier (dashboard login).
organization_idOrganizationIdrequired
Organization within a tenant.
roleRolerequired
Organization member role. Ordered by privilege: `Owner` ≥ `Admin` ≥ `Developer` ≥ `Viewer`. The ordering is what enables checks like `role >= Role::Admin`.
statusInvitationStatusrequired
curl -X GET https://api.opennozzle.com/v1/organizations/<organization_id>/invitations \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/organizations/{organization_id}/invitations

Invite an email address to join the organization.

tenancy:writeIdempotency-Keyemits invitation.sent

Parameters

organization_idpath · stringrequired

Request body

emailEmailAddressrequired
An email address, normalized to lowercase and trimmed. Must contain exactly one `@`, a non-empty local part, and a domain containing a dot. Max 320 bytes (RFC 5321).
roleRolerequired
Organization member role. Ordered by privilege: `Owner` ≥ `Admin` ≥ `Developer` ≥ `Viewer`. The ordering is what enables checks like `role >= Role::Admin`.

Response · 201

created_atstring · date-timerequired
emailstringrequired
email_deliveryDelivery | null
Whether the invitation email went out — present on create only.
expires_atstring · date-timerequired
idstring · uuidrequired
invited_byUserIdrequired
End-user identifier (dashboard login).
organization_idOrganizationIdrequired
Organization within a tenant.
roleRolerequired
Organization member role. Ordered by privilege: `Owner` ≥ `Admin` ≥ `Developer` ≥ `Viewer`. The ordering is what enables checks like `role >= Role::Admin`.
statusInvitationStatusrequired
curl -X POST https://api.opennozzle.com/v1/organizations/<organization_id>/invitations \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "you@example.com",
  "role": "viewer"
}'
get/v1/organizations/{organization_id}/members

List members of an organization.

identity:read

Parameters

organization_idpath · stringrequired

Response · 200

avatar_urlstring
display_namestring
emailstring
The person, on the members list. Absent where a membership is returned on its own (accepting an invitation).
joined_atstring · date-timerequired
organization_idOrganizationIdrequired
Organization within a tenant.
roleRolerequired
Organization member role. Ordered by privilege: `Owner` ≥ `Admin` ≥ `Developer` ≥ `Viewer`. The ordering is what enables checks like `role >= Role::Admin`.
user_idUserIdrequired
End-user identifier (dashboard login).
curl -X GET https://api.opennozzle.com/v1/organizations/<organization_id>/members \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
put/v1/organizations/{organization_id}/members/{user_id}

Change a member's role in the organization.

tenancy:writeIdempotency-Keyemits member.role_updated

Parameters

organization_idpath · stringrequired
user_idpath · stringrequired

Request body

roleRolerequired
Organization member role. Ordered by privilege: `Owner` ≥ `Admin` ≥ `Developer` ≥ `Viewer`. The ordering is what enables checks like `role >= Role::Admin`.

Response · 200

avatar_urlstring
display_namestring
emailstring
The person, on the members list. Absent where a membership is returned on its own (accepting an invitation).
joined_atstring · date-timerequired
organization_idOrganizationIdrequired
Organization within a tenant.
roleRolerequired
Organization member role. Ordered by privilege: `Owner` ≥ `Admin` ≥ `Developer` ≥ `Viewer`. The ordering is what enables checks like `role >= Role::Admin`.
user_idUserIdrequired
End-user identifier (dashboard login).
curl -X PUT https://api.opennozzle.com/v1/organizations/<organization_id>/members/<user_id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "role": "viewer"
}'
delete/v1/organizations/{organization_id}/members/{user_id}

Remove a member from the organization.

tenancy:writeIdempotency-Keyemits member.removed

Parameters

organization_idpath · stringrequired
user_idpath · stringrequired

Response · 204

Success. No response body.

curl -X DELETE https://api.opennozzle.com/v1/organizations/<organization_id>/members/<user_id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s
get/v1/organizations/{organization_id}/projects

List projects within an organization.

identity:read

Parameters

organization_idpath · stringrequired

Response · 200

created_atstring · date-timerequired
environmentProjectEnvironmentrequired
idProjectIdrequired
Project within an organization — the unit virtual keys belong to.
namestringrequired
organization_idOrganizationIdrequired
Organization within a tenant.
slugSlugrequired
A URL-safe identifier: lowercase alphanumerics and single dashes, 1–64 characters, no leading/trailing dash and no double dash. A small set of reserved words is additionally refused at runtime.
spend_capSpendCap | null
The project-wide spend ceiling, or `null` when uncapped.
curl -X GET https://api.opennozzle.com/v1/organizations/<organization_id>/projects \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/organizations/{organization_id}/projects

Create a project within an organization.

tenancy:writeIdempotency-Keyemits project.created

Parameters

organization_idpath · stringrequired

Request body

environmentProjectEnvironmentrequired
namestringrequired
slugSlugrequired
A URL-safe identifier: lowercase alphanumerics and single dashes, 1–64 characters, no leading/trailing dash and no double dash. A small set of reserved words is additionally refused at runtime.

Response · 201

created_atstring · date-timerequired
environmentProjectEnvironmentrequired
idProjectIdrequired
Project within an organization — the unit virtual keys belong to.
namestringrequired
organization_idOrganizationIdrequired
Organization within a tenant.
slugSlugrequired
A URL-safe identifier: lowercase alphanumerics and single dashes, 1–64 characters, no leading/trailing dash and no double dash. A small set of reserved words is additionally refused at runtime.
spend_capSpendCap | null
The project-wide spend ceiling, or `null` when uncapped.
curl -X POST https://api.opennozzle.com/v1/organizations/<organization_id>/projects \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "environment": "production",
  "name": "string",
  "slug": "string"
}'
post/v1/organizations/{organization_id}/transfer-ownership

Make another member the owner; you become an admin.

tenancy:writeIdempotency-Keyemits organization.ownership_transferred

Parameters

organization_idpath · stringrequired

Request body

user_idUserIdrequired
End-user identifier (dashboard login).

Response · 204

Success. No response body.

curl -X POST https://api.opennozzle.com/v1/organizations/<organization_id>/transfer-ownership \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "user_id": "01a0c96e-d51d-7213-9ab2-c2d969f9966a"
}'
get/v1/projects/{project_id}

Get a project by id.

identity:read

Parameters

project_idpath · stringrequired

Response · 200

created_atstring · date-timerequired
environmentProjectEnvironmentrequired
idProjectIdrequired
Project within an organization — the unit virtual keys belong to.
namestringrequired
organization_idOrganizationIdrequired
Organization within a tenant.
slugSlugrequired
A URL-safe identifier: lowercase alphanumerics and single dashes, 1–64 characters, no leading/trailing dash and no double dash. A small set of reserved words is additionally refused at runtime.
spend_capSpendCap | null
The project-wide spend ceiling, or `null` when uncapped.
curl -X GET https://api.opennozzle.com/v1/projects/<project_id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
patch/v1/projects/{project_id}

Rename a project. Its slug never changes.

tenancy:writeIdempotency-Keyemits project.renamed

Parameters

project_idpath · stringrequired

Request body

namestringrequired

Response · 200

created_atstring · date-timerequired
environmentProjectEnvironmentrequired
idProjectIdrequired
Project within an organization — the unit virtual keys belong to.
namestringrequired
organization_idOrganizationIdrequired
Organization within a tenant.
slugSlugrequired
A URL-safe identifier: lowercase alphanumerics and single dashes, 1–64 characters, no leading/trailing dash and no double dash. A small set of reserved words is additionally refused at runtime.
spend_capSpendCap | null
The project-wide spend ceiling, or `null` when uncapped.
curl -X PATCH https://api.opennozzle.com/v1/projects/<project_id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string"
}'
delete/v1/projects/{project_id}

Delete a project and revoke every key minted under it.

tenancy:writeIdempotency-Keyemits project.deleted

Parameters

project_idpath · stringrequired

Response · 200

revoked_keysinteger · uint64required
curl -X DELETE https://api.opennozzle.com/v1/projects/<project_id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s
put/v1/projects/{project_id}/budget

Set or lift the project-wide spend ceiling across all its keys.

tenancy:writeIdempotency-Keyemits project.budget_set

Parameters

project_idpath · stringrequired

Request body

spend_capSpendCap | null

Response · 200

created_atstring · date-timerequired
environmentProjectEnvironmentrequired
idProjectIdrequired
Project within an organization — the unit virtual keys belong to.
namestringrequired
organization_idOrganizationIdrequired
Organization within a tenant.
slugSlugrequired
A URL-safe identifier: lowercase alphanumerics and single dashes, 1–64 characters, no leading/trailing dash and no double dash. A small set of reserved words is additionally refused at runtime.
spend_capSpendCap | null
The project-wide spend ceiling, or `null` when uncapped.
curl -X PUT https://api.opennozzle.com/v1/projects/<project_id>/budget \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "spend_cap": {
    "budget_window": "daily",
    "max_budget_micro_cents": 0
  }
}'
post/v1/tenants

Create a tenant with its first organization and project, owned by you.

tenancy:writeIdempotency-Keyemits organization.created

Request body

namestringrequired
Display name for the tenant — your company, or whatever you call the billing boundary. The slug is derived from it unless you supply one.
organization_namestring
First organization's name. Defaults to the tenant name — the common case is one company, one organization, and asking twice for the same answer is a worse first experience than assuming it.
project_environmentProjectEnvironment | null
First project's environment. Defaults to production: a first project is overwhelmingly where real traffic goes, and a caller who wanted staging will say so.
project_namestring
First project's name. Defaults to `default`.
slugSlug | null
Optional explicit slug. Supply it when the derived one would be ugly, or when the name has no derivable slug at all (all punctuation, all emoji). Collisions are resolved automatically with a random suffix.

Response · 200

organizationOrganizationPublicrequired
created_atstring · date-timerequired
idOrganizationIdrequired
Organization within a tenant.
namestringrequired
owner_user_idUserIdrequired
End-user identifier (dashboard login).
slugSlugrequired
A URL-safe identifier: lowercase alphanumerics and single dashes, 1–64 characters, no leading/trailing dash and no double dash. A small set of reserved words is additionally refused at runtime.
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
projectProjectPublicrequired
created_atstring · date-timerequired
environmentProjectEnvironmentrequired
idProjectIdrequired
Project within an organization — the unit virtual keys belong to.
namestringrequired
organization_idOrganizationIdrequired
Organization within a tenant.
slugSlugrequired
A URL-safe identifier: lowercase alphanumerics and single dashes, 1–64 characters, no leading/trailing dash and no double dash. A small set of reserved words is additionally refused at runtime.
spend_capSpendCap | null
The project-wide spend ceiling, or `null` when uncapped.
tenantTenantPublicrequired
created_atstring · date-timerequired
idTenantIdrequired
Top-level tenancy: an organization / customer.
namestringrequired
regionstringrequired
slugSlugrequired
A URL-safe identifier: lowercase alphanumerics and single dashes, 1–64 characters, no leading/trailing dash and no double dash. A small set of reserved words is additionally refused at runtime.
statusTenantStatusrequired
curl -X POST https://api.opennozzle.com/v1/tenants \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "organization_name": null,
  "project_environment": null,
  "project_name": null,
  "slug": null
}'
get/v1/tenants/{tenant_id}

Get a tenant by id.

identity:read

Parameters

tenant_idpath · stringrequired

Response · 200

created_atstring · date-timerequired
idTenantIdrequired
Top-level tenancy: an organization / customer.
namestringrequired
regionstringrequired
slugSlugrequired
A URL-safe identifier: lowercase alphanumerics and single dashes, 1–64 characters, no leading/trailing dash and no double dash. A small set of reserved words is additionally refused at runtime.
statusTenantStatusrequired
curl -X GET https://api.opennozzle.com/v1/tenants/<tenant_id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/tenants/{tenant_id}/organizations

List organizations within a tenant.

identity:read

Parameters

tenant_idpath · stringrequired

Response · 200

created_atstring · date-timerequired
idOrganizationIdrequired
Organization within a tenant.
namestringrequired
owner_user_idUserIdrequired
End-user identifier (dashboard login).
slugSlugrequired
A URL-safe identifier: lowercase alphanumerics and single dashes, 1–64 characters, no leading/trailing dash and no double dash. A small set of reserved words is additionally refused at runtime.
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
curl -X GET https://api.opennozzle.com/v1/tenants/<tenant_id>/organizations \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/tenants/{tenant_id}/organizations

Create an organization within a tenant.

tenancy:writeIdempotency-Keyemits organization.created

Parameters

tenant_idpath · stringrequired

Request body

namestringrequired
slugSlugrequired
A URL-safe identifier: lowercase alphanumerics and single dashes, 1–64 characters, no leading/trailing dash and no double dash. A small set of reserved words is additionally refused at runtime.

Response · 201

created_atstring · date-timerequired
idOrganizationIdrequired
Organization within a tenant.
namestringrequired
owner_user_idUserIdrequired
End-user identifier (dashboard login).
slugSlugrequired
A URL-safe identifier: lowercase alphanumerics and single dashes, 1–64 characters, no leading/trailing dash and no double dash. A small set of reserved words is additionally refused at runtime.
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
curl -X POST https://api.opennozzle.com/v1/tenants/<tenant_id>/organizations \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "slug": "string"
}'
get/v1/tenants/{tenant_id}/usage

Get a tenant's cost rollup over 24h / 7d / 30d / all-time, plus per-kind breakdown.

usage:read

Parameters

tenant_idpath · stringrequired

Response · 200

all_time_centsinteger · int64required
last_24h_centsinteger · int64required
last_30d_by_kindUsageByKind[]required
cost_centsinteger · int64required
kindstringrequired
row_countinteger · int64required
last_30d_centsinteger · int64required
last_7d_centsinteger · int64required
tenant_idstring · uuidrequired
curl -X GET https://api.opennozzle.com/v1/tenants/<tenant_id>/usage \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/usage

Read your own usage rollup.

usage:read

Response · 200

all_time_centsinteger · int64required
last_24h_centsinteger · int64required
last_30d_by_kindUsageByKind[]required
cost_centsinteger · int64required
kindstringrequired
row_countinteger · int64required
last_30d_centsinteger · int64required
last_7d_centsinteger · int64required
tenant_idstring · uuidrequired
curl -X GET https://api.opennozzle.com/v1/usage \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s

Accounts & sessions

21 operations
post/v1/auth/email/verify

Consume an email-verification token and mark the email verified.

no authIdempotency-Keyemits user.email_verified

Request body

tokenstringrequired

Response · 204

Success. No response body.

curl -X POST https://api.opennozzle.com/v1/auth/email/verify \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "string"
}'
post/v1/auth/email/verify/resend

Send a fresh email-verification link to the authenticated user's address.

identity:writeIdempotency-Keyemits user.email_verification_resent

Response · 204

Success. No response body.

curl -X POST https://api.opennozzle.com/v1/auth/email/verify/resend \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s
post/v1/auth/login

Exchange email + password (+ MFA) for an access + refresh token pair.

no authIdempotency-Keyemits session.opened

Request body

emailEmailAddressrequired
An email address, normalized to lowercase and trimmed. Must contain exactly one `@`, a non-empty local part, and a domain containing a dot. Max 320 bytes (RFC 5321).
mfa_codeMfaCode | null
passwordPlaintextPasswordrequired
A plaintext password. Accepted on request bodies only — never present in any response. Held in memory as a zeroizing secret and dropped once hashed or verified.

Response · 200

access_expires_atstring · date-timerequired
access_tokenstringrequired
refresh_expires_atstring · date-timerequired
refresh_tokenstringrequired
userUserPublicrequired
The non-secret view of a User. This is what every endpoint that returns user info emits — `email_verified` instead of `email_verified_at`, no audit timestamps, no `mfa_required` flag (it's a security signal).
avatar_urlstring
created_atstring · date-timerequired
display_nameDisplayNamerequired
A display name. Trimmed on receipt; 1–128 characters; control characters are refused.
emailEmailAddressrequired
An email address, normalized to lowercase and trimmed. Must contain exactly one `@`, a non-empty local part, and a domain containing a dot. Max 320 bytes (RFC 5321).
email_verifiedbooleanrequired
idUserIdrequired
End-user identifier (dashboard login).
statusUserStatusrequired
curl -X POST https://api.opennozzle.com/v1/auth/login \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "you@example.com",
  "mfa_code": "string",
  "password": "string"
}'
post/v1/auth/logout

Revoke the current session.

identity:writeIdempotency-Keyemits session.closed

Response · 204

Success. No response body.

curl -X POST https://api.opennozzle.com/v1/auth/logout \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s
get/v1/auth/oauth/{provider}/callback

Finish a provider sign-in: set the session cookies and redirect to the console.

no authemits session.opened

Parameters

providerpath · stringrequired

Response · 204

Success. No response body.

curl -X GET https://api.opennozzle.com/v1/auth/oauth/<provider>/callback \
  -s
get/v1/auth/oauth/{provider}/start

Redirect the browser to the provider's consent screen (PKCE + single-use state).

no auth

Parameters

providerpath · stringrequired

Response · 204

Success. No response body.

curl -X GET https://api.opennozzle.com/v1/auth/oauth/<provider>/start \
  -s
get/v1/auth/oauth/providers

List the social sign-in providers this deployment offers.

no auth

Response · 200

providersstring[]required
Providers this deployment can sign in with, e.g. `["google","github"]`.
curl -X GET https://api.opennozzle.com/v1/auth/oauth/providers \
  -s
post/v1/auth/password/reset-confirm

Consume a reset token and set a new password.

no authIdempotency-Keyemits user.password_reset

Request body

new_passwordPlaintextPasswordrequired
A plaintext password. Accepted on request bodies only — never present in any response. Held in memory as a zeroizing secret and dropped once hashed or verified.
tokenstringrequired

Response · 204

Success. No response body.

curl -X POST https://api.opennozzle.com/v1/auth/password/reset-confirm \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "new_password": "string",
  "token": "string"
}'
post/v1/auth/password/reset-request

Request a password-reset email. Always 204 — never reveals account existence.

no authIdempotency-Keyemits user.password_reset_requested

Request body

emailEmailAddressrequired
An email address, normalized to lowercase and trimmed. Must contain exactly one `@`, a non-empty local part, and a domain containing a dot. Max 320 bytes (RFC 5321).

Response · 204

Success. No response body.

curl -X POST https://api.opennozzle.com/v1/auth/password/reset-request \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "you@example.com"
}'
post/v1/auth/refresh

Rotate a refresh token, yielding a new access + refresh pair.

no authIdempotency-Key

Request body

refresh_tokenstring

Response · 200

access_expires_atstring · date-timerequired
access_tokenstringrequired
refresh_expires_atstring · date-timerequired
refresh_tokenstringrequired
userUserPublicrequired
The non-secret view of a User. This is what every endpoint that returns user info emits — `email_verified` instead of `email_verified_at`, no audit timestamps, no `mfa_required` flag (it's a security signal).
avatar_urlstring
created_atstring · date-timerequired
display_nameDisplayNamerequired
A display name. Trimmed on receipt; 1–128 characters; control characters are refused.
emailEmailAddressrequired
An email address, normalized to lowercase and trimmed. Must contain exactly one `@`, a non-empty local part, and a domain containing a dot. Max 320 bytes (RFC 5321).
email_verifiedbooleanrequired
idUserIdrequired
End-user identifier (dashboard login).
statusUserStatusrequired
curl -X POST https://api.opennozzle.com/v1/auth/refresh \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "refresh_token": null
}'
post/v1/auth/signup

Create an account with email + password and start a session.

no authIdempotency-Keyemits user.signed_up

Request body

display_nameDisplayNamerequired
A display name. Trimmed on receipt; 1–128 characters; control characters are refused.
emailEmailAddressrequired
An email address, normalized to lowercase and trimmed. Must contain exactly one `@`, a non-empty local part, and a domain containing a dot. Max 320 bytes (RFC 5321).
passwordPlaintextPasswordrequired
A plaintext password. Accepted on request bodies only — never present in any response. Held in memory as a zeroizing secret and dropped once hashed or verified.

Response · 200

access_expires_atstring · date-timerequired
access_tokenstringrequired
refresh_expires_atstring · date-timerequired
refresh_tokenstringrequired
userUserPublicrequired
The non-secret view of a User. This is what every endpoint that returns user info emits — `email_verified` instead of `email_verified_at`, no audit timestamps, no `mfa_required` flag (it's a security signal).
avatar_urlstring
created_atstring · date-timerequired
display_nameDisplayNamerequired
A display name. Trimmed on receipt; 1–128 characters; control characters are refused.
emailEmailAddressrequired
An email address, normalized to lowercase and trimmed. Must contain exactly one `@`, a non-empty local part, and a domain containing a dot. Max 320 bytes (RFC 5321).
email_verifiedbooleanrequired
idUserIdrequired
End-user identifier (dashboard login).
statusUserStatusrequired
curl -X POST https://api.opennozzle.com/v1/auth/signup \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "display_name": "string",
  "email": "you@example.com",
  "password": "string"
}'
get/v1/me

Return the authenticated user.

identity:read

Response · 200

avatar_urlstring
created_atstring · date-timerequired
display_nameDisplayNamerequired
A display name. Trimmed on receipt; 1–128 characters; control characters are refused.
emailEmailAddressrequired
An email address, normalized to lowercase and trimmed. Must contain exactly one `@`, a non-empty local part, and a domain containing a dot. Max 320 bytes (RFC 5321).
email_verifiedbooleanrequired
idUserIdrequired
End-user identifier (dashboard login).
statusUserStatusrequired
curl -X GET https://api.opennozzle.com/v1/me \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
patch/v1/me

Update the authenticated user's display name or avatar.

identity:writeIdempotency-Keyemits user.profile_updated

Request body

avatar_urlstring
display_nameDisplayName | null

Response · 200

avatar_urlstring
created_atstring · date-timerequired
display_nameDisplayNamerequired
A display name. Trimmed on receipt; 1–128 characters; control characters are refused.
emailEmailAddressrequired
An email address, normalized to lowercase and trimmed. Must contain exactly one `@`, a non-empty local part, and a domain containing a dot. Max 320 bytes (RFC 5321).
email_verifiedbooleanrequired
idUserIdrequired
End-user identifier (dashboard login).
statusUserStatusrequired
curl -X PATCH https://api.opennozzle.com/v1/me \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "avatar_url": null,
  "display_name": null
}'
post/v1/me/email

Send a confirmation link to a new address; the account moves only when it is followed.

identity:writeIdempotency-Keyemits user.email_change_requested

Request body

current_passwordPlaintextPasswordrequired
A plaintext password. Accepted on request bodies only — never present in any response. Held in memory as a zeroizing secret and dropped once hashed or verified.
new_emailEmailAddressrequired
An email address, normalized to lowercase and trimmed. Must contain exactly one `@`, a non-empty local part, and a domain containing a dot. Max 320 bytes (RFC 5321).

Response · 204

Success. No response body.

curl -X POST https://api.opennozzle.com/v1/me/email \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "current_password": "string",
  "new_email": "you@example.com"
}'
post/v1/me/mfa/recovery-codes/generate

Generate one-time recovery codes for MFA fallback.

identity:writeIdempotency-Keyemits user.mfa_recovery_generated

Response · 200

codesstring[]required
Plaintext codes. Display once; never recoverable.
factor_idstring · uuidrequired
curl -X POST https://api.opennozzle.com/v1/me/mfa/recovery-codes/generate \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s
post/v1/me/mfa/totp/confirm

Confirm TOTP enrollment by submitting a current code.

identity:writeIdempotency-Keyemits user.mfa_totp_confirmed

Request body

codeMfaCoderequired
A second-factor code: either a 6-digit TOTP code or a recovery code. Trimmed on receipt.
factor_idstring · uuidrequired

Response · 204

Success. No response body.

curl -X POST https://api.opennozzle.com/v1/me/mfa/totp/confirm \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "string",
  "factor_id": "01a0c96e-d51d-7213-9ab2-c2d969f9966a"
}'
post/v1/me/mfa/totp/enroll

Begin TOTP enrollment; returns the shared secret and provisioning URI.

identity:writeIdempotency-Keyemits user.mfa_totp_enrolled

Response · 200

factor_idstring · uuidrequired
otpauth_uristringrequired
`otpauth://...` URI for the user's authenticator app QR code.
secretstringrequired
The Base32-encoded TOTP secret. Display once; never again.
curl -X POST https://api.opennozzle.com/v1/me/mfa/totp/enroll \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s
post/v1/me/password

Change the authenticated user's password.

identity:writeIdempotency-Keyemits user.password_changed

Request body

current_passwordPlaintextPasswordrequired
A plaintext password. Accepted on request bodies only — never present in any response. Held in memory as a zeroizing secret and dropped once hashed or verified.
new_passwordPlaintextPasswordrequired
A plaintext password. Accepted on request bodies only — never present in any response. Held in memory as a zeroizing secret and dropped once hashed or verified.

Response · 204

Success. No response body.

curl -X POST https://api.opennozzle.com/v1/me/password \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "current_password": "string",
  "new_password": "string"
}'
get/v1/me/sessions

List the authenticated user's active sessions.

identity:read

Response · 200

created_atstring · date-timerequired
currentbooleanrequired
expires_atstring · date-timerequired
idSessionIdrequired
A browser session.
ipstring
last_seen_atstring · date-timerequired
user_agentstring
curl -X GET https://api.opennozzle.com/v1/me/sessions \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
delete/v1/me/sessions/{session_id}

Revoke one of the authenticated user's sessions.

identity:writeIdempotency-Keyemits session.revoked

Parameters

session_idpath · stringrequired

Response · 204

Success. No response body.

curl -X DELETE https://api.opennozzle.com/v1/me/sessions/<session_id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s
post/v1/me/sessions/revoke-others

Revoke every active session except the current one.

identity:writeIdempotency-Keyemits user.logged_out_other_devices

Response · 200

revoked_countinteger · uint64required
curl -X POST https://api.opennozzle.com/v1/me/sessions/revoke-others \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s

Your provider keys

4 operations
get/v1/byok/credentials

List this tenant's provider credentials (last4 only, never key material).

keys:read

Response · 200

base_url_overridestring
created_atstring · date-timerequired
idstring · uuidrequired
key_last4stringrequired
last_verified_atstring · date-time
providerstringrequired
statusstringrequired
tenant_idTenantId | null
updated_atstring · date-timerequired
curl -X GET https://api.opennozzle.com/v1/byok/credentials \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/byok/credentials

Upload a provider API key (validated, sealed, one per provider).

keys:writeIdempotency-Key

Request body

api_keystringrequired
The customer's plaintext provider key. Sealed immediately; never stored, logged, or echoed.
base_url_overridestring
providerstringrequired
`models.upstream_providers.name` — a typo fails the FK at INSERT.

Response · 201

base_url_overridestring
created_atstring · date-timerequired
idstring · uuidrequired
key_last4stringrequired
last_verified_atstring · date-time
providerstringrequired
statusstringrequired
tenant_idTenantId | null
updated_atstring · date-timerequired
curl -X POST https://api.opennozzle.com/v1/byok/credentials \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "api_key": "string",
  "base_url_override": null,
  "provider": "string"
}'
delete/v1/byok/credentials/{id}

Delete a provider credential (hard delete — no ciphertext remains).

keys:writeIdempotency-Key

Parameters

idpath · stringrequired

Response · 204

Success. No response body.

curl -X DELETE https://api.opennozzle.com/v1/byok/credentials/<id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s
post/v1/byok/credentials/{id}/rotate

Replace a credential's key (re-validated, re-sealed on the current ring).

keys:writeIdempotency-Key

Parameters

idpath · stringrequired

Request body

api_keystringrequired
The replacement plaintext key. Same discipline as create.

Response · 200

base_url_overridestring
created_atstring · date-timerequired
idstring · uuidrequired
key_last4stringrequired
last_verified_atstring · date-time
providerstringrequired
statusstringrequired
tenant_idTenantId | null
updated_atstring · date-timerequired
curl -X POST https://api.opennozzle.com/v1/byok/credentials/<id>/rotate \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "api_key": "string"
}'

Webhooks

10 operations
get/v1/projects/{project_id}/webhooks

List webhook subscriptions in a project.

webhooks:read

Parameters

project_idpath · stringrequired

Response · 200

activebooleanrequired
created_atstring · date-timerequired
descriptionstring
disabled_atstring · date-time
event_typesstring[]required
idWebhookSubscriptionIdrequired
A tenant's outbound-webhook subscription.
project_idProjectIdrequired
Project within an organization — the unit virtual keys belong to.
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
updated_atstring · date-timerequired
urlstringrequired
curl -X GET https://api.opennozzle.com/v1/projects/<project_id>/webhooks \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/projects/{project_id}/webhooks

Create an outbound webhook subscription in a project.

webhooks:writeIdempotency-Key

Parameters

project_idpath · stringrequired

Request body

descriptionstring
event_typesstring[]required
Customer-namespace event types only — System events are refused.
urlstringrequired

Response · 201

activebooleanrequired
created_atstring · date-timerequired
descriptionstring
disabled_atstring · date-time
event_typesstring[]required
idWebhookSubscriptionIdrequired
A tenant's outbound-webhook subscription.
project_idProjectIdrequired
Project within an organization — the unit virtual keys belong to.
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
updated_atstring · date-timerequired
urlstringrequired
curl -X POST https://api.opennozzle.com/v1/projects/<project_id>/webhooks \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "description": null,
  "event_types": [
    "string"
  ],
  "url": "string"
}'
get/v1/webhooks/{webhook_id}

Get a webhook subscription (no signing secret).

webhooks:read

Parameters

webhook_idpath · stringrequired

Response · 200

activebooleanrequired
created_atstring · date-timerequired
descriptionstring
disabled_atstring · date-time
event_typesstring[]required
idWebhookSubscriptionIdrequired
A tenant's outbound-webhook subscription.
project_idProjectIdrequired
Project within an organization — the unit virtual keys belong to.
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
updated_atstring · date-timerequired
urlstringrequired
curl -X GET https://api.opennozzle.com/v1/webhooks/<webhook_id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
patch/v1/webhooks/{webhook_id}

Update a webhook subscription (url, events, active).

webhooks:writeIdempotency-Key

Parameters

webhook_idpath · stringrequired

Request body

activeboolean
descriptionstring
event_typesarray
urlstring

Response · 200

activebooleanrequired
created_atstring · date-timerequired
descriptionstring
disabled_atstring · date-time
event_typesstring[]required
idWebhookSubscriptionIdrequired
A tenant's outbound-webhook subscription.
project_idProjectIdrequired
Project within an organization — the unit virtual keys belong to.
tenant_idTenantIdrequired
Top-level tenancy: an organization / customer.
updated_atstring · date-timerequired
urlstringrequired
curl -X PATCH https://api.opennozzle.com/v1/webhooks/<webhook_id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "active": null,
  "description": null,
  "event_types": null,
  "url": null
}'
delete/v1/webhooks/{webhook_id}

Delete a webhook subscription.

webhooks:writeIdempotency-Key

Parameters

webhook_idpath · stringrequired

Response · 204

Success. No response body.

curl -X DELETE https://api.opennozzle.com/v1/webhooks/<webhook_id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s
get/v1/webhooks/{webhook_id}/deliveries

List recent delivery attempts for a subscription.

webhooks:read

Parameters

webhook_idpath · stringrequired

Response · 200

attemptinteger · uint32required
created_atstring · date-timerequired
delivered_atstring · date-time
event_idWebhookEventIdrequired
One fired event in api.webhook_event_log.
event_typestringrequired
idWebhookDeliveryIdrequired
One (event, subscription) delivery attempt-chain.
last_errorstring
last_status_codeinteger · int32
max_attemptsinteger · uint32required
next_attempt_atstring · date-timerequired
stateDeliveryStaterequired
The lifecycle state of one delivery attempt-chain.
subscription_idWebhookSubscriptionIdrequired
A tenant's outbound-webhook subscription.
curl -X GET https://api.opennozzle.com/v1/webhooks/<webhook_id>/deliveries \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/webhooks/{webhook_id}/rotate-secret

Rotate a subscription's signing secret.

webhooks:writeIdempotency-Key

Parameters

webhook_idpath · stringrequired

Response · 200

idWebhookSubscriptionIdrequired
A tenant's outbound-webhook subscription.
signing_secretstringrequired
curl -X POST https://api.opennozzle.com/v1/webhooks/<webhook_id>/rotate-secret \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s
post/v1/webhooks/{webhook_id}/test

Send a signed webhook.test delivery to this subscription now.

webhooks:writeIdempotency-Key

Parameters

webhook_idpath · stringrequired

Response · 200

attemptinteger · uint32required
created_atstring · date-timerequired
delivered_atstring · date-time
event_idWebhookEventIdrequired
One fired event in api.webhook_event_log.
event_typestringrequired
idWebhookDeliveryIdrequired
One (event, subscription) delivery attempt-chain.
last_errorstring
last_status_codeinteger · int32
max_attemptsinteger · uint32required
next_attempt_atstring · date-timerequired
stateDeliveryStaterequired
The lifecycle state of one delivery attempt-chain.
subscription_idWebhookSubscriptionIdrequired
A tenant's outbound-webhook subscription.
curl -X POST https://api.opennozzle.com/v1/webhooks/<webhook_id>/test \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s
post/v1/webhooks/deliveries/{delivery_id}/replay

Replay a past delivery (creates a fresh delivery).

webhooks:writeIdempotency-Key

Parameters

delivery_idpath · stringrequired

Response · 200

attemptinteger · uint32required
created_atstring · date-timerequired
delivered_atstring · date-time
event_idWebhookEventIdrequired
One fired event in api.webhook_event_log.
event_typestringrequired
idWebhookDeliveryIdrequired
One (event, subscription) delivery attempt-chain.
last_errorstring
last_status_codeinteger · int32
max_attemptsinteger · uint32required
next_attempt_atstring · date-timerequired
stateDeliveryStaterequired
The lifecycle state of one delivery attempt-chain.
subscription_idWebhookSubscriptionIdrequired
A tenant's outbound-webhook subscription.
curl -X POST https://api.opennozzle.com/v1/webhooks/deliveries/<delivery_id>/replay \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s
get/v1/webhooks/event-types

List the customer-subscribable webhook event types.

webhooks:read

Response · 200

event_typestringrequired
namespacestringrequired
curl -X GET https://api.opennozzle.com/v1/webhooks/event-types \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s

Notifications

8 operations
get/v1/notifications

Your workspace's notifications, newest first, with your unread count.

usage:read

Response · 200

has_morebooleanrequired
itemsInboxNotification[]required
bodystringrequired
created_atstring · date-timerequired
dataobjectrequired
idstring · uuidrequired
kindstringrequired
The event it came from, e.g. `virtual_key.revoked`.
linkstring
A console path to open, e.g. `/app/keys`.
project_idstring · uuid
readbooleanrequired
resource_idstring
resource_typestring
severityNotificationSeverityrequired
How loud a notification is. Mirrors the webhook registry's tiers so one vocabulary colours the bell, the webhook catalog and the audit log.
tenant_idstring · uuidrequired
titlestringrequired
next_cursorstring
unread_countinteger · int64required
curl -X GET https://api.opennozzle.com/v1/notifications \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/notifications/{id}/read

Mark one notification read for you.

usage:readIdempotency-Key

Parameters

idpath · stringrequired

Response · 204

Success. No response body.

curl -X POST https://api.opennozzle.com/v1/notifications/<id>/read \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s
post/v1/notifications/read-all

Mark every notification read for you.

usage:readIdempotency-Key

Response · 200

read_all_beforestring · date-timerequired
Everything created at or before this instant now reads as read.
curl -X POST https://api.opennozzle.com/v1/notifications/read-all \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s
get/v1/notifications/subscriptions

List your own notification subscriptions.

webhooks:read

Response · 200

activebooleanrequired
channelChannelrequired
created_atstring · date-timerequired
event_typestringrequired
idstring · uuidrequired
last_delivery_atstring · date-time
project_idstring · uuid
targetobjectrequired
tenant_idstring · uuidrequired
updated_atstring · date-timerequired
curl -X GET https://api.opennozzle.com/v1/notifications/subscriptions \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/notifications/unread-count

How many notifications you have not read.

usage:read

Response · 200

unread_countinteger · int64required
curl -X GET https://api.opennozzle.com/v1/notifications/unread-count \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/tenants/{tenant_id}/notifications/subscriptions

List the tenant's notification subscriptions.

webhooks:read

Parameters

tenant_idpath · stringrequired

Response · 200

activebooleanrequired
channelChannelrequired
created_atstring · date-timerequired
event_typestringrequired
idstring · uuidrequired
last_delivery_atstring · date-time
project_idstring · uuid
targetobjectrequired
tenant_idstring · uuidrequired
updated_atstring · date-timerequired
curl -X GET https://api.opennozzle.com/v1/tenants/<tenant_id>/notifications/subscriptions \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/tenants/{tenant_id}/notifications/subscriptions

Create a notification subscription (channel + event_type).

webhooks:writeIdempotency-Key

Parameters

tenant_idpath · stringrequired

Response · 201

activebooleanrequired
channelChannelrequired
created_atstring · date-timerequired
event_typestringrequired
idstring · uuidrequired
last_delivery_atstring · date-time
project_idstring · uuid
targetobjectrequired
tenant_idstring · uuidrequired
updated_atstring · date-timerequired
curl -X POST https://api.opennozzle.com/v1/tenants/<tenant_id>/notifications/subscriptions \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s
delete/v1/tenants/{tenant_id}/notifications/subscriptions/{id}

Delete a notification subscription.

webhooks:writeIdempotency-Key

Parameters

tenant_idpath · stringrequired
idpath · stringrequired

Response · 204

Success. No response body.

curl -X DELETE https://api.opennozzle.com/v1/tenants/<tenant_id>/notifications/subscriptions/<id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s

Live events

1 operation
get/v1/events/stream

Live tenant event stream (SSE): cost, keys, instances, notifications, webhooks, model health.

usage:read

Response · 200

Server-Sent Events. Each frame's `event:` is the kind (e.g. `cost.recorded`), `id:` is the resume token to send back as `Last-Event-ID`, and `data:` is one LiveEvent JSON object. Comment lines are keep-alives.

curl -X GET https://api.opennozzle.com/v1/events/stream \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s

Cost alerts

4 operations
get/v1/cost-alerts

Your workspace's cost alert rules, each with its spend in the current window.

billing:read

Response · 200

activebooleanrequired
created_atstring · date-timerequired
current_periodstringrequired
Spend in the current window so far — what the threshold is measured against right now.
current_spend_micro_centsinteger · int64required
idstring · uuidrequired
last_fired_atstring · date-time
last_fired_periodstring
The period this rule last fired in (`2026-09-22` / `2026-09`).
namestringrequired
tenant_idstring · uuidrequired
threshold_micro_centsinteger · int64required
updated_atstring · date-timerequired
virtual_key_idstring · uuid
`null` watches the whole workspace; set, it watches one key.
windowCostAlertWindowrequired
curl -X GET https://api.opennozzle.com/v1/cost-alerts \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/cost-alerts

Alert once per day or month when the workspace, or one key, spends past a threshold.

billing:writeIdempotency-Key

Request body

namestringrequired
threshold_micro_centsinteger · int64required
virtual_key_idstring · uuid
windowCostAlertWindowrequired

Response · 201

activebooleanrequired
created_atstring · date-timerequired
current_periodstringrequired
Spend in the current window so far — what the threshold is measured against right now.
current_spend_micro_centsinteger · int64required
idstring · uuidrequired
last_fired_atstring · date-time
last_fired_periodstring
The period this rule last fired in (`2026-09-22` / `2026-09`).
namestringrequired
tenant_idstring · uuidrequired
threshold_micro_centsinteger · int64required
updated_atstring · date-timerequired
virtual_key_idstring · uuid
`null` watches the whole workspace; set, it watches one key.
windowCostAlertWindowrequired
curl -X POST https://api.opennozzle.com/v1/cost-alerts \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "threshold_micro_cents": 0,
  "virtual_key_id": null,
  "window": "day"
}'
patch/v1/cost-alerts/{id}

Rename a cost alert, change its threshold, or pause it.

billing:writeIdempotency-Key

Parameters

idpath · stringrequired

Request body

activeboolean
namestring
threshold_micro_centsinteger · int64

Response · 200

activebooleanrequired
created_atstring · date-timerequired
current_periodstringrequired
Spend in the current window so far — what the threshold is measured against right now.
current_spend_micro_centsinteger · int64required
idstring · uuidrequired
last_fired_atstring · date-time
last_fired_periodstring
The period this rule last fired in (`2026-09-22` / `2026-09`).
namestringrequired
tenant_idstring · uuidrequired
threshold_micro_centsinteger · int64required
updated_atstring · date-timerequired
virtual_key_idstring · uuid
`null` watches the whole workspace; set, it watches one key.
windowCostAlertWindowrequired
curl -X PATCH https://api.opennozzle.com/v1/cost-alerts/<id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "active": null,
  "name": null,
  "threshold_micro_cents": null
}'
delete/v1/cost-alerts/{id}

Delete a cost alert.

billing:writeIdempotency-Key

Parameters

idpath · stringrequired

Response · 204

Success. No response body.

curl -X DELETE https://api.opennozzle.com/v1/cost-alerts/<id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s

Audit log

5 operations
get/v1/audit

List your own audit-log entries.

audit:read

Response · 200

has_morebooleanrequired
itemsAuditEntryPublic[]required
actionstringrequired
actor_idstring · uuid
actor_kindstringrequired
idAuditEntryIdrequired
One row in api.audit_log.
ipstring
methodstringrequired
occurred_atstring · date-timerequired
pathstringrequired
request_idstringrequired
resource_idstring
resource_typestring
status_codeinteger · int32required
tenant_idTenantId | null
trace_idstring
user_agentstring
next_cursorstring
curl -X GET https://api.opennozzle.com/v1/audit \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/audit/{audit_id}

Get one audit entry by id.

audit:read

Parameters

audit_idpath · stringrequired

Response · 200

actionstringrequired
actor_idstring · uuid
actor_kindstringrequired
idAuditEntryIdrequired
One row in api.audit_log.
ipstring
methodstringrequired
occurred_atstring · date-timerequired
pathstringrequired
request_idstringrequired
resource_idstring
resource_typestring
status_codeinteger · int32required
tenant_idTenantId | null
trace_idstring
user_agentstring
curl -X GET https://api.opennozzle.com/v1/audit/<audit_id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/audit/export

Export your own audit log as CSV.

admin:audit:export

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/audit/export \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/tenants/{tenant_id}/audit

List audit entries for a tenant (cursor-paginated).

audit:read

Parameters

tenant_idpath · stringrequired

Response · 200

has_morebooleanrequired
itemsAuditEntryPublic[]required
actionstringrequired
actor_idstring · uuid
actor_kindstringrequired
idAuditEntryIdrequired
One row in api.audit_log.
ipstring
methodstringrequired
occurred_atstring · date-timerequired
pathstringrequired
request_idstringrequired
resource_idstring
resource_typestring
status_codeinteger · int32required
tenant_idTenantId | null
trace_idstring
user_agentstring
next_cursorstring
curl -X GET https://api.opennozzle.com/v1/tenants/<tenant_id>/audit \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/tenants/{tenant_id}/audit/export

Stream a tenant's audit log as CSV (capped at 10k rows).

admin:audit:export

Parameters

tenant_idpath · stringrequired

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/tenants/<tenant_id>/audit/export \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s

Health

3 operations
get/v1/health/liveness

Cheap probe: returns OK as long as the process is responding.

no auth

Response · 200

build_shastringrequired
Git commit this container was deployed from (`"unknown"` when the deploy did not say).
servicestringrequired
statusstringrequired
uptime_secondsinteger · uint64required
versionstringrequired
curl -X GET https://api.opennozzle.com/v1/health/liveness \
  -s
get/v1/health/readiness

Returns OK only when every dependency is reachable.

no auth

Response · 200

checksDependencyCheck[]required
errorstring
latency_msinteger · uint64required
namestringrequired
statusCheckStatusrequired
statusReadinessStatusrequired
curl -X GET https://api.opennozzle.com/v1/health/readiness \
  -s
get/v1/openapi.json

Get the OpenAPI 3.1 spec describing every Surface::Public route.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/openapi.json \
  -s

Batches

13 operations
get/anthropic/v1/messages/batches

Anthropic Message Batches drop-in: list.

inference:call

Response · 200

dataAnthropicBatchObject[]required
archived_atstring
cancel_initiated_atstring
created_atstringrequired
ended_atstring
expires_atstringrequired
idstringrequired
processing_statusstringrequired
`in_progress`, `canceling` or `ended`.
request_countsAnthropicRequestCountsrequired
canceledinteger · int64required
erroredinteger · int64required
expiredinteger · int64required
processinginteger · int64required
succeededinteger · int64required
results_urlstring
typestringrequired
first_idstring
has_morebooleanrequired
last_idstring
curl -X GET https://api.opennozzle.com/anthropic/v1/messages/batches \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/anthropic/v1/messages/batches

Anthropic Message Batches drop-in: create a batch of Messages requests.

inference:call

Request body

requestsAnthropicBatchRequest[]required
custom_idstringrequired
paramsobjectrequired
run_idRunId | null
Nozzle extension; see `CreateBatchRequest::run_id`.

Response · 201

archived_atstring
cancel_initiated_atstring
created_atstringrequired
ended_atstring
expires_atstringrequired
idstringrequired
processing_statusstringrequired
`in_progress`, `canceling` or `ended`.
request_countsAnthropicRequestCountsrequired
canceledinteger · int64required
erroredinteger · int64required
expiredinteger · int64required
processinginteger · int64required
succeededinteger · int64required
results_urlstring
typestringrequired
curl -X POST https://api.opennozzle.com/anthropic/v1/messages/batches \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "requests": [
    {
      "custom_id": "string",
      "params": {}
    }
  ],
  "run_id": null
}'
get/anthropic/v1/messages/batches/{batch_id}

Anthropic Message Batches drop-in: one batch.

inference:call

Parameters

batch_idpath · stringrequired

Response · 200

archived_atstring
cancel_initiated_atstring
created_atstringrequired
ended_atstring
expires_atstringrequired
idstringrequired
processing_statusstringrequired
`in_progress`, `canceling` or `ended`.
request_countsAnthropicRequestCountsrequired
canceledinteger · int64required
erroredinteger · int64required
expiredinteger · int64required
processinginteger · int64required
succeededinteger · int64required
results_urlstring
typestringrequired
curl -X GET https://api.opennozzle.com/anthropic/v1/messages/batches/<batch_id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/anthropic/v1/messages/batches/{batch_id}/cancel

Anthropic Message Batches drop-in: cancel.

inference:call

Parameters

batch_idpath · stringrequired

Response · 200

archived_atstring
cancel_initiated_atstring
created_atstringrequired
ended_atstring
expires_atstringrequired
idstringrequired
processing_statusstringrequired
`in_progress`, `canceling` or `ended`.
request_countsAnthropicRequestCountsrequired
canceledinteger · int64required
erroredinteger · int64required
expiredinteger · int64required
processinginteger · int64required
succeededinteger · int64required
results_urlstring
typestringrequired
curl -X POST https://api.opennozzle.com/anthropic/v1/messages/batches/<batch_id>/cancel \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/anthropic/v1/messages/batches/{batch_id}/results

Anthropic Message Batches drop-in: results as JSONL, one line per request.

inference:call

Parameters

batch_idpath · stringrequired

Response · 200

object

curl -X GET https://api.opennozzle.com/anthropic/v1/messages/batches/<batch_id>/results \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/batches

Your batches, newest first.

inference:call

Response · 200

dataBatchObject[]required
cancelled_atinteger · int64
cancelling_atinteger · int64
completed_atinteger · int64
completion_windowstringrequired
created_atinteger · int64required
endpointstringrequired
error_file_idstring
errorsobject
expired_atinteger · int64
expires_atinteger · int64
failed_atinteger · int64
finalizing_atinteger · int64
idstringrequired
in_progress_atinteger · int64
input_file_idstring
metadataobject
objectstringrequired
output_file_idstring
request_countsRequestCountsrequired
Counts of a batch's lines, OpenAI's names.
completedinteger · int64required
failedinteger · int64required
totalinteger · int64required
statusstringrequired
usageBatchUsagerequired
What a batch has cost so far and how much of its input was read from cache. Nozzle's own addition to OpenAI's object; SDKs ignore unknown fields.
cached_tokensinteger · int64required
completion_tokensinteger · int64required
cost_micro_centsinteger · int64required
prompt_tokensinteger · int64required
first_idstring
has_morebooleanrequired
last_idstring
objectstringrequired
curl -X GET https://api.opennozzle.com/v1/batches \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/batches

Run an input file's chat requests asynchronously, at the provider's batch price where it has one (Anthropic: 50%).

inference:call

Request body

completion_windowstringrequired
Only `24h`.
endpointstringrequired
Only `/v1/chat/completions` today.
input_file_idstringrequired
metadataobject
run_idRunId | null
Nozzle extension: the run every line's call and charge is filed under (`GET /v1/usage/runs/{run_id}`). Defaults to the `X-Nozzle-Run-Id` header; naming a different run than the header is refused.

Response · 201

cancelled_atinteger · int64
cancelling_atinteger · int64
completed_atinteger · int64
completion_windowstringrequired
created_atinteger · int64required
endpointstringrequired
error_file_idstring
errorsobject
expired_atinteger · int64
expires_atinteger · int64
failed_atinteger · int64
finalizing_atinteger · int64
idstringrequired
in_progress_atinteger · int64
input_file_idstring
metadataobject
objectstringrequired
output_file_idstring
request_countsRequestCountsrequired
Counts of a batch's lines, OpenAI's names.
completedinteger · int64required
failedinteger · int64required
totalinteger · int64required
statusstringrequired
usageBatchUsagerequired
What a batch has cost so far and how much of its input was read from cache. Nozzle's own addition to OpenAI's object; SDKs ignore unknown fields.
cached_tokensinteger · int64required
completion_tokensinteger · int64required
cost_micro_centsinteger · int64required
prompt_tokensinteger · int64required
curl -X POST https://api.opennozzle.com/v1/batches \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "completion_window": "string",
  "endpoint": "string",
  "input_file_id": "string",
  "metadata": null,
  "run_id": null
}'
get/v1/batches/{batch_id}

One batch, with its request counts and cost so far.

inference:call

Parameters

batch_idpath · stringrequired

Response · 200

cancelled_atinteger · int64
cancelling_atinteger · int64
completed_atinteger · int64
completion_windowstringrequired
created_atinteger · int64required
endpointstringrequired
error_file_idstring
errorsobject
expired_atinteger · int64
expires_atinteger · int64
failed_atinteger · int64
finalizing_atinteger · int64
idstringrequired
in_progress_atinteger · int64
input_file_idstring
metadataobject
objectstringrequired
output_file_idstring
request_countsRequestCountsrequired
Counts of a batch's lines, OpenAI's names.
completedinteger · int64required
failedinteger · int64required
totalinteger · int64required
statusstringrequired
usageBatchUsagerequired
What a batch has cost so far and how much of its input was read from cache. Nozzle's own addition to OpenAI's object; SDKs ignore unknown fields.
cached_tokensinteger · int64required
completion_tokensinteger · int64required
cost_micro_centsinteger · int64required
prompt_tokensinteger · int64required
curl -X GET https://api.opennozzle.com/v1/batches/<batch_id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/batches/{batch_id}/cancel

Cancel a batch. Requests that already finished keep their results and are billed.

inference:call

Parameters

batch_idpath · stringrequired

Response · 200

cancelled_atinteger · int64
cancelling_atinteger · int64
completed_atinteger · int64
completion_windowstringrequired
created_atinteger · int64required
endpointstringrequired
error_file_idstring
errorsobject
expired_atinteger · int64
expires_atinteger · int64
failed_atinteger · int64
finalizing_atinteger · int64
idstringrequired
in_progress_atinteger · int64
input_file_idstring
metadataobject
objectstringrequired
output_file_idstring
request_countsRequestCountsrequired
Counts of a batch's lines, OpenAI's names.
completedinteger · int64required
failedinteger · int64required
totalinteger · int64required
statusstringrequired
usageBatchUsagerequired
What a batch has cost so far and how much of its input was read from cache. Nozzle's own addition to OpenAI's object; SDKs ignore unknown fields.
cached_tokensinteger · int64required
completion_tokensinteger · int64required
cost_micro_centsinteger · int64required
prompt_tokensinteger · int64required
curl -X POST https://api.opennozzle.com/v1/batches/<batch_id>/cancel \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/files

Your batch files, newest first.

inference:call

Response · 200

dataFileObject[]required
bytesinteger · int64required
created_atinteger · int64required
expires_atinteger · int64
filenamestringrequired
idstringrequired
objectstringrequired
purposestringrequired
statusstringrequired
Always `processed`: a file is usable the moment its upload returns.
has_morebooleanrequired
objectstringrequired
curl -X GET https://api.opennozzle.com/v1/files \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/files

Upload a JSONL batch input file (multipart: `purpose=batch`, `file`).

inference:call

Request body

object

Response · 200

object

curl -X POST https://api.opennozzle.com/v1/files \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
get/v1/files/{file_id}

One file.

inference:call

Parameters

file_idpath · stringrequired

Response · 200

bytesinteger · int64required
created_atinteger · int64required
expires_atinteger · int64
filenamestringrequired
idstringrequired
objectstringrequired
purposestringrequired
statusstringrequired
Always `processed`: a file is usable the moment its upload returns.
curl -X GET https://api.opennozzle.com/v1/files/<file_id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/files/{file_id}/content

A file's bytes. Output and error files are rendered from the batch's results, in OpenAI's batch output line shape.

inference:call

Parameters

file_idpath · stringrequired

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/files/<file_id>/content \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s

Fanout

1 operation
post/v1/fan/chat/completions

One chat request answered by several models in one stream (or one document), every chunk labelled with its seat; each seat billed as its own chat call.

inference:call

Request body

object

Response · 200

object

curl -X POST https://api.opennozzle.com/v1/fan/chat/completions \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Jobs

4 operations
get/v1/embeddings/jobs

Your embedding jobs, newest first; filter by `run_id`.

inference:call

Parameters

limitquery · int64
run_idquery · string

Response · 200

dataJobView[]required
achievedobject
appliedobject
attemptsinteger · int32required
Attempts the job has run (each resumes from the last part written).
cost_micro_centsinteger · int64required
cost_usdnumber · doublerequired
created_atstring · date-timerequired
errorJobErrorView | null
finished_atstring · date-time
inputInputViewrequired
id_columnstringrequired
uristringrequired
job_idstring · uuidrequired
kindstringrequired
last_errorstring
Why the last attempt stopped, while the job is still queued or running; a finished job's outcome is `status` and `error`.
modelstringrequired
objectstringrequired
outputOutputViewrequired
errors_uristringrequired
manifest_uristringrequired
parts_writteninteger · int32required
uristringrequired
prioritystringrequired
rate_limitedinteger · int64required
Calls the provider refused for a rate limit, in the parts written.
requestsinteger · int64required
Calls billed for the job, their provider-reported tokens and their cost: the sum of the ledger rows filed under the job, so the job and the ledger cannot disagree, a part redone after a restart included.
rowsRowCountsrequired
ok + truncated + failed always equals the input rows once a job succeeds.
failedinteger · int64required
okinteger · int64required
totalinteger · int64
truncatedinteger · int64required
run_idstring
started_atstring · date-time
statusJobStatusrequired
timingsobjectrequired
tokensinteger · int64required
objectstringrequired
curl -X GET https://api.opennozzle.com/v1/embeddings/jobs \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/embeddings/jobs

Embed every row of a parquet input in your storage with any /v1/embeddings model; vectors are written back as parquet parts under the job's output prefix.

inference:callstorage:readstorage:writeIdempotency-Key

Request body

dimensionsinteger · uint32
inputEmbedInputrequired
id_columnstringrequired
text_columnstringrequired
uristringrequired
One parquet object, or a prefix (ending in `/`) whose `.parquet` objects are read in key order.
input_typestring
`query` or `document`; the model's recorded convention decides what it does.
instructionstring
modelstringrequired
outputOutputSpec | null
priorityPriority
How a job spends: `fast` fans out over the providers' sync APIs at the highest concurrency they hold; `cheap` uses a provider's batch API.
run_idstring
truncateTruncate
What to do with a row longer than the model takes.

Response · 201

achievedobject
appliedobject
attemptsinteger · int32required
Attempts the job has run (each resumes from the last part written).
cost_micro_centsinteger · int64required
cost_usdnumber · doublerequired
created_atstring · date-timerequired
errorJobErrorView | null
finished_atstring · date-time
inputInputViewrequired
id_columnstringrequired
uristringrequired
job_idstring · uuidrequired
kindstringrequired
last_errorstring
Why the last attempt stopped, while the job is still queued or running; a finished job's outcome is `status` and `error`.
modelstringrequired
objectstringrequired
outputOutputViewrequired
errors_uristringrequired
manifest_uristringrequired
parts_writteninteger · int32required
uristringrequired
prioritystringrequired
rate_limitedinteger · int64required
Calls the provider refused for a rate limit, in the parts written.
requestsinteger · int64required
Calls billed for the job, their provider-reported tokens and their cost: the sum of the ledger rows filed under the job, so the job and the ledger cannot disagree, a part redone after a restart included.
rowsRowCountsrequired
ok + truncated + failed always equals the input rows once a job succeeds.
failedinteger · int64required
okinteger · int64required
totalinteger · int64
truncatedinteger · int64required
run_idstring
started_atstring · date-time
statusJobStatusrequired
timingsobjectrequired
tokensinteger · int64required
curl -X POST https://api.opennozzle.com/v1/embeddings/jobs \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "dimensions": null,
  "input": {
    "id_column": "string",
    "text_column": "string",
    "uri": "string"
  },
  "input_type": null,
  "instruction": null,
  "model": "string",
  "output": {},
  "priority": "fast",
  "run_id": null,
  "truncate": "end"
}'
get/v1/embeddings/jobs/{job_id}

One embedding job: status, row counts (ok, truncated, failed), tokens, cost, stage timings and the achieved rate.

inference:call

Parameters

job_idpath · stringrequired

Response · 200

achievedobject
appliedobject
attemptsinteger · int32required
Attempts the job has run (each resumes from the last part written).
cost_micro_centsinteger · int64required
cost_usdnumber · doublerequired
created_atstring · date-timerequired
errorJobErrorView | null
finished_atstring · date-time
inputInputViewrequired
id_columnstringrequired
uristringrequired
job_idstring · uuidrequired
kindstringrequired
last_errorstring
Why the last attempt stopped, while the job is still queued or running; a finished job's outcome is `status` and `error`.
modelstringrequired
objectstringrequired
outputOutputViewrequired
errors_uristringrequired
manifest_uristringrequired
parts_writteninteger · int32required
uristringrequired
prioritystringrequired
rate_limitedinteger · int64required
Calls the provider refused for a rate limit, in the parts written.
requestsinteger · int64required
Calls billed for the job, their provider-reported tokens and their cost: the sum of the ledger rows filed under the job, so the job and the ledger cannot disagree, a part redone after a restart included.
rowsRowCountsrequired
ok + truncated + failed always equals the input rows once a job succeeds.
failedinteger · int64required
okinteger · int64required
totalinteger · int64
truncatedinteger · int64required
run_idstring
started_atstring · date-time
statusJobStatusrequired
timingsobjectrequired
tokensinteger · int64required
curl -X GET https://api.opennozzle.com/v1/embeddings/jobs/<job_id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/embeddings/jobs/{job_id}/cancel

Cancel a job. Parts already written stay, and are billed.

inference:callIdempotency-Key

Parameters

job_idpath · stringrequired

Response · 200

achievedobject
appliedobject
attemptsinteger · int32required
Attempts the job has run (each resumes from the last part written).
cost_micro_centsinteger · int64required
cost_usdnumber · doublerequired
created_atstring · date-timerequired
errorJobErrorView | null
finished_atstring · date-time
inputInputViewrequired
id_columnstringrequired
uristringrequired
job_idstring · uuidrequired
kindstringrequired
last_errorstring
Why the last attempt stopped, while the job is still queued or running; a finished job's outcome is `status` and `error`.
modelstringrequired
objectstringrequired
outputOutputViewrequired
errors_uristringrequired
manifest_uristringrequired
parts_writteninteger · int32required
uristringrequired
prioritystringrequired
rate_limitedinteger · int64required
Calls the provider refused for a rate limit, in the parts written.
requestsinteger · int64required
Calls billed for the job, their provider-reported tokens and their cost: the sum of the ledger rows filed under the job, so the job and the ledger cannot disagree, a part redone after a restart included.
rowsRowCountsrequired
ok + truncated + failed always equals the input rows once a job succeeds.
failedinteger · int64required
okinteger · int64required
totalinteger · int64
truncatedinteger · int64required
run_idstring
started_atstring · date-time
statusJobStatusrequired
timingsobjectrequired
tokensinteger · int64required
curl -X POST https://api.opennozzle.com/v1/embeddings/jobs/<job_id>/cancel \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s

Judgments

1 operation
post/v1/judgments

Typed judgment: a state and named choice / score / noul questions in, calibrated answers out. Bills the input tokens read.

inference:call

Request body

object

Response · 201

object

curl -X POST https://api.opennozzle.com/v1/judgments \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Leases

4 operations
get/v1/leases

The caller's leases, newest first; ?open=true keeps the ones still running, ?limit= up to 500.

instances:read

Response · 200

Response shape is not described.

curl -X GET https://api.opennozzle.com/v1/leases \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/leases

Rent one dedicated GPU pod of a Blueprint for one job: {blueprint, job_ref, max_minutes, max_cost_cents, run_id?, provider?, gpu_sku?, gpu_count?, ssh_public_key?}. The cheapest available offer that holds the model is chosen unless one is named; the same job_ref returns the same lease. Poll until state is ready, then call the router with model = the lease's model. A workbench Blueprint (workbench_torch) serves no model: send ssh_public_key (one id_*.pub line), and the ready lease answers ssh {host, port, user} for a pod you run your own code on (training, evals) until you release it, its deadline passes or its cost cap is reached; upload what you want to keep to /v1/storage before then. Refusals carry details.code lease.spend_cap | lease.busy | lease.platform_busy | lease.no_capacity | lease.ssh_key_required | lease.ssh_key_invalid | lease.ssh_key_not_accepted.

instances:writeIdempotency-Key

Response · 200

Response shape is not described.

curl -X POST https://api.opennozzle.com/v1/leases \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s
get/v1/leases/{id}

One lease: launching | ready | ended, its model (null for a workbench), ssh {host, port, user} while a workbench is ready, offer, hourly price, cost so far against its ceiling, deadline and how it ended.

instances:read

Parameters

idpath · stringrequired

Response · 200

Response shape is not described.

curl -X GET https://api.opennozzle.com/v1/leases/<id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
delete/v1/leases/{id}

End a lease now and terminate its pod. Releasing an ended lease changes nothing; call it however the job ends.

instances:write

Parameters

idpath · stringrequired

Response · 200

Response shape is not described.

curl -X DELETE https://api.opennozzle.com/v1/leases/<id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s

Llms

32 operations
get/llms.txt

The map of the API for an agent: one line per route group and where to read more.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/llms.txt \
  -s
get/v1/analytics/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/analytics/llms.txt \
  -s
get/v1/audit/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/audit/llms.txt \
  -s
get/v1/batches/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/batches/llms.txt \
  -s
get/v1/billing/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/billing/llms.txt \
  -s
get/v1/byok/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/byok/llms.txt \
  -s
get/v1/catalog/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/catalog/llms.txt \
  -s
get/v1/compute-catalog/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/compute-catalog/llms.txt \
  -s
get/v1/cost-alerts/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/cost-alerts/llms.txt \
  -s
get/v1/events/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/events/llms.txt \
  -s
get/v1/fanout/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/fanout/llms.txt \
  -s
get/v1/health/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/health/llms.txt \
  -s
get/v1/identity/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/identity/llms.txt \
  -s
get/v1/instances/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/instances/llms.txt \
  -s
get/v1/jobs/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/jobs/llms.txt \
  -s
get/v1/judgments/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/judgments/llms.txt \
  -s
get/v1/keys/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/keys/llms.txt \
  -s
get/v1/leases/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/leases/llms.txt \
  -s
get/v1/model-intel/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/model-intel/llms.txt \
  -s
get/v1/notifications/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/notifications/llms.txt \
  -s
get/v1/openai-compat/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/openai-compat/llms.txt \
  -s
get/v1/openapi/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/openapi/llms.txt \
  -s
get/v1/playground/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/playground/llms.txt \
  -s
get/v1/prompt-cache/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/prompt-cache/llms.txt \
  -s
get/v1/quotas/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/quotas/llms.txt \
  -s
get/v1/runs/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/runs/llms.txt \
  -s
get/v1/sdk-compat/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/sdk-compat/llms.txt \
  -s
get/v1/shared-instances/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/shared-instances/llms.txt \
  -s
get/v1/storage/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/storage/llms.txt \
  -s
get/v1/tenancy/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/tenancy/llms.txt \
  -s
get/v1/variants/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/variants/llms.txt \
  -s
get/v1/webhooks/llms.txt

This group's routes, for an agent: verbs, paths, scopes, parameters and types.

no auth

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/webhooks/llms.txt \
  -s

Model Intel

16 operations
get/v1/categories

The model taxonomy: every category with its parents, children and how many models it holds.

catalog:read

Response · 200

dataCategoryNode[]required
attribute_schemaobjectrequired
childrenstring[]required
direct_modelsinteger · int64required
Base models filed directly here.
meaningstringrequired
namestringrequired
originstringrequired
parentsstring[]required
primary_parentstring
rankablebooleanrequired
Whether any leaderboard weight ranks this category or a descendant.
slugstringrequired
transitive_modelsinteger · int64required
Base models filed here or under any descendant.
objectstringrequired
curl -X GET https://api.opennozzle.com/v1/categories \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/categories/{slug}/models

Models in a category or any of its descendants, filterable by modality, interaction and open weights.

catalog:read

Parameters

slugpath · stringrequired
interactionquery · string
`batch`, `streaming` or `realtime_duplex`.
limitquery · int64
1–500, default 100.
modality_inquery · string
An input modality the model takes (`text`, `image`, `audio`, `video`, …).
modality_outquery · string
An output modality it produces (`text`, `image`, `audio`, `vector`, …).
open_weightsquery · boolean

Response · 200

dataTaxonomyModel[]required
categoriesstring[]required
derivativesinteger · int64required
Quants and fine-tunes that roll up onto this entry.
interactionstring[]required
licensestring
makerstring
modality_instring[]required
modality_outstring[]required
modelstring
The catalog model this entry is placed on, when placed.
open_weightsboolean
params_bnumber · double
raw_namestringrequired
servedbooleanrequired
objectstringrequired
curl -X GET https://api.opennozzle.com/v1/categories/<slug>/models \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/evals/results

Measured arms you may read (yours and public ones), each board's frontier marked: on_frontier (no arm beats it on score, cost and latency), best_quality, and best_value (the cheapest arm statistically tied with the best).

catalog:read

Parameters

suitequery · string
taskquery · string

Response · 200

dataArmRow[]required
best_qualitybooleanrequired
The highest quality on the board.
best_valuebooleanrequired
The cheapest arm whose result cannot be told apart from the best.
ci_lowernumber · double
ci_uppernumber · double
configstringrequired
cost_unitstringrequired
cost_usd_per_unitnumber · double
datasetstringrequired
dataset_versionstringrequired
failuresinteger · int32
higher_is_betterbooleanrequired
latency_p50_msnumber · double
latency_p95_msnumber · double
metricstringrequired
modelstring
The catalog model it is placed on, or null.
ninteger · int32
observed_atstring · date-timerequired
on_frontierbooleanrequired
No other arm on the board beats it on quality, cost and (when both state it) p50 latency. False when its cost is unknown.
providerstringrequired
raw_modelstringrequired
reasoning_effortstringrequired
run_idstring
splitstringrequired
suitestringrequired
taskstringrequired
valuenumber · doublerequired
visibilitystringrequired
yoursbooleanrequired
True when the caller posted it.
curl -X GET https://api.opennozzle.com/v1/evals/results \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/evals/results

Post a board of measured arms (model, host, reasoning effort, config, score with interval, cost per unit, latency) from a task you ran; yours alone unless `public`, and re-posting an arm replaces it.

evals:writeIdempotency-Key

Request body

armsArmIn[]required
ci_lowernumber · double
ci_uppernumber · double
configstring
Anything else that defines the arm (`method=hybrid`, `dims=512`).
cost_usd_per_unitnumber · double
failuresinteger · int32
latency_p50_msnumber · double
latency_p95_msnumber · double
modelstringrequired
The model as you called it; Nozzle places it on a catalog model.
ninteger · int32
providerstring
reasoning_effortstring
run_idstring
The `X-Nozzle-Run-Id` the arm ran under, so its calls and cost can be read back.
valuenumber · doublerequired
cost_unitstring
What `cost_usd_per_unit` is per (`page`, `query`, `card`, `mtok`).
datasetstringrequired
dataset_versionstring
higher_is_betterbooleanrequired
metricstringrequired
The metric's name (`ndcg@10`, `recall@100`, `field_f1`).
observed_atstring · date-time
When the measurement was taken; now when omitted.
splitstring
suitestringrequired
Your name for the experiment family (`bidauthor.reading`, `deepcontext.retrieval`).
taskstringrequired
The task, ideally a ranking category slug (`embedding`, `reranker`, `document_understanding`).
visibilityVisibilityIn | null
`tenant` (default): only you read it. `public`: everyone does.

Response · 200

placedobjectrequired
`raw_model` → the catalog model it was placed on.
unplacedstring[]required
Names no catalog model answers to; kept, ranked by their raw name.
writteninteger · uint64required
curl -X POST https://api.opennozzle.com/v1/evals/results \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "arms": [
    {
      "model": "string",
      "value": 0
    }
  ],
  "cost_unit": "",
  "dataset": "string",
  "dataset_version": "",
  "higher_is_better": false,
  "metric": "string",
  "observed_at": null,
  "split": "",
  "suite": "string",
  "task": "string",
  "visibility": "tenant"
}'
delete/v1/evals/results

Withdraw arms you posted: every arm of a suite, or only one task or dataset version of it.

evals:writeIdempotency-Key

Parameters

dataset_versionquery · string
suitequery · string
taskquery · string

Response · 200

removedinteger · uint64required
curl -X DELETE https://api.opennozzle.com/v1/evals/results \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s
get/v1/frontier

A ranking category's models by quality against the cheapest live price (3:1 input:output per million tokens) and Nozzle's measured p50 latency, with the frontier, best quality and best value marked.

catalog:read

Parameters

categoryquery · string
frontier_onlyquery · boolean
`true`: only frontier models.
limitquery · int64
Models to weigh, 1–500 (default 200).

Response · 200

categorystringrequired
dataValueRow[]required
benchmarks_scoredinteger · int64required
best_qualitybooleanrequired
best_valuebooleanrequired
modelstringrequired
on_frontierbooleanrequired
p50_latency_msnumber · double
Nozzle-measured p50 over 7 days, or null when Nozzle has not served it.
pricePrice | null
Cheapest live price, or null when nobody states one.
qualitynumber · doublerequired
The category blend, 0–1.
methodstringrequired
How price, frontier and value are computed.
curl -X GET https://api.opennozzle.com/v1/frontier \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/hub/repos

Search Hugging Face repos Nozzle tracks: by task, tags, library, retrieval kind (dense, sparse, late_interaction, cross_encoder), licence, size and gate; sorted by likes, downloads or date.

catalog:read

Parameters

authorquery · string
child_ofquery · string
Repos that name this repo as a base.
created_afterquery · date-time
created_beforequery · date-time
derivative_kindquery · string
gatedquery · boolean
include_removedquery · boolean
libraryquery · string
licensequery · string
limitquery · int64
offsetquery · int64
originalquery · boolean
params_maxquery · int64
params_minquery · int64
pipeline_tagquery · string
qquery · string
Case-insensitive substring of the repo id.
retrieval_kindquery · string
Comma-separated: dense, sparse, late_interaction, cross_encoder (any of them).
sortquery · string
tag_matchquery · string
tagsquery · string
Comma-separated tags, spelled as the Hub spells them.

Response · 200

limitinteger · int64required
offsetinteger · int64required
reposRepoView[]required
authorstringrequired
base_modelsstring[]required
created_atstring · date-time
derivative_kindDerivativeKindrequired
downloads_30dinteger · int64
downloads_all_timeinteger · int64
first_public_atstring · date-time
first_public_basisOccurredBasis | null
first_seen_atstring · date-timerequired
gatedstring
head_shastring
idstringrequired
is_originalbooleanrequired
last_modifiedstring · date-time
librarystring
licensestring
likesinteger · int32
paramsinteger · int64
pipeline_tagstring
removed_atstring · date-time
retrieval_kindsRetrievalKind[]required
What the repo is to retrieval, read from its tags, library and name.
tagsstring[]required
Every tag the Hub lists for the repo, as it lists them (case kept).
traction_as_ofstring · date
trending_scoreinteger · int32
updated_atstring · date-timerequired
weight_formatsstring[]required
totalinteger · int64required
curl -X GET https://api.opennozzle.com/v1/hub/repos \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/hub/repos/{owner}/{name}

One Hugging Face repo with its tags, retrieval kinds, traction, the repos it derives from, its copies by kind, and the inference providers that serve it.

catalog:read

Parameters

ownerpath · stringrequired
namepath · stringrequired

Response · 200

childrenChildCount[]required
derivative_kindDerivativeKindrequired
reposinteger · int64required
parentsRepoView[]required
The repos it declares as its bases, as far as the mirror holds them.
authorstringrequired
base_modelsstring[]required
created_atstring · date-time
derivative_kindDerivativeKindrequired
downloads_30dinteger · int64
downloads_all_timeinteger · int64
first_public_atstring · date-time
first_public_basisOccurredBasis | null
first_seen_atstring · date-timerequired
gatedstring
head_shastring
idstringrequired
is_originalbooleanrequired
last_modifiedstring · date-time
librarystring
licensestring
likesinteger · int32
paramsinteger · int64
pipeline_tagstring
removed_atstring · date-time
retrieval_kindsRetrievalKind[]required
What the repo is to retrieval, read from its tags, library and name.
tagsstring[]required
Every tag the Hub lists for the repo, as it lists them (case kept).
traction_as_ofstring · date
trending_scoreinteger · int32
updated_atstring · date-timerequired
weight_formatsstring[]required
providersProviderMapping[]required
context_lengthinteger · int32
input_pricenumber · double
observed_atstring · date-timerequired
output_pricenumber · double
providerstringrequired
provider_model_idstring
statusstring
structured_outputboolean
taskstring
tool_callingboolean
tpsnumber · double
ttft_msnumber · double
repoRepoViewrequired
authorstringrequired
base_modelsstring[]required
created_atstring · date-time
derivative_kindDerivativeKindrequired
downloads_30dinteger · int64
downloads_all_timeinteger · int64
first_public_atstring · date-time
first_public_basisOccurredBasis | null
first_seen_atstring · date-timerequired
gatedstring
head_shastring
idstringrequired
is_originalbooleanrequired
last_modifiedstring · date-time
librarystring
licensestring
likesinteger · int32
paramsinteger · int64
pipeline_tagstring
removed_atstring · date-time
retrieval_kindsRetrievalKind[]required
What the repo is to retrieval, read from its tags, library and name.
tagsstring[]required
Every tag the Hub lists for the repo, as it lists them (case kept).
traction_as_ofstring · date
trending_scoreinteger · int32
updated_atstring · date-timerequired
weight_formatsstring[]required
curl -X GET https://api.opennozzle.com/v1/hub/repos/<owner>/<name> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/labs

Every lab that makes models, with how many it has and its newest release.

catalog:read

Response · 200

dataLabRow[]required
hf_orgstring
homepagestring
kindstringrequired
latest_release_atstring · date-time
model_countinteger · int64required
namestringrequired
open_weights_modelsinteger · int64required
slugstringrequired
curl -X GET https://api.opennozzle.com/v1/labs \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/labs/{slug}

One lab and every model it has made, newest first, with when each was released and where it was seen.

catalog:read

Parameters

slugpath · stringrequired

Response · 200

hf_orgstring
homepagestring
kindstringrequired
latest_release_atstring · date-time
model_countinteger · int64required
modelsLabModelRow[]required
display_namestring
first_public_atstring · date-time
first_seen_atstring · date-time
hf_repostring
idstring · uuidrequired
licensestring
modalitystringrequired
namestringrequired
open_weightsboolean
released_atstring · date-time
sourcesarray
namestringrequired
open_weights_modelsinteger · int64required
slugstringrequired
curl -X GET https://api.opennozzle.com/v1/labs/<slug> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/models/{id}/categories

Every category a model is filed under, with the attributes that membership carries.

catalog:read

Parameters

idpath · stringrequired

Response · 200

dataMembership[]required
attributesobjectrequired
categorystringrequired
category_namestringrequired
confidencenumber · double
raw_namestringrequired
sourcestringrequired
source_urlstring
verifiedbooleanrequired
objectstringrequired
curl -X GET https://api.opennozzle.com/v1/models/<id>/categories \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/models/{id}/offerings

Every provider that serves a model, its prices and Nozzle's measured latency, and where Nozzle would route you.

catalog:read

Parameters

idpath · stringrequired

Response · 200

dataOffering[]required
cached_input_cents_per_mtoknumber · double
context_lengthinteger · int32
first_seen_atstring · date-timerequired
input_cents_per_mtoknumber · double
Cents per million tokens, the catalog's unit. Null when the provider does not state it.
keyedbooleanrequired
Nozzle holds a key for this provider.
last_seen_atstring · date-timerequired
latencyLatencyrequired
p50_msnumber · double
Time to response head (time to first byte for streams), ms.
p90_msnumber · double
samplesinteger · int64required
Successful calls Nozzle routed there in the window.
windowstringrequired
max_output_tokensinteger · int32
output_cents_per_mtoknumber · double
price_sourcestring
`provider` (its own list), `nozzle_list_price` (what Nozzle bills you on the route it uses), or null when no price is known.
providerstringrequired
provider_model_idstringrequired
The model's id on that provider's API.
routes_you_herebooleanrequired
Your requests for this model would be routed to this offering now.
sourcestringrequired
Where these facts come from: `provider_list:<p>` is the provider's own API, read through a key Nozzle holds; otherwise the named host or feed.
modelstringrequired
servedbooleanrequired
updated_atstring · date-time
ETag
Strong tag over the body. Send it as `If-None-Match` to get 304 with no body when nothing changed.
curl -X GET https://api.opennozzle.com/v1/models/<id>/offerings \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/models/{id}/rankings

Every leaderboard's latest score and rank for one model.

catalog:read

Parameters

idpath · stringrequired

Response · 200

display_namestringrequired
labstring
modelstringrequired
open_weightsboolean
scoresScore[]required
as_ofstring · daterequired
benchmarkstringrequired
ci_lowernumber · double
ci_uppernumber · double
higher_is_betterbooleanrequired
licensestring
metricstringrequired
rankinteger · int32
reasoning_effortstring
`variant` as a `reasoning_effort` your binding accepts, or null when it is not one (or you have no binding for the model).
scalestringrequired
`elo`, `fraction` (0–1), `percent` (0–100), `count` or `raw`.
sourcestringrequired
source_namestringrequired
The name exactly as the leaderboard writes it.
source_urlstring
taskstringrequired
valuenumber · doublerequired
variantstring
The leaderboard's variant of the model (`high`, `max`, `thinking`), or null.
votesinteger · int64
Votes, observations or runs behind the value, as the source counts them.
servedbooleanrequired
updated_atstring · date-time
ETag
Strong tag over the body. Send it as `If-None-Match` to get 304 with no body when nothing changed.
curl -X GET https://api.opennozzle.com/v1/models/<id>/rankings \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/models/{id}/run-options

Every way to run a model: its maker's API, every host with prices and measured speed, and the rentable GPU nodes that hold its weights (fewest GPUs per GPU model at bf16, fp8 or int4, priced per node, with cost per million tokens where measured).

catalog:read

Parameters

idpath · stringrequired

Response · 200

first_partyHosted[]required
The maker's own API, when the maker runs one Nozzle knows.
cached_input_cents_per_mtoknumber · double
context_lengthinteger · int32
input_cents_per_mtoknumber · double
last_seen_atstring · date-timerequired
max_output_tokensinteger · int32
measuredMeasure[]required
Newest value per metric, each with the source that measured it.
measured_atstring · date-timerequired
metricstringrequired
sourcestringrequired
valuenumber · doublerequired
output_cents_per_mtoknumber · double
providerstringrequired
provider_model_idstringrequired
hostedHosted[]required
Every other host that lists the model.
cached_input_cents_per_mtoknumber · double
context_lengthinteger · int32
input_cents_per_mtoknumber · double
last_seen_atstring · date-timerequired
max_output_tokensinteger · int32
measuredMeasure[]required
Newest value per metric, each with the source that measured it.
measured_atstring · date-timerequired
metricstringrequired
sourcestringrequired
valuenumber · doublerequired
output_cents_per_mtoknumber · double
providerstringrequired
provider_model_idstringrequired
measured_hostsMeasuredHost[]required
Hosts known only from a measuring source (Hugging Face's provider map, OpenRouter's endpoints) with no listing of their own in the catalog.
measuredMeasure[]required
measured_atstring · date-timerequired
metricstringrequired
sourcestringrequired
valuenumber · doublerequired
sourcestringrequired
`hf:<host>` or `openrouter:<host>`.
modelModelHeadrequired
context_lengthinteger · int32
display_namestring
hf_repostring
idstring · uuidrequired
labstring
lab_input_cents_per_mtoknumber · double
The maker's own stated per-token price, from its pricing page.
lab_output_cents_per_mtoknumber · double
licensestring
max_output_tokensinteger · int32
modalitystring
namestringrequired
open_weightsboolean
released_atstring · date-time
nozzleNozzleRoute[]required
How Nozzle itself serves it, if it does.
providerstringrequired
scopestringrequired
upstream_modelstring
self_hostedSelfHostingrequired
Renting GPUs and running the weights.
nodesSelfHostedNode[]required
Nodes that hold the weights, cheapest first: per GPU model, the fewest GPUs at bf16, at fp8 when that takes fewer, at int4 only when neither fits that GPU model.
cents_per_mtoknumber · double
The node's hourly price spread over the tokens it serves in that hour.
cheapest_hoststringrequired
enginestring
gpu_countinteger · int32required
gpu_memory_gbnumber · doublerequired
gpu_modelstringrequired
hosts_offeringinteger · int64required
launchablebooleanrequired
Whether a Nozzle lease can launch this node: every Blueprint's engine runs on CUDA, so an AMD Instinct or Intel Gaudi node is listed for its price but no lease picks it.
node_cents_per_hournumber · doublerequired
The cheapest on-demand price for a whole node of this size, any host.
precisionPrecisionrequired
The precisions a node is offered at, best quality first.
throughputThroughputrequired
tokens_per_secondnumber · double
The node's measured output tokens per second.
sizeModelSize | null
The model's size and the memory it takes to serve, when known.
unavailableSelfHostingGap | null
Why `nodes` is empty; absent when there are nodes.
ETag
Strong tag over the body. Send it as `If-None-Match` to get 304 with no body when nothing changed.
curl -X GET https://api.opennozzle.com/v1/models/<id>/run-options \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/rankings

Models ranked for a task category from public leaderboards, with whether you can call each now; `benchmark=source:benchmark` ranks by one of the category's inputs alone.

catalog:read

Parameters

benchmarkquery · string
Rank by one of the category's inputs alone, as `source:benchmark` (`mteb:rteb_eng_beta`, `mteb:eng_v2.retrieval`); the response's `composite.inputs` without it lists the valid ones.
categoryquery · string
A task category slug (`frontier_chat`, `code_agents`, `vision`, `image_gen`, `video_gen`, …).
limitquery · int64
Rows to return, 1–200 (default 50).
open_weightsquery · boolean
`true` for open-weights models only, `false` for closed only. Models whose licence is unknown are excluded by either.

Response · 200

categorystringrequired
compositeCompositerequired
How `score` is computed, so a move between two polls can be told apart from a change of formula.
descriptionstringrequired
inputsCompositeInput[]required
benchmarkstringrequired
sourcestringrequired
weightnumber · doublerequired
methodstringrequired
price_weightnumber · doublerequired
prior_weightnumber · doublerequired
Weight of the neutral 0.5 every blend is shrunk toward.
speed_weightnumber · doublerequired
versioninteger · uint32required
dataRankedModel[]required
benchmarks_scoredinteger · int64required
benchmarks_weightedinteger · int64required
display_namestringrequired
embedding_dimensionsinteger · int32
The native width of one output vector, for an embedder.
labstring
modelstringrequired
The `/v1/catalog/models` id.
open_weightsboolean
From the catalog's licence and weights repo; null when unknown.
positioninteger · uintrequired
qualitynumber · doublerequired
The benchmark blend alone, 0–1.
retrieval_kindsstring[]required
What the model is for retrieval: `dense`, `sparse`, `late_interaction`, `cross_encoder` (an embedder can be several).
scorenumber · doublerequired
The composite, 0–1 (plus price/speed terms when the category weighs them).
scoresScore[]required
as_ofstring · daterequired
benchmarkstringrequired
ci_lowernumber · double
ci_uppernumber · double
higher_is_betterbooleanrequired
licensestring
metricstringrequired
rankinteger · int32
reasoning_effortstring
`variant` as a `reasoning_effort` your binding accepts, or null when it is not one (or you have no binding for the model).
scalestringrequired
`elo`, `fraction` (0–1), `percent` (0–100), `count` or `raw`.
sourcestringrequired
source_namestringrequired
The name exactly as the leaderboard writes it.
source_urlstring
taskstringrequired
valuenumber · doublerequired
variantstring
The leaderboard's variant of the model (`high`, `max`, `thinking`), or null.
votesinteger · int64
Votes, observations or runs behind the value, as the source counts them.
servedbooleanrequired
Whether YOUR key can call this model now.
descriptionstringrequired
display_namestringrequired
updated_atstring · date-time
ETag
Strong tag over the body. Send it as `If-None-Match` to get 304 with no body when nothing changed.
curl -X GET https://api.opennozzle.com/v1/rankings \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/releases

Every public release of a model, newest first: which source showed it, how, and when.

catalog:read

Parameters

cursorquery · uuid
The `next_cursor` of the previous page.
kindquery · string
`first_seen`, `weights_public`, `api_listed`, `announced` or `benchmarked`.
labquery · string
A lab's slug (`/v1/labs`).
limitquery · int64
Rows to return, 1–200 (default 50).
model_idquery · uuid
One model's releases (a `/v1/catalog/models` id).
sincequery · date-time
Only releases Nozzle saw at or after this time.
sourcequery · string
A source, as `<method>:<subject>` (`provider_list:anthropic`, `hf_activity:nvidia`).
untilquery · date-time
Only releases Nozzle saw before this time.

Response · 200

dataReleaseEventRow[]required
confidencestringrequired
embargo_lifted_atstring · date-time
embargoedbooleanrequired
evidence_sha256string
evidence_urlstring
Where the source showed it; null only on rows recorded before evidence was kept.
idstring · uuidrequired
kindstringrequired
lag_secondsnumber · double
Seconds from the source's own time to Nozzle seeing it.
model_display_namestring
model_idstring · uuidrequired
model_namestringrequired
observed_atstring · date-timerequired
occurred_atstring · date-time
occurred_at_basisstring
organization_namestring
organization_slugstring
sourcestringrequired
next_cursorstring · uuid
Pass as `cursor` for the next page; null on the last.
curl -X GET https://api.opennozzle.com/v1/releases \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s

Prompt Cache

5 operations
put/v1/keys/{key_id}/prompt-cache

Set the prompt-cache policy of one key; it wins over the workspace's.

keys:writeIdempotency-Key

Parameters

key_idpath · stringrequired

Request body

breakpointsarray
modestringrequired
prompt_cache_keystring
prompt_cache_retentionstring
ttlstring

Response · 200

breakpointsarray
Spans `auto` marks: any of `tools`, `system`, `messages`.
modestringrequired
`caller` passes your own cache markers through; `auto` has Nozzle place them; `off` removes them.
prompt_cache_keystring
How `auto` keys OpenAI-wire caching: `none`, `per_tenant`, `per_key`.
prompt_cache_retentionstring
OpenAI cache lifetime under `auto`: `in_memory` or `24h`.
ttlstring
Lifetime of a cache write `auto` places: `5m` or `1h`.
updated_atstring · date-timerequired
curl -X PUT https://api.opennozzle.com/v1/keys/<key_id>/prompt-cache \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "breakpoints": null,
  "mode": "string",
  "prompt_cache_key": null,
  "prompt_cache_retention": null,
  "ttl": null
}'
delete/v1/keys/{key_id}/prompt-cache

Remove one key's prompt-cache policy so it inherits the workspace's again.

keys:writeIdempotency-Key

Parameters

key_idpath · stringrequired

Response · 204

Success. No response body.

curl -X DELETE https://api.opennozzle.com/v1/keys/<key_id>/prompt-cache \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s
get/v1/prompt-cache

Your workspace's prompt-cache policy, each key's, and the platform default they inherit from.

keys:read

Response · 200

keysKeyPromptCachePolicy[]required
breakpointsarray
Spans `auto` marks: any of `tools`, `system`, `messages`.
modestringrequired
`caller` passes your own cache markers through; `auto` has Nozzle place them; `off` removes them.
prompt_cache_keystring
How `auto` keys OpenAI-wire caching: `none`, `per_tenant`, `per_key`.
prompt_cache_retentionstring
OpenAI cache lifetime under `auto`: `in_memory` or `24h`.
ttlstring
Lifetime of a cache write `auto` places: `5m` or `1h`.
updated_atstring · date-timerequired
virtual_key_idstring · uuidrequired
platform_defaultPromptCachePolicyView | null
workspacePromptCachePolicyView | null
curl -X GET https://api.opennozzle.com/v1/prompt-cache \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
put/v1/prompt-cache

Set how Nozzle caches prompts for every key in your workspace. Re-sending the same body writes the same row.

keys:writeIdempotency-Key

Request body

breakpointsarray
modestringrequired
prompt_cache_keystring
prompt_cache_retentionstring
ttlstring

Response · 200

breakpointsarray
Spans `auto` marks: any of `tools`, `system`, `messages`.
modestringrequired
`caller` passes your own cache markers through; `auto` has Nozzle place them; `off` removes them.
prompt_cache_keystring
How `auto` keys OpenAI-wire caching: `none`, `per_tenant`, `per_key`.
prompt_cache_retentionstring
OpenAI cache lifetime under `auto`: `in_memory` or `24h`.
ttlstring
Lifetime of a cache write `auto` places: `5m` or `1h`.
updated_atstring · date-timerequired
curl -X PUT https://api.opennozzle.com/v1/prompt-cache \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "breakpoints": null,
  "mode": "string",
  "prompt_cache_key": null,
  "prompt_cache_retention": null,
  "ttl": null
}'
delete/v1/prompt-cache

Remove your workspace's prompt-cache policy so it inherits the platform default again.

keys:writeIdempotency-Key

Response · 204

Success. No response body.

curl -X DELETE https://api.opennozzle.com/v1/prompt-cache \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -s

Runs

2 operations
get/v1/usage/runs

Your recent runs (calls tagged X-Nozzle-Run-Id), most recently active first.

usage:read

Response · 200

dataRunListItem[]required
callsinteger · int64required
chargesinteger · int64required
cost_micro_centsinteger · int64required
cost_usdnumber · doublerequired
errorsinteger · int64required
first_atstring · date-time
input_tokensinteger · int64required
last_atstring · date-time
output_tokensinteger · int64required
run_idRunIdrequired
Your label for one experiment. Send it as the X-Nozzle-Run-Id header (or in a job or batch body); every call and charge it causes carries it, and GET /v1/usage/runs/{run_id} reads the run back.
total_tokensinteger · int64required
`input_tokens + output_tokens`.
limitinteger · int64required
sincestring · date-timerequired
curl -X GET https://api.opennozzle.com/v1/usage/runs \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/usage/runs/{run_id}

What one run did: calls, errors, tokens, cost and latency, by model and by route.

usage:read

Parameters

run_idpath · stringrequired

Response · 200

by_modelModelUsage[]required
Most expensive first.
callsinteger · int64required
chargesinteger · int64required
cost_micro_centsinteger · int64required
cost_usdnumber · doublerequired
errorsinteger · int64required
input_tokensinteger · int64required
latency_msLatencyMsrequired
Call latency over a run (or one slice of it), in milliseconds. Observed values (`percentile_disc`), not interpolations; all `None` when the slice has no logged calls.
maxinteger · int32
p50integer · int32
p90integer · int32
p95integer · int32
p99integer · int32
modelstring
The model as Nozzle resolved it; `None` for calls refused before a model was resolved and for charges not priced per model.
output_tokensinteger · int64required
total_tokensinteger · int64required
`input_tokens + output_tokens`.
by_routeRouteUsage[]required
Most expensive first.
callsinteger · int64required
chargesinteger · int64required
cost_micro_centsinteger · int64required
cost_usdnumber · doublerequired
errorsinteger · int64required
input_tokensinteger · int64required
latency_msLatencyMsrequired
Call latency over a run (or one slice of it), in milliseconds. Observed values (`percentile_disc`), not interpolations; all `None` when the slice has no logged calls.
maxinteger · int32
p50integer · int32
p90integer · int32
p95integer · int32
p99integer · int32
output_tokensinteger · int64required
routestringrequired
The route family: the call's kind (`inference.embed`, `inference.chat`, `inference.rerank`, …); batch lines bill as `inference.batch`.
total_tokensinteger · int64required
`input_tokens + output_tokens`.
cached_tokensinteger · int64required
Input tokens served from a provider cache (already inside `input_tokens`).
callsinteger · int64required
Logged inference calls.
chargesinteger · int64required
Ledger rows: every billed request, batch lines included.
cost_micro_centsinteger · int64required
Exact total in the ledger's unit (a millionth of a cent).
cost_usdnumber · doublerequired
The same total in dollars, for display.
errorsinteger · int64required
Calls that ended with a status of 400 or more.
first_atstring · date-time
input_tokensinteger · int64required
last_atstring · date-time
latency_msLatencyMsrequired
Call latency over a run (or one slice of it), in milliseconds. Observed values (`percentile_disc`), not interpolations; all `None` when the slice has no logged calls.
maxinteger · int32
p50integer · int32
p90integer · int32
p95integer · int32
p99integer · int32
output_tokensinteger · int64required
run_idRunIdrequired
Your label for one experiment. Send it as the X-Nozzle-Run-Id header (or in a job or batch body); every call and charge it causes carries it, and GET /v1/usage/runs/{run_id} reads the run back.
total_tokensinteger · int64required
`input_tokens + output_tokens`: the run's whole token count in one field.
curl -X GET https://api.opennozzle.com/v1/usage/runs/<run_id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s

Shared Instances

5 operations
get/v1/platform/shared-instances

List the platform tenant's shared Instances.

platform:instances:shared

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/platform/shared-instances \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/platform/shared-instances

Launch a shared Instance owned by the platform tenant (operator-granted scope).

platform:instances:sharedIdempotency-Keyemits instance.create_requested

Request body

object

Response · 201

object

curl -X POST https://api.opennozzle.com/v1/platform/shared-instances \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
get/v1/platform/shared-instances/{id}

Read one shared Instance.

platform:instances:shared

Parameters

idpath · stringrequired

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/platform/shared-instances/<id> \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
get/v1/platform/shared-instances/{id}/logs

Read a shared Instance's launch and lifecycle timeline.

platform:instances:shared

Parameters

idpath · stringrequired

Response · 200

object

curl -X GET https://api.opennozzle.com/v1/platform/shared-instances/<id>/logs \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/platform/shared-instances/{id}/stop

Stop a shared Instance.

platform:instances:sharedIdempotency-Key

Parameters

idpath · stringrequired

Request body

object

Response · 200

object

curl -X POST https://api.opennozzle.com/v1/platform/shared-instances/<id>/stop \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Storage

4 operations
post/v1/storage/downloads

Presigned GET URLs for objects in your storage.

storage:readIdempotency-Key

Request body

expires_in_secsinteger · uint64
urisstring[]required

Response · 200

downloadsDownload[]required
expires_atstring · date-timerequired
methodstringrequired
size_bytesinteger · uint64required
uristringrequired
urlstringrequired
curl -X POST https://api.opennozzle.com/v1/storage/downloads \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "expires_in_secs": null,
  "uris": [
    "string"
  ]
}'
get/v1/storage/objects

Objects under a `nozzle://` prefix, in key order, with sizes.

storage:read

Parameters

limitquery · uint
prefixquery · string
`nozzle://datasets/bids/` — everything under it.

Response · 200

has_morebooleanrequired
objectsListed[]required
etagstring
last_modifiedstring · date-timerequired
size_bytesinteger · uint64required
uristringrequired
curl -X GET https://api.opennozzle.com/v1/storage/objects \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -s
post/v1/storage/objects/delete

Delete objects from your storage. Deleting a missing object is not an error.

storage:writeIdempotency-Key

Request body

urisstring[]required

Response · 200

deletedinteger · uintrequired
curl -X POST https://api.opennozzle.com/v1/storage/objects/delete \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "uris": [
    "string"
  ]
}'
post/v1/storage/uploads

Presigned PUT URLs for paths in your storage (`nozzle://…`). PUT the bytes straight to each URL; one object per URL, up to 5 GiB.

storage:writeIdempotency-Key

Request body

expires_in_secsinteger · uint64
filesUploadFile[]required
uristringrequired
`nozzle://datasets/<name>/<version>/part-0.parquet`

Response · 200

uploadsPresign[]required
expires_atstring · date-timerequired
methodstringrequired
uristringrequired
urlstringrequired
curl -X POST https://api.opennozzle.com/v1/storage/uploads \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "expires_in_secs": null,
  "files": [
    {
      "uri": "string"
    }
  ]
}'

Variants

1 operation
post/v1/variants

Exactly k distinct variants of a prompt (reword, reframe, wild, or planned concepts) across one or more models, deduplicated, with per-variant model, cost and request id.

inference:call

Request body

attachmentsVariantAttachment[]
image_urlstring
An image, as an `https://` or `data:` URL. Needs a vision model.
rolestringrequired
What the material is for, in your words: `brand_voice`, `logo`, `reference`, `palette`… It is shown to the model next to the material.
textstring
Text material.
budget_centsnumber · double
Stop scheduling further calls (the top-up round) once this much is spent.
constraintsstring[]
Facts every variant must keep.
diversitystring
How the variants should spread: tones, framings, odd transforms.
json_schemaobject
JSON Schema of ONE variant, for structured variants. Default: a string (reword/reframe/wild) or `{title, subject, why}` (plan). Must suit the models' strict structured output (an object needs every property in `required` and `additionalProperties: false`).
kinteger · uint32required
How many distinct variants to return, 1–32.
modeVariantModerequired
How the variants differ from the prompt.
modelsarray
Models that write the variants. Omitted: the platform default for the mode (`models.composite_defaults`, `variants.rewrite` / `variants.plan`).
promptstringrequired
The prompt to vary.
reasoning_effortstring
Passed through as each call's `reasoning_effort`.
seedinteger · int64
Passed to the models that accept `seed`.
strategyVariantStrategy
How the `k` variants are dealt across `models`.
streamboolean
Stream one `variant` event per accepted variant.
system_promptstring
Replaces the mode's built-in instructions.

Response · 201

callsVariantCall[]required
askedinteger · uintrequired
Variants requested of this call.
callinteger · uintrequired
cost_micro_centsinteger · int64required
errorobject
modelstringrequired
request_idstringrequired
returnedinteger · uintrequired
Candidates it returned.
statusstringrequired
`ok` or `error`.
usageobject
completebooleanrequired
`true` when exactly `k` variants came back; `false` is a typed partial (`shortfall` and `dropped` say what is missing and why).
droppedDroppedVariant[]required
callinteger · uint
errorobject
reasonDropReasonrequired
Why a candidate or a call did not become a variant.
valueobject
kinteger · uint32required
modeVariantModerequired
How the variants differ from the prompt.
objectstringrequired
Always `variants`.
shortfallinteger · uint32required
total_cost_micro_centsinteger · int64required
variantsVariant[]required
callinteger · uintrequired
The call (index into `calls`) that wrote it.
cost_micro_centsinteger · int64required
Its share of that call's cost.
indexinteger · uintrequired
modelstringrequired
request_idstringrequired
valueobjectrequired
A string, or an object matching `json_schema`.
curl -X POST https://api.opennozzle.com/v1/variants \
  -H "Authorization: Bearer $NOZZLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "attachments": [],
  "budget_cents": null,
  "constraints": [],
  "diversity": null,
  "json_schema": null,
  "k": 0,
  "mode": "reword",
  "models": null,
  "prompt": "string",
  "reasoning_effort": null,
  "seed": null,
  "strategy": "round_robin",
  "stream": false,
  "system_prompt": null
}'