---
title: "Create HITL approval request"
method: POST
path: "/api/v1/hitl/queue"
tags: ["HITL"]
---

# Create HITL approval request

`POST /api/v1/hitl/queue`

## Request

- Base URL: `https://agent.getaxonflow.com`
- URL: `https://agent.getaxonflow.com/api/v1/hitl/queue`
- Auth: none declared. Required headers: `Authorization`
- TypeScript: <https://skmtc.dev/getaxonflow/apis/axonflow-agent-api/docs/api/v1/hitl/queue/post.ts> (a function with typed inputs; its response is checked against the schema)

Route a high-risk AI decision for human review.
EU AI Act Article 14 requires human oversight for high-risk AI systems.

Requires both `X-Org-ID` and `X-Tenant-ID` headers (stamped by the
auth middleware) — **400** when either is missing.

**Enterprise only** — community builds expose only
`GET /api/v1/hitl/status`.

## Headers

- `Authorization` string, required
- `Idempotency-Key` string

## Request body

- HITLCreateRequest: Body for POST /api/v1/hitl/queue. Org/tenant identity comes from the `X-Org-ID` / `X-Tenant-ID` headers, not the body. Source of truth: `platform/agent/hitl/handler.go` (CreateRequestInput).
  - `client_id` string, required
  - `user_id` string
  - `original_query` string, required: The query/action awaiting human review
  - `request_type` string, required: Request classification (e.g. `mcp_query`, `llm_chat`)
  - `request_context` object
  - `triggered_policy_id` string, required
  - `triggered_policy_name` string, required
  - `trigger_reason` string, required
  - `severity` 'low' | 'medium' | 'high' | 'critical'
  - `eu_ai_act_article` string
  - `compliance_framework` string
  - `risk_classification` string
  - `expires_in_seconds` integer: TTL before the request auto-expires
  - `notify_url` string, uri: Optional outbound webhook URL fired asynchronously after the request transitions to a terminal state (approved / rejected / overridden / expired). Must use `https://` or `http://`. The platform signs the envelope with HMAC-SHA256 over the body keyed by the deployment's `AXONFLOW_HITL_WEBHOOK_SIGNING_KEY`, sent as `X-AxonFlow-Signature: sha256=<hex>`. See the HITLWebhookEnvelope schema and `docs.getaxonflow.com/docs/governance/hitl` for the full shape + verification recipe.

## Response `201`

Approval request created

- object
  - `success` boolean
  - `data` HITLApprovalRequest: An approval-queue row. Source of truth: `platform/agent/hitl/repository.go` (ApprovalRequest).
    - `id` integer
    - `request_id` string, uuid
    - `org_id` string
    - `tenant_id` string
    - `client_id` string
    - `user_id` string
    - `original_query` string
    - `request_type` string
    - `request_context` object
    - `triggered_policy_id` string
    - `triggered_policy_name` string
    - `trigger_reason` string
    - `severity` string
    - `eu_ai_act_article` string
    - `compliance_framework` string
    - `risk_classification` string
    - `status` 'pending' | 'approved' | 'rejected' | 'overridden' | 'expired'
    - `reviewer_id` string
    - `reviewer_email` string
    - `reviewer_role` string
    - `review_comment` string
    - `reviewed_at` string, date-time
    - `override_justification` string
    - `override_authorized_by` string
    - `notify_url` string
    - `expires_at` string, date-time
    - `created_at` string, date-time
    - `updated_at` string, date-time

## Other responses

- `400`: Invalid request body or parameters
- `401`: Missing or invalid authentication. Handler-written 401s use the `{success, error}` envelope; 401s written by the auth middleware use the `{"error": {"code", "message"}}` envelope (JSONError).
- `403`: HITL approvals are disabled for the deployment's license tier. Entitled tiers are `Professional`, `Enterprise` and `Enterprise Plus`; `Community`, `Free`, `Pro`, `Premium` and `Evaluation` are refused (HITL became Enterprise-only on 2026-08-26; Evaluation was entitled until then). The refusal names no tier, because it is raised for five of them.
- `429`: Community SaaS pending-approvals cap reached for the tenant. Not returned on self-hosted or Enterprise deployments.

---

[API](https://skmtc.dev/getaxonflow/apis/axonflow-agent-api.md) - [All operations](https://skmtc.dev/getaxonflow/apis/axonflow-agent-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getaxonflow/apis/axonflow-agent-api/revisions/34d30fcb7fa1?raw)