---
title: "Cancel a pending approval request"
method: POST
path: "/api/approval-requests/{id}/cancel"
tags: ["ApprovalRequests"]
---

# Cancel a pending approval request

`POST /api/approval-requests/{id}/cancel`

## Request

- Base URL: `http://localhost:3013`
- URL: `http://localhost:3013/api/approval-requests/{id}/cancel`
- Auth: HTTP bearer

## Path parameters

- `id` string, uuid, required

## Request body

- object
  - `reason` string

## Response `200`

Request cancelled, or already cancelled. A request that gates a running or waiting workflow run cancels that run too.

- object
  - `approvalRequest` object, required
    - `id` string, required
    - `title` string, required
    - `questions` object[], required
      - `id` string, required
      - `type` 'approval' | 'text' | 'single-select' | 'multi-select' | 'boolean' | 'config', required
      - `label` string, required
      - `required` boolean
      - `description` string
      - `placeholder` string
      - `multiline` boolean
      - `options` object[]
        - `value` string, required
        - `label` string, required
        - `description` string
      - `minSelections` integer
      - `maxSelections` integer
      - `defaultValue` boolean
      - `config` object: Config question settings. Answers are written to swarm_config and replaced by a result that never holds a secret value.
        - `key` string, required: The swarm config key to set, e.g. BITBUCKET_TOKEN
        - `scope` 'global' | 'agent' | 'repo', required: Config scope the value is written to
        - `scopeId` string: Agent or repo id for agent/repo scope. From request-human-input, agent scope defaults to the calling agent; pass it explicitly when asking on behalf of another agent.
        - `isSecret` boolean: Store encrypted and never show the value (default true). An existing secret row always stays secret.
        - `helpUrl` string, uri: Link shown next to the field, e.g. where to create the token
        - `options` object[]: Allowed values for a non-secret key, rendered as a choice
          - `value` string, required
          - `label` string, required
          - `description` string
        - `defaultValue` string: Prefilled value for a non-secret key
    - `workflowRunId` string, nullable, required
    - `workflowRunStepId` string, nullable, required
    - `sourceTaskId` string, nullable, required
    - `approvers` object, required
      - `users` string[]
      - `roles` string[]
      - `policy` union, required
        - 'any'
        - 'all'
        - object
          - `min` integer, required
    - `status` 'pending' | 'approved' | 'rejected' | 'timeout' | 'cancelled', required
    - `responses` object, nullable, required
    - `approvals` object[], nullable, required: Every accepted answer, in order. A request with an `all` or `{ min: N }` policy stays pending until enough approve.
      - `responder` string, required: Who answered, from the credential: a user id, or `operator` for the shared key.
      - `approved` boolean, required
      - `responses` object, required
      - `claimedRespondedBy` string: The `respondedBy` the client sent. Unverified; display only.
      - `respondedAt` string, required
    - `approvalProgress` object, nullable, required: Quorum progress while the request is pending; null once it is resolved.
      - `approved` integer, required: Approvals that count toward the policy so far.
      - `required` integer, required: Approvals the policy needs before the request resolves.
    - `resolvedBy` string, nullable, required: Who resolved the request, from the credential: a user id, `operator` for the shared key, or an agent id for a cancellation.
    - `resolvedAt` string, nullable, required
    - `resolutionReason` string, nullable, required
    - `timeoutSeconds` number, nullable, required
    - `expiresAt` string, nullable, required
    - `notificationChannels` object[], nullable, required
      - `channel` 'slack' | 'email', required
      - `target` string, required
      - `messageTs` string
    - `createdBy` string
    - `createdAt` string, required
    - `updatedAt` string, required
    - `configState` object: Live state of each config question's key, by question id. Read at request time and never stored. `value` appears only for non-secret keys.
  - `alreadyCancelled` boolean, required
  - `runCancelled` boolean, required

## Other responses

- `403`: Caller may not cancel this request
- `404`: Not found
- `409`: Already resolved with approved, rejected, or timeout, or its expiresAt passed

## Changes

- **2026-10-23** `d41b785c6831`: 1 warning, 2 info
  - added the new `config` enum value to the `approvalRequest/questions/items/type` response property for the response status `200`
  - added the optional property `approvalRequest/configState` to the response with the `200` status
  - added the optional property `approvalRequest/questions/items/config` to the response with the `200` status
- **2026-10-05** `7b0e62d4b905`: 2 info
  - added the required property `approvalRequest/approvalProgress` to the response with the `200` status
  - added the required property `approvalRequest/approvals` to the response with the `200` status
- **2026-09-28** `0a7da444e778`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/changes/api/approval-requests/:id/cancel/post.md)

---

[API](https://skmtc.dev/desplega-ai/apis/agent-swarm-api.md) - [All operations](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/llms.txt) - [OpenAPI document](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/revisions/7e4c7198192a?raw)