API Reference

Conversations

Retrieve conversation history, transcripts, audio recordings, and per-conversation feedback.

Base URL: https://api.aethexai.com/api/v1
Endpoints: 8
Scopes: conversations:read

GET/conversations

Paginate through all conversations for your account.

List Conversations

Returns a paginated list of conversations ordered newest first. Each item includes status, turn count, total duration, and links to transcript and audio if available.

Path & Query

offsetintegeroptional
Number of conversations to skip (default: 0).
limitintegeroptional
Maximum number to return (default: 50, max: 100).

Errors

401Unauthorized

Missing or invalid API key.

Add X-API-Key: YOUR_KEY to your request headers.

403Forbidden

Your API key does not have the conversations:read scope.

Issue a new key with the conversations:read scope.

422Unprocessable Entity

offset or limit is not a valid integer or is out of range.

Use a non-negative integer for offset and a value between 1 and 100 for limit.

Response

json

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "call_id": "7c3a1d44-9e0b-4a2f-8c5e-2e6f1c8d4a90",
      "agent_id": "8b71f4d2-a21c-4f7e-b5d3-1a9f0c4d8e21",
      "status": "completed",
      "turn_count": 7,
      "total_duration_ms": 45200,
      "transcript_text": "Agent: Hi! How can I help?\nUser: I need to check my order...",
      "recording_url": "https://api.aethexai.com/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/audio.wav",
      "has_recording": true,
      "has_transcript": true,
      "created_at": "2025-01-15T14:30:00Z"
    },
    {
      "id": "9c2b1a55-6d8e-4f3c-a1b2-5e7d8f0a2b3c",
      "call_id": null,
      "agent_id": "8b71f4d2-a21c-4f7e-b5d3-1a9f0c4d8e21",
      "status": "active",
      "turn_count": 2,
      "total_duration_ms": null,
      "transcript_text": null,
      "recording_url": null,
      "has_recording": false,
      "has_transcript": false,
      "created_at": "2025-01-15T14:31:12Z"
    }
  ],
  "total": 2,
  "offset": 0,
  "limit": 50
}

GET/conversations/search

Full-text search across conversation transcripts.

Search Conversations

Performs a full-text search over all transcript turns for your account. Returns matching turn excerpts with their parent conversation IDs.

Path & Query

qstringrequired
Search query string.
limitintegeroptional
Maximum number of results to return (default: 20).

Errors

401Unauthorized

Missing or invalid API key.

Add X-API-Key: YOUR_KEY to your request headers.

403Forbidden

Your API key does not have the conversations:read scope.

Issue a new key with the conversations:read scope.

422Unprocessable Entity

q is missing or empty.

Provide a non-empty q query parameter.

Response

json

{
  "query": "order status",
  "results": [
    {
      "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
      "turn_id": "f1e2d3c4-b5a6-4978-8d6e-1c2b3a4f5e6d",
      "text": "I need to check the status of my order.",
      "role": "user",
      "turn_index": 1,
      "created_at": "2025-01-15T14:30:04Z"
    },
    {
      "conversation_id": "9c2b1a55-6d8e-4f3c-a1b2-5e7d8f0a2b3c",
      "turn_id": "a7b8c9d0-e1f2-4304-95a6-b7c8d9e0f1a2",
      "text": "Sure, your order status is shipped.",
      "role": "assistant",
      "turn_index": 4,
      "created_at": "2025-01-14T09:12:33Z"
    }
  ],
  "total": 2
}

GET/conversations/:conversation_id

Fetch a single conversation record by ID.

Get Conversation

Returns the full conversation record including status, turn count, total duration, and whether a transcript and recording are available.

Path & Query

conversation_idstring (uuid)required
UUID of the conversation.

Errors

401Unauthorized

Missing or invalid API key.

Add X-API-Key: YOUR_KEY to your request headers.

403Forbidden

Your API key does not have the conversations:read scope.

Issue a new key with the conversations:read scope.

404Not Found

No conversation with this ID exists.

Confirm the UUID from GET /conversations.

422Unprocessable Entity

conversation_id is not a valid UUID.

Pass a valid UUID from GET /conversations.

