Skip to main content

API Reference

The CaesuraO REST API lets you analyze conversations, manage saved conversations, and generate, evaluate, or shorten outreach messages.

The API base URL is https://api.caesurao.com. All endpoints below use the /api path prefix.

API sections​

  • Analyze: Submit a transcript and receive guidance for a named participant, including an AI agent.
  • Conversation: Create, retrieve, rename, or delete saved conversations. Pass a conversation's ID as sessionId when saving analyses.
  • Outreach: Generate tailored messages, evaluate existing copy, or shorten content to fit a character limit.

Each section includes an interactive reference with request parameters, response details, and examples generated from the OpenAPI specification.

Analyze and save conversations​

POST /api/analyze saves by default. First create a conversation with POST /api/conversation, then pass its returned id as sessionId. Set persist: false for analysis without saving. Supply chronological context on every request: sessionId does not load earlier dialogue, and each saved analysis records the last supplied transcript message.

Use speakerRole: "user" for both human and AI dialogue participants. Reserve assistant for previous CaesuraO analysis context. Set currentUser to the intended guidance recipient's speakerName. The SDKs perform this mapping for you; see Conversations & Persistence.

The current REST analysis response is an open-ended JSON object; fields depend on the configured call type. Plain-text model output appears in elaboration. Check isSame === true for duplicate guidance; new analyses may omit the flag.

Authentication​

API endpoints require a bearer token: either an OAuth/JWT token or a CaesuraO API key.

Authorization: Bearer caesura_xxxxxx

See the Authentication guide for details on creating and using an API key.