Agents

An agent is a reusable, versioned configuration. Each version stores its model, system prompt, skills, tools, and metadata. New sessions record the latest version at creation time. All endpoints use x-api-key authentication.

Create an agent

POST /v1/agents

Creates an agent and its initial version.

curl -X POST "https://api.herm.run/v1/agents" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $HERM_API_KEY" \
  -d '{
    "name": "Acme Creative Agent",
    "modelName": "openai/gpt-4o-mini",
    "systemPrompt": "Help Acme plan and execute media workflows.",
    "skills": [],
    "tools": [],
    "roles": [],
    "mcpServers": [],
    "rateLimits": {
      "conversationsPerMinute": 5,
      "messagesPerMinute": 100
    },
    "metadata": {
      "productArea": "media-generation"
    }
  }'

Request body

Field	Type	Required	Description
`name`	string	Yes	Human-readable agent name.
`modelName`	string	Yes	Provider and model name, such as `openai/gpt-4o-mini`.
`systemPrompt`	string	Yes	System instructions for the agent.
`skills`	object[]	Yes	Configured Markdown skills available to the agent version. Each item has `name` and `content`. See Skills. Use `[]` if none.
`tools`	object[]	Yes	Built-in toolset, MCP toolset, and custom tool configuration. Use `[]` if none.
`roles`	object[]	No	Named role-specific tool policies. Defaults to `[]`. Sessions can opt into one with `role`.
`mcpServers`	object[]	No	MCP server connections available to MCP toolsets. Defaults to `[]`.
`rateLimits`	object	No	Per-user limits for this agent. `conversationsPerMinute` accepts an integer from 1 through 300; `messagesPerMinute` accepts an integer from 1 through 1,000. Omitted fields default to 5 and 100, respectively.
`metadata`	object	No	String-keyed metadata values for your own tracking.

Tool objects can be built-in toolsets, MCP toolsets, or custom tools. See Tools for full details. Role objects use this shape:

Field	Type	Required	Description
`name`	string	Yes	Role name passed to `POST /v1/sessions` as `role`.
`description`	string	No	Human-readable explanation for the role.
`tools`	object[]	Yes	Tool configuration used when a session runs with this role.

When a session specifies a role, that role’s tools replace the agent version’s top-level tools for approval decisions. Sessions without a role use the version’s top-level tools. Custom tools use this shape:

Field	Type	Required	Description
`type`	string	Yes	Must be `custom_tool`.
`name`	string	Yes	Tool name.
`description`	string	Yes	Tool description for the agent.
`input_schema`	object	Yes	JSON-schema-like object input schema.
`enabled`	boolean	No	Defaults to `true`.

Example custom tool:

{
  "type": "custom_tool",
  "name": "check_order_status",
  "description": "Look up an order by ID.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string", "description": "Customer order ID" }
    },
    "required": ["order_id"],
    "additionalProperties": false
  },
  "enabled": true
}

Response

{
  "id": "agent_123",
  "name": "Acme Creative Agent",
  "status": "active",
  "metadata": {
    "productArea": "media-generation"
  },
  "createdAt": "2026-06-20T23:12:04.746Z",
  "updatedAt": "2026-06-20T23:12:04.746Z",
  "rateLimits": {
    "conversationsPerMinute": 5,
    "messagesPerMinute": 100
  },
  "version": {
    "id": "version_123",
    "version": 0,
    "modelName": "openai/gpt-4o-mini",
    "systemPrompt": "Help Acme plan and execute media workflows.",
    "skills": [],
    "roles": [],
    "mcpServers": [],
    "metadata": {
      "productArea": "media-generation"
    },
    "createdAt": "2026-06-20T23:12:04.746Z"
  },
  "tools": [
    {
      "type": "agent_toolset",
      "defaultConfig": {
        "enabled": true,
        "permissionPolicy": { "type": "always_ask" }
      },
      "configs": []
    }
  ]
}

Agent list, get, create, update, and rate-limit update responses include rateLimits.

List agents

GET /v1/agents

Returns agents owned by the API key’s organization, newest first.

curl "https://api.herm.run/v1/agents?limit=20&offset=0" \
  -H "x-api-key: $HERM_API_KEY"

Query	Type	Description
`limit`	integer	Page size, 1 to 100. Defaults to `50`.
`offset`	integer	Offset for pagination. Defaults to `0`.
`status`	string	Optional agent status filter, such as `active` or `archived`.

Get an agent

GET /v1/agents/{agentId}

Returns the latest agent definition and version.

curl "https://api.herm.run/v1/agents/agent_123" \
  -H "x-api-key: $HERM_API_KEY"

Update an agent

POST /v1/agents/{agentId}

