Skip to main content

Analyze a conversation

POST 
/api/analyze

Returns analysis for the participant identified by currentUser. Requires at least 10 available credits; actual usage depends on the analysis. Analysis fields vary by the configured call type.

Identify participants

  • currentUser: the name of the participant who should receive recommendations. Match their speakerName exactly. If omitted, the authenticated account name is used. This does not change the authenticated account or conversation owner.
  • speakerIndex: a stable, zero-based number for each participant. Use different indexes for different participants and keep them consistent across requests.
  • speakerName: the name used to label that participant in the transcript. Use the same name in currentUser to request recommendations for that participant.
  • speakerRole: use user for all conversation participants, including AI agents. Reserve assistant for previous CaesuraO analysis results supplied as context. It does not identify an AI participant in your conversation.

Human + AI agent example

Sales Agent is your AI agent (index 0) and opens the conversation. Alex is a human (index 1) who replies. Both use speakerRole: "user". Set currentUser: "Sales Agent" to request recommendations for the agent. Your application can pass the returned guidance to your agent.

Persistence and context

Set persist: false to analyze without creating a conversation. Otherwise, first call POST /api/conversation and send its id as sessionId; persistence defaults to true and requires a conversation owned by the authenticated account. The server saves the last message and the generated analysis, not every message in the request. Send messages in chronological order, ending with the latest transcript message. Include the context needed for each request: sessionId does not automatically load previous messages or analyses.

To save a complete transcript, append customer messages, agent replies, and greetings through POST /api/conversation/messages. Then supply the saved customer message ID as transcriptMessageId to attach analysis to that message. Its speakerIndex must match the final transcript entry; the original saved text and timestamp remain unchanged. The SDKs handle this flow automatically. Widget conversations cannot be analyzed through this endpoint.

Optionally include previous CaesuraO results in subsequent requests to help improve recommendations. Add them to messages with speakerRole: "assistant" and text: JSON.stringify(previousAnalysis), followed by new participant messages. Sending prior analyses back is not required. These entries represent CaesuraO recommendations, not words spoken by your agent. Their speaker index does not select the recommendation recipient; currentUser does.

isSame is optional. When isSame === true, there is no new recommendation to act on. New analyses may omit the flag; the API does not automatically return isSame: false. Check explicitly for true and otherwise process the returned analysis.

Request​

Responses​

Open-ended JSON object whose analysis fields depend on the configured call type. Parsed JSON fields are preserved; plain-text model output is returned in elaboration. The HTTP response itself is always an object. Example analysis fields are illustrative, not a fixed response shape. A new analysis can omit isSame or include false; clients must not require the flag to be present.

Response Headers
    X-Credit-Usage

    Credits consumed by this analysis, when requested and available. May contain a decimal value.