Chit API Reference

Overview

Chit also provides deterministic invocation readback for synchronous Decide calls and other Runtime invocations. A Decide receipt includes typed answers, usage, node/project attribution, and no Thread or message IDs; Chit never performs a new model call while rendering it.

/chit is the deterministic, machine- and human-readable "node information sheet" exposed over HTTP for every addressable node. It describes what the node is, what it can do, and what to expect operationally — all without relying on model inference.

For a conceptual comparison with /chat, see Chat & Chit.

Endpoints

Individual discovery and readback use GET. Selected receipt collections and invocation cancellation use POST. Routes are relative to your node's base URL: https://YOUR-NODE-ALIAS.interlocute.ai.

Find a receipt using your own invocation ID

A direct Async chat request can supply an externalInvocationId. Chit resolves that Node-scoped alias and returns the same receipt as the internal-ID route, including status, outputs, usage, execution settings, and recorded economics. Lookup makes no model call.

GET /chit/by-external-id?externalInvocationId=orders%3Ajob-123

# Explicit Node addressing
GET /nodes/{nodeId}/chit/by-external-id?externalInvocationId=orders%3Ajob-123

# Existing internal-ID route remains available
GET /nodes/{nodeId}/chit/{invocationId}

URL-encode the query value. The alias is echoed as externalInvocationId; invocationId remains Interlocute's canonical identity. Both routes support format=json|plain|markdown and the same Node authentication rules. An ID is not a credential; receipts on nodes allowing anonymous Chit are publicly readable.

• 200: receipt found; continue polling while terminal=false.
• 400: missing or invalid ID; accepted IDs are case-sensitive, 1–256 alphanumeric or -_.:/ characters.
• 404: no alias on this node, or Chit is unavailable.
• 410: the dispatched receipt was removed; the alias remains reserved.

Reading receipt money

"economics": {
  "currencyCode": "USD",
  "moneyScale": 6,
  "providerCostMicros": 700,
  "tenantChargeMicros": 900,
  "providerPricingMissing": false
}

Amounts are integers scaled by decimal places: divide by 10^moneyScale to obtain currency units. Here provider cost is USD 0.000700 and tenant charge is USD 0.000900. The currency code identifies the currency; the integers are not already dollars. These are the invocation's recorded economics, not a total of all work in its thread.

Cancel a direct Async invocation

Request cancellation using the original invocation ID or your Node-scoped external ID. Authenticate with a tenant API key or authorized JWT, including on nodes allowing anonymous Chit reads. Repeating the request preserves the original cancellation timestamp and all invocation identities. Send a POST with no request body; a successful response is the JSON invocation receipt. This route applies to options.responseMode: "Async" chat, including chat submitted with an external invocation ID.

# Cancel using Interlocute's invocation ID
curl -X POST "https://my-node.interlocute.ai/chit/01JX4K7M2N.../cancel" \
  -H "Authorization: Bearer $API_KEY"

# Cancel using your own ID (URL-encode the query value)
curl -X POST "https://my-node.interlocute.ai/chit/by-external-id/cancel?externalInvocationId=orders%3Ajob-123" \
  -H "Authorization: Bearer $API_KEY"

# Explicit Node addressing
POST /nodes/{nodeId}/chit/{invocationId}/cancel
POST /nodes/{nodeId}/chit/by-external-id/cancel?externalInvocationId=orders%3Ajob-123

• 200 / canceled: the provider confirmed cancellation. Read cancellationConfirmedAtUtc and cancellationDelivery: confirmed.
• 202 / cancel_requested: the provider acknowledged the cancel command and remains active. cancellationDelivery: provider_request_accepted and upstreamCancellationRequested: true establish delivery.
• 409 / cancellation_not_possible: completion, failure or incomplete execution already won. The response includes the actual receipt.
• 503 / cancellation_delivery_uncertain: delivery is unconfirmed. Retry cancellation or read the original Chit; never replay the paid invocation.
• 503 / provider_execution_not_ready: provider identity is not durable yet. Observe the original Chit.

{
  "invocationId": "01JX4K7M2N...",
  "providerExecutionId": "resp_example",
  "providerExecutionStatus": "cancelled",
  "status": "canceled",
  "terminal": true,
  "cancellationDelivery": "confirmed",
  "upstreamCancellationRequested": true,
  "providerCancellationAcknowledgedAtUtc": "2026-10-10T03:10:00Z",
  "cancellationConfirmedAtUtc": "2026-10-10T03:10:00Z"
}

