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: the selection configuration resolves 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

​
security_mode
enum<string>

Security screening of the context this request delivers. Per request, and available to any caller. Omitted, the request keeps the operating point's setting: enforce on np-2026-10-r7 and np-2026-10-r8, and off on every other listed operating point. Sent, it replaces that setting for this request only.

audit screens and reports in the receipt without changing what is delivered. quarantine removes flagged spans from the delivered context and marks each removal in place. enforce does the same and, when nothing deliverable remains, returns outcome: blocked with no context. See Errors for the two outcomes and How billing works for the charge.

Available options:
off,
audit,
quarantine,
enforce
Example:

"audit"

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. When security screening removed a span, the removed text is replaced in place by the marker [QUARANTINED: instruction-like candidate text removed]; on outcome: blocked this is a placeholder line with none of your content.

​
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 eligible full context exceeded the capacity it had to fit inside, so selected is empty and rendered_context is an empty string), stood_down (Needlepath stood down: no selection was returned, so send your full input), and two that appear only when security screening ran, because the request sent security_mode or ran on np-2026-10-r7 or np-2026-10-r8: sanitized_fallback (a full-context fallback delivered as rendered_context with flagged spans removed and marked in place; records_selected is 0 and fallback_used is false, so send rendered_context) and blocked (under enforce, nothing deliverable remained; no context is returned). See Errors.

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 returns no context. Treat it as "use the context you already had". It is not an error, and it is not a saving. blocked returns no context either; the published clients treat it as a decline and continue with the context you already had, and it is charged.

Examples:

"engaged"

"escalated"

"stood_down"

"sanitized_fallback"

"blocked"

​
fallback_used
boolean
required

true means send the context you submitted: the response returns it essentially intact. It does not tell you why: a stand-down (an empty selection with outcome: stood_down, or every record returned), 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 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 on some responses, and null on np-2026-07-r2's fixed-budget path. A null safety means the response carries no safety summary, never that the selection was sound.

​
gate
object | null

Informational. Not the result of the request; see outcome.

​
format_metrics
object

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

  • engine_fallback_reason: present only on a fallback response, 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.
  • security_mode, security_action, security_findings_count, security_source_kinds: present only when security screening ran, that is when the request sent a security_mode other than off, or ran on np-2026-10-r7 or np-2026-10-r8 without sending off. The mode that applied; what screening did (keep, audit, quarantine or block); how many spans were flagged; and the provenance kinds of the records it read. See Errors.
​
usage
object

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