Tork Chat API

Chat API Reference

Complete reference for the Tork Chat REST API. Send messages, stream responses, ingest documents, and manage conversations.

Overview

Base URL

https://chat.tork.network

Authentication

X-Tork-Key header

Content-Type

application/json

bash

curl -X POST https://chat.tork.network/chat \
  -H "X-Tork-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello!", "tenant_id": "your-tenant", "session_id": "session-1"}'

Endpoints

POST/chat

Send a message and get an AI response. The message is routed through the multi-agent system and passes through the governance pipeline before returning.

Request Body

json

{
  "message": "What vehicles do you have?",
  "tenant_id": "valuecar",
  "session_id": "sess_abc123"
}

Response

json

{
  "response": "We have 12 vehicle groups including the VW Polo Vivo...",
  "conversation_id": "conv_7f3a2b1c",
  "governance": {
    "receipt_id": "rcpt_hmac_9x8y7z",
    "pii_detected": false
  }
}

POST/chat/stream

Stream a response via Server-Sent Events (SSE). Returns token-by-token delivery for real-time UI rendering.

Request Body

json

{
  "message": "What is your insurance policy?",
  "tenant_id": "valuecar",
  "session_id": "sess_abc123"
}

Response (SSE Stream)

text

event: typing
data: {"status": "processing"}

event: token
data: {"token": "We"}

event: token
data: {"token": " offer"}

event: governance
data: {"receipt_id": "rcpt_hmac_4a5b6c", "pii_detected": false}

event: done
data: {"conversation_id": "conv_7f3a2b1c"}

POST/ingest

Upload a document to the knowledge base. Supports PDF, DOCX, and TXT files. Documents are chunked and embedded for RAG retrieval.

Request

bash

curl -X POST https://chat.tork.network/ingest \
  -H "X-Tork-Key: your-api-key" \
  -F "file=@pricing-guide.pdf" \
  -F "tenant_id=valuecar"

Response

json

{
  "chunks": 47,
  "document_id": "doc_8k2m4n6p"
}

GET/admin/{slug}/conversations

List conversations for a tenant with pagination, search, and filtering.

Query Parameters

limitnumberResults per page (default 20, max 100)

offsetnumberPagination offset

searchstringSearch message content

date_fromISO 8601Filter by start date

date_toISO 8601Filter by end date

has_escalationbooleanFilter escalated conversations

Response

json

{
  "conversations": [
    {
      "conversation_id": "conv_7f3a2b1c",
      "session_id": "sess_abc123",
      "message_count": 12,
      "created_at": "2026-03-24T10:30:00Z",
      "last_message_at": "2026-03-24T10:45:00Z"
    }
  ],
  "total": 284
}

GET/admin/{slug}/analytics

Get conversation analytics and usage metrics for a tenant.

Response

json

{
  "conversations_today": 34,
  "messages_today": 187,
  "avg_messages_per_conversation": 5.5,
  "active_sessions_24h": 12,
  "top_intents": [
    { "intent": "fleet_query", "count": 89 },
    { "intent": "pricing", "count": 67 },
    { "intent": "booking", "count": 45 }
  ],
  "governance": {
    "total_governed": 1842,
    "pii_detected": 23,
    "escalations": 7
  }
}

GET/health

Health check endpoint. Returns service status, version, connectivity to Supabase, Redis, and Anthropic, plus uptime. No authentication required.

Response

json

{
  "status": "healthy",
  "version": "2.1.0",
  "agents": 7,
  "tests": 251,
  "uptime_seconds": 86421.3,
  "supabase": "connected",
  "redis": "connected",
  "anthropic": "configured"
}

GET/api/admin/usage/{tenant_id}

Get detailed usage statistics for a tenant by ID. Returns current billing period usage, plan limits, and remaining capacity.

Response

json

{
  "plan": "growth",
  "messages_used": 1247,
  "messages_limit": 5000,
  "documents_used": 12,
  "documents_limit": 50,
  "period": "2026-03",
  "days_remaining": 7,
  "usage_percentage": 24.9
}

Rate Limits

Free100 messages/month

Starter1,000 messages/month

Growth5,000 messages/month

Business25,000 messages/month

EnterpriseUnlimited