API Reference

Authentication

All API requests require an API key passed in the Authorization header. Generate keys from Project Settings → API keys. Keys use the cdt_ prefix.

curl -X POST /api/v1/conversations/user_123/interact \
  -H "Authorization: Bearer cdt_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"action": {"type": "text", "payload": "Hello!"}}'

Base URL

All endpoints are relative to your deployment's base URL:

Rate Limits

Conversation interact endpoints are rate-limited per user. Rate limit headers are included in every response:

APIs

Runtime mode

Conduet projects run in one of two runtime modes — agentic or conversation-flow. The mode is decided per project by the framework field. The conversation API surface (/interact, /state, KB, channels) is identical across modes — what differs is what arrives in the SSE trace stream and how the project is configured. See Runtime Modes for the comparison.

Agentic harness configuration

For projects with framework: "agentic", the harness reads its config from behaviourConfig.agentHarness on the project blob. Persist the project (POST /v1/projects/:id/persist) with this shape:

behaviourConfig: {
  agentHarness: {
    implementation?: 'default-v1' | 'checkhero-v1';
    allowedToolIds?: string[];        // project tools the harness may use
    allowedPlaybookIds?: string[];    // reachable via the handoff builtin
    maxHandoffs?: number;             // default 2
    snapshotKeys?: string[];          // override auto-derivation from variables[]
    uiBuiltins?: {                    // all default false (opt-in)
      showBadge?: boolean;
      showTip?: boolean;
      showSummary?: boolean;
      showActionSteps?: boolean;
      showContactCard?: boolean;
    };
    phases?: PhaseConfig[];           // see /docs/agentic-mode
    phaseStateVar?: string;           // default '_ch_conversation_phase'
  }
}

Schema is additive and back-compat — unknown fields pass through. Full reference: Agentic Mode.

Error Codes

The API returns standard HTTP status codes. Error responses include a JSON body:

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE"
}