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

# Response actions

> Propose, preview, and undo response actions, and read or change the project's auto-run policy.

Response actions follow one policy: nothing runs on its own by default, a project can turn on
auto-run for reversible actions, and an irreversible action always needs a person. See
[Response actions](https://docs.squasher.ai/features/response-actions.md).

| Operation | Route | Scope | Use |
| - | - | - | - |
| `actions.get` | `GET /v1/projects/{project_id}/actions/{action_id}` | `investigations:read` | Read one action with its effect and undo action. |
| `actions.propose` | `POST /v1/projects/{project_id}/actions` | `investigations:write` | Propose an action, or preview it. |
| `actions.undo` | `POST /v1/projects/{project_id}/actions/{action_id}/undo` | `investigations:write` | Propose the undo of a succeeded action. |
| `actions.getPolicy` | `GET /v1/projects/{project_id}/actions/policy` | `investigations:read` | Read the auto-run policy. |
| `actions.updatePolicy` | `PUT /v1/projects/{project_id}/actions/policy` | `actions:approve` | Turn auto-run of reversible actions on or off. |

## Propose an action

`actions.propose` and `actions.undo` need an `Idempotency-Key` header. The same key returns the
first proposal and runs nothing again. The same key with a different action returns `422`.

```bash theme={null}
curl --request POST \
  --url "https://api.squasher.ai/v1/projects/$SQUASHER_PROJECT_ID/actions" \
  --header "Authorization: Bearer $SQUASHER_API_KEY" \
  --header "Idempotency-Key: $(uuidgen)" \
  --header "Content-Type: application/json" \
  --data '{
    "provider": "aws",
    "action_id": "iam.deactivate_access_key",
    "title": "Deactivate the leaked key",
    "target": { "kind": "aws_access_key", "id": "AKIA..." },
    "params": { "user_name": "ci-bot" }
  }'
```

The response has `action` (with `effect`, `undo_action_id`, `status`, and `decided_by_type`),
`auto_run`, `created`, and `run_reason`. When `auto_run` is true, the policy approved the action and
it ran at once; `action.status` is the result.

## Preview

Add `?dry_run=true` to `actions.propose` or `actions.undo`. The response has `dry_run: true`, the
`change`, the `precondition` read from the provider, `effect`, `undo_action_id`, `auto_run`, and
`requires_approval`. Nothing is stored and nothing changes. A dry run needs no `Idempotency-Key`.

## Undo

`POST /v1/projects/{project_id}/actions/{action_id}/undo` proposes the undo action of a succeeded
reversible action on the same target. It returns `409` for an irreversible action or an action that
did not succeed.

## Policy

```json theme={null}
{
  "policy": {
    "auto_reversible": false,
    "irreversible_requires_approval": true,
    "updated_at": null,
    "updated_by": null
  }
}
```

Only an owner or admin, signed in as a person, can change the policy. The body is
`{ "auto_reversible": true }`; there is no setting for irreversible actions. Each change is written
to the audit log.

## Approve

Approve with `actions.approve` (see [Investigations](https://docs.squasher.ai/api-reference/investigations.md)). An
irreversible action can be approved only in the dashboard. OAuth tokens, such as the token of an
MCP client or the CLI, get `403`.


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