Skip to main content
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.

Make your first call

cURL, Python and TypeScript, in about two minutes.

​
What makes it different

Selection, not rewriting

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.

It declines

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.

Stateless by construction

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.

Pinned behaviour

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.

​
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.
1

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

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.

​
Where to go next

Quickstart

Your first call, in three languages.

Authentication

Bearer keys, format, rotation.

Limits

What each limit is, and how exact it actually is.

API reference

Every field, generated from the contract.