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

# Submit a human pull request review

> Submits a review (COMMENT, APPROVE or REQUEST_CHANGES, with inline comments) on a pull request as the caller's own GitHub user, never the app's, pinned to the head they inspected, and answers 201 with the review as GitHub reports it.

Use this tool when you need to:
- Approve a pull request, or request changes on it, as yourself
- Leave several inline comments on a pull request's lines in one review
- Make sure a verdict applies only to the commit that was actually read

Examples:
- POST /pull-requests/{pullRequestID}/github/reviews {"idempotency_key": "2b5d7c3a-1e4f-4a6b-8c9d-0e1f2a3b4c5d", "event": "APPROVE", "expected_head_sha": "9fceb02d0ae598e95dc970b74767f19372d61af8"}
- POST /pull-requests/6f1c2a9e-3b7d-4c55-9a2e-0d8b1f4e7c21/github/reviews {"idempotency_key": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "event": "REQUEST_CHANGES", "expected_head_sha": "9fceb02d0ae598e95dc970b74767f19372d61af8", "body": "The retry loop never backs off.", "comments": [{"path": "apps/api/github/client.go", "line": 42, "side": "RIGHT", "body": "Add a backoff here."}]}

Hints:
- pullRequestID is the pull request's uuid and org_id an optional uuid naming the owning organization to act in, the org_id getPullRequest answers. Required: idempotency_key (a uuid), event (COMMENT, APPROVE or REQUEST_CHANGES) and expected_head_sha (exactly 40 lowercase hex characters); optional: body and comments.
- Each comment requires path, line (at least 1) and body, path and body each with a character other than space, tab, newline, form feed or carriage return, and takes side LEFT or RIGHT (RIGHT when omitted).
- The schema answers 422 for a missing, malformed or unknown field and a body that is not JSON is 400; the handler answers 422, before the key is claimed, for REQUEST_CHANGES without a body, COMMENT with neither body nor comments, and a path or comment body that is only whitespace.
- expected_head_sha must be the pull request's head as Aether's mirror holds it (merge_box.head_sha from getPullRequestGithub); a head that moved past it is a 409 head_moved and nothing is posted. The review is made at that commit, so inline comments anchor to it.
- The idempotency key is the caller's on this pull request and claimed before GitHub is called: a completed key replays its review, read back from GitHub as the caller, and a key whose attempt failed before GitHub posted the review, head_moved included, or never finished is burnt: 409 idempotency_key_conflict. A review GitHub posted whose verdict then failed to record answers 500, and a retry with the same key records the verdict and replays the review without posting again.
- Answers 201 with github_review_id (an integer from 1 to 9007199254740991), author_login, author_is_bot, state, body, submitted_at and html_url; the verdict is stored at once, so getPullRequestGithub's reviews and reviewers show it before the webhook lands, and its webhook reaches the author task as human feedback.
- GitHub's 422 (an inline comment outside the diff, or approving one's own pull request) is a 422 with its message, and any other GitHub failure a 502.
- Use createPullRequestReviewRun instead to ask Aether to review the pull request, and createPullRequestGithubComment for a top-level comment without a verdict.
- A member with a product role (owner, admin or member) in an owning organization of the pull request (one whose task published or reviewed it, or with a project on its repository) may call it while they keep GitHub access to its repository; GitHub judges the review against the caller's own permission.
- A viewer or billing member is refused with 403 org_role_insufficient and a suspended organization with 403 org_suspended, each when no other owning organization admits the caller, and an agent host's grant with 403 agent_host_route_not_allowed; 503 when the membership check is unavailable.
- A caller linked to the repository's installation whose GitHub authorization is missing or revoked is refused with 409 github_identity_required (reconnect GitHub), whether at the gate or during the write.
- A pull request that does not exist, one no organization of the caller owns, an org_id that does not own it and one whose repository the caller cannot see on GitHub (no link to its installation included) answer the same 404; omitting org_id while more than one owning organization admits the caller is a 422 org_id_required, and a GitHub access check that cannot run is a 500.



## OpenAPI

````yaml api-reference/openapi.json POST /pull-requests/{pullRequestID}/github/reviews
openapi: 3.1.0
info:
  title: Aether API
  version: 0.1.0
servers:
  - url: https://api.runaether.dev
security:
  - bearerAuth: []
