Send session events

POST /v1/sessions/{sessionId}/events

Use this endpoint to send prompt, control, and result events to an existing session. A request contains 1 to 100 events, and only one event may start a new turn. Control events and immediate custom tool results can be sent while a turn is running or paused for required action. A final long-running custom tool result starts a new turn and requires an idle session. Exceeding a limit — more than 100 events per request, more than 100 text blocks in a content array, or a text value over 20,000 characters — rejects the whole request with 400 validation_error. Nothing is truncated, and the error message names the failing field and limit. See Text content block. A user.message starts a new turn, and a session runs one turn at a time: by default a prompt sent while a turn is running is rejected with 409. Set the request-level delivery field to "when_idle" to queue the prompt instead — see Queue a message while a turn is running.

Send a message

curl -X POST "https://api.herm.run/v1/sessions/session_123/events" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PRISM_API_KEY" \
  -d '{
    "events": [
      {
        "type": "user.message",
        "content": [
          {
            "type": "text",
            "text": "Say hello in one sentence."
          }
        ],
        "metadata": {
          "source": "dashboard",
          "accountId": "acct_123",
          "priority": true
        }
      }
    ]
  }'

metadata is optional turn context for the agent. It is persisted on the user.message event payload and returned by list/stream APIs, but it is not part of the visible content text your UI renders as the user’s message. Metadata values must be strings, numbers, booleans, or null.

Send a message with attachments

user.message accepts up to 10 turn-scoped file attachments. Attachments are sent as base64 data_url sources. The accepted event, including each source.dataUrl, is retained in session event history.

curl -X POST "https://api.herm.run/v1/sessions/session_123/events" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PRISM_API_KEY" \
  -d '{
    "events": [
      {
        "type": "user.message",
        "content": [
          {
            "type": "text",
            "text": "Summarize the attached notes and list action items."
          }
        ],
        "attachments": [
          {
            "type": "file",
            "filename": "notes.txt",
            "mediaType": "text/plain",
            "sizeBytes": 37,
            "source": {
              "type": "data_url",
              "dataUrl": "data:text/plain;base64,VGhlIGN1c3RvbWVyIGFza2VkIGZvciBhIFFCUiBwbGFuLg=="
            }
          }
        ]
      }
    ]
  }'

Supported attachment types are PDF, CSV, TXT, Markdown, DOCX, PNG, JPEG, WebP, GIF, and BMP. The agent can inspect images and documents as part of the turn. PDFs default to document mode; set analysisMode: "visual" on a PDF attachment only when you want page-image analysis.

Field	Type	Required	Description
`type`	string	Yes	Must be `file`.
`filename`	string	Yes	Display name used after sanitization.
`mediaType`	string	Yes	One of the supported MIME types.
`sizeBytes`	integer	No	Declared byte size. Enforced when present.
`source.type`	string	Yes	Must be `data_url`.
`source.dataUrl`	string	Yes	Base64 data URL whose MIME type matches `mediaType`.
`analysisMode`	string	No	`default` or `visual`; `visual` is PDF-only.

Limits: images, CSV, TXT, Markdown, and DOCX are capped at 25 MB per attachment; PDFs are capped at 50 MB.

Queue a message while a turn is running

By default, sending a prompt-starting event while a turn is already running fails with 409 invalid_state (“A turn is already in progress”), and your application owns the retry. When your caller means “deliver this whenever the agent can take it” — for example a background job posting a completion notification into a session — set the request-level delivery field to "when_idle":

curl -X POST "https://api.herm.run/v1/sessions/session_123/events" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PRISM_API_KEY" \
  -d '{
    "delivery": "when_idle",
    "events": [
      {
        "type": "user.message",
        "content": [
          {
            "type": "text",
            "text": "Render job 42 finished successfully."
          }
        ],
        "metadata": {
          "source": "workflow_completion",
          "jobId": "42"
        }
      }
    ]
  }'

`delivery`	Behavior while a turn is running
`"immediate"` (default)	The request is rejected with `409 invalid_state`. Identical to omitting the field.
`"when_idle"`	The prompt-starting event is persisted with `status: "queued"` and the request returns `202` immediately. Herm starts the queued turn automatically when the running turn ends.

With "when_idle":

If the session is idle, the prompt starts a turn immediately — exactly like an immediate send.
Queued prompts start oldest-first, one per turn end, and each runs as its own turn.
The 202 response echoes the persisted events; data[].status === "queued" tells you the prompt was parked rather than started. The status moves to received when its turn starts, then processed like any other prompt.
Queued prompts remain durable until they are delivered once the session is idle again.

A when_idle request must contain only prompt-starting user.message events. Control and result events (user.steer, user.approval_response, and so on) target the currently running turn and are never queued for a later one, so a when_idle request that includes them is rejected with 400 validation_error — send them in a separate request with the default delivery.

Rate-limit counting

The agent’s message limit defaults to 100 accepted inbound user.* events per stable subject (subjectId) per fixed 60-second window. Every event in a request consumes one point from this allowance.

Immediate events count when they are accepted for persistence.
A delivery: "when_idle" prompt counts when it is accepted into the durable queue. It is not counted again when the queue drains.
Validation, not-found, archived-session, and prompt-conflict failures rejected before persistence do not count. A control event that is persisted but cannot reach a live turn does count.
user.steer, user.interrupt, user.approval_response, user.clarify_result, and user.custom_tool_result each count.

The subject comes from the stored session; it cannot be changed on this route. Limited successful event requests include RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset. See Rate limits and Errors.

Supported inbound events

