---
title: "Submit an approval decision on a trail"
method: POST
path: "/api/v1/trails/{forge}/{owner}/{repo}/{number}/approvals"
tags: ["Trails"]
---

# Submit an approval decision on a trail

`POST /api/v1/trails/{forge}/{owner}/{repo}/{number}/approvals`

## Path parameters

- `forge` string, required
- `owner` string, required
- `repo` string, required
- `number` string, required

## Request body

- object
  - `event` 'APPROVE' | 'REQUEST_CHANGES', required — Approval action
  - `body` string — Approval comment (required for REQUEST_CHANGES)

## Response `200`

Approval submitted

- object
  - `ok` boolean, required
  - `approval` object, required
    - `id` string, required
    - `author` string, required
    - `event` string, required
    - `body` string, nullable, required
    - `commit_sha` string, required
    - `created_at` string, required
  - `gates` object, nullable, required
    - `head_sha` string, nullable, required
    - `gates` object[], required
      - `reviewers` object[]
        - `login` string, required
        - `state` 'pending' | 'approved' | 'stale' | 'changes_requested' | 'excluded', required
        - `reviewed_head_sha` string, nullable, required
        - `reason` string, nullable, required
      - `runner_ids` string[]
      - `state` 'not_run' | 'running' | 'evaluated' | 'stale' | 'disabled' | 'not_applicable' | 'configuration_error'
      - `outcome` 'passed' | 'failed' | 'errored', nullable
      - `evaluated_at_sha` string, nullable
      - `stale_reason` 'head_moved' | 'config_changed', nullable
      - `finding_count` number, nullable
      - `id` string, required
      - `gate_definition_id` string, required
      - `gate_key` string, required
      - `gate_type` 'approvals' | 'findings' | 'checks' | 'up_to_date' | 'base_checks' | 'eval', required
      - `blocking` boolean, required
      - `status` 'passed' | 'failed' | 'pending' | 'error' | 'skipped', required
      - `head_sha` string, nullable, required
      - `value` unknown, required
      - `rationale` string, nullable, required
      - `created_at` string, required
      - `completed_at` string, nullable, required
    - `blocking_failures` object[], required
      - `reviewers` object[]
        - `login` string, required
        - `state` 'pending' | 'approved' | 'stale' | 'changes_requested' | 'excluded', required
        - `reviewed_head_sha` string, nullable, required
        - `reason` string, nullable, required
      - `runner_ids` string[]
      - `state` 'not_run' | 'running' | 'evaluated' | 'stale' | 'disabled' | 'not_applicable' | 'configuration_error'
      - `outcome` 'passed' | 'failed' | 'errored', nullable
      - `evaluated_at_sha` string, nullable
      - `stale_reason` 'head_moved' | 'config_changed', nullable
      - `finding_count` number, nullable
      - `id` string, required
      - `gate_definition_id` string, required
      - `gate_key` string, required
      - `gate_type` 'approvals' | 'findings' | 'checks' | 'up_to_date' | 'base_checks' | 'eval', required
      - `blocking` boolean, required
      - `status` 'passed' | 'failed' | 'pending' | 'error' | 'skipped', required
      - `head_sha` string, nullable, required
      - `value` unknown, required
      - `rationale` string, nullable, required
      - `created_at` string, required
      - `completed_at` string, nullable, required
    - `mergeable` boolean, required
    - `evaluated_at` string, nullable, required

## Other responses

- `400` — Validation error
- `404` — Trail not found

## Changes

- **2026-09-24** `ba1409f8f36b` — 2 warning
  - added the new `base_checks` enum value to the `gates/anyOf[subschema #1]/blocking_failures/items/gate_type` response property for the response status `200`
  - added the new `base_checks` enum value to the `gates/anyOf[subschema #1]/gates/items/gate_type` response property for the response status `200`
- **2026-09-17** `e1f0e2f14d0a` — 2 info
  - added the optional property `gates/anyOf[subschema #1]/blocking_failures/items/reviewers` to the response with the `200` status
  - added the optional property `gates/anyOf[subschema #1]/gates/items/reviewers` to the response with the `200` status

[Change history](https://skmtc.dev/entire/apis/entire-api/changes/api/v1/trails/:forge/:owner/:repo/:number/approvals/post.md)

---

[API](https://skmtc.dev/entire/apis/entire-api.md) · [All operations](https://skmtc.dev/entire/apis/entire-api/llms.txt) · [OpenAPI document](https://skmtc.dev/entire/apis/entire-api/revisions/d69a682d6e44?raw)