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

# Approve Change

> Record your approval and merge the change once the folder's approval rule is satisfied.

<Note>
  You must have `OWNERS` **write** authority on every path the change touches.
  Self-approval is rejected when a folder rule requires distinct approvers. The
  change merges to the Ontology only once the required approvals are met;
  until then the response reports `merged: false` with the running
  `approval_count` / `required_approvals`.
</Note>

<Warning>
  Two behaviors matter when you describe this control to an auditor:

  Organization admins hold full Library access, so they count as an Owner of
  every path for approval purposes even when they are not listed in the folder's
  `OWNERS` file. Your approver population for a governed folder is its declared
  Owners plus every org admin.

  An approval rule scoped to a set of author roles applies only to authors
  holding one of those roles. Any other author is outside the rule, and their
  changes to that folder apply on their own authority. Leave the author roles
  empty for a rule that must govern every author.
</Warning>


## OpenAPI

````yaml POST /v2/changes/{id}/approve
openapi: 3.1.0
info:
  title: TextQL v2 API
  version: '2.0'
  description: >
    REST API for TextQL platform operations. All endpoints require Bearer token
    authentication.
servers:
  - url: https://app.textql.com
security:
  - bearerAuth: []
tags:
  - name: Chat
    description: Create and manage AI chat sessions
  - name: Connectors
    description: List available data connectors
  - name: Playbooks
    description: Create, configure, and run automated playbooks
  - name: Sandcastles
    description: Manage Python sandbox environments for code execution
  - name: Changes
    description: Review, approve, and deny Ontology changes
  - name: API Keys
    description: Mint and revoke scoped platform API keys
paths:
  /v2/changes/{id}/approve:
    post:
      tags:
        - Changes
      summary: Approve Change
      description: |
        Record the caller's approval and merge the change to the Ontology
        once the folder's approval rule is satisfied. The caller must have
        `OWNERS` write authority on every path the change touches. Self-approval
        is rejected when a folder rule requires distinct approvers.
      operationId: v2.approveChange
      parameters:
        - $ref: '#/components/parameters/ChangeId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExpectedGitRefBody'
      responses:
        '200':
          description: Approval recorded (and merged when the rule is satisfied)
          content:
            application/json:
              schema:
                type: object
                properties:
                  merged:
                    type: boolean
                  approval_count:
                    type: integer
                    format: int32
                  required_approvals:
                    type: integer
                    format: int32
                  already_approved:
                    type: boolean
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Change is not OPEN/DRAFT, or expected_git_ref is stale
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    ChangeId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Change ID
  schemas:
    ExpectedGitRefBody:
      type: object
      required:
        - expected_git_ref
      properties:
        expected_git_ref:
          type: string
          description: The change git_ref the caller reviewed; a stale value returns 409.
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code
              enum:
                - invalid_request
                - unauthenticated
                - permission_denied
                - not_found
                - conflict
                - rate_limit_exceeded
                - internal
                - timeout
                - cancelled
                - execution_failed
                - no_report
            message:
              type: string
              description: Human-readable error message
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: invalid_request
              message: Invalid request body
    Unauthorized:
      description: Missing or invalid authentication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: unauthenticated
              message: Authentication required
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: permission_denied
              message: Insufficient permissions
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: not_found
              message: Resource not found
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: rate_limit_exceeded
              message: Rate limit exceeded
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: internal
              message: Internal server error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or JWT token

````

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