Create Message

Send a message to a session and trigger workflow execution

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