Conversations

Returns your most recent conversations, newest activity first. Archived (deleted) conversations are not listed. meta.count is the number of conversations returned.

Creates an empty conversation about one audio file and returns it with 201. You do not need this call to chat: POST /v1/chat creates a conversation by itself when you leave out conversation_id. Use this route to prepare a conversation before the first message. audio_url must be a public http or https URL, or a file in your own library.

Returns one conversation with its messages, oldest first. A customer key sees the newest 50 messages: when the conversation holds more, truncated is true and total_available says how many exist. Each message carries its text and role only. Internal reasoning, tool calls, tool results and model details are never returned. To read the assistant's reply to a chat message, poll GET /v1/conversations/{conversation_id}/status until no turn is active, then call this route.

Deletes a conversation: it no longer appears in GET /v1/conversations, and if a chat turn is running in it, the turn is asked to stop. The response reports status: "archived". The call is safe to repeat: deleting a conversation that is already deleted answers 200 again. Only a conversation that is not yours, or that does not exist, answers 404 not_found.

Asks the running chat turn of a conversation to stop. The call is safe to repeat: when no turn is running it answers 200 with signaled: false and delivery: "no_active_turn". delivery says whether the stop signal reached the turn: sent, send_failed (your intent is recorded but the signal did not arrive), binding_missing, or stale (the turn you saw ended and a new one started before the signal could be sent, so nothing was cancelled; call again to cancel the new turn).

Reports how far a conversation has got: the newest exchange, whether an assistant reply arrived since since_turn_index, and, when you pass job_id, whether that job's result has been delivered into the conversation and the progress of its steps. Use it to show progress while a long job runs.

Clears the unread marker: is_unread in GET /v1/conversations becomes false for this conversation. The call has no request body and is safe to repeat.

Use this to edit a message you already sent. It deletes the message you name, together with its reply and every later exchange, so you can send the edited message again with POST /v1/chat. The deleted messages cannot be recovered. user_message_ordinal is the position of the message among the messages you sent, counted from 0. The optional guards make the call delete nothing when your copy of the thread differs from the stored one: message_id (the id of a message read from GET /v1/conversations/{conversation_id}) picks the target directly, user_messages_after must equal the number of your messages that come after the target, and expected_text must equal the target's stored text. When no message matches, the call answers 409 rewind_target_mismatch and deletes nothing. While a turn is running in the conversation, or an analysis recipe is running for it, the call answers 409 turn_in_progress and deletes nothing.

Tells you whether a chat turn is running in the conversation. After POST /v1/chat, poll this route every few seconds: active_turn_workflow_id is the id of the running turn and becomes null when the turn is over. Then read the reply with GET /v1/conversations/{conversation_id}.