Keep reading the original receipt while terminal=false. A completed result racing cancellation remains completed. Cancellation does not mean zero cost; recorded amounts are preserved and missing usage/economics remain unknown. A failed cancellation response never proves delivery. Retry the cancellation command with the same ID. Legacy receipts without provider identity remain readable, but this route cannot claim provider-native cancellation for them.

Authentication

Like /chat, the /chit endpoints support API key, JWT, and anonymous read access. Anonymous access must be explicitly enabled per node; cancellation always requires authentication. See Auth & Keys for details.

Content negotiation

Chit discovery resources support the Accept header for content negotiation. The same semantic content is returned in different representations:

• application/json — structured JSON (default)
• text/plain — human-readable plain text
• text/markdown — formatted Markdown

No HTML or XML output is supported. Invocation GETs use ?format= as described below; cancellation POSTs return JSON.

# JSON (default)
curl https://my-node.interlocute.ai/chit/identity

# Plain text
curl -H "Accept: text/plain" \
  https://my-node.interlocute.ai/chit/identity

# Markdown
curl -H "Accept: text/markdown" \
  https://my-node.interlocute.ai/chit/identity

Deterministic & inference-free

/chit output is generated entirely from typed node facts, capability flags, and persisted operator configuration. There is:

• No model inference or LLM creativity
• No reflection or dynamic property access
• Predictable, stable structure across identical configurations

This makes /chit safe for automated discovery, agent-to-agent negotiation, and governance tooling.

Verbosity

/chit supports a deterministic verbosity level: low, standard (default), or high. Higher verbosity includes more detail (descriptions, tool schemas, model parameters) without changing the fundamental structure.

Operator overrides

Each node has an optional configuration that controls each chit section:

• Enabled / disabled — a disabled sub-resource returns 404
• Mode: Standard — content is generated from node configuration (default)
• Mode: Custom — the operator provides an override body

Custom mode constraints:

• Exactly one override body per section
• Override must be text/plain or text/markdown
• The JSON representation wraps the custom text in a structured envelope

Example: /chit/identity (JSON)

{
  "nodeId": "nd_abc123",
  "name": "Support Assistant",
  "description": "Customer support node for Acme Corp",
  "model": "gpt-4o",
  "capabilities": {
    "memory": true,
    "rag": true,
    "toolUse": true,
    "streaming": true,
    "scheduling": false
  },
  "tools": ["lookup_order", "search_kb"],
  "verbosity": "standard"
}

Read selected receipts — POST /chits

Batch and Economy completion callbacks use this same receipt collection. You can keep reading Chit even when callback delivery is unavailable. See optional batch callbacks for registration, signature verification, paging and acknowledgement.

Send up to 100 internal invocation IDs belonging to one Node. They may span direct Async work, Economy and multiple provider batches. On the shared Runtime host use POST /nodes/{nodeId}/chits. This read requires authentication even when the Node allows anonymous disclosure.

curl -X POST https://YOUR-NODE-ALIAS.interlocute.ai/chits \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invocationIds": ["inv_async_1", "inv_economy_1", "missing_id"],
    "pageSize": 25,
    "offset": 0
  }'

The response is HTTP 200 with an entry for each returned ID. Each successful entry's invocation is the ordinary Chit receipt, including full outputs, execution settings, usage, batchId and any stored external invocation ID. A missing or wrong-Node ID returns per-item 404 / not_found without failing other items. Storage failures return per-item 503 / receipt_persistence_unresolved.

{
  "items": [
    {
      "invocationId": "inv_async_1",
      "statusCode": 200,
      "refreshStatus": "read",
      "invocation": {
        "invocationId": "inv_async_1",
        "status": "completed",
        "terminal": true,
        "outputs": [{ "kind": "assistantMessage", "content": "answer" }]
      }
    },
    {
      "invocationId": "inv_economy_1",
      "statusCode": 200,
      "refreshStatus": "requested",
      "invocation": {
        "invocationId": "inv_economy_1",
        "batchId": "economy_...",
        "status": "queued",
        "terminal": false,
        "outputs": []
      }
    },
    {
      "invocationId": "missing_id",
      "statusCode": 404,
      "errorCode": "not_found"
    }
  ],
  "nextOffset": null,
  "hasMore": false
}

