Engine Inference

The Engine is Telegraph's inference coordinator. You send it a question; it picks a miner, calls that miner, and returns the answer with routing and cost metadata. You never manage miner endpoints, API keys, or schemas yourself.

There are three ways to ask:

• Auto-routed, plain language. You describe what you want and the Engine classifies it and selects the best miner.
• Auto-routed, canonical. You name the intent and send typed params. The node validates them before anything is charged.
• Direct. You already know which miner you want, so you skip routing and call it by ID, with either the miner's native request or the same canonical intent + params.

All of them are paid per call, via x402 or from your escrow. All of them run fresh, on-demand inference, not reads from a cache.

The Engine is not the Daemon. The Engine answers your questions on demand. The Daemon is a separate background service that generates its own questions on a schedule and stores them for the dashboard, see Daemon Signal Feed. If you want a live answer to your own question, you want the Engine.

Engine base URL (testnet): https://devnode.telegraphprotocol.com/engine

A note on naming: parts of the Telegraph API still use subnet in field names (subnet_id, subnet_name on the Daemon and WebSocket signal feeds) and tool names (the tg_engine_*_subnet MCP tools). This is legacy naming from when every provider was a Bittensor subnet. Today any provider integrated via YAML is a miner. Read subnet as "miner" wherever you see it.

Auto-Routed Ask

Send a natural-language query and let the Engine choose the miner:

POST /engine/v1/ask
Content-Type: application/json

{
  "query": "What is the current weather in London?"
}

The endpoint is gated: your first request returns a 402 Payment Required challenge. Complete the payment and retry exactly as described in Paying with x402, or pay from escrow with scheme: "escrow".

Response (200):

{
  "miner_id": "41",
  "miner_name": "fx-frankfurter",
  "endpoint": "/latest",
  "result": { "rate": 0.8712, "base": "USD", "quote": "EUR" },
  "result_shape": "intent",
  "format_version": 1,
  "field_status": { "rate": "ok", "base": "ok", "quote": "ok" },
  "input": { "base": "USD", "quote": "EUR" },
  "input_schema_version": 2,
  "cost_usd": 0.01,
  "duration_ms": 412,
  "timestamp": "2026-10-26T19:24:42Z",
  "reasoning": "Query asks for a live FX rate.",
  "intent": "FX_NOW_EUR",
  "signal_hash": "0x7a44569d..."
}

Changed in V2. Before V2, result was always the miner's raw output and a separate parsed object held any extracted fields. parsed is gone; the same information is now result. If your code reads the miner's own JSON out of result, read the Intent's fields instead, or branch on result_shape == "raw".

Errors before payment

These are answered before any payment is taken, and nothing is charged:

The answer's shape

Different miners for the same Intent answer in different formats. So that your code reads one shape, a node that runs the response parser reads the miner's answer into the Intent's response format and returns it as result. Every field of the format is read from the answer and the keys are the same whichever miner answered.

A format is an ordered list of fields, each with a name, a description, a type (number, integer, string, enum, bool, date, datetime, list, object) and, where relevant, a unit, a plausible range, the allowed values of an enum, or the texts that mean true and false. Read an Intent's format from GET /engine/v1/intents/{intent} (response.fields).

How a field is read: the parser model copies the value, and code rejects anything not present word for word in the answer, converts units (an inverse FX quote is turned round), checks ranges, and maps enum and bool values.

A field marked processed is not copied but worked out for your request: a total over your window, a maximum, whether a reading crosses your threshold. The model must cite the values it used, and code checks that at least one is written in the answer itself.

{
  "result": { "rate": 0.8712, "base": "USD", "quote": "EUR" },
  "result_shape": "intent",
  "format_version": 1,
  "field_status": { "rate": "ok", "base": "ok", "quote": "ok" }
}

The keys are always all present, in the format's order.

When the node cannot produce the shape, result is the miner's raw output, result_shape is raw, and shape_error says why:

Shaping never changes the status code or what you pay: a raw fallback still returns 200 and still settles. What is stored and signed is always the miner's raw answer, and signal_hash covers it, so the shaped result is a convenience view of it.

Some miners declare an intent_mapping in their YAML. Then the node reads their answer through that mapping: each field is found at a declared path and numbers are computed in code (unit conversion, a maximum over a series, a formula) instead of by the model. The reply is the same shape either way.

Canonical ask: intent + params

Every Intent has one request schema: the params a request for it carries. It is the same whichever miner serves the Intent, and the same off-chain and on-chain. Read it first:

curl https://devnode.telegraphprotocol.com/engine/v1/intents/WEATHER_CHECK

{
  "intent_id": "WEATHER_CHECK",
  "class": "deterministic",
  "request": {
    "schema_version": 3,
    "params": [
      { "name": "location", "type": "string", "required": true, "description": "Place the reading is for" },
      { "name": "days", "type": "integer", "min": 1, "max": 7, "default": 1, "description": "How many days" }
    ]
  },
  "response": { "format_version": 3, "fields": [ { "name": "temp_c", "type": "number", "unit": "degrees Celsius" } ] },
  "onchain": { "ready": true }
}

Then send it:

curl -X POST https://devnode.telegraphprotocol.com/engine/v1/ask \
  -H "Content-Type: application/json" \
  -H "PAYMENT-SIGNATURE: <base64-payment-payload>" \
  -d '{"intent": "WEATHER_CHECK", "params": {"location": "Tokyo"}}'

What a param can say

Validation is deterministic. Coercion is only ever safe: "3" is read as the integer 3, "five" is a type error, 2.5 is never an integer, "true" and "false" are bools, "yes" is not. Params the schema does not have are refused (unknown), never silently dropped. Limits: the whole params object at most 16 KiB of JSON, a string at most 2000 characters, a list at most 100 items.

