Skip to content
Kindo Kindo Docs

Conversations API quickstart

GET https://api.kindo.ai/v1/conversations/{conversation_id}/items speaks the OpenAI Conversations API. Stock OpenAI clients work unmodified.

The Conversations API is a read-only view into the items that make up a Kindo-managed conversation. It’s the companion to /v1/responses when you run with store: true (or supply conversation) and want to fetch the persisted history server-side rather than re-reading it from your own application state.

Two endpoints:

  • GET /v1/conversations/{conversation_id}/items — list every item in a conversation (messages, function calls, function results).
  • GET /v1/conversations/{conversation_id}/items/{item_id} — fetch one item.

Prerequisites

  • A Kindo API key (see Authentication).
  • A conversation_id. The two common ways to get one:
    • The response.conversation.id field returned by a POST /v1/responses call with store: true.
    • The Kindo Terminal exposes conversation IDs in the agent / chat-actions view.

List the items in a conversation

Terminal window
curl https://api.kindo.ai/v1/conversations/conv_abc123/items \
  -H "Authorization: Bearer $KINDO_API_KEY"

Response:

{
  "object": "list",
  "data": [
    {
      "id": "msg_xyz789",
      "type": "message",
      "role": "user",
      "content": [
        { "type": "input_text", "text": "What is the capital of France?" }
      ],
      "status": "completed"
    },
    {
      "id": "msg_xyz790",
      "type": "message",
      "role": "assistant",
      "content": [
        { "type": "output_text", "text": "The capital of France is Paris." }
      ],
      "status": "completed"
    }
  ],
  "has_more": false,
  "first_id": "msg_xyz789",
  "last_id": "msg_xyz790"
}

has_more, first_id, and last_id are always present on the list response. Pass last_id as ?after= to fetch the next page; see Request shape for limit, order, and after.

A single assistant turn can produce multiple top-level items in data — for example a function_call (tool use) followed by a message are emitted as siblings, not nested. Treat the response as a flat ordered stream and dispatch on each item’s type.

Fetch a single item

Terminal window
curl https://api.kindo.ai/v1/conversations/conv_abc123/items/msg_xyz789 \
  -H "Authorization: Bearer $KINDO_API_KEY"

The response object matches a single entry from data[] on the list call.

When to use this surface

  • Auditing — replay the exact items the model saw, in order, after a run finished.
  • Resuming UI state — fetch a conversation on page load instead of caching it client-side.
  • Tool-call analysis — inspect every function_call and function_call_output pair that the model emitted.

Conversations is read-only. To continue a stored conversation, send a new POST /v1/responses with conversation: "conv_..." — see Responses → Chat Actions extensions.

Next steps

  • Request shape — query parameters, response shape, and item types.
  • Errors — the OpenAI-style nested envelope and the (type, code) pairs Conversations returns.