> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nextmoca.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Three endpoints, one credential, and the two client rules that keep an integration working across additive changes.

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

| Endpoint                   | Does                                                           |
| -------------------------- | -------------------------------------------------------------- |
| `POST /v1/context/select`  | The one endpoint that does work: records in, selection out.    |
| `GET /v1/operating-points` | The public registry of immutable configuration labels.         |
| `GET /v1/health`           | Liveness, the default operating point, and the build identity. |

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

## Base URL

```
https://{host}/v1/…
```

`{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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Card title="Versioning policy" icon="code-branch" href="/versioning">
  What counts as breaking, and the commitment that a version keeps serving until
  it is formally deprecated.
</Card>

## 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.

| Field                                  | Today                                                                                                                                                               |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `render`                               | **No effect.** `rendered_context` is always built and returned, including when you send `render: false`. Ignore the field in the response if you do not want it.    |
| `budget.max_excerpt_tokens_per_record` | **No effect.** Per-record excerpt size comes from the operating point.                                                                                              |
| `task.required_record_ids`             | **Does not pin.** Do not rely on it to keep a record in.                                                                                                            |
| `task.parent_record_ids`               | **Does not pin**, for the same reason.                                                                                                                              |
| `task.recent_prompts`                  | **Not used for drift today**, although it *is* counted by the per-request ceiling. Sending a long history costs you allowance and buys nothing until this is wired. |
| `budget.require_evidence_coverage`     | **Adaptive mode only.** On the fixed-budget path no coverage verdict runs at all, which is also why `safety` is `null` there.                                       |

<Warning>
  **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.
</Warning>

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](/billing/recompute-your-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](/errors#the-two-cases-that-are-not-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.