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

# Execute Action

> Perform an interaction on a page by executing a discovered action.

## `POST /api/sites/:slug/actions/:state/:action`

Navigates to the page state and executes the action's interaction code on the live page. Use this to click buttons, fill forms, submit data, and trigger any interaction the AI discovered.

When you call this endpoint, the execution server:

1. Looks up the manifest for the site
2. Finds the target state and action
3. Opens a new browser page
4. Navigates to the state's URL (expanding template variables from inputs)
5. Waits for the DOM to settle
6. Runs the action's code with the provided inputs
7. Returns the result

## Path parameters

<ParamField path="slug" type="string" required>
  The site identifier (e.g., `example-com`).
</ParamField>

<ParamField path="state" type="string" required>
  The state name from the manifest (e.g., `LoginPage`, `CheckoutPage`).
</ParamField>

<ParamField path="action" type="string" required>
  The action name within the state (e.g., `submit_login`, `add_to_cart`).
</ParamField>

## Request body

Action inputs are supplied as a flat JSON object. The available inputs are defined in the manifest under the action's `inputs` array.

```json theme={null}
{
  "email": "user@example.com",
  "password": "secret"
}
```

Actions with no inputs can be called with an empty body or `{}`.

## Example

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST http://127.0.0.1:8787/api/sites/example-com/actions/LoginPage/submit_login \
    -H "Content-Type: application/json" \
    -d '{"email": "user@example.com", "password": "secret"}'
  ```

  ```json Response theme={null}
  {
    "ok": true,
    "state": "LoginPage",
    "steps": [
      "navigate:https://example.com/login",
      "action:submit_login"
    ]
  }
  ```
</CodeGroup>

## Response fields

| Field   | Type      | Description                                  |
| ------- | --------- | -------------------------------------------- |
| `ok`    | `boolean` | `true` on success                            |
| `state` | `string`  | The state name where the action was executed |
| `steps` | `array`   | Ordered list of steps the executor performed |

## Error responses

| Status | Body                                                                     |
| ------ | ------------------------------------------------------------------------ |
| `404`  | `{ "error": "Manifest not found" }`                                      |
| `404`  | `{ "error": "State 'BadState' not found" }`                              |
| `404`  | `{ "error": "Route 'bad_action' not found" }`                            |
| `429`  | `{ "error": "Max concurrent executions (3) reached. Try again later." }` |
| `500`  | `{ "error": "Action 'submit_login' failed: <message>" }`                 |

<Warning>
  Actions execute on a real browser page. They perform real interactions — form submissions, button clicks, navigation. Make sure you understand what an action does before calling it against a production site.
</Warning>