Skip to main content

​
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

​
slug
string
required
The site identifier (e.g., example-com).
​
state
string
required
The state name from the manifest (e.g., LoginPage, CheckoutPage).
​
action
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"}'

​
Response fields

FieldTypeDescription
okbooleantrue on success
statestringThe state name where the action was executed
stepsarrayOrdered list of steps the executor performed

​
Error responses

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