Chit API Reference

Overview

/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

All endpoints use GET and are relative to your node's base URL: https://YOUR-NODE-ALIAS.interlocute.ai.

Authentication

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

Content negotiation

/chit and all sub-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.

# 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"
}

Invocation polling — GET /chit/{invocationId}

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

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.

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.

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",
  "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

Error responses

What /chit is NOT

• Not a per-interaction receipt — it does not log individual requests or responses
• Not a tool-call log — it does not record which tools were called during a conversation
• Not a billing line item — token usage and cost are tracked elsewhere (in the usage and observability layer)
• Not a conversation transcript — threads and messages live in the /chat surface

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