TuringArte

Public API reference

HTTP reference for the embed SDK, health probes, and public preset catalog. Authenticated dashboard APIs require a Clerk session.

Base URL

All paths are relative to your TuringArte deployment origin, e.g. https://app.turingarte.com or http://localhost:3000.

Authentication

Public embed endpoints use a publishable key (pk_live_… or test-prefixed keys when enabled). Pass it in one of:

  • Header x-publishable-key: pk_live_…
  • Header Authorization: Bearer pk_live_…
  • JSON body field key (chat/session) or query ?key= (config GET)

Browser calls also send Origin. Keys may restrict allowed origins. CORS preflight is supported via OPTIONS on public routes.

Not for LLM keys

Never send OpenAI/xAI secrets to these endpoints or to the browser. Provider keys stay on the server (Dashboard → API Keys).

Error shape

Typical error bodyjson
{
  "error": "Human readable message",
  "code": "unauthorized"
}

Common codes:

  • unauthorized — missing/invalid key
  • forbidden / forbidden_origin
  • validation — bad input
  • rate_limited — with Retry-After
  • feature_disabled — kill switch
  • not_found / inactive
  • db_unavailable / internal

Embed chat APIs

GET/api/public/config

Returns public employee branding for the widget (name, greeting). Requires employeeId and publishable key.

Examplebash
curl -s "$ORIGIN/api/public/config?employeeId=EMP_UUID&key=pk_live_xxx" \
  -H "Origin: https://yoursite.com"
200 responsejson
{
  "employeeId": "…",
  "name": "Support",
  "greeting": "Hi — how can I help?",
  "businessName": "Acme",
  "branding": {
    "primaryColor": "#7c3aed",
    "footer": "Powered by TuringArte"
  }
}
POST/api/public/chat/session

Create or resume an open embed conversation for a visitor. Body JSON:

Request bodyjson
{
  "employeeId": "EMP_UUID",
  "visitorId": "optional-stable-id",
  "conversationId": "optional-existing-id",
  "key": "pk_live_…"
}
200 responsejson
{
  "conversationId": "…",
  "visitorId": "…",
  "resumed": false
}
POST/api/public/chat

Send a user message and receive the agent reply. Employee must be active. Rate limited (~30 req/min per key+IP). Max message length 4000 characters.

Request bodyjson
{
  "employeeId": "EMP_UUID",
  "message": "What are your support hours?",
  "conversationId": "optional",
  "visitorId": "optional",
  "key": "pk_live_…"
}
curlbash
curl -s -X POST "$ORIGIN/api/public/chat" \
  -H "Content-Type: application/json" \
  -H "x-publishable-key: pk_live_xxx" \
  -H "Origin: https://yoursite.com" \
  -d '{
    "employeeId": "EMP_UUID",
    "message": "What are your support hours?"
  }'
200 responsejson
{
  "conversationId": "…",
  "reply": "We're available weekdays 9–5 ET…",
  "model": "gpt-4o-mini",
  "usedKnowledge": true,
  "tools": []
}

Rate limits

  • Chat: ~30 requests / minute / key prefix + IP
  • Session & config: similar sliding windows (see responses for 429)

Catalog & health

GET/api/presets

Public preset catalog (no secrets). Same data as the Create Employee UI / agent catalog docs.

Shapejson
{
  "presets": [
    {
      "id": "customer-support",
      "name": "Customer Support",
      "description": "…",
      "version": "1.0.0",
      "status": "ga",
      "defaultTools": ["email_alert", "…"],
      "defaultChannels": ["chat_embed", "…"],
      "suggestedKnoloTopics": ["…"],
      "createAsDraftOnly": false
    }
  ]
}
GET/api/health

Shallow health for uptime checks. Add ?deep=1 to probe database, encryption config, voice bridge, Sentry, and feature flags. Returns 503 when degraded.

Deep probebash
curl -s "$ORIGIN/api/health?deep=1" | jq

Human UI: /status

Dashboard (session) APIs

Routes under /api/employees, /api/knowledge, /api/me, etc. require a signed-in Clerk user with organization context. They power the dashboard UI and are not intended for third-party browser embeds. A dedicated server-to-server agent API is on the roadmap.

Webhooks (platform)

  • POST /api/webhooks/clerk — user/org sync
  • POST /api/webhooks/twilio/sms — inbound SMS
  • POST /api/webhooks/twilio/voice — voice entry
  • POST /api/webhooks/calcom — calendar events

These verify provider signatures and are for platform configuration — not general partner use.

Upcoming API surface

  • Server SDK / secret keys — create sessions and run chat from your backend without Clerk browser cookies
  • Streaming chat — SSE or chunked replies for the widget
  • Employee CRUD API — provision agents for multi-tenant SaaS partners
  • Webhook out — notify your systems on conversation events and tool results
  • OpenAPI document — machine-readable schema export

Static SDK assets

  • GET /sdk/v1/loader.js
  • GET /sdk/v1/widget.js

Integration guide: Embed SDK.