Skip to content
Kindgi

Read conversation messages

View as Markdown
GET
/v1/conversations/{conversationId}/messages
curl --request GET \
  --url 'https://example.com/v1/conversations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/messages?limit=25' \
  --header 'Authorization: Bearer <token>'

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

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
conversationId
required
string format: uuid

ConversationId — opaque branded string (a UUID).

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.

Responses

Section titled “Responses”

200

Section titled “200”

Page of messages.

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

Monotonic index within the conversation. Sort order for the list endpoint.

integer
role
required
string
Allowed values: user agent tool system
content
required

Free-form string OR a structured object (tool results).

files

Stored files the message carries, on a user message (its run’s input files) or a tool’s result: references, never bytes. A later turn shows its model each one the run’s rule still admits, and a line for one that’s gone.

Array<object>

A stored file as a value: in a run’s input, a tool’s result or a conversation message. Only artifactId is trusted: the runtime shows a model a file by its own checked record of it, never by the value’s other fields. A message’s files are the ones its run admitted, with the record’s fields.

object
type
required
string
Allowed value: kindgi.file
artifactId
required

The stored file (POST /v1/artifacts): its blobId.

string
>= 1 characters
name

The file’s name.

string
contentType
required

Its type, as checked from its bytes.

string
size
required

Its size in bytes.

integer
sha256
required

Sha256 of its bytes, hex-encoded, lowercase.

string
/^[0-9a-f]{64}$/
pages

A PDF’s page count, as checked from its bytes.

integer
>= 1
notShown

Set when the model isn’t shown it, and reads a line naming it instead: type (not a type a model is shown), size (over its type’s limit), model (the agent or its model doesn’t take images and PDFs), limit (over a call’s or a list’s limits), store (no file store), gone (no longer stored), changed (not the bytes that were checked), refused (the model couldn’t read it when it was attached), storage (a tool’s store found the tenant’s storage full), reading (what the model is sent in its place, an image or a text made from it, isn’t made yet).

string
Allowed values: type size model limit store gone changed refused storage reading
toolCall
object
toolId
required
string
invocationId
required
string
actor
string
createdAt
required
string format: date-time
nextCursor

Opaque cursor for the next page. Absent when hasMore: false. Sort is sequence asc.

string
hasMore
required
boolean
Example
{
  "data": [
    {
      "role": "user",
      "files": [
        {
          "type": "kindgi.file",
          "notShown": "type"
        }
      ]
    }
  ]
}

400

Section titled “400”

Malformed cursor, or conversationId is not a conversation id (a UUID).

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"
  }
}

404

Section titled “404”

No conversation with that id under this tenant, or one the caller can’t read (read on its project, or on its agent for one from before projects): the same answer, byte for byte.

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"
  }
}

503

Section titled “503”

The database was too busy to answer in time (database-busy); Retry-After (whole seconds) says when to try again.

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