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

# Needlepath

> Select which context records enter a model call — selecting your own text rather than rewriting it, and stepping aside when trimming would not pay.

Needlepath decides **which of your records go into a prompt**.

You send the records you are holding — retrieved documents, tool results, prior
turns, workflow state — plus the task they have to serve and a token budget.
Needlepath returns the subset worth sending, **drawn from your own text**,
together with a rendered block you can drop straight into your prompt.

It is one stateless HTTP call. There is no index to build, no upload step, and
no session to keep alive.

```bash theme={null}
curl -sS https://api.nextmoca.com/v1/context/select \
  -H "Authorization: Bearer $NEEDLEPATH_API_KEY" \
  -H "content-type: application/json" \
  -d '{
        "request_id": "req-0001",
        "records": [{"id": "r-1", "kind": "tool_result", "text": "…"}],
        "task": {"prompt": "Can this invoice still be refunded?"},
        "budget": {"max_context_tokens": 4000, "operating_point": "np-2026-07-r2"}
      }'
```

<Card title="Make your first call" icon="play" href="/quickstart">
  cURL, Python and TypeScript, in about two minutes.
</Card>

## What makes it different

<CardGroup cols={2}>
  <Card title="Selection, not rewriting" icon="quote-left">
    Needlepath decides *which* of your records to send. It does not paraphrase or
    summarise them into new prose, and there is no model in the loop writing
    replacement text — every excerpt is built from the record's own content.

    It is **not** a byte-for-byte guarantee: under a tight excerpt budget an
    excerpt can be a whitespace-normalised, relevance-ordered set of lines from
    your record rather than one contiguous span. See
    [what comes back](/concepts/records-and-tasks#what-comes-back).
  </Card>

  <Card title="It declines" icon="hand">
    When trimming would not pay, Needlepath stands down and hands your context
    back essentially intact rather than cutting for the sake of cutting. A
    stand-down is a normal `200` — see [Reading a stand-down](/errors#reading-a-stand-down).
  </Card>

  <Card title="Stateless by construction" icon="shield">
    Records ride in on every request and nothing is persisted. The service holds
    no database on the request path, and its execution role grants log-writing and
    nothing else — so there is no permission with which your records *could* be
    stored. One field is the deliberate exception: `request_id` is logged, because
    it is your correlation key. See [Retention and trust](/retention-and-trust).
  </Card>

  <Card title="Pinned behaviour" icon="lock">
    An **operating point** is an opaque, immutable label naming a frozen
    configuration. Retuning mints a new label; a published label never changes
    meaning. Pin one and your results do not move under you.
    See [Operating points](/concepts/operating-points).
  </Card>
</CardGroup>

## When to reach for it

Needlepath is aimed at the case where a model call has **more candidate context
than budget**, and where the candidates are heterogeneous — a tool result, a
retrieved page, a schema, three turns of conversation — rather than a uniform
list of retrieved chunks.

It is a good fit when:

* an agent loop is accumulating tool results and the message list is growing
  faster than the useful signal in it;
* you are already retrieving more than you can afford to send;
* the content must survive intact, because it is a schema, a legal clause, a
  code fragment or a JSON payload that a summariser would break.

It is a poor fit when your prompt already fits comfortably in budget. Sending a
small request is not harmful — the engine will simply stand down — but you are
adding a network hop for nothing.

## The two rules for every integration

Both are load-bearing. Every first-party integration obeys them and yours
should too.

<Steps>
  <Step title="Fail open">
    If the call times out, returns non-2xx, or returns an empty selection, **send
    your original context unmodified**. Selection is an optimisation; a failed
    optimisation must degrade to "no optimisation", never to an empty prompt.
  </Step>

  <Step title="Pin the operating point">
    Always send `budget.operating_point`. Omitting it inherits the server's
    current default, and that default moves when a new label is minted — which is
    exactly how behaviour changes under a caller who never asked for it.
  </Step>
</Steps>

## Where to go next

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">Your first call, in three languages.</Card>
  <Card title="Authentication" icon="key" href="/authentication">Bearer keys, format, rotation.</Card>
  <Card title="Limits" icon="gauge" href="/limits">What each limit is, and how exact it actually is.</Card>
  <Card title="API reference" icon="code" href="/api-reference/introduction">Every field, generated from the contract.</Card>
</CardGroup>