Hooks API - Autosana

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

flow_id

string

Optional. Filter to setup/teardown hooks attached to this flow. Runtime hooks (embedded in flow instructions as ${hooks:NAME}) are NOT returned.

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"

Response Fields

hooks

array

List of hook objects.

Show Hook object

string

Unique identifier (UUID).

name

string

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

script

string

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

script_type

string

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

description

string | null

Optional human-readable note.

created_at

string

ISO 8601 timestamp.

updated_at

string

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

count

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",
      "created_at": "2026-01-15T10:31:00Z"
    }
  ],
  "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

name

string

required

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

script

string

required

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

script_type

string

required

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

description

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.

hook_id

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.

hook_id

string

required

UUID of the hook.

script

string

New script content.

script_type

string

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

description

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.

hook_id

string

required

UUID of the hook.

force

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

environment_id

string

required

UUID of the environment whose env vars to inject.

script_override

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

success

boolean

Whether the hook executed successfully.

status_code

integer | null

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

output

string

Captured stdout/stderr from the sandbox.

execution_time_ms

integer

Wall-clock duration in milliseconds.

error

string | null

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

Documentation Index

​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