List messages (PRIMARY data)

GET

/v1/sessions/{session_id}/messages

const url = 'https://app.everruns.com/api/v1/sessions/example/messages';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://app.everruns.com/api/v1/sessions/example/messages

Parameters

Path Parameters

session_id

required

string

Session ID (prefixed, e.g., sess_…)

Responses

200

List of messages

application/json

Response wrapper for list endpoints. All list endpoints return responses wrapped in a data field.

object

data

required

Array of items returned by the list operation.

Array<object>

Message - primary conversation data (API response)

object

content

required

Array of content parts

Array

One of:

Text content

object

annotations

Claim-level citations attached to spans of text.

The narrow render contract shared by all citation capabilities (see knowledge/runtime-resources/citations.md). Empty for non-cited text, so the wire shape of existing messages is unchanged.

Array<object>

A claim-level citation attached to a span of generated text.

The single shared type across every citation capability: a text span linked to a source. Producers agree only on this render contract — each capability keeps its own richer representation (e.g. KnowledgeIndexCitation) and maps into this envelope at emit time. See knowledge/runtime-resources/citations.md.

object

end

required

Exclusive end char offset.

integer

external_id

Opaque producer id (e.g. kchk_…, kbe_…, a URL hash). Not interpreted by the render contract.

string | null

origin

required

Capability id that produced this annotation (e.g. citation_retrieval). Lets the UI and evals attribute and filter each citation by feed.

string

source

required

The cited source.

object

location

Provenance within the document (line / char / page / block ranges), reusing the retrieval location JSONB shape.

snippet

Trimmed passage that backs the claim. Display-only; never relied on for prompt reconstruction.

string | null

title

Human-readable source title, when known.

string | null

uri

required

Stable, linkable locator (e.g. github://owner/repo@main/docs/x.md or an https:// URL).

string

start

required

0-indexed start char offset into the enclosing TextContentPart.text.

integer

verified

One of:

null
object

null

Verification verdict, filled by the citation_verification capability. Absent means unverified (not “unsupported”).

object

score

Entailment confidence in [0, 1], when the verifier produced one.

number | null format: float

status

required

Whether the cited source supports the claim.

string

Allowed values: entailed unsupported uncertain

text

required

string

type

required

string

Allowed values: text

controls

One of:

null
object

null

Runtime controls (model, reasoning, etc.)

object

error_disclosure

Error disclosure override for this turn: “generic”, “standard”, or “detailed”. Clamped to at most the mode allowed by the agent’s error_disclosure capability (capability absent => “standard”), so a client can narrow but never widen disclosure.

string | null

hints

Generic client hints — arbitrary key-value pairs declared by the client. Session-level defaults are set at session creation; per-message values override session hints key-by-key (shallow merge).

Examples: {"setup_connection": true, "rich_media": true}

object | null

locale

Locale override for this message turn (BCP 47, e.g. uk-UA). Overrides the session locale for backend-authored strings and prompts.

string | null

model_id

Model ID to use for this message (format: model_{32-hex}). Overrides session and agent model settings.

string | null

reasoning

One of:

null
object

null

speed

Speed (service tier) for this message turn: “flex”, “default”, or “priority”. Only sent to providers whose model profile advertises a speed config (OpenAI service_tier).

string | null

verbosity

Verbosity for this message turn: “low”, “medium”, or “high”. Only sent to providers whose model profile advertises a verbosity config (OpenAI verbosity).

string | null

created_at

required

Timestamp when this resource was created (RFC 3339).

string format: date-time

external_actor

One of:

null
object

null

required

Unique message ID (format: message_{32-hex})

string

metadata

Message-level metadata (locale, etc.)

object | null

role

required

Message role in the conversation

string

Allowed values: system user agent tool_result

sequence

required

integer format: int32

session_id

required

Session ID this message belongs to (format: session_{32-hex})

string

Example

{
  "data": [
    {
      "content": [
        {
          "annotations": [
            {
              "end": 19,
              "external_id": "kchk_01j9y3q8w2",
              "origin": "citation_retrieval",
              "source": {
                "snippet": "The control plane owns durable state.",
                "title": "Architecture Overview",
                "uri": "github://owner/repo@main/docs/x.md"
              },
              "start": 0,
              "verified": {
                "score": 0.92,
                "status": "entailed"
              }
            }
          ],
          "type": "text"
        }
      ],
      "controls": {
        "model_id": "model_01933b5a00007000800000000000001"
      },
      "id": "message_01933b5a00007000800000000000001",
      "role": "system",
      "session_id": "session_01933b5a00007000800000000000001"
    }
  ]
}

400

Invalid ID format

404

Session not found

500

Internal server error