Event	Description	Required fields
`user.message`	Start a new agent turn with user text, optional metadata, and optional attachments.	`content`
`user.steer`	Add guidance to the current session without starting a normal prompt.	`message`
`user.interrupt`	Interrupt the active turn.	none
`user.approval_response`	Allow or deny a pending tool approval request.	`approval_id`, `result`
`user.custom_tool_result`	Return the result of an application-owned custom tool. Use `status` for long-running workflow kickoff and completion updates.	`tool_use_id`, `content`
`user.clarify_result`	Answer an `agent.clarify_request`.	`request_id`, `answer`

See the Events Reference for the complete schema for each event.

Action responses

When the stream emits session.status_idle with payload.stop_reason.type: "requires_action", the event_ids array contains the IDs your application needs to answer.

Pending event	Respond with	ID mapping
`agent.approval_request`	`user.approval_response`	`agent.approval_request.id` -> `approval_id`
`agent.custom_tool_use`	`user.custom_tool_result`	`agent.custom_tool_use.id` -> `tool_use_id`
`agent.clarify_request`	`user.clarify_result`	`agent.clarify_request.request_id` -> `request_id`

Confirm a tool request

curl -X POST "https://api.herm.run/v1/sessions/session_123/events" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PRISM_API_KEY" \
  -d '{
    "events": [
      {
        "type": "user.approval_response",
        "approval_id": "approval_123",
        "result": "allow",
        "scope": "once"
      }
    ]
  }'

result is allow or deny. scope is optional and can be once, session, or always; omit it to allow once.

Answer a clarify request

curl -X POST "https://api.herm.run/v1/sessions/session_123/events" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PRISM_API_KEY" \
  -d '{
    "events": [
      {
        "type": "user.clarify_result",
        "request_id": "clarify_123",
        "answer": "Use the production environment."
      }
    ]
  }'

Use an empty answer to skip the question and let the agent continue with its own default.

Return a custom tool result

Custom tools are executed by your application, not by the managed agent. When the stream emits agent.custom_tool_use, execute the named tool and return the result with user.custom_tool_result.

curl -X POST "https://api.herm.run/v1/sessions/session_123/events" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PRISM_API_KEY" \
  -d '{
    "events": [
      {
        "type": "user.custom_tool_result",
        "tool_use_id": "custom_toolu_123",
        "content": [
          {
            "type": "text",
            "text": "Order #123 ships tomorrow."
          }
        ],
        "is_error": false
      }
    ]
  }'

Set is_error: true when your application could not complete the tool. The text is still sent back to the model as tool output, so include a concise, model-readable error message. For long-running workflows, return a kickoff result within approximately five minutes:

{
  "events": [
    {
      "type": "user.custom_tool_result",
      "tool_use_id": "custom_toolu_123",
      "content": [{ "type": "text", "text": "Workflow started." }],
      "status": "running",
      "is_error": false
    }
  ]
}

The kickoff resolves the pending tool call and lets the original turn continue. When the workflow finishes and the session is idle, send a second result with the same tool_use_id:

{
  "events": [
    {
      "type": "user.custom_tool_result",
      "tool_use_id": "custom_toolu_123",
      "content": [{ "type": "text", "text": "Workflow finished." }],
      "status": "completed",
      "is_error": false
    }
  ]
}

When a matching running result exists, the completion replaces it in event history, emits session.tool_updated, and starts a new agent turn with the final text. It cannot use delivery: "when_idle"; wait for session.status_idle before posting it. See Long-running custom tools for the complete flow, UI reconciliation, and retry constraints.

Response

The endpoint returns the events persisted by the request. Additional agent events can be retrieved with List Session Events or streamed with Stream Events. A message parked by delivery: "when_idle" is returned with status: "queued" instead of received.

{
  "object": "list",
  "data": [
    {
      "id": "evt_123",
      "type": "user.message",
      "sessionId": "session_123",
      "sequence": 0,
      "turnId": "turn_123",
      "status": "received",
      "payload": {
        "type": "user.message",
        "content": [{ "type": "text", "text": "Say hello in one sentence." }],
        "metadata": { "source": "dashboard", "accountId": "acct_123" }
      },
      "processedAt": null,
      "createdAt": "2026-06-20T23:27:54.866Z"
    }
  ]
}

Errors

Status	Error	When
`400`	`validation_error`	Invalid request body, text over 20,000 characters, more than 100 text blocks or events, unsupported attachment, malformed data URL, oversized attachment, more than one prompt-starting event, or a `delivery: "when_idle"` request containing control or result events. The message names the failing field, e.g. `events[0].content[0].text: Expected a string at most 20000 character(s) long`.
`404`	`not_found`	Session does not exist.
`409`	`invalid_state`	Session is archived, or a prompt-starting event was sent while a turn is already running. This includes final long-running custom tool results.
`409`	`no_active_turn`	The session is no longer waiting for this custom tool result. The event may already be present in history; reconcile history before retrying.
`429`	`rate_limited`	The agent’s per-user event allowance is exhausted. The events are not persisted, queued, or executed.

Getting Started

Agents

Sessions and events

Capabilities

Credentials

Resources

Send session events

Send a message

Send a message with attachments

Queue a message while a turn is running

Rate-limit counting

Supported inbound events

Action responses

Confirm a tool request

Answer a clarify request

Return a custom tool result

Response

Errors

​Send a message

​Send a message with attachments

​Queue a message while a turn is running

​Rate-limit counting

​Supported inbound events

​Action responses

​Confirm a tool request

​Answer a clarify request

​Return a custom tool result

​Response

​Errors

Send a message

Send a message with attachments

Queue a message while a turn is running

Rate-limit counting

Supported inbound events

Action responses

Confirm a tool request

Answer a clarify request

Return a custom tool result

Response

Errors