Response

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "call_id": "7c3a1d44-9e0b-4a2f-8c5e-2e6f1c8d4a90",
  "agent_id": "8b71f4d2-a21c-4f7e-b5d3-1a9f0c4d8e21",
  "status": "completed",
  "turn_count": 7,
  "total_duration_ms": 45200,
  "transcript_text": "Agent: Hi! How can I help?\nUser: I need to check my order...",
  "recording_url": "https://api.aethexai.com/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/audio.wav",
  "has_recording": true,
  "has_transcript": true,
  "created_at": "2025-01-15T14:30:00Z"
}

GET/conversations/:conversation_id/transcript

Retrieve the full turn-by-turn transcript for a conversation.

Get Transcript

Returns an ordered array of turns with speaker role (user, assistant, or human_agent for the person a conference transfer reached), text, latency metrics, and any tool calls made by the agent. Caller turns also carry text_raw, the speech recogniser's own output, when post-call correction changed the text. Agent turns the caller cut short carry interrupted_after_ms, how long the agent spoke before being interrupted, and estimated_text_spoken, the part of the sentence that fits in that time. All three are null otherwise. Every turn also carries start_ms, the offset in milliseconds from the first sample of the call recording to the moment that turn became audible. Hand it to a player alongside the audio from GET /conversations/{id}/audio and the turn's own words start there. It is published per turn: an individual turn reports null when its onset was not measured (a reply that never played, a caller turn with no detected onset, or a keypad entry) while the turns around it keep theirs, and every caller turn reports null when part of the caller's audio never reached us, while the agent's turns keep theirs. null on every turn of a call means one of three things: the offsets contradicted each other or the recording, the call's media reconnected mid-way, or the call predates this field.

Path & Query

conversation_idstring (uuid)required
UUID of the conversation.

Errors

401Unauthorized

Missing or invalid API key.

Add X-API-Key: YOUR_KEY to your request headers.

403Forbidden

Your API key does not have the conversations:read scope.

Issue a new key with the conversations:read scope.

404Not Found

No conversation with this ID exists.

Confirm the UUID from GET /conversations.

422Unprocessable Entity

conversation_id is not a valid UUID.

Pass a valid UUID from GET /conversations.

Response

json

