Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/everruns/everruns/llms.txt

Use this file to discover all available pages before exploring further.

​
POST /v1/sessions//messages

Create a new message in a session. This triggers the agent workflow execution.

​
Path Parameters

​
session_id
string
required
The unique identifier of the session

​
Request Body

​
message
object
required
The message object to create
​
message.content
array
required
Array of content parts. Each part can be text or an image file.Text content part:
{ "type": "text", "text": "Your message here" }
Image content part:
{ "type": "image_file", "image_id": "01933b5a-...", "filename": "photo.png" }
​
message.controls
object
Optional control parameters for the message
​
message.controls.max_tokens
integer
Maximum tokens to generate in response
​
message.metadata
object
Optional arbitrary metadata for the message

​
Response

Returns the created message object with generated ID and timestamp.
​
id
string
Message identifier (UUID v7)
​
role
string
Message role: user, agent, or tool
​
content
array
Array of content parts
​
controls
object
Control parameters (if provided)
​
metadata
object
Message metadata (if provided)
​
created_at
string
ISO 8601 timestamp

​
Example Request

curl -X POST https://api.everruns.com/v1/sessions/{session_id}/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "content": [
        { "type": "text", "text": "What is the weather in Tokyo?" }
      ]
    }
  }'

​
Example with Image

curl -X POST https://api.everruns.com/v1/sessions/{session_id}/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "content": [
        { "type": "text", "text": "What is in this image?" },
        { "type": "image_file", "image_id": "01933b5a-...", "filename": "photo.png" }
      ]
    }
  }'

​
Example Response

{
  "id": "01937abc-def0-7000-8000-000000000001",
  "role": "user",
  "content": [
    { "type": "text", "text": "What is the weather in Tokyo?" }
  ],
  "created_at": "2024-01-15T10:30:00.000Z"
}

​
Workflow Execution

Creating a message triggers the agent workflow:
  1. Message Storage: The user message is persisted and an input.message event is emitted
  2. Turn Execution: A new turn begins with turn.started event
  3. Session Activation: session.activated event signals the session is active
  4. Agent Processing: The agent processes the message through its reasoning and action loop
  5. Response: Agent emits output.message.started, output.message.delta (streaming), and output.message.completed events
  6. Session Idle: session.idled event signals turn completion

​
Event Streaming

To receive real-time updates during workflow execution, connect to the SSE endpoint before sending the message: 
curl -N https://api.everruns.com/v1/sessions/{session_id}/sse \
  -H "Authorization: Bearer YOUR_API_KEY"
See Event Streaming for details.

​
Error Responses

​
error
string
Error message
​
status
integer
HTTP status code

​
Common Errors

  • 400 Bad Request: Invalid message format or missing required fields
  • 404 Not Found: Session does not exist
  • 422 Unprocessable Entity: Message validation failed
  • 500 Internal Server Error: Server error during processing

Build docs developers (and LLMs) love

Get started for freeTalk to us