---
title: "Create a new approval request"
method: POST
path: "/api/approval-requests"
tags: ["ApprovalRequests"]
---

# Create a new approval request

`POST /api/approval-requests`

## Request body

- object
  - `title` string, required
  - `questions` object[], required
    - `id` string, required
    - `type` 'approval' | 'text' | 'single-select' | 'multi-select' | 'boolean', 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
  - `approvers` object, required
    - `users` string[]
    - `roles` string[]
    - `policy` union, required
      - 'any'
      - 'all'
      - object
        - `min` integer, required
  - `workflowRunId` string, uuid
  - `workflowRunStepId` string, uuid
  - `sourceTaskId` string, uuid
  - `timeoutSeconds` integer
  - `notifications` object[]
    - `channel` 'slack' | 'email', required
    - `target` string, required

## Response `201`

Approval request created

- object
  - `approvalRequest` object, required
    - `id` string, required
    - `title` string, required
    - `questions` object[], required
      - `id` string, required
      - `type` 'approval' | 'text' | 'single-select' | 'multi-select' | 'boolean', 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
    - `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
    - `resolvedBy` string, nullable, required
    - `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

## Other responses

- `400` — Validation error

## Changes

- **2026-09-02** `781ead084899` — 1 warning, 1 info
  - added the new `cancelled` enum value to the `approvalRequest/status` response property for the response status `201`
  - added the required property `approvalRequest/resolutionReason` to the response with the `201` status
- **2026-08-07** `06cac6a7c5bc` — 2 info
  - added the media type `application/json` for the response with the status `201`
  - added the media type `application/json` for the response with the status `400`

[Change history](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/changes/api/approval-requests/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-service-production.skmtc.workers.dev/v1/apis/desplega-ai/agent-swarm-api/revisions/e0acd2155cad/schema)