paths:
  /pull-requests/{pullRequestID}/github/reviews:
    post:
      tags:
        - pull-requests
      summary: Submit a human pull request review
      description: >-
        Submits a review (COMMENT, APPROVE or REQUEST_CHANGES, with inline
        comments) on a pull request as the caller's own GitHub user, never the
        app's, pinned to the head they inspected, and answers 201 with the
        review as GitHub reports it.


        Use this tool when you need to:

        - Approve a pull request, or request changes on it, as yourself

        - Leave several inline comments on a pull request's lines in one review

        - Make sure a verdict applies only to the commit that was actually read


        Examples:

        - POST /pull-requests/{pullRequestID}/github/reviews {"idempotency_key":
        "2b5d7c3a-1e4f-4a6b-8c9d-0e1f2a3b4c5d", "event": "APPROVE",
        "expected_head_sha": "9fceb02d0ae598e95dc970b74767f19372d61af8"}

        - POST
        /pull-requests/6f1c2a9e-3b7d-4c55-9a2e-0d8b1f4e7c21/github/reviews
        {"idempotency_key": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "event":
        "REQUEST_CHANGES", "expected_head_sha":
        "9fceb02d0ae598e95dc970b74767f19372d61af8", "body": "The retry loop
        never backs off.", "comments": [{"path": "apps/api/github/client.go",
        "line": 42, "side": "RIGHT", "body": "Add a backoff here."}]}


        Hints:

        - pullRequestID is the pull request's uuid and org_id an optional uuid
        naming the owning organization to act in, the org_id getPullRequest
        answers. Required: idempotency_key (a uuid), event (COMMENT, APPROVE or
        REQUEST_CHANGES) and expected_head_sha (exactly 40 lowercase hex
        characters); optional: body and comments.

        - Each comment requires path, line (at least 1) and body, path and body
        each with a character other than space, tab, newline, form feed or
        carriage return, and takes side LEFT or RIGHT (RIGHT when omitted).

        - The schema answers 422 for a missing, malformed or unknown field and a
        body that is not JSON is 400; the handler answers 422, before the key is
        claimed, for REQUEST_CHANGES without a body, COMMENT with neither body
        nor comments, and a path or comment body that is only whitespace.

        - expected_head_sha must be the pull request's head as Aether's mirror
        holds it (merge_box.head_sha from getPullRequestGithub); a head that
        moved past it is a 409 head_moved and nothing is posted. The review is
        made at that commit, so inline comments anchor to it.

        - The idempotency key is the caller's on this pull request and claimed
        before GitHub is called: a completed key replays its review, read back
        from GitHub as the caller, and a key whose attempt failed before GitHub
        posted the review, head_moved included, or never finished is burnt: 409
        idempotency_key_conflict. A review GitHub posted whose verdict then
        failed to record answers 500, and a retry with the same key records the
        verdict and replays the review without posting again.

        - Answers 201 with github_review_id (an integer from 1 to
        9007199254740991), author_login, author_is_bot, state, body,
        submitted_at and html_url; the verdict is stored at once, so
        getPullRequestGithub's reviews and reviewers show it before the webhook
        lands, and its webhook reaches the author task as human feedback.

        - GitHub's 422 (an inline comment outside the diff, or approving one's
        own pull request) is a 422 with its message, and any other GitHub
        failure a 502.

        - Use createPullRequestReviewRun instead to ask Aether to review the
        pull request, and createPullRequestGithubComment for a top-level comment
        without a verdict.

        - A member with a product role (owner, admin or member) in an owning
        organization of the pull request (one whose task published or reviewed
        it, or with a project on its repository) may call it while they keep
        GitHub access to its repository; GitHub judges the review against the
        caller's own permission.

        - A viewer or billing member is refused with 403 org_role_insufficient
        and a suspended organization with 403 org_suspended, each when no other
        owning organization admits the caller, and an agent host's grant with
        403 agent_host_route_not_allowed; 503 when the membership check is
        unavailable.

        - A caller linked to the repository's installation whose GitHub
        authorization is missing or revoked is refused with 409
        github_identity_required (reconnect GitHub), whether at the gate or
        during the write.

        - A pull request that does not exist, one no organization of the caller
        owns, an org_id that does not own it and one whose repository the caller
        cannot see on GitHub (no link to its installation included) answer the
        same 404; omitting org_id while more than one owning organization admits
        the caller is a 422 org_id_required, and a GitHub access check that
        cannot run is a 500.
      operationId: createPullRequestGithubReview
      parameters:
        - in: path
          name: pullRequestID
          required: true
          schema:
            format: uuid
            type: string
        - description: >-
            The pull request's owning organization to act in: the org_id the
            PullRequest carries. Omitted, getPullRequest and the review page's
            operations (its review, file, head snapshot and stack) act in the
            owning organization getPullRequest ranks first, and a console
            operation refuses with 422 org_id_required when more than one of the
            caller's organizations owns the pull request.
          explode: false
          in: query
          name: org_id
          schema:
            description: >-
              The pull request's owning organization to act in: the org_id the
              PullRequest carries. Omitted, getPullRequest and the review page's
              operations (its review, file, head snapshot and stack) act in the
              owning organization getPullRequest ranks first, and a console
              operation refuses with 422 org_id_required when more than one of
              the caller's organizations owns the pull request.
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitPullRequestReviewRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskGitHubPullRequestReview'
          description: Created
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PullRequestsErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PullRequestsErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/PullRequestsErrorResponse'
                  - $ref: '#/components/schemas/OrgAuthorizationErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PullRequestsErrorResponse'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PullRequestsErrorResponse'
          description: Conflict
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PullRequestsErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PullRequestsErrorResponse'
          description: Internal Server Error
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PullRequestsErrorResponse'
          description: Bad Gateway
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PullRequestsErrorResponse'
          description: Service Unavailable