Duplicate IDs are returned once, in first-occurrence order. pageSize defaults to 25 and accepts 1–100. Responses are limited to 1 MiB of JSON and may contain fewer items than requested. When hasMore is true, repeat the same ID list using nextOffset as the new offset. Offsets refer to the deduplicated list. Outputs are never truncated; an individual receipt too large for this collection gets per-item 413 / receipt_too_large and can be read through individual Chit.

Batch items sharing a parent request one parent refresh for that page. Refreshes run with bounded concurrency and a 30-second work budget. refreshStatus: "requested" means the batch owner handled the refresh request; leases or backoff may reuse saved progress. Direct receipts use "read". A parent retrieval failure or exhausted budget can return the saved receipt with "unavailable" or "deferred" and a separate refreshErrorCode. Retry that read; it does not mean execution failed. No inference is submitted and no periodic polling is started by this route.

This selector accepts internal invocation IDs. To recover a direct Async receipt by external ID, use the existing external-ID lookup; for Economy, replay the identical submission to recover its invocation ID. To retrieve a whole batch, use the existing Batch detail and paged results routes.

Invocation polling — GET /chit/{invocationId}

When you submit a chat request with responseMode: "async" or "scheduled" or "economy", the 202 response includes a pollUrl and an invocationId. Poll GET /chit/{invocationId} to check status and retrieve outputs.

Economy and batch-item retrieval is demand-driven: reading an authorized Chit requests progress and collects available results. Frequent requests may reuse saved status. If you never request the result, Interlocute does not periodically collect it; accepted provider processing and charges continue. There is no local age cutoff for uncollected results. Reads check upstream availability; a deleted provider job or result produces an explicit unavailable error. Collected results remain available locally. To recover a lost Economy acceptance, repeat the identical Chat POST with its externalInvocationId, then use the returned pollUrl. The external-ID lookup endpoint applies to direct Async.

A multi-item batch also creates one invocation per item, so each terminal item can be read here by invocation ID. Its receipt includes batchId; Economy receipts also echo externalInvocationId when supplied at acceptance. Use the Batch API to monitor the parent lifecycle and retrieve the full correlated result set.

This endpoint lives on /chit by design: polling an invocation is a discovery act — you are asking the node "what is the state of this commitment?" — not starting a new conversation.

Direct Async receipt states

GET returns HTTP 200 when the receipt is available, including when execution failed or its outcome is unknown. Read the top-level status and terminal fields; the GET response is not wrapped in an invocation object.

New Direct Async work is provider-managed and has no host expiry deadline or progress heartbeat. providerExecutionId identifies the accepted upstream execution; providerExecutionStatus reports its latest observed state. After Async acceptance, Interlocute does not monitor or collect the execution automatically. Read Chit when you want progress or results. Each active read retrieves only that requested execution and saves a terminal result into the original turn; the accepting request has already ended. Terminal receipts return the saved result without another provider read. Provider retention governs any result not yet collected; retrieval errors never turn into successful or zero-cost receipts. A cancellation acknowledged while still active is resolved by a later Chit read. Historical host-owned receipts can still report unresolved. See how to request cancellation.

Format parameter

The ?format= query parameter controls the response representation. Unlike the rest of /chit (which uses the Accept header), polling uses a query parameter because it is commonly called from simple URL-only contexts (webhooks, low-code tools, browsers).

Examples

# JSON receipt (default)
curl https://my-node.interlocute.ai/chit/01JX4K7M2N... \
  -H "Authorization: Bearer $API_KEY"

# Plain text: single sentence
curl "https://my-node.interlocute.ai/chit/01JX4K7M2N...?format=plain"

# Markdown table
curl "https://my-node.interlocute.ai/chit/01JX4K7M2N...?format=markdown"

Plain format examples (all deterministic, no LLM)

Invocation 01JX4K7M2N... is queued and waiting to be processed.

Invocation 01JX4K7M2N... is currently running.

Cancellation was requested for invocation 01JX4K7M2N.... Upstream termination and final billing are not confirmed.

Invocation 01JX4K7M2N... has an unknown upstream outcome: cancellation_unconfirmed. Do not automatically resubmit.

Invocation 01JX4K7M2N... is running — step 2 of 5 (analyze-competitors).

Invocation 01JX4K7M2N... completed successfully in 7200ms.

