API Overview
The Interlocute API is a means to invoke nodes. Start from goals, not endpoints.
Philosophy
The Interlocute API is not the product — it is the interface to the product. Start from what you want your node to do, then find the endpoint that does it. The API surface is intentionally small: most interactions use a single endpoint.
Node addressing
Every node is addressable by its alias. The base URL for any node is:
https://YOUR-NODE-ALIAS.interlocute.ai
Replace YOUR-NODE-ALIAS with the alias you chose when creating your node
(visible on the dashboard). All endpoints are relative to this base.
Routes
Every API endpoint supports three equivalent routing patterns. All accept the same request bodies and return the same responses. The docs use the alias (subdomain) form throughout — but all three work interchangeably.
| Pattern | Example | When to use |
|---|---|---|
| Alias (subdomain) | https://my-node.interlocute.ai/chat | Default. Shortest URL, human-readable. Used throughout these docs. |
| Path-based (node ID) | https://api.interlocute.ai/nodes/{nodeId}/chat | When you have the raw node GUID and don't know the alias. |
| Path-based (alias) | https://api.interlocute.ai/nodes/my-node/chat | When subdomain routing isn't available in your environment. |
Concept mapping
node alias
The stable subdomain for your node. Found on the dashboard. Forms the base URL: https://YOUR-NODE-ALIAS.interlocute.ai.
threadId
Identifies a conversation. Omit to start a new thread; include to continue an existing one. Returned in every response.
content
The user's message text. Required in /chat requests.
usage
Token accounting returned with every response: input tokens, output tokens, computation tokens.
Primary endpoints
/decideSubmit bounded state plus named questions and receive typed probabilistic answers. Decide is a sibling of Chat and creates no Thread or messages. See Decide API Reference.
/chatSend a message to the node. Supports buffered JSON and SSE streaming via Accept header. See Chat API Reference.
/chitDeterministic node information sheet for discovery and governance. See Chit API Reference.
/chit/identityNode identity and capabilities — primary v1 starting point for /chit. See Chit API Reference.
/informFeed knowledge into the node — text, documents, images. Async processing with polling. See Inform API Reference.
/chit/{invocationId}/cancelIdempotently request cancellation of direct Async chat, using its invocation ID or external ID. HTTP 202 records intent; continue reading the original receipt for the outcome. See invocation cancellation.
/nodes/{nodeId}/batchesSubmit independent chat turns as one provider-managed operation, then monitor lifecycle and page through correlated results. See Batch API Reference.
/media/audio/transcribeAudio-to-text transcription. Capability-gated — requires media.audio.transcribe. See Audio Transcribe API.
Error model
Error responses follow a consistent structure:
{
"error": {
"code": "quota_exceeded",
"message": "Token quota for this key has been reached.",
"status": 429
}
}401
Missing or invalid API key
403
Key lacks required scope
400
Malformed request body
422
Policy refusal — the node declined the request
429
Quota exceeded or rate limited
status: failed or unresolved.
A cancellation POST can return HTTP 202 with cancel_requested;
this confirms intent, not upstream termination or stopped billing. On a receipt/cancellation 503, retry the same
GET or cancellation request with backoff. Do not automatically resubmit paid work with an unknown outcome.
Next steps
- Batch API Reference — submit, monitor, cancel, and retrieve per-item results
- Chat API Reference — full /chat endpoint reference
- Inform API Reference — full /inform endpoint reference
- Chit API Reference — full /chit endpoint reference
- Audio Transcribe API — POST /media/audio/transcribe reference
- API Examples — copy-paste code in cURL, C#, and JavaScript
- Auth & Keys — credential setup