> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Hooks API

> Manage hooks (curl, scripts, app launch args) programmatically

These endpoints let you create, read, update, and delete [hooks](/docs/hooks.md) — the setup, teardown, and runtime scripts that prepare app state and bridge your backend with the BugRadar agent.

Requests authenticate with an API key in the `X-API-Key` header. The [Test Hook](#test-hook) endpoint also accepts a signed-in user's session token. See [API Reference](/docs/api-reference.md) for authentication and the standard `401` / `403` / `429` / `500` error shapes shared by every endpoint on this page.

> [!TIP]
>
> 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](https://usebugradar.com/hooks) or the BugRadar MCP. Runtime hooks need no attachment — reference them from flow instructions as `${hooks:Hook Name}`.

***

## List Hooks

> [!NOTE]
>
> **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. Mutually exclusive with `suite_id`.

**suite\_id** `string`

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

### Example Request

```bash theme={null}
curl -X GET https://backend.usebugradar.com/api/v1/hooks \
  -H "X-API-Key: YOUR_API_KEY"

# Filter to a flow's setup/teardown hooks
curl -X GET "https://backend.usebugradar.com/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.usebugradar.com/api/v1/hooks?suite_id=SUITE_UUID" \
  -H "X-API-Key: YOUR_API_KEY"
```

### Response Fields

**hooks** `array`

List of hook objects.

**Hook object**

**id** `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.

**slug** `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.

**created\_at** `string`

ISO 8601 timestamp.

**updated\_at** `string`

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

**hook\_types** `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`).

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

**count** `integer`

Total number of hooks returned.

#### Example Response

```json theme={null}
{
  "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.

> [!NOTE]
>
> **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](/docs/hooks.md#hook-types) for what each one runs.

**description** `string`

Optional description of what the hook does.

### Example Request

```bash theme={null}
curl -X POST https://backend.usebugradar.com/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

```json theme={null}
{
  "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

> [!NOTE]
>
> **GET** `/api/v1/hooks/{hook_id}` — Returns `200 OK` with the same shape as items in [List Hooks](#list-hooks), or `404` if the hook does not exist.

**hook\_id** `string` *required*

UUID of the hook.

```bash theme={null}
curl -X GET https://backend.usebugradar.com/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.

> [!WARNING]
>
> **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.

> [!NOTE]
>
> **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.

```bash theme={null}
curl -X PATCH https://backend.usebugradar.com/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.

> [!NOTE]
>
> **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.

> [!WARNING]
>
> `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.

```bash theme={null}
# Refuses to delete if attached anywhere
curl -X DELETE https://backend.usebugradar.com/api/v1/hooks/HOOK_UUID \
  -H "X-API-Key: YOUR_API_KEY"

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

#### Example 409 Response

```json theme={null}
{
  "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.

Authenticate with `X-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.

> [!NOTE]
>
> **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

```bash theme={null}
# Test the saved script
curl -X POST https://backend.usebugradar.com/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.usebugradar.com/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`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.