[
  {
    "id": "f1e2d3c4-b5a6-4978-8d6e-1c2b3a4f5e6d",
    "turn_index": 0,
    "role": "assistant",
    "text": "Hi! How can I help you today?",
    "text_raw": null,
    "estimated_text_spoken": null,
    "interrupted_after_ms": null,
    "stt_latency_ms": null,
    "llm_latency_ms": 120,
    "tts_latency_ms": 85,
    "total_latency_ms": 205,
    "start_ms": 1000,
    "tool_calls": null,
    "confidence": null,
    "created_at": "2025-01-15T14:30:01Z"
  },
  {
    "id": "a7b8c9d0-e1f2-4304-95a6-b7c8d9e0f1a2",
    "turn_index": 1,
    "role": "user",
    "text": "I need to check the status of my order.",
    "text_raw": "i need to check the status of my oder",
    "estimated_text_spoken": null,
    "interrupted_after_ms": null,
    "stt_latency_ms": 95,
    "llm_latency_ms": null,
    "tts_latency_ms": null,
    "total_latency_ms": null,
    "start_ms": 4000,
    "tool_calls": null,
    "confidence": null,
    "created_at": "2025-01-15T14:30:04Z"
  },
  {
    "id": "e1d2c3b4-a5f6-4708-91a2-b3c4d5e6f708",
    "turn_index": 2,
    "role": "assistant",
    "text": "Sure, your order shipped yesterday and should arrive Friday.",
    "text_raw": null,
    "estimated_text_spoken": "Sure, your order shipped",
    "interrupted_after_ms": 1400,
    "stt_latency_ms": null,
    "llm_latency_ms": 340,
    "tts_latency_ms": 92,
    "total_latency_ms": 432,
    "start_ms": 6000,
    "tool_calls": [
      {
        "name": "lookup_order",
        "arguments": { "customer_id": "cust_123" },
        "result": { "tracking": "1Z999AA1", "eta": "2025-01-17" }
      }
    ],
    "confidence": null,
    "created_at": "2025-01-15T14:30:06Z"
  },
  {
    "id": "b2c3d4e5-f6a7-4819-92b3-c4d5e6f7a809",
    "turn_index": 3,
    "role": "user",
    "text": "Great. Can you also confirm the delivery address?",
    "stt_latency_ms": 88,
    "llm_latency_ms": null,
    "tts_latency_ms": null,
    "total_latency_ms": null,
    "start_ms": 11000,
    "tool_calls": null,
    "confidence": null,
    "created_at": "2025-01-15T14:30:11Z"
  },
  {
    "id": "c3d4e5f6-a7b8-4920-a3c4-d5e6f7a8b910",
    "turn_index": 4,
    "role": "assistant",
    "text": "It's being delivered to 221B Baker Street, London.",
    "stt_latency_ms": null,
    "llm_latency_ms": 210,
    "tts_latency_ms": 88,
    "total_latency_ms": 298,
    "start_ms": 13000,
    "tool_calls": null,
    "confidence": null,
    "created_at": "2025-01-15T14:30:13Z"
  },
  {
    "id": "d4e5f6a7-b8c9-4031-b4d5-e6f7a8b9ca21",
    "turn_index": 5,
    "role": "user",
    "text": "Perfect. And what's the tracking link?",
    "stt_latency_ms": 91,
    "llm_latency_ms": null,
    "tts_latency_ms": null,
    "total_latency_ms": null,
    "start_ms": 18000,
    "tool_calls": null,
    "confidence": null,
    "created_at": "2025-01-15T14:30:18Z"
  },
  {
    "id": "e5f6a7b8-c9d0-4142-c5e6-f7a8b9cadb32",
    "turn_index": 6,
    "role": "assistant",
    "text": "Your tracking number is 1Z999AA1; you can follow it on the carrier portal.",
    "stt_latency_ms": null,
    "llm_latency_ms": 295,
    "tts_latency_ms": 96,
    "total_latency_ms": 391,
    "start_ms": 21000,
    "tool_calls": null,
    "confidence": null,
    "created_at": "2025-01-15T14:30:21Z"
  },
  {
    "id": "f6a7b8c9-d0e1-4253-d6f7-a8b9cadbec43",
    "turn_index": 7,
    "role": "user",
    "text": "Can you email it to me as well?",
    "stt_latency_ms": 84,
    "llm_latency_ms": null,
    "tts_latency_ms": null,
    "total_latency_ms": null,
    "start_ms": 26000,
    "tool_calls": null,
    "confidence": null,
    "created_at": "2025-01-15T14:30:26Z"
  },
  {
    "id": "a7b8c9d0-e1f2-4364-e7a8-b9cadbecfd54",
    "turn_index": 8,
    "role": "assistant",
    "text": "Done. I've sent the tracking details to the email on file.",
    "stt_latency_ms": null,
    "llm_latency_ms": 260,
    "tts_latency_ms": 90,
    "total_latency_ms": 350,
    "start_ms": 29000,
    "tool_calls": [
      {
        "name": "send_email",
        "arguments": { "template": "order_tracking", "order_id": "ord_456" },
        "result": { "message_id": "msg_8910" }
      }
    ],
    "confidence": null,
    "created_at": "2025-01-15T14:30:29Z"
  },
  {
    "id": "b8c9d0e1-f2a3-4475-f8b9-cadbecfdae65",
    "turn_index": 9,
    "role": "user",
    "text": "Thanks, that's all I needed.",
    "stt_latency_ms": 79,
    "llm_latency_ms": null,
    "tts_latency_ms": null,
    "total_latency_ms": null,
    "start_ms": 36000,
    "tool_calls": null,
    "confidence": null,
    "created_at": "2025-01-15T14:30:36Z"
  },
  {
    "id": "c9d0e1f2-a3b4-4586-a9ca-dbecfdaebf76",
    "turn_index": 10,
    "role": "assistant",
    "text": "Happy to help. Have a great day!",
    "stt_latency_ms": null,
    "llm_latency_ms": 140,
    "tts_latency_ms": 78,
    "total_latency_ms": 218,
    "start_ms": 38000,
    "tool_calls": null,
    "confidence": null,
    "created_at": "2025-01-15T14:30:38Z"
  },
  {
    "id": "d0e1f2a3-b4c5-4697-bacb-ecfdaebfca87",
    "turn_index": 11,
    "role": "user",
    "text": "You too, bye.",
    "stt_latency_ms": 73,
    "llm_latency_ms": null,
    "tts_latency_ms": null,
    "total_latency_ms": null,
    "start_ms": 41000,
    "tool_calls": null,
    "confidence": null,
    "created_at": "2025-01-15T14:30:41Z"
  },
  {
    "id": "e1f2a3b4-c5d6-47a8-cbdc-fdaebfcadb98",
    "turn_index": 12,
    "role": "assistant",
    "text": "Thanks for calling. Goodbye!",
    "stt_latency_ms": null,
    "llm_latency_ms": 118,
    "tts_latency_ms": null,
    "total_latency_ms": null,
    "start_ms": null,
    "tool_calls": null,
    "confidence": null,
    "created_at": "2025-01-15T14:30:43Z"
  }
]

