Hooks API

These endpoints let you create, read, update, and delete hooks — the setup, teardown, and runtime scripts that prepare app state and bridge your backend with the Autosana agent. All requests require an API key in the X-API-Key header. See API Reference for authentication and the standard 401 / 403 / 429 / 500 error shapes shared by every endpoint on this page.

This API covers hook CRUD and test execution. To attach a hook as a setup/teardown step on a flow or suite, use the dashboard or the Autosana MCP. Runtime hooks need no attachment — reference them from flow instructions as ${hooks:Hook Name}.

List Hooks

GET /api/v1/hooks — Returns 200 OK

Query Parameters

string

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.

string

Optional. Filter to setup/teardown hooks attached to this suite. Mutually exclusive with flow_id.

Example Request

curl -X GET https://backend.autosana.ai/api/v1/hooks \
  -H "X-API-Key: YOUR_API_KEY"

# Filter to a flow's setup/teardown hooks
curl -X GET "https://backend.autosana.ai/api/v1/hooks?flow_id=FLOW_UUID" \
  -H "X-API-Key: YOUR_API_KEY"

# Filter to a suite's setup/teardown hooks
curl -X GET "https://backend.autosana.ai/api/v1/hooks?suite_id=SUITE_UUID" \
  -H "X-API-Key: YOUR_API_KEY"

Response Fields

array

List of hook objects.

Show Hook object

string

Unique identifier (UUID).

string

Hook name. Referenced from flow instructions as ${hooks:NAME} for runtime hooks.

string

Full hook script (curl command, Python source, etc.).

string

One of curl, python, javascript, typescript, bash, launch_args.

string | null

Optional human-readable note.

string | null

Filename-derived identity (e.g. seed-db) used by code-managed tooling to name the exported hook file and to match on adopt-by-slug.

string

ISO 8601 timestamp.

string

ISO 8601 timestamp of the last modification. Useful for sync tooling that polls for drift.

array

Present only when filtering by flow_id or suite_id: which attachment(s) this hook has on that flow/suite — setup, teardown, or both (parallel to run_orders).

array

Present only when filtering by flow_id or suite_id: the execution order for each entry in hook_types, parallel by index.

integer

Total number of hooks returned.

Example Response

{
  "hooks": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Create Test User",
      "script": "curl -X POST https://api.example.com/users -d '{...}'",
      "script_type": "curl",
      "description": "Provisions a fresh test user before each flow",
      "slug": "create-test-user",
      "created_at": "2026-01-15T10:31:00Z",
      "updated_at": "2026-01-15T10:31:00Z",
      "hook_types": ["setup"],
      "run_orders": [1]
    }
  ],
  "count": 1
}

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 Created

Request Body

string

required

Name of the hook (1–255 characters). Used as the ${hooks:NAME} reference in flow instructions.

string

required

The script content (curl command, Python source, etc.).

string

required

One of curl, python, javascript, typescript, bash, launch_args. See Hook Types for what each one runs.

string

Optional description of what the hook does.

Example Request

curl -X POST https://backend.autosana.ai/api/v1/hooks \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Create Test User",
    "script": "curl -X POST https://api.example.com/users -H \"Content-Type: application/json\" -d \"{\\\"email\\\":\\\"test@example.com\\\"}\"",
    "script_type": "curl",
    "description": "Provisions a fresh test user"
  }'

Example Response

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "name": "Create Test User",
  "script": "curl -X POST https://api.example.com/users ...",
  "script_type": "curl",
  "description": "Provisions a fresh test user",
  "created_at": "2026-01-15T10:31:00Z"
}

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.

string

required

UUID of the hook.

curl -X GET https://backend.autosana.ai/api/v1/hooks/HOOK_UUID \
  -H "X-API-Key: YOUR_API_KEY"

Update Hook

Update a hook’s script, script_type, and/or description. Omitted fields are left unchanged.

Hook names cannot be updated. Runtime hooks reference hooks by name in flow instructions (${hooks:NAME}), so renaming would silently break those references. To rename safely: create a new hook, update every flow that references the old name to use the new one, then delete the old hook. There is no atomic rename.

PATCH /api/v1/hooks/{hook_id} — Returns 200 OK. 400 if no recognized fields are provided. 404 if the hook does not exist.

string

required

UUID of the hook.

string

New script content.

string

New script type (curl, python, javascript, typescript, bash, launch_args).

string | null

New description. Pass "" or null to clear.

curl -X PATCH https://backend.autosana.ai/api/v1/hooks/HOOK_UUID \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "script": "curl -X POST https://api.example.com/v2/users" }'

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 returns 409 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.

string

required

UUID of the hook.

boolean

Defaults to false. When true, deletes the hook even if it’s attached to flows or suites — those attachments are deactivated.

force=true detaches the hook from every flow and suite at once. There’s no per-attachment opt-out, no dry-run, and no undo. Inspect the 409 conflict response (without force) first to see exactly which flows/suites will be affected.

# Refuses to delete if attached anywhere
curl -X DELETE https://backend.autosana.ai/api/v1/hooks/HOOK_UUID \
  -H "X-API-Key: YOUR_API_KEY"

# Force delete + detach
curl -X DELETE "https://backend.autosana.ai/api/v1/hooks/HOOK_UUID?force=true" \
  -H "X-API-Key: YOUR_API_KEY"

Example 409 Response

{
  "detail": "Hook 'Create Test User' is used in flow(s): Login Flow. Deleting will detach it from these flows/suites. Pass ?force=true to delete anyway."
}

Test Hook

Execute the hook in isolation against a chosen environment and return the result. Uses a shorter 60-second timeout for fast feedback.

POST /api/v1/hooks/{hook_id}/test — Returns 200 OK. 404 if the hook does not exist.

Request Body

string

required

UUID of the environment whose env vars to inject.

string

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

Example Request

# Test the saved script
curl -X POST https://backend.autosana.ai/api/v1/hooks/HOOK_UUID/test \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "environment_id": "ENV_UUID" }'

# Test a proposed script change without saving
curl -X POST https://backend.autosana.ai/api/v1/hooks/HOOK_UUID/test \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environment_id": "ENV_UUID",
    "script_override": "curl -X POST https://api.example.com/v2/users -d \"{...}\""
  }'

Response Fields

boolean

Whether the hook executed successfully.

integer | null

Exit code (for scripts) or HTTP status (for curl).

string

Captured stdout/stderr from the sandbox.

integer

Wall-clock duration in milliseconds.

string | null

Category of failure when success=false (e.g. Execution timed out, Missing environment variable).

Getting Started

Core Features

Best Practices

Code-Managed Flows

Guides

Integrations

Uploading Your App

APIs

List Hooks

Query Parameters

Example Request

Response Fields

Example Response

Create Hook

Request Body

Example Request

Example Response

Get Hook

Update Hook

Delete Hook

Example 409 Response

Test Hook

Request Body

Example Request

Response Fields

​List Hooks

​Query Parameters

​Example Request

​Response Fields

​Example Response

​Create Hook

​Request Body

​Example Request

​Example Response

​Get Hook

​Update Hook

​Delete Hook

​Example 409 Response

​Test Hook

​Request Body

​Example Request

​Response Fields

List Hooks

Query Parameters

Example Request

Response Fields

Example Response

Create Hook

Request Body

Example Request

Example Response

Get Hook

Update Hook

Delete Hook

Example 409 Response

Test Hook

Request Body

Example Request

Response Fields