Decide API Reference

Overview

POST /decide is the synchronous Runtime API for bounded decision inference. It is a sibling of Chat: Chat creates conversational messages in a Thread, while Decide evaluates caller-supplied state against named questions and returns typed answers. Decide does not create a Thread or messages.

Every provider-bearing call is attributed to the addressed node/project, recorded as an invocation receipt, and available through GET /chit/{invocationId}. The response is synchronous, but the receipt is durable for operators and later readback.

Authentication and routing

Decide uses the normal Runtime API authentication and node policy boundary. Send a tenant or node-scoped Bearer API key unless the node's public Runtime policy explicitly allows anonymous inference.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

The alias, node-id path, and Runtime subdomain routes accept the same body and produce the same response shape. See API routes for addressing details.

Request

The request contains JSON-compatible state and one or more named questions. Questions are bounded and typed; the provider never chooses the question structure.

Question types

Complete request example

curl "https://my-node.interlocute.ai/decide" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": {
      "ticketAgeHours": 26,
      "customerTier": "pro",
      "recentFailures": 2
    },
    "questions": {
      "route": {
        "type": "choice",
        "instructions": "Choose the best owning team.",
        "criteria": {
          "support": "Account and usage help",
          "billing": "Invoices and payment issues",
          "engineering": "Product failures and defects"
        }
      },
      "needsEscalation": {
        "type": "boolean",
        "instructions": "Is an immediate human escalation warranted?"
      },
      "severity": {
        "type": "score",
        "instructions": "Estimate operational severity.",
        "criteria": ["informational", "minor", "major", "critical"]
      }
    },
    "options": {
      "model": "jev-latest",
      "includeProjectConstitution": true
    }
  }'

Response

A successful response contains the durable invocationId, resolved provider/model, typed answers keyed by question name, and normalized usage. The public response does not expose provider wire fields.

{
  "invocationId": "01JX4K7M2NDECIDE",
  "operation": "decide",
  "provider": "TYPESAFE",
  "model": "jev-latest",
  "answers": {
    "route": {
      "type": "choice",
      "choice": "engineering",
      "confidence": 0.82,
      "probabilities": {
        "support": 0.08,
        "billing": 0.10,
        "engineering": 0.82
      }
    },
    "needsEscalation": {
      "type": "boolean",
      "probability": 0.94
    },
    "severity": {
      "type": "score",
      "score": 2.64,
      "confidence": 0.73,
      "legend": {
        "0": "informational",
        "1": "minor",
        "2": "major",
        "3": "critical"
      },
      "probabilities": {
        "0": 0.03,
        "1": 0.18,
        "2": 0.66,
        "3": 0.13
      }
    }
  },
  "usage": {
    "inputTokens": 412,
    "outputTokens": 98,
    "totalTokens": 510
  }
}

Model selection, usage, and cost

Model selection is provider-neutral. The catalog exposes decision-capable model IDs and the Runtime resolves the provider behind the selected ID. There is no public provider/model pair and no implicit Chat model fallback.

TypeSafe/Jev usage is attributed to the node and project and priced from the maintained provider catalog. OpenThai reports provider usage when available; Interlocute does not invent a local GPU price when no provider price is published. Usage is returned in the response and receipt, while normalized cost is recorded through the existing usage ledger and remains available through node/project observability.

The initial request limits are intentionally bounded: up to 32 named questions, 255 choice options per question, 10 score criteria per question, 128-character question names, and a 64 KiB serialized request. Providers may advertise tighter limits.

Invocation receipt and Chit readback

On a provider-bearing request, Interlocute persists an invocation with operation: "decide" and source: "api-decide". Node/project attribution, initiator/channel metadata, provider/model settings, timing, status, usage, caller state, named questions, typed answers, and constitution inclusion are durable. Thread ID, input message ID, and output message ID remain null because Decide is not Chat.

Read the same receipt as JSON, plain text, or Markdown: GET /chit/{invocationId}?format=json|plain|markdown. Chit rendering is deterministic and performs no new model call.

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

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

Errors

Coming soon

Decide 0.1 intentionally does not add scheduled or asynchronous Decide, batch decision operations, recipes, or Chat-to-Decide composition. Those are separate product decisions and are not implied by this synchronous contract.

Next steps

• Chit API Reference — durable invocation and human-readable readback
• Chat API Reference — conversational messages and Threads
• API Overview — routes and error semantics