Skip to main content
Start to finish: create an account, mint a key, make one call, read what came back, and check the dashboard to see it land.

​
1. Create your account

Go to console.nextmoca.com. The page you land on is the sign-in screen, so if you have never been here before, follow its “New here? Create your workspace” link first. Sign up with Google, GitHub, or email. There is no waitlist and no approval step: you land in a workspace immediately. Which workspace, and whether it carries trial credit, depends on your email address. A personal address founds a new workspace of your own, with trial credit on it. A corporate address, once verified, joins the existing workspace for your domain if there already is one, and that workspace’s balance is shared across its members: only its first five members bring a welcome credit into it, so a later joiner starts with no grant of their own. If you land in a workspace with no credit, add credit from the dashboard’s Wallet page, or email hello@nextmoca.com.

​
2. Create an API key

From the dashboard, open Keys and create one. The full secret is shown exactly once, at creation; copy it before you navigate away. A key looks like:
Keys are org-scoped and grant the ability to spend your organisation’s allowance. Keep them server-side. Never put one in a browser bundle, a mobile app, or a URL, and never in request_id, which reaches our logs (why).
See Authentication for the full key format, rotation, and what a leaked key means.

​
3. Set your credentials

The calls below are raw HTTP, on purpose: they show you the contract, which is what you will be reading when something surprises you.If you would rather start with a client, pip install needlepath or npm install @nextmoca/needlepath-sdk (both 0.2.0, Apache-2.0) and skip to Integrations. Both fail open, and neither adds a runtime dependency.

​
4. Check you can reach the service

build_id names the engine build currently serving every operating point. It is not pinned by an operating point and it changes when we deploy, so record it alongside policy_version whenever you are keeping results to compare later: see what a label pins. The value above is what the endpoint returned when this page was last verified; expect yours to differ. A 401 here means no usable Authorization header reached us; a 403 means one did and it was refused. The difference is worth wiring separately; see Errors.

​
5. Make a selection

Send every record you are considering, the task they must serve, and the budget they have to fit inside. There are two request shapes. Start with the short one: it is a single paste and it exercises the whole path. The full records[] example follows, in three languages.

​
Start here: the smallest call that works

When you just have text, not pre-split records, send it as text instead of records. Needlepath splits it on blank lines and assigns each resulting record a content-hash id, so the same paragraph always comes back as the same id. This is the request on the homepage, reproduced here in full so this page stands alone. It is the same billing-dispute scenario as the fuller records[] example below.
Each blank-line-delimited paragraph becomes one record of kind external_data, with sha256:<16 hex characters> as its id: the hash of that record’s own text, so you can recompute it yourself. Eight paragraphs went in (the dispute, the refund policy, and six unrelated distractors: an office move, a marketing draft, a Slack migration, an OKR review, a status-page change, a conference-room policy) and two came back:
This is also a real illustration of gate versus outcome. The response above is real under np-2026-08-r4: fallback_used: false, outcome: "engaged", two records selected. Its gate.reason nonetheless reads standdown:source_support_missing, because gate is the envelope gate’s own shadow assessment and not the decision. Branch on outcome, never on gate.engaged.
task.prompt is still required, exactly as with records[]. So is budget.max_context_tokens: on this path there is no operating-point default to fall back to, since there is no explicit budget anywhere else in the request. budget.operating_point stays optional, though you should send it anyway; whichever one resolves is echoed back in policy_version, same as always. Metering runs over the records Needlepath derived from your text, exactly as if you had sent them yourself under records[], so the receipt in usage is recomputable the same way described in How to recompute your own bill.
text and records are mutually exclusive. Sending both is a 400 with error: "text_and_records_both_set"; pick one per request.

​
The canonical example, in three languages

This is the canonical example used throughout these docs and in the API playground: a support agent deciding a billing dispute from thirty candidate records, most of them plausible support-desk noise (other accounts’ tickets, unrelated policies, ops notes, marketing drafts). It is longer to paste, and it is the one whose response section 6 walks through field by field.
This is the exact request behind the API playground example named engages. If you would rather click than paste, try it there; your key prefills straight into the header.

​
6. Read the response

Thirty candidate records went in: ten of them part of Meridian’s own billing-dispute story (the invoice, the account, two refund-policy excerpts, a usage pull, a traffic pull, the customer’s message, the credit policy, the account’s own open ticket, and a prior agent turn), and twenty support-desk distractors (other accounts’ tickets, unrelated handbook policies, ops notes, marketing drafts). Five came back, led by the credit policy, for tokens_saved: 1461 out of tokens_before: 1775.
engine_latency_ms will not match yours. It is a per-call measurement and varies on every request. Everything else here (the selection, the token counts, reduction_ratio) is what this request returned on the engine build named in /v1/health when this page was last verified, and repeated calls on that build return it identically. A later build can move it without any operating point having changed; see what a label pins.That the credit-policy excerpt (r-009, score 32.66) is listed before the customer’s own message (r-008, score 54.11), despite scoring lower, is not a mistake in the example: selected[] order is not sorted by score. It is what this configuration returns on this input, and it is a fair illustration of why you spot-check selected[] against your own expectations rather than trusting an aggregate savings number or assuming list order tracks score.
Four fields carry most of the meaning:
tokens_before and tokens_after are the engine’s own accounting, useful for seeing how much a selection moved. They are not the billing quantity (that is the usage block), and cannot be recomputed from your payload alone. See How to recompute your own bill.

​
7. Fail open

This is the part to get right before you ship. Selection is an optimisation, so a failure must degrade to no optimisation, never to an empty prompt.
Do not retry a 403: none of its causes are transient. Do retry a 429 with exponential backoff and jitter, and a 5xx only if the request is unchanged. Errors has the full table.

​
8. Watch it land on the dashboard

Open console.nextmoca.com/needlepath/dashboard to see your calls, tokens saved, and remaining trial credit. Usage typically appears within about an hour of a call: billing reconciles hourly, so do not expect the dashboard to move the instant a response comes back.

​
Next

Records and tasks

What to put in each field, and what each one buys you.

Adaptive budget

Let the engine escalate its own budget instead of guessing one.

Limits

Rate, quota and the one exact ceiling.

Authentication

Key format, rotation, and what a leaked key means.