Execute 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:

Looks up the manifest for the site
Finds the target state and action
Opens a new browser page
Navigates to the state’s URL (expanding template variables from inputs)
Waits for the DOM to settle
Runs the action’s code with the provided inputs
Returns the result

Path parameters

string

required

The site identifier (e.g., example-com).

string

required

The state name from the manifest (e.g., LoginPage, CheckoutPage).

string

required

The action name within the state (e.g., submit_login, add_to_cart).

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.

{
  "email": "user@example.com",
  "password": "secret"
}

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

Example

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"}'

{
  "ok": true,
  "state": "LoginPage",
  "steps": [
    "navigate:https://example.com/login",
    "action:submit_login"
  ]
}

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>" }`

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.

Overview

Endpoints

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

Path parameters

Request body

Example

Response fields

Error responses

​POST /api/sites/:slug/actions/:state/:action

​Path parameters

​Request body

​Example

​Response fields

​Error responses

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

Path parameters

Request body

Example

Response fields

Error responses