Skip to main content
Everything in this reference is generated from the OpenAPI document, which is derived from the published wire contract rather than written alongside it.

​
The surface

All three require Authorization: Bearer np_live_…. There is no unauthenticated route.

​
Base URL

{host} is the durable custom domain issued with your key. Pin the URL version explicitly, exactly as you pin an operating point — there is no implicit “latest” and nothing is served unversioned.

​
Two rules for your client

These are the client’s side of the contract. A client that ignores them will break on a change this API considers non-breaking.
1

Ignore response fields you do not recognise

New optional fields ship within /v1. Strict validation that rejects unknown fields will fail on the next additive change — and one is already designed: the usage metering receipt.
2

Do not exhaustively match the gate outcome or its reason

The gate outcome is an open, extensible enum. Today gate.engaged is true for a select outcome and false for a stand down, with the trigger in gate.reason. A third outcome is planned and will arrive additively.

Versioning policy

What counts as breaking, and the commitment that a version keeps serving until it is formally deprecated.

​
Fields with no effect

Some fields are part of the published contract, are accepted, and have no effect on the response. They are listed here rather than left for you to discover from a behaviour that does not change.
If a record must not be dropped, do not send it to be selected. With required_record_ids inert, the reliable way to guarantee a record reaches your prompt is to keep it out of records[] and concatenate it yourself around rendered_context. That is the correct pattern for a system prompt, a schema the model must call against, or the current user turn.
These are behaviour, not contract changes: each field stays in the schema and starts working without a version bump when it is wired.

​
Reading the schemas

A few things are worth knowing before you read the field list:
  • x-future marks something designed and not serving. The usage schema and the 402 response are documented so the shapes are settled and so clients can reserve the cases — not because you can call them today.
  • tokens_before / tokens_after are engine-internal accounting, not the billing quantity, and cannot be recomputed from your payload. See How to recompute your own bill.
  • A 200 is not always an engagement. A stand-down and an engine-internal failure both return 200 with a usable body. See Errors.
  • No method-tuning knobs appear in the request. Thresholds, weightings and gate parameters are resolved server-side from budget.operating_point. That is a contract property, not an omission.