client.conversations

client.conversations — the conversations operations.

On AsyncKindgi every method is the same, awaited.

client.conversations.list()

list(
    *,
    limit: int | None = None,
    cursor: str | None = None,
    scope_kind: Literal['tenant', 'org', 'project'] | None = None,
    scope_id: str | UUID | None = None,
    agent_id: str | UUID | None = None,
    status: Literal['open', 'closed'] | None = None,
    replays: Literal['exclude', 'include', 'only'] | None = None,
    opened_by: Literal['me'] | None = None,
    timeout: float | None = None,
) -> ConversationCollectionPage

Signature

List conversations. GET /v1/conversations

Cursor-paginated. Fixed sort: openedAt desc, id desc. Filters: ?agentId=, ?status=open|closed, ?openedBy=me (the caller's own), ?replays=exclude|include|only (default exclude: a comparison's replay conversations are left out), and scopeKind/scopeId for one project's conversations, or every project's in an org. Conversations from before Kindgi 0.1.3 have no project and are listed only without a scope.

client.conversations.open()

open(
    body: OpenConversationBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> Conversation

Signature

Open a conversation. POST /v1/conversations

Pins (agentId, agentVersion) at open time. title defaults to "Untitled conversation" when omitted; projectId puts it in a project, which must reach the agent (lists filter by it; omitted, the agent's own project, as for a run, or the Default project for an agent filed under none); scope accepts arbitrary JSON.

client.conversations.get()

get(conversation_id: str | UUID, /, *, timeout: float | None = None) -> Conversation

Signature

Fetch a conversation. GET /v1/conversations/{conversationId}

client.conversations.close()

close(
    conversation_id: str | UUID,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
) -> Conversation

Signature

Close a conversation. POST /v1/conversations/{conversationId}/close

Idempotent: closing an already-closed conversation returns 200 with the current row (no timestamp bump).

client.conversations.unregister()

unregister(
    conversation_id: str | UUID,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
) -> Conversation

Signature

Unregister a conversation. POST /v1/conversations/{conversationId}/unregister

A tombstone: from now on no read, list or recall of earlier conversations returns it, and no message can be added. The retention sweep removes it after the tenant's grace.

client.conversations.messages()

messages(
    conversation_id: str | UUID,
    /,
    *,
    limit: int | None = None,
    cursor: str | None = None,
    timeout: float | None = None,
) -> ConversationMessageCollectionPage

Signature

Read conversation messages. GET /v1/conversations/{conversationId}/messages

Cursor-paginated. Sort is sequence asc (natural conversation reading order) — distinct from most list endpoints, which use createdAt desc.