How the node completes your request

1. intent + params that cover every required param: validated in code. No model is called.
2. A free-form query only: the parser model reads exactly the schema's params out of the question. It never guesses; anything the question does not state is null, and a free-text value that is not in the question is discarded. Then the same validation runs.
3. params that are valid but incomplete, plus a query: your supplied values are validated first (a wrong type or range is refused before any model is called), then the model is asked once for the missing params with your values as known facts. Your values are kept.
4. A value in the query that differs from a supplied param is refused as a conflict, naming both values. The node never overrides what you sent silently.
5. context: keys that match the schema stand in for params but never override explicit params. The whole context is still merged into the miner request as before.
6. Defaults: only the schema's own defaults are applied. A required value is never invented.

Whether a free-form ask is enforced against the schema is set by the node operator (INPUT_SCHEMA_MAPPING: off, shadow or on). Explicit params are always validated.

When params are refused

The check runs before any miner is chosen, called or paid. Nothing is charged, no payment authorization is spent and nothing is recorded.

{
  "error": "invalid_params",
  "intent": "WEATHER_CHECK",
  "schema_version": 3,
  "problems": [
    {"param": "location", "code": "missing", "message": "location is required (string)"},
    {"param": "days", "code": "range", "message": "days: 9 is outside 1 to 7"},
    {"param": "colour", "code": "unknown", "message": "unknown param \"colour\"; this intent takes: location, days"},
    {"param": "date", "code": "conflict", "supplied": "2026-10-24", "stated": "2026-10-25",
     "message": "date: params say \"2026-10-24\" but the query says \"2026-10-25\""}
  ],
  "message": "location is required (string); days: 9 is outside 1 to 7; ..."
}

Direct Ask

When you already know which miner you want, call it by ID and skip routing. There are two request forms. Pick one; mixing them is refused with 400.

Native form: the miner's own request

You supply the miner's endpoint and payload yourself:

POST /engine/v1/ask/{minerId}
Content-Type: application/json

{
  "method": "POST",
  "endpoint": "/chat",
  "payload": {
    "messages": [{ "role": "user", "content": "Explain Bitcoin in one sentence." }]
  }
}

The reply is the miner's raw output. It carries result_shape: "raw" to say so, and has no reasoning or intent.

{
  "miner_id": "104",
  "miner_name": "litellm",
  "result": { "...miner's raw output..." },
  "result_shape": "raw",
  "cost_usd": 0.01,
  "duration_ms": 650,
  "timestamp": "2026-10-26T19:24:42Z",
  "signal_hash": "0x7a44569d..."
}

Canonical form: intent + params on one miner

Send the same typed request you would send to /ask, but to a miner you chose:

curl -X POST https://devnode.telegraphprotocol.com/engine/v1/ask/wx-openmeteo \
  -H "Content-Type: application/json" \
  -H "PAYMENT-SIGNATURE: <base64-payment-payload>" \
  -d '{"intent": "WEATHER_CHECK", "params": {"location": "Tokyo"}}'

The node maps your params onto that one miner's own API and calls it. There is no fallback. The reply has the same structure as the routed ask: result in the Intent's shape, result_shape, field_status, input, intent, endpoint (the one the mapping chose), signal_hash. Two miners with different native APIs answer the same Intent in the same structure.

Errors specific to this form, all before payment:

Replace {minerId} with a miner ID or slug from the discovery endpoint. Miner IDs are not stable across time, so always take them from discovery rather than from an example.

Rate limits are counted per miner across the whole node, so a warnings entry about a rate limit usually means switching to another miner for the same Intent works better than retrying the same one.

Pre-request validation

Before calling the miner, the node checks your request against the constraints that miner declared in its YAML: body and parameter sizes, value and count limits, and whether its call-rate allowance is already spent.

On the direct path this stops the request, because you named the miner and nothing else will be tried:

{
  "error": "request is predicted to fail",
  "warnings": ["miner \"zeus\" has reached its rate limit; try another miner for this intent, or try again later"],
  "proceed_anyway": {
    "field": "acknowledge_warnings",
    "value": true,
    "note": "resend with this field set to run the request regardless; you are charged only if it runs"
  }
}

That comes back as 422, and you are not charged. Your options:

1. Pick another miner for the same Intent (usually right for rate limits).
2. Fix the request, if the warning is about your payload.
3. Resend with "acknowledge_warnings": true to run it anyway.

On the auto-routed path nothing is ever blocked. A fallback is already lined up behind the primary miner, so warnings are attached to the response instead.

The payment gate runs first

Payment is checked before your request is validated, except for the input checks above. An unregistered miner ID or a malformed native body can still come back as 402 rather than 404 or 400. You are not charged for it, since payment settles only on success, but you cannot probe an endpoint's shape for free. Check your miner ID and endpoint against /api/miners before you build the request.

Listing Available Miners

GET /api/miners

Returns a JSON array of every registered miner: numeric id, slug, name, endpoints (path, method, and schema), supported_intents, activation_status, and min_price_usdc. Filter server-side instead of fetching the whole catalog: ?intent=, ?status=, and &limit= are supported. See Discover Available Miners for the full field reference.

Available Intents

See Intents for how prefixes and sub-intents work, how each is scored, and how to propose one. To read the live set:

curl https://devnode.telegraphprotocol.com/engine/v1/intents

Streaming over WebSocket

The same ask and ask_direct operations, including intent + params, are available over the Engine's WebSocket interface, which streams routing progress as events instead of returning a single response. See WebSocket Signals.

When to Use What