> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hermai.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Actions

> Read and write actions that schemas expose.

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:

```json theme={null}
{
  "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:

```bash theme={null}
# 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:

```bash theme={null}
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](/concepts/schemas#contributing-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.