Skip to main content
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

KindWhat it doesExample
api_callCall a JSON API endpointPOST /cart/add.js on Shopify
navigateFetch a page by URLGET /products/cruiser
searchSearch the siteGET /search?q={query}
paginateMove through result pagesGET /items?page={page}
submit_formSubmit an HTML formPOST /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 directly.

​
Parameters

Each action lists its parameters with:
FieldMeaning
nameParameter name (e.g. id, query, page)
sourceWhere it goes: body, query, path
requiredWhether 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

There is no special execution layer in the current release. Your agent calls the 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}'
The catalog gives you the recipe. Your agent (or HTTP client) executes it.

​
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.