Skip to main content
POST
cURL

Authorizations

​
Authorization
string
header
required

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.

Body

application/json

Either ContextRequest (typed records[]) or SimpleTextContextRequest (free-form text); never both. Maximum body size is 6 MB, the AWS Lambda synchronous payload cap. API Gateway rejects an oversized body before the service is invoked, so guard it client-side rather than relying on a readable error.

​
records
object[]
required

The records Needlepath may keep, drop or excerpt. An empty array is accepted and yields an empty selection. Record order breaks score ties, and record count is capped per request alongside the token ceiling. See Limits and Records and tasks.

Example:
​
task
object
required

The query the selected context has to serve.

Example:
​
budget
object
required

The operating point, in arm-neutral quantities only. No method-tuning knobs appear here or anywhere else in the request: thresholds, weightings, tier rules and gate parameters resolve server-side from the operating_point label.

Example:
​
request_id
string

Your correlation id, echoed back byte-for-byte. Optional: it is sent-side only, a caller correlation id we never require; absent is echoed back as "". When sent, keep it to ≤ 128 characters of [A-Za-z0-9._:-], and put no record content, customer text or credentials in it, because it reaches our logs. See Retention and trust.

Example:

"req-2026-09-03-0001"

​
render
boolean
default:true

Ask for rendered_context, a model-facing string assembled from the selection. render has no effect; rendered_context is always returned. Ignore it client-side if unwanted.

Example:

true

​
render_format
enum<string>
default:plain

plain leaves excerpts as text. hybrid additionally permits a structured excerpt to be re-encoded into a more compact form, and excerpt_format reports which form was used. Send plain if you re-parse excerpts as JSON.

Available options:
plain,
hybrid
Example:

"plain"

​
return_per_record
boolean
default:true

Include the selected[] per-record detail: score, reason, excerpt and token count. Set false for rendered_context plus the token arithmetic only, which is a materially smaller response body.

Example:

true

Response

A selection. Includes stand-downs and engine-internal failures, so read fallback_used and selection_error. This service returns 200 with a usable body rather than a 5xx when its own selection pass fails, because the correct client behaviour in that case is to send the original context, which the body already contains.

The selection.

Required by the contract (the published client raises if any is missing, or if request_id does not echo): request_id, rendered_context, tokens_before, tokens_after, tokens_saved, records_available, records_selected, fallback_used, outcome, engine_latency_ms.

Everything else is optional and new optional fields ship within /v1, so ignore what you do not recognise.

This object is open, and it already carries keys this schema does not list. Some are operating-point specific, so the exact set varies with the operating_point you send. A generated client must tolerate unknown keys rather than reject or drop the response: validate the required fields above and pass the rest through. If your generator defaults additionalProperties to false, it will produce a client that current responses already fail.

​
request_id
string
required

Your request_id, echoed byte-for-byte.

​
rendered_context
string
required

The model-facing block, assembled from the selection. Always returned.

​
tokens_before
integer
required

The engine's own accounting of the context available before filtering. It is not the billing quantity: the meter also counts record.title, task.prompt and task.recent_prompts, so usage.input_tokens is the larger number. Budget against this, do not reconcile an invoice with it. See How to recompute your own bill.

​
tokens_after
integer
required

Context size after selection, on the same engine-internal basis as tokens_before.

​
tokens_saved
integer
required

tokens_before - tokens_after. Zero on a stand-down, which is a correct outcome rather than a failed one.

​
records_available
integer
required

How many records the engine considered.

​
records_selected
integer
required

How many it selected.

​
outcome
string
required

How the engine resolved this request, at the top level so that you never have to read a nested object to find it.

An open enum. Do not exhaustively match it, and do not fail closed on a value you do not recognise: new outcomes ship additively within /v1. Current values are engaged (records were selected), escalated (the engine declined to select because the eligible full context exceeded the capacity it had to fit inside, so selected is empty and rendered_context is an empty string) and stood_down (the engine chose not to act).

This is not the same field as usage.outcome, and the two can legitimately disagree on a single response. This field reports what the engine did. usage.outcome reports how the request was priced, and it resolves selection failures first, so a response can carry outcome: "engaged" alongside usage.outcome: "fallback". Read this field to decide what to do with the response; read usage.outcome to explain a charge.

escalated is charged at the full rate and returns no context. Treat it as "use the context you already had". It is not an error, and it is not a saving.

Examples:

"engaged"

"escalated"

"stood_down"

​
fallback_used
boolean
required

The engine stood aside and returned your context essentially intact. It does not tell you why: a stand-down, an empty record set and an engine-internal exception all produce it. Read outcome first, then selection_error and format_metrics.engine_fallback_reason to tell the last two apart. Do not read gate for this: it is the envelope gate's shadow assessment and can disagree with outcome. See Errors.

​
engine_latency_ms
number<double>
required

Server-measured selection time, excluding network transit, so it is not your round trip. Example values in this document are illustrative and are not a performance commitment.

​
policy_version
string | null

The frozen version behind the operating_point that actually ran. Record it with every result: it is how you detect that you inherited a default you did not choose.

​
selected
object[]

Per-record detail, in selection order. Empty when you sent return_per_record: false and also empty on some stand-downs, so read records_selected rather than the array length.

​
records_expanded
integer

How many extra candidates budget.autochunk produced: the candidate count minus the number of records you sent. Present only on requests that set budget.autochunk, and absent -- not zero -- on every other request, so that its absence cannot be read as "autochunk ran and split nothing".

​
selection_error
string | null

Set when the engine's own selection pass raised. The HTTP status is still 200 and the body carries a usable full-context result. Alarm on this field, not on 5xx.

​
budget_tokens
integer

The budget the returned selection was produced under.

​
attempted_budget_tokens
integer[]

Every rung attempted on the adaptive ladder, in order. Empty on the fixed path. Watch it to see whether an adaptive workload is doing several selection passes per request.

​
reduction_ratio
number<double>

tokens_saved / tokens_before, on the engine-internal basis. Zero when tokens_before is zero.

​
safety
object | null

Present only when a coverage verdict ran, and null on the fixed-budget path. A null safety means no verdict was computed, never that the verdict was fine.

​
gate
object | null

Present when a gate decision was made.

​
format_metrics
object

Free-form, additive rendering and diagnostic telemetry. Treat unknown keys as informational. Keys you may see:

  • engine_fallback_reason: present only when the engine stood aside, carrying its own reason.
  • request_id_sanitized: true: your request_id broke the length or charset bound and the internal copy was truncated. Your echo is still your bytes.
  • client_latency_ms: added by the published client, not by the server.
​
usage
object

The metering receipt for this request. See How billing works.