Conversations API request shape

Both endpoints speak the OpenAI Conversations API verbatim, exposing the items stored when you run /v1/responses with store: true. Both are GET and return JSON.

GET /v1/conversations/{conversation_id}/items

Lists items in the conversation in the order they were appended.

curl https://api.kindo.ai/v1/conversations/conv_abc123/items?limit=50&order=asc \
  -H "Authorization: Bearer $KINDO_API_KEY"

Query parameters

Name	Type	Default	Notes
limit	integer	20	Messages per page. Range 1–100. Each message may expand to multiple items (an assistant turn with a tool call produces a function_call plus a message), so the returned data length may exceed limit.
order	string	desc	asc or desc. Sort order by message index.
after	string	—	Cursor: return items appended after this item ID. Pass last_id from the previous response. An item ID not present in this conversation produces 400 invalid_cursor.

Response

Field	Type	Notes
object	string	Always "list".
data	array	One entry per item. See Item types.
has_more	boolean	true when another page is available; pass last_id as ?after=.
first_id	string | null	ID of the first item in data, or null when data is empty.
last_id	string | null	ID of the last item in data, or null when data is empty.

Item types

The type field on each item determines the rest of its shape. A single assistant turn can produce multiple top-level items (function_call siblings of message) — treat data as a flat ordered stream rather than assuming one item per turn.

type	Shape (key fields)	Notes
message	id, role, content[], status	role is user, assistant, or system. content[] contains typed text/image blocks.
function_call	id, call_id, name, arguments	A model-emitted function-tool call.
function_call_output	call_id, output	The matching tool result (echoed back by the caller). Identified by call_id — function_call_output items do not carry their own id.

message items carry a status field, currently always "completed" (Kindo stores items as they are persisted, not while streaming). Items do not carry an object field — the outer list envelope has object: "list", but individual items omit it. Dispatch on type instead.

Unrecognized item types are forwarded verbatim from the underlying store, so new OpenAI Responses item shapes appear without requiring a Kindo upgrade.

The API normalizes a developer role to system before persisting; responses always show system.

GET /v1/conversations/{conversation_id}/items/{item_id}

Fetches a single item. The response object matches one entry from the data[] array on the list endpoint.

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

{
  "id": "msg_xyz789",
  "type": "message",
  "role": "user",
  "content": [
    { "type": "input_text", "text": "What is the capital of France?" }
  ],
  "status": "completed"
}

See also

• Quickstart — list + fetch flow.
• Errors — the OpenAI-style nested envelope and the (type, code) pairs returned by these endpoints.
• Responses → Chat Actions extensions — how a stored conversation is created and continued.