components:
  schemas:
    SubmitPullRequestReviewRequest:
      additionalProperties: false
      properties:
        body:
          type: string
        comments:
          items:
            $ref: '#/components/schemas/SubmitPullRequestReviewComment'
          type: array
        event:
          enum:
            - COMMENT
            - APPROVE
            - REQUEST_CHANGES
          type: string
        expected_head_sha:
          maxLength: 40
          minLength: 40
          pattern: ^[0-9a-f]{40}$
          type: string
        idempotency_key:
          format: uuid
          type: string
      required:
        - event
        - expected_head_sha
        - idempotency_key
      type: object
    TaskGitHubPullRequestReview:
      additionalProperties: false
      properties:
        author_is_bot:
          type: boolean
        author_login:
          minLength: 1
          type:
            - string
            - 'null'
        body:
          type: string
        github_review_id:
          format: int64
          maximum: 9007199254740991
          minimum: 1
          type: integer
        html_url:
          minLength: 1
          type: string
        state:
          minLength: 1
          type: string
        submitted_at:
          format: date-time
          type: string
      required:
        - github_review_id
        - author_login
        - author_is_bot
        - state
        - body
        - submitted_at
        - html_url
      type: object
    PullRequestsErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - account_deleting
            - aether_inference_unserved
            - agent_pr_blocked
            - agent_pr_pending
            - agent_profile_changed
            - agent_starts_off
            - app_identity_missing
            - attribution_unavailable
            - bad_gateway
            - bad_request
            - caller_inactive
            - chat_archived
            - computer_connection_stale
            - computer_starts_no_agents
            - computer_starts_no_forks
            - computer_unreachable
            - conflict
            - connection_harness_mismatch
            - connection_not_held
            - contents_write_required
            - continuation_failed
            - continuation_unavailable
            - control_forbidden
            - embeddings_unavailable
            - fix_not_requested
            - fix_requests_unrecorded
            - forbidden
            - fork_branch_delete_unsupported
            - fork_forbidden
            - gateway_timeout
            - github_failed
            - github_identity_required
            - github_push_access_required
            - gone
            - handed_branch_protected
            - head_moved
            - html_render_nul_byte
            - html_render_too_large
            - idempotency_key_conflict
            - idempotency_key_reused
            - idle_compaction_not_pending
            - idle_compaction_skipped
            - inference_proxy_unavailable
            - insufficient_credits
            - insufficient_inference_balance
            - internal_error
            - invalid_request
            - last_queued_message
            - main_chat_permanent
            - mcp_server_not_connected
            - merge_when_ready_requires_pr_review
            - message_not_queued
            - method_not_allowed
            - mode_forbidden
            - no_checkout_on_computer
            - no_dispatch_target
            - not_acceptable
            - not_found
            - not_implemented
            - onboarding_already_completed
            - onboarding_requirements_missing
            - org_id_required
            - org_role_insufficient
            - org_suspended
            - payment_required
            - pr_review_actor_required
            - pr_review_publish_forbidden
            - precondition_failed
            - project_has_no_repository
            - project_required
            - pull_request_closed
            - pull_request_mirror_failed
            - pull_request_not_mirrored
            - queued_stop_requires_discard
            - rate_limited
            - request_canceled
            - request_timeout
            - request_too_large
            - service_unavailable
            - stack_cycle
            - stack_too_large
            - stack_two_parents
            - stale_execution
            - stale_or_indeterminate
            - stale_pending_input
            - stream_delivery_gap
            - stream_event_conflict
            - task_awaiting_message
            - task_awaiting_tool_response
            - task_backed_by_work_tree
            - task_connection_disconnected
            - task_creator_deleted
            - task_fork_refused
            - task_has_no_repository
            - task_ineligible
            - task_not_accepting_messages
            - task_not_pinnable
            - task_settings_changed
            - teleport_unavailable
            - terminal_chat_continuation_refused
            - unauthenticated
            - unsigned_aether_head
            - unsigned_commit
            - unsupported_changes
            - unsupported_media_type
            - untyped_error
            - validation_failed
            - workspace_git_unavailable
            - workspace_rejected
          minLength: 1
          type: string
        error:
          minLength: 1
          type: string
        errors:
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type: array
      required:
        - error
        - code
      type: object
    OrgAuthorizationErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - org_membership_required
            - org_role_insufficient
            - org_suspended
            - account_deleting
            - agent_host_route_not_allowed
            - credential_kind_not_admitted
            - grant_scope_insufficient
          type: string
        error:
          minLength: 1
          type: string
      required:
        - error
        - code
      type: object
    SubmitPullRequestReviewComment:
      additionalProperties: false
      properties:
        body:
          minLength: 1
          pattern: \S
          type: string
        line:
          format: int64
          minimum: 1
          type: integer
        path:
          minLength: 1
          pattern: \S
          type: string
        side:
          enum:
            - LEFT
            - RIGHT
          type: string
      required:
        - path
        - line
        - body
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: >-
            Where the error occurred, e.g. 'body.items[3].tags' or
            'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http

````

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