Invocation 01JX4K7M2N... failed: execution_error — Provider returned 429.

JSON receipt (completed)

{
  "invocationId": "01JX4K7M2N...",
  "status": "completed",
  "terminal": true,
  "source": "api-chat",
  "threadId": "thr_xyz789",
  "enqueuedAtUtc": "2025-07-15T10:00:00Z",
  "startedAtUtc": "2025-07-15T10:00:01Z",
  "completedAtUtc": "2025-07-15T10:00:08Z",
  "durationMs": 7200,
  "outputs": [
    { "kind": "userMessage",      "outputId": "msg_in_001",  "threadId": "thr_xyz789", "content": "What is our return policy?" },
    { "kind": "assistantMessage", "outputId": "msg_out_001", "threadId": "thr_xyz789", "content": "Our return policy allows..." }
  ]
}

JSON receipt (completed — inform with extraction)

When polling an /inform invocation, the outputs include the artifact pointer, the full comprehended content, and per-attachment extractionRecord outputs with extraction metadata.

{
  "invocationId": "01KKWQHPD3...",
  "status": "completed",
  "durationMs": 8500,
  "outputs": [
    {
      "kind": "artifact",
      "outputId": "artifact-001",
      "threadId": "art_thr_abc",
      "metadata": { "artifactType": "informed" }
    },
    {
      "kind": "assistantMessage",
      "outputId": "msg_out_002",
      "threadId": "art_thr_abc",
      "content": "## Summary\nThe Q1 report shows..."
    },
    {
      "kind": "extractionRecord",
      "outputId": "extraction-0",
      "metadata": {
        "fileName": "q1-report.pdf",
        "contentType": "application/pdf",
        "extractionKind": "Document",
        "profile": "TextAndLanguage",
        "extractedCharCount": "20678",
        "sizeBytes": "6286344",
        "durationMs": "3100"
      }
    }
  ]
}

Output kinds

For Async or Scheduled chat that requested web search, inspect the assistant output's responseMetadata.grounding. searchRequested, searchEnabled and searchPerformed distinguish intent, availability and reported use. Unavailable search continues as ordinary chat and includes searchUnavailableReason and a note; it does not make the receipt fail. Older outputs may omit the availability fields.

• searchPerformed: true: the provider reported search activity; inspect actions and citations for evidence.
• searchEnabled: false: search was skipped as unavailable; searchUnavailableReason explains why.
• searchEnabled: true with searchPerformed: false: the tool was offered but no search was reported. The note makes this explicit.

For GET /nodes/{nodeId}/chit/{invocationId}, read outputs[] where kind is assistantMessage, then responseMetadata.grounding. For POST /nodes/{nodeId}/chit with an invocationId, the same outputs are nested under invocation.outputs[]. Use JSON format for these structured fields.

Error responses

Discovery and invocation receipts

Discovery routes such as /chit/identity describe the node. /chit/{invocationId} reads one invocation's status, outputs and recorded economics; the cancellation route records intent against that same invocation. These receipts retain correlation to the conversation, while the usage ledger and dashboard provide billing and observability across invocations.

Forward-looking

As Interlocute evolves — particularly around long-running and deferred execution — /chit may expand to describe additional operational facets. The core design principle remains: deterministic, operator-controlled, inference-free.

Next steps

• Chat API Reference — full /chat endpoint reference
• Chat & Chit — conceptual overview of the two node surfaces
• API Examples — copy-paste starters in cURL, C#, and JavaScript

Decide invocation receipts

A successful POST /decide returns an invocation ID immediately. Read it with GET /chit/{invocationId}?format=json|plain|markdown. The JSON receipt uses operation: "decide" and source: "api-decide", and its typed decision output retains the question definitions, caller state, constitution inclusion, answers, and normalized usage. Thread, input-message, and output-message IDs are null by design.

Decision 01JX4K7M2NDECIDE completed in 118ms: route=engineering (82% confidence), needsEscalation=94% true (79% confidence), severity=2.64 (73% confidence).

| Question | Type | Result | Confidence |
|---|---|---|---|
| route | choice | engineering | 82% |
| needsEscalation | boolean | 94% true | 79% |
| severity | score | 2.64 | 73% |

Chit rendering is deterministic and human-readable. It is not inference and it is not the usage ledger; the receipt and ledger are the durable observability records for the invocation.