Fully replaces the agent configuration and always creates a new immutable agent version. Use this method when removing skills or tools. New sessions always use the latest version and cannot select a historical one. Existing session records retain the version selected when they were created.

curl -X POST "https://api.herm.run/v1/agents/agent_123" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $HERM_API_KEY" \
  -d '{
    "name": "Acme Creative Agent v2",
    "modelName": "openai/gpt-4o-mini",
    "systemPrompt": "Answer in one concise sentence.",
    "skills": [],
    "tools": [],
    "mcpServers": [],
    "metadata": {
      "revision": "v2"
    }
  }'

Partially update an agent

PATCH /v1/agents/{agentId}

Publishes a new immutable version while preserving omitted configuration. Collection entries are upserted instead of replacing the whole collection. This lets you update one skill or tool without fetching and resending every other entry.

curl -X PATCH "https://api.herm.run/v1/agents/agent_123" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $HERM_API_KEY" \
  -d '{
    "skills": [
      {
        "name": "customer-support",
        "content": "# Customer Support\n\nUse the updated escalation policy."
      }
    ],
    "expectedVersion": 3
  }'

The patch may contain name, modelName, systemPrompt, skills, tools, roles, mcpServers, metadata, and expectedVersion. At least one field other than expectedVersion is required.

Collection	Matching identity
`skills`	`name`
`tools`	`type` plus `name` for custom tools, or `mcpServerName` for MCP toolsets
`roles`	`name`
`mcpServers`	`name`

A matching entry is replaced with the supplied object. An entry with a new identity is appended, and all entries not included in the request are preserved. Passing an empty collection does not remove existing entries; use the full POST update when you intend to remove skills or tools. expectedVersion is optional. When provided, it must equal the current version or the request returns 409 conflict. When omitted, the gateway protects the version it read while applying the patch, so a concurrent update also returns 409 instead of overwriting changes. The response is the full agent representation with the newly created version.

Update per-user rate limits

PATCH /v1/agents/{agentId}/rate-limits

Updates mutable operational policy without creating a new agent version. The change applies immediately to every version and existing session for the agent.

curl -X PATCH "https://api.herm.run/v1/agents/agent_123/rate-limits" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $HERM_API_KEY" \
  -d '{
    "conversationsPerMinute": 10,
    "messagesPerMinute": 200
  }'

At least one field is required. Conversation limits accept integers from 1 through 300; user-event limits accept integers from 1 through 1,000. The response is the full agent representation. See Rate limits for scoping, counting, headers, and error behavior.

Archive an agent

POST /v1/agents/{agentId}/archive

Archives the agent. New sessions cannot be created from archived agents. Existing sessions remain accessible.

curl -X POST "https://api.herm.run/v1/agents/agent_123/archive" \
  -H "x-api-key: $HERM_API_KEY"

List versions

GET /v1/agents/{agentId}/versions

Returns the version history for an agent, newest first.

curl "https://api.herm.run/v1/agents/agent_123/versions?limit=20&offset=0" \
  -H "x-api-key: $HERM_API_KEY"

Get a version

GET /v1/agents/{agentId}/versions/{version}

Returns a historical agent version by version number.

curl "https://api.herm.run/v1/agents/agent_123/versions/1" \
  -H "x-api-key: $HERM_API_KEY"

Endpoint summary

Method	Path	Description
`POST`	`/v1/agents`	Create an agent and initial version.
`GET`	`/v1/agents`	List agents.
`GET`	`/v1/agents/{agentId}`	Retrieve an agent’s latest version.
`POST`	`/v1/agents/{agentId}`	Fully replace an agent and create a new version.
`PATCH`	`/v1/agents/{agentId}`	Partially update an agent and create a new version.
`PATCH`	`/v1/agents/{agentId}/rate-limits`	Update per-user limits without creating a version.
`POST`	`/v1/agents/{agentId}/archive`	Archive an agent.
`GET`	`/v1/agents/{agentId}/versions`	List versions.
`GET`	`/v1/agents/{agentId}/versions/{version}`	Retrieve a version.

Getting Started

Sessions and events

Capabilities

Integrations

Credentials

Resources

Agents

Create an agent

Request body

Response

List agents

Get an agent

Update an agent

Partially update an agent

Update per-user rate limits

Archive an agent

List versions

Get a version

Endpoint summary

​Create an agent

​Request body

​Response

​List agents

​Get an agent

​Update an agent

​Partially update an agent

​Update per-user rate limits

​Archive an agent

​List versions

​Get a version

​Endpoint summary

Create an agent

Request body

Response

List agents

Get an agent

Update an agent

Partially update an agent

Update per-user rate limits

Archive an agent

List versions

Get a version

Endpoint summary