Skip to content
Kindgi

List conversations

View as Markdown
GET
/v1/conversations
curl --request GET \
  --url 'https://example.com/v1/conversations?limit=25&scopeKind=tenant&status=open&replays=exclude&openedBy=me' \
  --header 'Authorization: Bearer <token>'

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.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
limit
integer
default: 25 >= 1 <= 100

1..100. Default 25.

cursor
string

Where the previous page ended: its nextCursor, as it came. A runtime that seals cursors takes one only for the same list, filters and caller, within a day; otherwise 400 bad-input, and the list starts again without it. Absent → first page.

scopeKind

Discriminator for the ?scopeKind + ?scopeId + ?inherit triplet. Tenant carries no id (implicit from session); org/project require scopeId.

string
Allowed values: tenant org project

Optional scope discriminator. If absent, no scope filter is applied.

scopeId
string
>= 1 characters

Required IF scopeKind is org or project. MUST be absent if scopeKind=tenant (tenant is implicit from the session). Malformed combinations return 400 scope-invalid.

agentId
string
status

Lifecycle status derived from closedAt: open when null, closed otherwise.

string
Allowed values: open closed

Filter by conversation lifecycle status.

replays
string
default: exclude
Allowed values: exclude include only

Replay conversations (opened by a comparison’s replay turn; metadata.replayOf names the run it replays). exclude (default) leaves them out; include lists them with the others; only lists just them.

openedBy
string
Allowed values: me

me: only the conversations the caller opened (none for a caller with no principal). Conversations an older runtime opened record no opener and aren’t listed by it.

Responses

Section titled “Responses”

200

Section titled “200”

Page of conversations.

Media typeapplication/json
object
data
required
Array<object>
object
id
required

ConversationId.

string format: uuid
tenantId
required
string format: uuid
agentId
required
string
agentVersion
required

Semver.

string
title
required
string
participantId
string
projectId

The project the conversation is in: the project of the run that opened it, or projectId on open (when omitted, the agent’s own project, or the tenant’s Default project for an agent filed under none). Absent on conversations from before Kindgi 0.1.3; those are listed only without a scope.

string format: uuid
openedBy

Who opened it: the caller’s principal (user:<id>, service_account:<id>), or, for one a turn opened, whoever the run acts for. Set by the server, never from a request’s body. Absent on conversations an older runtime opened, and when the caller had no principal; those aren’t listed by ?openedBy=me.

string
scope
required

Free-form scope object (currently { tenantId } in tests; enterprises extend with matterId, engagementId, etc.).

object
key
additional properties
any
status
required

Lifecycle status derived from closedAt: open when null, closed otherwise.

string
Allowed values: open closed
openedAt
required
string format: date-time
closedAt
string format: date-time
unregisteredAt

When it was unregistered (POST /v1/conversations/{conversationId}/unregister). Only the unregister call returns it: reads no longer do.

string format: date-time
turnCount
required
integer
lastMessageAt
string format: date-time
metadata
object
key
additional properties
any
nextCursor

Opaque cursor for the next page. Absent when hasMore: false.

string
hasMore
required
boolean
openedBy

me on every page of a list asked for with ?openedBy=me, an empty one too: it holds only the conversations the caller opened. Absent from a runtime before Kindgi 0.1.9, which ignores openedBy and lists everyone’s.

string
Allowed values: me
Example
{
  "data": [
    {
      "status": "open"
    }
  ],
  "openedBy": "me"
}

400

Section titled “400”

Malformed query parameter or scope.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Section titled “401”

Missing / malformed / expired / revoked bearer token.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also