Skip to main content

​
Overview

Enterprise-ready reference for the conversation-intelligence platform that powers docs.illocution.ai. The FastAPI service exposes REST and Server-Sent Event (SSE) endpoints for uploading media, replaying recordings with realtime feedback, and streaming fully live sessions. This document is structured so it can be dropped directly into Mintlify.

🚀 Start Testing in 30 Seconds

Use our demo API key and sample files to test the API immediately - no sign-up required.
Need a production API key? Contact jam@lissus.com - we’re here to help you get started quickly.

​
Primary Customer Use Cases

  1. Sales / Success intelligence - highlight objections, low-confidence answers, and emotional swings in discovery calls.
  2. Behavioral interview review - surface commitment drops and fear spikes for hiring managers.
  3. Research panels & UX testing - quantify engagement levels and narrative arcs across respondents.

Quickstart Playbook

Follow step-by-step guides for batch upload, realtime replay, and live capture workflows.

Base URL

Deployment specific (e.g., https://api.illocution.ai)

Version

Surfaced via FastAPI.title/version headers and /metrics

Contact

jam@lissus.com - Get API keys, request quotas, and SLA adjustments

Open CORS

Open CORS enabled for web clients when authenticated

​
Product Snapshot

​
Access, Security, and Limits

Missing or invalid API keys will result in a 401 Unauthorized response with {"detail": "Invalid or missing API key"}.

Error Handling Guide

Learn about error codes, retry strategies, and troubleshooting common issues.

​
Workflow Deep Dive (Data Flow)

The platform offers three ingestion patterns. Each feeds the same downstream analytics stack but differs in how media is supplied and how results are streamed back.

​
Batch Upload (POST /analyze)

  1. Client sends a single multipart/form-data request with the media file.
  2. Backend processes the file and generates complete analysis results.
  3. Server returns the full JSON payload with all insights and artifacts.
  4. Recommended when latency is less critical than simplicity (e.g., overnight processing).

Batch Analyze Endpoint

Full endpoint documentation with request parameters, response examples, and error handling.

​
Realtime Replay (POST /analyze/stream)

  1. Client uploads the entire file and immediately receives an SSE stream.
  2. Analysis results are streamed in real-time as processing completes.
  3. Consumers receive incremental updates (status, transcripts, emotion, cognitive, transitions).
  4. Ideal for coaching portals that want “live” feedback from recorded calls without implementing chunk uploads.

Realtime Replay Endpoint

Complete endpoint reference with SSE setup and event handling.

SSE Events Reference

All Server-Sent Event types, schemas, and examples for streaming endpoints.

​
Live Capture Sessions (/analyze/live/*)

  1. Client requests a session, receiving chunk, events, and control endpoints.
  2. Audio or video chunks are uploaded sequentially and processed in real time.
  3. Analysis events (final_transcript, emotion, cognitive, transition, moment) are streamed as they become available.
  4. Clients call /control with finalize when the live source ends (or cancel if interrupted). Summary + segmentation follow automatically.
  5. Designed for browser microphones, SIP bridges, or any streaming producer.

Live Capture Endpoint

Complete guide to session management, chunk uploads, and real-time streaming.
Regardless of mode, the resulting timeline, summary, and artifacts share the same schema, so downstream analytics do not need to care how the conversation was ingested.

​
Processing Pipeline & Artifacts

Uploaded media undergoes comprehensive analysis to produce multimodal insights including transcripts, emotion detection, cognitive state analysis, prosody metrics, and conversation-level summaries. The platform generates structured outputs including:
  • Timeline - Per-utterance analysis with transcripts, emotions, cognitive signals, and prosody markers
  • Summary - High-level conversation insights and key takeaways
  • Segmentation - Conversation phases with transitions and narrative arcs
  • Moments - Detected key moments such as objections, CTAs, and topic shifts
  • Artifacts - Complete analysis results persisted for auditing or re-processing
Consumers typically ingest the HTTP/SSE response and optionally fetch artifacts for auditing.

Response Schemas

Detailed schemas for timeline entries, summaries, segmentation, and all response types.

​
Endpoint Overview

Each endpoint is documented with request tables, typical responses, and failure semantics. Click the links above for detailed documentation.

​
Supported Media Formats

  • Video: .mp4, .mov, .webm
  • Audio: .mp3, .wav, .m4a, .aac

​
Content Types

  • Upload endpoints: Expect multipart/form-data
  • SSE consumers: Must set Accept: text/event-stream
  • JSON endpoints: Use application/json

OpenAPI Specification

View the complete OpenAPI specification

​
Implementation Tips

  • Javascript SSE clients: use EventSource/EventSourcePolyfill; close the stream on done. See the SSE Events reference for complete event handling examples.
  • Timeout budget: allow at least media_length + 60s for replay requests; live sessions stay open until you finalize.
  • Artifacts: artifacts can be persisted to external storage (S3, GCS) if you need to retain outputs beyond the container lifecycle.
  • Response structure: review the Response Schemas documentation to understand all available fields and data types.