Create message (user message triggers workflow)

POST

/v1/sessions/{session_id}/messages

const url = 'https://app.everruns.com/api/v1/sessions/example/messages';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"addressed_participant_id":"part_01933b5a00007000800000000000001","controls":{"error_disclosure":"example","hints":"example","locale":"example","model_id":"model_01933b5a00007000800000000000001","reasoning":{"effort":"example"},"speed":"example","verbosity":"example"},"external_actor":{"actor_id":"example","actor_name":"example","metadata":"example","source":"example"},"message":{"content":[{"text":"Why is the build failing on main?","type":"text"}],"role":"user"},"metadata":{"source":"slack","thread_ts":"1715000000.123456"},"tags":["bug-report","from-slack"]}'
};

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

curl --request POST \
  --url https://app.everruns.com/api/v1/sessions/example/messages \
  --header 'Content-Type: application/json' \
  --data '{ "addressed_participant_id": "part_01933b5a00007000800000000000001", "controls": { "error_disclosure": "example", "hints": "example", "locale": "example", "model_id": "model_01933b5a00007000800000000000001", "reasoning": { "effort": "example" }, "speed": "example", "verbosity": "example" }, "external_actor": { "actor_id": "example", "actor_name": "example", "metadata": "example", "source": "example" }, "message": { "content": [ { "text": "Why is the build failing on main?", "type": "text" } ], "role": "user" }, "metadata": { "source": "slack", "thread_ts": "1715000000.123456" }, "tags": [ "bug-report", "from-slack" ] }'

Parameters

Path Parameters

session_id

required

string

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

Request Body^required

application/json

Request to create a message

object

addressed_participant_id

Optional active agent participant to address for this turn. When omitted, the session host remains the responder.

string | null

Example

part_01933b5a00007000800000000000001

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

Example

model_01933b5a00007000800000000000001

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

external_actor

One of:

null
object

null

message

required

The message to create. Example shape is defined on InputMessage.

object

content

required

Array of content parts (text and image only)

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 specs/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 specs/citations.md.

object

end

required

Exclusive end char offset.

integer

Example

external_id

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

string | null

Example

kchk_01j9y3q8w2

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

Example

citation_retrieval

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

Example

The control plane owns durable state.

title

Human-readable source title, when known.

string | null

Example

Architecture Overview

uri

required

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

string

Example

github://owner/repo@main/docs/x.md

start

required

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

integer

Example

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

Example

0.92

status

required

Whether the cited source supports the claim.

string

Allowed values: entailed unsupported uncertain

Example

entailed

text

required

string

type

required

string

Allowed values: text

Image file content (reference to uploaded image by ID)

object

filename

Original filename (for display)

string | null

image_id

required

ID of the uploaded image (format: img_{32-hex})

string

Example

img_01933b5a00007000800000000000001

type

required

string

Allowed values: image_file

role

Message role (always “user” for API-created messages)

string

Allowed values: system user agent tool_result

Example

{
  "content": [
    {
      "text": "Why is the build failing on main?",
      "type": "text"
    }
  ],
  "role": "user"
}

metadata

Request-level metadata. Arbitrary key/value pairs persisted with the message for downstream filtering and analytics. Not interpreted by the agent.

object | null

Example

{
  "source": "slack",
  "thread_ts": "1715000000.123456"
}

tags

Tags for the message. Free-form labels used for grouping and filtering.

Array<string> | null

Example

[
  "bug-report",
  "from-slack"
]

Responses

201

Message created successfully

application/json

A message in the conversation

object

content

required

Message content as array of content parts (text, images, tool calls, tool results)

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 specs/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.

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

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 the message was created

string format: date-time

external_actor

One of:

null
object

null

required

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

string

metadata

Message-level metadata

object | null

phase

One of:

null
string

null

role

required

Message role

string

Allowed values: system user agent tool_result

thinking

Thinking content from extended thinking models (Anthropic Claude) This is the model’s chain-of-thought reasoning before producing the response. Must be included in subsequent API calls when thinking is enabled.

string | null

thinking_signature

Cryptographic signature for thinking content (Anthropic Claude) Required when sending thinking back in subsequent API calls.

string | null

Example

{
  "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",
  "phase": "Commentary",
  "role": "system"
}

400

Invalid ID format

404

Session not found

500

Internal server error

Create message (user message triggers workflow)

Parameters

Path Parameters

Request Bodyrequired

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Responses

201

Example

400

404

500

Request Body^required