Quickstart

The Herm API is a RESTful API at https://api.herm.run. This quickstart uses curl; no SDK is required.

Prerequisites

A Herm workspace. Open Herm, sign in, and create or select a workspace.
An API key. Open Settings → API keys, create a key, and copy it when it is shown.
curl

Set your key in the shell: Herm is a Prism product, so examples use the PRISM_API_KEY environment variable. Requests authenticate with the x-api-key header.

export PRISM_API_KEY="your-api-key-here"

Every request must include x-api-key: $PRISM_API_KEY. Requests with a body must also include Content-Type: application/json.

Create an agent

curl -X POST "https://api.herm.run/v1/agents" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PRISM_API_KEY" \
  -d '{
    "name": "Quickstart Agent",
    "modelName": "anthropic/claude-sonnet-4.5",
    "systemPrompt": "You are a helpful product research agent.",
    "skills": [],
    "tools": []
  }'

The response contains the agent id and its initial immutable version. Save the id for the next request.

Create a session

Create a session using a stable subjectId from your application:

curl -X POST "https://api.herm.run/v1/sessions" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PRISM_API_KEY" \
  -d '{
    "agentId": "agent_123",
    "subjectId": "user_123",
    "title": "First research task"
  }'

Reuse the same subjectId for the same user or organization. A session records the latest agent version when it is created.

Open the event stream

In another terminal, open the session’s Server-Sent Events stream before sending the message:

curl -N "https://api.herm.run/v1/sessions/session_123/events/stream" \
  -H "x-api-key: $PRISM_API_KEY"

Each frame has an SSE event name and a JSON event envelope in data. Assistant text arrives as agent.message; turn lifecycle events are session.status_running and session.status_idle.

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": "Summarize the three most important trends in developer tooling." }
        ]
      }
    ]
  }'

The endpoint returns 202 Accepted with the accepted inbound event. Responses arrive on the stream; there is no separate run resource.

Read the response

The stream emits frames like:

event: session.status_running
data: {"type":"session.status_running","payload":{"type":"session.status_running"},...}

event: agent.message
data: {"type":"agent.message","payload":{"type":"agent.message","delta":true,"content":[{"type":"text","text":"The first trend"}]},...}

event: session.status_idle
data: {"type":"session.status_idle","payload":{"type":"session.status_idle","stop_reason":{"type":"end_turn"}},...}

For agent.message, render text from payload.content. A delta: true payload is a streaming chunk; durable completed messages use delta: false.

Next steps

Agents

Configure models, skills, MCP servers, and tools.

Sessions

Manage session identity and lifecycle.

Stream events

Handle events, required actions, and reconnection.

Long-running tools

Complete application-owned work asynchronously.

Getting Started

Agents

Sessions and events

Capabilities

Credentials

Resources

Prerequisites

Next steps

Agents

Sessions

Stream events

Long-running tools

​Prerequisites

​Next steps

Agents

Sessions

Stream events

Long-running tools

Prerequisites

Next steps