AI lookup cookbook

Use an application API key in Authorization: Bearer YOUR_API_KEY. Pass the central organisation UUID in X-AutoAppy-Workspace. Writes require a read/write key. Never embed a key in frontend source.

Conversation and result lookups

GET /api/orchestration/channels lists authorised channels. GET /api/orchestration/conversations?channel_id=CHANNEL returns conversations; use data[].external_id for a message event's stable conversation ID and data[].subject_ref for the stable person ID. data[].id is the internal conversation ID used by GET /api/orchestration/conversations/{conversation}. That detail response contains turns; choose turns[].id for GET /api/orchestration/turns/{turn}. Cursor lists expose next_cursor; pass it as cursor. Conversation detail uses before_sequence for older turns.

GET /api/orchestration/channels/{channel}/people/{subject}/memory reads person memory. Channel, person and turn access is tenant-scoped. Unknown IDs return 404; insufficient permission returns 403. No lookup changes memory.

Submit one new event

POST /api/orchestration/channels/{channel}/events:

{"contract_version":"1.0","conversation_id":"customer-42-chat","subject_id":"customer-42","event_id":"source-message-123","message":{"role":"user","text":"Hello","at":"2026-09-22T10:30:00Z"}}

conversation_id is stable across the chat; subject_id identifies the person across chats; event_id is unique per incoming event and reused only for an exact retry; message.at is the original ISO 8601 timestamp. New event IDs and timestamps should be mapped from the source, never chosen from historical dropdown entries. A 202 response means queued; map data.id to Get AI result and poll conservatively. Never resubmit to poll.

All five utilities

POST /api/ai-jobs creates a private job. Required body: job_type and input. The response data.id is a job ID; data.status starts as pending. GET /api/ai-jobs/{id} retrieves its status and result. Job IDs and conversation turn IDs are different. List your jobs with GET /api/ai-jobs?job_type=TYPE&per_page=20.

{"job_type":"call_transcript_url","input":{"call_url":"https://example.com/audio.mp3","output_mode":"original"}}

{"job_type":"meeting_transcript_url","input":{"video_url":"https://example.com/video.mp4","track_index":0,"output_mode":"english"}}

{"job_type":"web_process","input":{"start_url":"https://example.com","mode":"topic","topic":"contact information"}}

{"job_type":"text_extraction","input":{"long_text":"Raj: raj@example.com","fields":[{"name":"email","type":"string","description":"Email address"}]}}

{"job_type":"smart_selector","input":{"input":{"text":"Please send my invoice","options":["Sales","Support","Billing"],"prompt":"Choose the most relevant department"}}}

Audio/video URL, website start_url, extraction long_text/fields and selector input are required for their respective jobs. Output mode, track index, website topic (for mode topic), short extraction context and selector prompt are optional. Files must be fetchable; URL security checks still apply. Output modes are original/english, website modes all/topic. fields is an array of named typed extraction fields; options is an array of candidates. Completion may produce warnings or need review; read status before consuming result.content. A failed or cancelled job is not an empty successful result.

401/403: authentication or access; 404: job not owned by caller; 422: malformed job request; 409: incompatible lifecycle change; downstream failures appear in job status. Avoid automatically creating another job to retry an unknown outcome.

General errors and pagination

All example IDs are placeholders. Look them up using your own authorised connection. 401 requires renewed authentication; 403 requires checking application, read/write permissions and workspace; 404 means unavailable resource; 422 contains invalid-field details; 429 requires respecting Retry-After. Dropdowns display the current API page; Map Data accepts an exact identifier from a later page or previous action. Lists never broaden permissions to fill choices.