X-API-Key header. The Test Hook endpoint also accepts a signed-in user’s session token. See API Reference for authentication and the standard 401 / 403 / 429 / 500 error shapes shared by every endpoint on this page.
List Hooks
GET
/api/v1/hooks — Returns 200 OKQuery Parameters
Optional. Filter to setup/teardown hooks attached to this flow. Runtime hooks (embedded in flow instructions as
${hooks:NAME}) are NOT returned. Mutually exclusive with suite_id.Optional. Filter to setup/teardown hooks attached to this suite. Mutually exclusive with
flow_id.Example Request
Response Fields
Example Response
Create Hook
Create a new hook. Reference it in flow instructions as${hooks:NAME} for runtime use, or attach it as a setup/teardown hook from the dashboard.
POST
/api/v1/hooks — Returns 201 CreatedRequest Body
Name of the hook (1–255 characters). Used as the
${hooks:NAME} reference in flow instructions.One of
curl, python, javascript, typescript, bash, launch_args. See Hook Types for what each one runs.Example Request
Example Response
Get Hook
GET
/api/v1/hooks/{hook_id} — Returns 200 OK with the same shape as items in List Hooks, or 404 if the hook does not exist.Update Hook
Update a hook’sscript, script_type, and/or description. Omitted fields are left unchanged.
PATCH
/api/v1/hooks/{hook_id} — Returns 200 OK. 400 if no recognized fields are provided. 404 if the hook does not exist.Delete Hook
Deletes the hook. Past run history (the rows that referenced this hook when they ran) is preserved. If the hook is currently attached to one or more flows or suites, the call returns409 Conflict with the names of the affected resources. Pass ?force=true to detach and delete anyway — the setup/teardown attachments are deactivated as part of the delete.
DELETE
/api/v1/hooks/{hook_id} — Returns 204 No Content. 409 if the hook is in use and force=false. 404 if the hook does not exist.Defaults to
false. When true, deletes the hook even if it’s attached to flows or suites — those attachments are deactivated.Example 409 Response
Test Hook
Execute the hook in isolation against a chosen environment and return the result. Uses a shorter 60-second timeout for fast feedback. Authenticate withX-API-Key or Authorization: Bearer <session_access_token>. Both the hook and environment must belong to the authenticated organization. If both credentials are supplied, the API key takes precedence. The dashboard sends your session token automatically, so testing a hook there does not require creating or pasting an API key.
POST
/api/v1/hooks/{hook_id}/test — Returns 200 OK. 404 if the hook does not exist.Request Body
Optional. Test a modified script without saving the changes — useful for CI to dry-run a proposed update before persisting it via
PATCH /api/v1/hooks/{id}.