> ## 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. # The public registry of immutable operating-point labels > Every label this deployment can resolve, and the frozen `policy_version` behind each. Only the label and its version cross the wire — the configuration a label resolves to (excerpt tiers, gate mode, floors) is not disclosed. That is the documented limit of the reproducibility promise: published results are **verifiable** and **re-runnable**, and they are **not inspectable**. A label naming a *configuration* does not pin an *engine build*. Serving a historical label from a later build reproduces that configuration, not the figures published from the build it was minted against. ## OpenAPI ````yaml /api-reference/openapi.yaml get /v1/operating-points openapi: 3.1.0 info: title: Needlepath Context Selection API version: 1.0.0 summary: Select which context records enter a model call, verbatim. description: | Needlepath decides **which of your records go into a prompt**. You send the records you hold — documents, tool results, prior turns — plus the task they have to serve and a token budget. Needlepath returns the subset worth sending, verbatim, with a rendered block you can paste straight into your prompt. Three properties shape everything else in this document: - **Nothing is stored.** Records ride in on every request. There is no session, no upload step, no retention. The service holds no database on the request path and its execution role grants log-writing and nothing else. See *Retention and trust*. - **The same request gets the same answer.** Behaviour is pinned by an opaque, immutable `operating_point` label. Retuning mints a *new* label; a published label never changes meaning. - **It can decline.** When trimming would not pay, the engine stands down and hands back a selection that is effectively your input. That is a designed outcome, not a failure — see `fallback_used` and `gate`. ### Versioning URL versions are **major-only**: `/v1`, `/v2`, …. A breaking change mints a new URL version; optional additions — a new response field, a new optional request field with a safe default, a new operating-point label — ship at the existing one. Nothing is served unversioned and there is no implicit "latest". A version keeps serving until it is **formally deprecated**, which requires a published notice naming the replacement and a sunset date, a written migration path, and a notice period that has elapsed before removal. ### Forward compatibility, required of clients Two rules, both from `INTERFACE.md`, and a client that ignores them will break on a change this contract considers non-breaking: 1. **Ignore response fields you do not recognise.** New optional fields ship within `/v1`. 2. **Do not exhaustively match `gate.reason` or the gate outcome.** The gate outcome is an open, extensible enum. Today it takes two values — a *select* outcome (`gate.engaged = true`) and a *stand_down* outcome (`gate.engaged = false`) — with the specific trigger in `reason` (`engage:needle`, `standdown:high_drift`, …). A third outcome, *escalate*, is a planned additive change. contact: name: Needlepath support url: https://nextmoca.com x-logo: altText: Needlepath servers: - url: https://api.nextmoca.com description: Needlepath hosted API. security: - bearerAuth: [] tags: - name: Selection description: The one endpoint that does work. - name: Registry description: Public, unchanging facts about the deployment. paths: /v1/operating-points: get: tags: - Registry summary: The public registry of immutable operating-point labels description: | Every label this deployment can resolve, and the frozen `policy_version` behind each. Only the label and its version cross the wire — the configuration a label resolves to (excerpt tiers, gate mode, floors) is not disclosed. That is the documented limit of the reproducibility promise: published results are **verifiable** and **re-runnable**, and they are **not inspectable**. A label naming a *configuration* does not pin an *engine build*. Serving a historical label from a later build reproduces that configuration, not the figures published from the build it was minted against. operationId: listOperatingPoints responses: '200': description: The registry. content: application/json: schema: $ref: '#/components/schemas/OperatingPointRegistry' example: default: np-2026-07-r2 operating_points: - label: np-2026-07-r1 policy_version: np-2026-07-r1 - label: np-2026-07-r2 policy_version: np-2026-07-r2 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' components: schemas: OperatingPointRegistry: type: object required: - default - operating_points properties: default: type: string description: >- The label applied when a request omits `budget.operating_point`. **It moves when a new label is minted** — which is why you should always send one. operating_points: type: array items: type: object required: - label - policy_version properties: label: type: string policy_version: type: string GatewayError: type: object description: | Generated by API Gateway, not by the service. The key is capitalised inconsistently between cases (`message` vs `Message`) because these are AWS's own bodies passed through unchanged — **match on the status code, not on this body.** properties: message: type: string Message: type: string responses: Unauthorized: description: | **No `Authorization` header at all.** Rejected at the gateway before anything of ours is invoked, so the body is the platform's, not ours. A header that is present but not `Bearer`-shaped is **not** a 401 — it reaches authorization and comes back `403`. Wire the two separately: **401 = the header never arrived** (fix the client), **403 = it arrived and was refused** (fix the credential). content: application/json: schema: $ref: '#/components/schemas/GatewayError' example: message: Unauthorized Forbidden: description: > A header arrived and authorization refused it. The reason is deliberately not returned — a caller learns only that the credential does not work, because an error that distinguishes "no such key" from "suspended org" is an oracle. Causes: an `Authorization` header that is present but not `Bearer`-shaped; an unknown, revoked or malformed key; a suspended org; a control-plane projection too stale to vouch for. Not retryable. Retrying a 403 will not resolve any of its causes. content: application/json: schema: $ref: '#/components/schemas/GatewayError' example: Message: >- User is not authorized to access this resource with an explicit deny securitySchemes: bearerAuth: type: http scheme: bearer description: | `Authorization: Bearer np_live_…` One credential form. There is no query-parameter, cookie or `x-api-key` alternative — the legacy `x-api-key` header stopped being accepted at the Bearer cutover and now fails authorization. Keys are **org-scoped**, never user-scoped, and the secret is shown exactly once at mint. Rotation is create-then-revoke. ````