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":"none"},"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": "none" }, "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

Reasoning configuration

object

effort

One of:

null
string

null

Effort level for reasoning.

Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let minimal silently mean “no reasoning” on budget-based models.

string

Allowed values: none minimal low medium high xhigh

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

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: user agent

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

Message - primary conversation data (API response)

object

content

required

Array of content parts.

Reasoning artifacts appear here as reasoning parts, in the order the provider emitted them, with opaque replay state (signatures, encrypted payloads) stripped.

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.

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

Provider reasoning artifact, ordered against the text and tool calls it was interleaved with.

object

bound_tool_call_id

Id of the tool call this artifact is bound to, when the provider scopes it that way (Gemini attaches a thought signature to one function call).

string | null

encrypted

Provider-encrypted reasoning context (OpenAI encrypted_content). Opaque.

string | null

item_id

Provider-assigned identifier, carried verbatim (e.g. OpenAI rs_…).

string | null

provider

required

Provider that produced this artifact (e.g. anthropic, openai). Replay is only valid against the provider that issued it.

string

signature

Provider signature over this specific block (Anthropic thinking signature, Gemini thoughtSignature). Opaque.

string | null

text

One of:

null
object

null

One of:

Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions reasoning_content).

object

kind

required

string

Allowed values: plain

text

required

string

Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses summary_text). Safe to display; never the model’s own words.

object

kind

required

string

Allowed values: summary

parts

required

Array<string>

The provider withheld the content (Anthropic redacted_thinking). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text.

object

kind

required

string

Allowed values: redacted

tokens

Reasoning tokens attributed to this artifact, when reported.

integer | null format: int32

type

required

string

Allowed values: reasoning

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

Reasoning configuration

object

effort

One of:

null
string

null

Effort level for reasoning.

string

Allowed values: none minimal low medium high xhigh

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

phase

One of:

null
string

null

Execution phase for agent messages: whether this is intermediate commentary or the turn’s final_answer. Absent on user messages.

Without this a client cannot tell an intermediate message from the answer, which is the single question most consumers of a session need answered.

string

Allowed values: commentary final_answer

phase_source

One of:

null
string

null

Whether phase was reported by the provider or inferred by the runtime from tool-call presence.

derived is a weak signal: it means only “this message called tools”, so a text-only preamble is reported as final_answer. Clients needing a dependable classification should treat derived accordingly.

string

Allowed values: provider derived

role

required

Message role (API layer)

Simplified to only user and agent messages. Tool results are conveyed via tool.completed events. System messages are internal and not exposed via API.

string

Allowed values: user agent

sequence

required

integer format: int32

session_id

required

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

string

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",
    "reasoning": {
      "effort": "none"
    }
  },
  "id": "message_01933b5a00007000800000000000001",
  "phase": "commentary",
  "phase_source": "provider",
  "role": "user",
  "session_id": "session_01933b5a00007000800000000000001"
}

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