AI
Thread classification and the AI tier configuration.
Every endpoint needs Authorization: Bearer lk_live_.... See
Conventions for headers, status codes
and error shape.
Read the tenant’s AI configuration
GET /v1/ai-config · scope tenant:read
Mode (off/byok/units), model, masked key hint, AI-unit balance, whether the units tier is available on this deployment.
Response 200
AI config
| Field | Type | Notes |
|---|---|---|
mode |
string (False, byok, units) |
Required. |
model |
string | Required. |
byok_key_hint |
string | |
units_balance |
integer | |
units_available |
boolean | True when a platform model key is configured. |
Configure the AI tier
PUT /v1/ai-config · scope tenant:admin
Body: {“mode”: “off|byok|units”, “model”: “…”, “anthropic_key”: “sk-ant-…”}. BYOK keys are stored AES-256-GCM encrypted; the cleartext is never returned. Omit anthropic_key to keep the stored one.
Response 200
Applied
| Field | Type | Notes |
|---|---|---|
mode |
string (False, byok, units) |
Required. |
model |
string | Required. |
Buy prepaid AI units
POST /v1/billing/ai-units/checkout · scope tenant:admin
Body: {“bundle”: “300|1500|6000”}. One classification = one unit; bundles expire after 3 months. Admin session required. 503 until Paystack billing is configured; 409 while prepaid AI units are not available on this server.
Response 200
Paystack authorization URL for the selected AI unit bundle.
| Field | Type | Notes |
|---|---|---|
authorization_url |
string | Required. |
reference |
string | Required. |
units |
integer |
LLM-classify a thread
POST /v1/threads/{threadID}/classify · scope inboxes:read
Returns {intent, urgency, summary, suggested_action} via the tenant’s AI tier (BYOK or prepaid units, see /v1/ai-config). Cached per thread state: unchanged threads return the cache free; ?refresh=true forces a re-run. A failed model call charges nothing. 402 when the AI tier is off.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
threadID |
path | string | Required. |
refresh |
query | boolean |
Response 200
Classification
| Field | Type | Notes |
|---|---|---|
thread_id |
string | Required. |
cached |
boolean | True when a previous classification was reused. |
billed |
boolean | True when this call consumed an AI unit. |
classification |
Classification |
Errors: 402