GET/conversations/:conversation_id/audio

Obtain a short-lived signed URL for the conversation recording.

Get Audio URL

Issues a signed URL (valid 60 minutes) for downloading the WAV recording. Use this URL with a standard HTTP client; it does not require the X-API-Key header.

Path & Query

conversation_idstring (uuid)required
UUID of the conversation.

Errors

401Unauthorized

Missing or invalid API key.

Add X-API-Key: YOUR_KEY to your request headers.

403Forbidden

Your API key does not have the conversations:read scope.

Issue a new key with the conversations:read scope.

404Not Found

No recording exists for this conversation, or the recording is empty or still finalizing. The endpoint returns 404 in all of these cases — it never issues a URL for an empty recording.

Check has_recording: true on the conversation before requesting the audio URL.

422Unprocessable Entity

conversation_id is not a valid UUID.

Pass a valid UUID from GET /conversations.

Response

json

{
  "url": "https://api.aethexai.com/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/audio.wav?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "format": "wav",
  "expires_in": 3600
}

GET/conversations/:conversation_id/audio.wav

Stream or download the WAV recording directly.

Stream Audio

Returns the raw WAV file. Supports Range headers for partial downloads. Authenticate with the token query parameter (value from GET .../audio) or the X-API-Key header.

Path & Query

conversation_idstring (uuid)required
UUID of the conversation.
tokenstringoptional
Signed token from GET /conversations/:conversation_id/audio; if omitted the request must carry X-API-Key.

Errors

401Unauthorized

No valid API key or signed token was provided.

Add X-API-Key: YOUR_KEY or a valid token query parameter.

403Forbidden

Authenticated but not allowed to access this recording.

Issue a new key with the conversations:read scope.

404Not Found

No recording exists for this conversation, or the recording is empty or still finalizing. The endpoint returns 404 in all of these cases — it never streams a zero-length WAV.

Check has_recording: true on the conversation before streaming audio.

416Range Not Satisfiable

The requested Range exceeds the file size.

Check Content-Length first or omit the Range header.

502Bad Gateway

The storage backend returned an error while streaming the file.

Retry after a brief delay; if the error persists, contact support.

Response

json

// 200 OK or 206 Partial Content
// Content-Type: audio/wav
// Accept-Ranges: bytes
// Content-Length: 1245184
// Content-Range: bytes 0-65535/1245184   (only on Range requests)
// <binary WAV body>

POST/conversations/:conversation_id/audio/revoke

Invalidate a previously issued signed audio URL.

Revoke Audio Token

Immediately revokes a signed token so the URL can no longer be used to stream the recording. Useful when a URL is accidentally exposed.

Path & Query

conversation_idstring (uuid)required
UUID of the conversation.

Request body

tokenstringrequired
Signed token string returned by GET /conversations/:conversation_id/audio.

Errors

401Unauthorized

Missing or invalid API key.

Add X-API-Key: YOUR_KEY to your request headers.

403Forbidden

Authenticated but not allowed to access this recording.

Issue a new key with the conversations:read scope.

404Not Found

No conversation with this ID exists.

Confirm the UUID from GET /conversations.

422Unprocessable Entity

token field is missing or empty.

Supply the token string from GET .../audio in the request body.

POST/conversations/:conversation_id/feedback

Record a star rating and optional comment for a conversation.

Submit Feedback

Attaches a 1–5 star rating and optional free-text comment to a conversation. Feedback is stored server-side and available in your analytics dashboard.

Path & Query

conversation_idstring (uuid)required
UUID of the conversation.

Request body

ratingintegerrequired
Integer rating from 1 (worst) to 5 (best).
commentstringoptional
Optional free-text comment (max 1000 characters).

Errors

401Unauthorized

Missing or invalid API key.

Add X-API-Key: YOUR_KEY to your request headers.

403Forbidden

Your API key does not have the conversations:read scope.

Issue a new key with the conversations:read scope.

404Not Found

No conversation with this ID exists.

Confirm the UUID from GET /conversations.

422Unprocessable Entity

rating is missing, not an integer, or outside the 1–5 range.

Pass rating as an integer between 1 and 5.