interlocute.ai beta
+Node

Chit-Chat

Every Interlocute node exposes exactly two surfaces: /chit and /chat. That's it. One for discovery, one for conversation.

Why two endpoints?

Most AI platforms bury node capabilities behind dashboards, documentation portals, or proprietary SDKs. Interlocute takes a different approach: every node is self-describing and self-addressable through a single pair of HTTP endpoints.

  • GET /chit — tells you what the node is and what it can do (deterministic, inference-free)
  • POST /chat — lets you talk to it (interactive, model-driven)

This design is intentional. A human with curl can discover a node and start a conversation in two requests. An agent or orchestrator can do the same programmatically — no SDK, no API key exchange protocol, no out-of-band documentation required.

The contract is small enough to memorize, stable enough to build on, and open enough for interoperability across tools, platforms, and organizations.

What is /chit?

/chit is the deterministic, machine- and human-readable "node information sheet" exposed over HTTP for every addressable node.

It is for discovery, governance, and status, not conversation. It tells a caller:

  • What the node is (identity and capabilities)
  • What it can do (supported operations, tools, models)
  • What to expect operationally (status, pricing, invocation shape)
  • The current state of a deferred invocation — poll GET /chit/{invocationId} after submitting an async or scheduled chat request

All of this is generated from typed node facts, capability flags, and persisted operator configuration — without relying on model inference. The output is predictable, stable, and deterministic.

For the full endpoint list, content negotiation, verbosity levels, operator overrides, and response examples, see the Chit API Reference.

What is /chat?

/chat is the interactive conversation surface on every node. You POST a message, the node processes it (potentially retrieving memory, consulting a knowledge base, or invoking tools), and streams or returns a response. Each exchange flows through a thread — the unit of conversation state.

Chat is model-driven and non-deterministic: the same input may produce different outputs depending on conversation history, model temperature, and tool results.

For the full request/response schema, streaming protocol, thread lifecycle, and error codes, see the Chat API Reference.

Side by side

/chit (info sheet + receipt)
  • GET /chit/identity
  • name: "Support Assistant"
  • model: "gpt-4o"
  • capabilities: [memory, rag, tools]
  • GET /chit/01JX4K7M2N...
  • status: "completed" ← poll async job
  • Deterministic, inference-free
/chat (conversation)
  • POST /chat
  • → "What are my open orders?"
  • ← "You have 3 open orders: …"
  • Interactive, model-driven

When to use which

Use /chit when…

You want to discover what a node is, what it can do, and how it's configured — without invoking the model. Ideal for agent-to-agent discovery, governance tooling, and directory listings. Also use it to poll the status of an async or scheduled invocation via GET /chit/{invocationId}.

Use /chat when…

You want to have a conversation: ask questions, give instructions, get creative responses, or trigger tool-augmented actions.

Your job ID, the same Chit receipt

When submitting a direct Async chat, you can optionally supply externalInvocationId. Your worker can then poll /chit/by-external-id?externalInvocationId=your-job-id even if the submission acknowledgement was lost. Identical retries return the original invocation; changed request intent with the same ID is rejected. IDs are unique per node.

Use externalCorrelationId for a conversation and externalInvocationId for one submitted job. Both the caller-ID lookup and the original internal-ID route return the same receipt, including its recorded economics. Omit the new field to keep the ordinary submission path.

See request, retry, and polling examples.

Canceling an Async invocation

Submit direct Async work through /chat, then use its Chit receipt to follow or cancel that invocation. Send an authenticated POST /chit/{invocationId}/cancel, or cancel using your external invocation ID. Stopping polling does not cancel the work.

cancel_requested means the request is recorded; it does not mean the provider or billing stopped. Continue reading the same receipt. An unconfirmed outcome becomes unresolved, and a finalized late result can still appear under the original ID. See the cancellation reference or submit, cancel, and readback example.

Next steps

Auth & KeysMemory