Execute Message

Execute a message in an existing session and get the agent’s response. This call runs the agent to completion and returns the result — it is not a streaming endpoint.

Human-in-the-Loop is not supported on this endpoint. There is no way to receive an approval card or send a resume over REST. If the agent equips a tool that pauses for human approval — see Human-in-the-Loop — the run suspends with no way to answer it, and the call cannot complete normally.Either use the WebSocket API, or make sure no tool on the agent is gated: set disable_human_approval: true on tools whose source declares default_on, and avoid tools declared mandatory (those cannot be ungated at all).

string

required

The session ID

Request Body

string | array

required

The message content. Can be a simple string or multimodal content blocks.

string

Optional correlation ID for tracking related events

Simple Text Message

curl -X POST https://api.artaios.ai/api/v1/runtime/session_abc123/execute/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "What is the weather like today?"
  }'

import requests

data = {
    "content": "What is the weather like today?"
}

response = requests.post(
    "https://api.artaios.ai/api/v1/runtime/session_abc123/execute/",
    headers={"x-api-key": "YOUR_API_KEY"},
    json=data
)
result = response.json()

const data = {
  content: "What is the weather like today?"
};

const response = await fetch('https://api.artaios.ai/api/v1/runtime/session_abc123/execute/', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
});

const result = await response.json();

Multimodal Message (with images)

{
  "content": [
    {
      "type": "text",
      "text": "What's in this image?"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/image.jpg"
      }
    }
  ]
}

Response

{
  "success": true,
  "message_id": "msg_789",
  "response": {
    "content": "Based on the current weather data, it's sunny and 72°F today.",
    "tool_calls": []
  },
  "correlation_id": "corr_123"
}

The response includes the agent’s generated content and any tool calls that were made during execution.

API Overview

Agents

Sessions

Runtime

Artifacts

Files

Collections

Knowledge Bases

Images

Request Body

Simple Text Message

Multimodal Message (with images)

Response

​Request Body

​Simple Text Message

​Multimodal Message (with images)

​Response

Request Body

Simple Text Message

Multimodal Message (with images)

Response