Conversations

List, read, rename, and delete the conversations your asks thread into: keyset pagination, per-turn history, on_behalf_of partitions, and delete semantics.

Every ask threads into a conversation. Pass conversation_id on [POST /v1/ask](post-ask) to continue one, and the agent answers with the prior questions and answers in view; omit it and a fresh conversation is created, with its id returned on the 202. The conversation endpoints under /v1/agent/conversations are the management surface for those threads: list them, read one with its full turn history, rename it, and delete it. All reads require the read scope; rename and delete require write.

Conversations created through the API belong to the workspace's API principal, a derived owner that is not a platform user. The isolation cuts both ways: an API key sees the conversations asked through the API and can never list, read, rename, or delete a colleague's in-product agent chats, and in-product users do not see the key's threads in their own history. Within the API space, on_behalf_of selects a further per-user partition: turns run for a user thread into that user's own partition, so one user's conversation history is never replayed as context into a turn run for someone else, and a continuation across partitions reads as not found rather than silently leaking history.

The list is ordered by newest activity first and keyset-paginated: pass ?limit (1 to 100, default 30) and continue by passing the previous page's next_cursor as ?cursor, until next_cursor comes back null. The cursor is an ISO timestamp, so it stays stable as new conversations arrive while you page. Each row carries the conversation id, its title, how many turns it holds, and its creation and last-activity timestamps.

curl -s "https://api.talonic.com/v1/agent/conversations?limit=2" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

{
  "conversations": [
    {
      "conversation_id": "8c4f2a1e-0b6d-4e2f-9a3c-5d7e1f2a3b4c",
      "title": "Overdue invoices in Q3",
      "turn_count": 3,
      "created_at": "2026-07-30T09:12:00.000Z",
      "last_activity_at": "2026-07-30T09:41:00.000Z"
    },
    {
      "conversation_id": "2b7d9f4a-1c3e-4f5a-8b6d-7e9f0a1b2c3d",
      "title": "MSA termination clauses",
      "turn_count": 1,
      "created_at": "2026-07-29T16:05:00.000Z",
      "last_activity_at": "2026-07-29T16:05:00.000Z"
    }
  ],
  "next_cursor": "2026-07-29T16:05:00.000Z"
}

Read one conversation

GET /v1/agent/conversations/:id returns one conversation with its asks in order, oldest first, so the array reads as the transcript. Each turn carries the ask_id, the question, its lifecycle status (processing, completed, or error), the answer text once settled (empty until then), and its creation timestamp. For the full completed payload of any turn, with structured citations, verification, and usage, fetch it by id via [GET /v1/ask/:id](ask-results): the ask_id here is the same identifier.

{
  "conversation_id": "8c4f2a1e-0b6d-4e2f-9a3c-5d7e1f2a3b4c",
  "title": "Overdue invoices in Q3",
  "created_at": "2026-07-30T09:12:00.000Z",
  "turns": [
    {
      "ask_id": "7c2f0a4e-9d31-4b8a-b3e6-2f1c5d9a8e07",
      "question": "Which invoices in this pipeline are overdue?",
      "status": "completed",
      "answer": "Two invoices are overdue: INV-1041 by 12 days and INV-1055 by 3 days.",
      "created_at": "2026-07-30T09:12:00.000Z"
    },
    {
      "ask_id": "1d4e7a2b-8f6c-4a3d-9e5b-0c1f2a3b4c5d",
      "question": "And only the ones above 5,000 EUR?",
      "status": "processing",
      "answer": "",
      "created_at": "2026-07-30T09:41:00.000Z"
    }
  ]
}

Rename and delete

Both management routes require the write scope, so a read-only integration key can consume threads but not alter them. PATCH /v1/agent/conversations/:id renames: the body is {"title": "..."}, up to 300 characters, trimmed server-side, and the response echoes the conversation id with the new title. DELETE /v1/agent/conversations/:id deletes: the conversation disappears from the list and can no longer be continued with conversation_id, and the response is {"conversation_id": "...", "deleted": true}.

curl -s -X PATCH https://api.talonic.com/v1/agent/conversations/8c4f2a1e-0b6d-4e2f-9a3c-5d7e1f2a3b4c \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Q3 collections review"}'

{"conversation_id": "8c4f2a1e-0b6d-4e2f-9a3c-5d7e1f2a3b4c", "title": "Q3 collections review"}

curl -s -X DELETE https://api.talonic.com/v1/agent/conversations/8c4f2a1e-0b6d-4e2f-9a3c-5d7e1f2a3b4c \
  -H "Authorization: Bearer $TALONIC_API_KEY"

{"conversation_id": "8c4f2a1e-0b6d-4e2f-9a3c-5d7e1f2a3b4c", "deleted": true}

Errors