How a call is handled

Worth reading once, because almost every question about what Navige did to a request is answered by knowing which of these steps it reached.

The path

your agent
     │
     ▼
  api.navige.ai
     │
     ├─ 1. identify       which agent, which organisation
     ├─ 2. correlate      which business job this belongs to
     ├─ 3. check          kill switch, budget, policy
     ├─ 4. act            route, cache, or pass through untouched
     │
     ▼
  the provider  (OpenAI, Anthropic, Google, xAI, Bedrock…)
     │
     ▼
     ├─ 5. price          tokens in, tokens out, cached, at that model's rate
     ├─ 6. record         the call, the cost, the job it belongs to
     │
     ▼
  your agent, with the provider's own response

1. Identify

The nv_ key names one agent inside one organisation. Everything after this point — which policies apply, which budget is drawn down, whose spend page the call appears on — follows from that.

Key lookups are cached for a minute. A revoked key stops working within that minute, not instantly; if you need it dead now, the kill switch is immediate.

2. Correlate

If the request carries x-navige-workflow, a W3C traceparent, or an x-navige-transaction, the call joins a transaction — one business job made of many calls. If it carries none of those, it is recorded on its own and the cost is reported per call.

3. Check

Three gates, in this order, and they are not the same gate:

1. Kill switch — on every tier, free included. If you have stopped an agent, it is stopped.
2. Spend cap — also on every tier. A hard ceiling is a safety control, not a feature.
3. Policy — on paid accounts this denies or holds a call. On Watchtower it is evaluated and recorded, and the call proceeds.

4. Act

On a paid account with levers on, this is where a call may be routed to a cheaper model that your own history says handles this job, or answered from cache. Each of those is a decision Navige records and can show you afterwards, with what it saved.

On Watchtower, nothing happens here. The request goes upstream exactly as your agent wrote it.

5. Price

The provider's own usage numbers are read off the response and priced at that model's rate. Cached and uncached input are counted separately, because providers do not agree on whether one includes the other — getting that wrong is how a bill comes out an order of magnitude adrift.

If Navige has no price for a model, the cost is recorded as unknown, not as zero. A zero you cannot tell from a real zero is a lie in a spreadsheet.

6. Record

Then your agent gets the provider's response, unmodified.

When Navige is the problem

If the gateway cannot reach its own policy context, counters or budget state, what happens depends on what the tool is. Reads and unclassified tools fail open — the call goes through, marked as a degraded decision rather than a normal allow. Writes, destructive actions and anything financial fail closed. Both halves are configurable.

The asymmetry is the point: a degraded Navige should not be why your support agents stop answering tickets, and should not be why an unreviewed payment went out.

• Failure behaviour has the detail, including which failures are which.