Actions - Hermai

An action is a single thing your agent can do on a website: read a product catalog, add an item to a cart, search for listings, submit a form. Schemas describe actions alongside endpoints, giving your agent a menu of capabilities for each site.

Action types

Kind	What it does	Example
`api_call`	Call a JSON API endpoint	`POST /cart/add.js` on Shopify
`navigate`	Fetch a page by URL	`GET /products/cruiser`
`search`	Search the site	`GET /search?q={query}`
`paginate`	Move through result pages	`GET /items?page={page}`
`submit_form`	Submit an HTML form	`POST /contact`

Reading actions from the catalog

When you call GET /v1/catalog/{domain}, the response includes both read endpoints and write actions in the same list:

{
  "endpoints": [
    {
      "name": "shopify_products",
      "method": "GET",
      "url": "https://www.allbirds.com/products.json",
      "description": "Product catalog"
    },
    {
      "name": "add_to_cart",
      "method": "POST",
      "url": "https://www.allbirds.com/cart/add.js",
      "headers": { "Content-Type": "application/json" },
      "kind": "api_call",
      "description": "Add a product variant to the cart",
      "params": [
        { "name": "id", "source": "body", "required": true },
        { "name": "quantity", "source": "body", "required": true }
      ]
    }
  ]
}

Your agent reads the method, url, headers, and params fields and constructs the HTTP request. For registered endpoints that support hosted execution, you can also call POST /v1/fetch with the endpoint name and params.

Parameters

Each action lists its parameters with:

Field	Meaning
`name`	Parameter name (e.g. `id`, `query`, `page`)
`source`	Where it goes: `body`, `query`, `path`
`required`	Whether the parameter is mandatory

For body parameters, your agent builds a JSON object. For query parameters, it appends to the URL. For path parameters, it fills in {placeholder} segments in the URL template.

Executing actions

You can execute a schema in two ways. For self execution, your agent calls the upstream site directly:

# Read: get the product catalog
curl "https://www.allbirds.com/products.json"

# Write: add to cart
curl -X POST "https://www.allbirds.com/cart/add.js" \
     -H "Content-Type: application/json" \
     -d '{"id": 41397031600208, "quantity": 1}'

For hosted execution, call Hermai with the registered site, endpoint, and params:

curl -sS -X POST "https://api.hermai.ai/v1/fetch" \
  -H "Authorization: Bearer ${HERMAI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "site": "semanticscholar.org",
    "endpoint": "get_paper",
    "params": {
      "paper_id": "ARXIV:1706.03762",
      "fields": "title,authors,year"
    }
  }'

The catalog gives you the recipe. Hosted fetch runs registered endpoints through Hermai.

Actions in contributed schemas

When you contribute a schema, you can include actions alongside endpoints. Write actions (add-to-cart, submit form, login) are easiest to capture with hermai intercept, which launches a browser, lets you perform the action in the UI, and records the underlying XHR request for replay.

​Action types

​Reading actions from the catalog

​Parameters

​Executing actions

​Actions in contributed schemas

Action types

Reading actions from the catalog

Parameters

Executing actions

Actions in contributed schemas