Send text into a running session.

POST /v1/agents/sessions/{id}/message

Records message as a durable control event carrying the caller's text and answers 200 with {command, event, forwarded} — this is how a dashboard steers an agent mid-run. It is the one command with a required body: a message (up to 16 KiB) or a payload, and 400 with neither. The credential scan that guards an appended turn covers payload here; message is bounded but not scanned.

Requires a validated principal carrying an org, and the session must exist IN THAT ORG — a foreign id is a 404, so no tenant can steer another's agents. A FINISHED session (done or error) refuses every command with 409: a run that has ended cannot be steered.

THE COMMAND IS AN INTENT, NOT A STATE CHANGE. Nothing here writes the session's status. A 200 means the command was durably recorded and delivered, never that the agent has actually paused, resumed or stopped; the status becomes paused, done or error only when the surface running the agent reports it back through a session update. That surface learns of the command in one of two ways: a task-backed session (one carrying a workflow id, with a tasks backend wired) has it forwarded to the durable-execution engine, and forwarded says so; everything else is record-only, and the running surface — a locally started hanzo code session, for one — drains it by polling the session's control endpoint. Today that is every session: the only controller wired forwards nothing, so forwarded is false and polling is how a command arrives. If a forward is attempted and fails, the answer is 502 stating that the command was recorded but not forwarded: the intent is never lost.

Request

1 field.

Response

The document declares no response body for this operation. It answers 200 on success and the platform error shape on failure — see Errors.

Examples

hanzo agents sessions message <id>

import { Configuration, AgentsApi } from 'hanzoai';

const api = new AgentsApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postAgentsSessionsByIdMessage({ id: 'id' });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import AgentsApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = AgentsApi(client).post_agents_sessions_by_id_message(id='id')

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.AgentsAPI.PostAgentsSessionsByIdMessage(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_cloud::apis::{configuration::Configuration, agents_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = agents_api::post_agents_sessions_by_id_message(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.AgentsApi;

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new AgentsApi(client).postAgentsSessionsByIdMessage();

curl -X POST https://api.hanzo.ai/v1/agents/sessions/<id>/message \
  -H "Authorization: Bearer $HANZO_API_KEY"

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_agent_conversations"
         }
       }
     }'

Agents API · All Hanzo APIs · Interactive reference