> ## 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.

# Request an Aether review of a pull request

> Asks Aether to review a pull request at its current head, even an unchanged one, and answers 201 with the review run it woke, or the run it created when the pull request had none.

Use this tool when you need to:
- Request a fresh Aether review of a pull request after a push, or again at the same head
- Start the first Aether review of a pull request no review run has reviewed yet

Examples:
- POST /pull-requests/{pullRequestID}/review/runs
- POST /pull-requests/6f1c2a9e-3b7d-4c55-9a2e-0d8b1f4e7c21/review/runs?org_id=0b9d3e57-2c1a-4f6e-8d7b-5a4c3e2f1d09

Hints:
- pullRequestID is the pull request's uuid and org_id (uuid) names an owning organization; there is no body. The schema answers 422 for a malformed value.
- The review runs in the resolved organization's non-archived project on the pull request's repository, at the head Aether's GitHub mirror holds: it wakes the organization's newest review run of the pull request, or creates one when there is none. Repeated requests at one head deliver one instruction, and a retry of the request that created the first run answers that run.
- Answers 201 with the run: task_id, run_number, status, created_at, trigger, head_sha, agent_type, model, and duration_seconds and error when known.
- Use getPullRequest instead to follow the run in review_runs, and dispatchPullRequestGithubFeedback to hand feedback to the authoring task rather than review again.
- 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 the repository, checked live through their own GitHub connection.
- 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 GitHub access the caller has lost (or never connected) answer the same 404, and omitting org_id while more than one of the caller's organizations owns it is 422 org_id_required.
- A closed or merged pull request is 422 pull_request_closed, a repository no project of the organization is connected to 422 project_required, a project with no review actor 409 pr_review_actor_required (when a run must be created), a review profile whose pinned connection's usage limit has not lifted 409 pr_review_connection_spent (when a run must be created: the error names the profile, the connection and when the limit lifts, the head's Aether Review check shows the same as queued, and the run is created when the limit lifts), an MCP server the new run requires that is not connected 409 mcp_server_not_connected, and a pull request Aether has not mirrored yet 503.
- When no owner admits the caller, a viewer or billing member is refused with 403 org_role_insufficient and a member of a suspended organization with 403 org_suspended; an agent host's grant is refused with 403 agent_host_route_not_allowed, and 503 answers when the membership check is unavailable.



## OpenAPI

````yaml api-reference/openapi.json POST /pull-requests/{pullRequestID}/review/runs
openapi: 3.1.0
info:
  title: Aether API
  version: 0.1.0
servers:
  - url: https://api.runaether.dev
security:
  - bearerAuth: []
paths:
  /pull-requests/{pullRequestID}/review/runs:
    post:
      tags:
        - pull-requests
      summary: Request an Aether review of a pull request
      description: >-
        Asks Aether to review a pull request at its current head, even an
        unchanged one, and answers 201 with the review run it woke, or the run
        it created when the pull request had none.


        Use this tool when you need to:

        - Request a fresh Aether review of a pull request after a push, or again
        at the same head

        - Start the first Aether review of a pull request no review run has
        reviewed yet


        Examples:

        - POST /pull-requests/{pullRequestID}/review/runs

        - POST
        /pull-requests/6f1c2a9e-3b7d-4c55-9a2e-0d8b1f4e7c21/review/runs?org_id=0b9d3e57-2c1a-4f6e-8d7b-5a4c3e2f1d09


        Hints:

        - pullRequestID is the pull request's uuid and org_id (uuid) names an
        owning organization; there is no body. The schema answers 422 for a
        malformed value.

        - The review runs in the resolved organization's non-archived project on
        the pull request's repository, at the head Aether's GitHub mirror holds:
        it wakes the organization's newest review run of the pull request, or
        creates one when there is none. Repeated requests at one head deliver
        one instruction, and a retry of the request that created the first run
        answers that run.

        - Answers 201 with the run: task_id, run_number, status, created_at,
        trigger, head_sha, agent_type, model, and duration_seconds and error
        when known.

        - Use getPullRequest instead to follow the run in review_runs, and
        dispatchPullRequestGithubFeedback to hand feedback to the authoring task
        rather than review again.

        - 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 the repository, checked live through their own GitHub
        connection.

        - 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 GitHub access the
        caller has lost (or never connected) answer the same 404, and omitting
        org_id while more than one of the caller's organizations owns it is 422
        org_id_required.

        - A closed or merged pull request is 422 pull_request_closed, a
        repository no project of the organization is connected to 422
        project_required, a project with no review actor 409
        pr_review_actor_required (when a run must be created), a review profile
        whose pinned connection's usage limit has not lifted 409
        pr_review_connection_spent (when a run must be created: the error names
        the profile, the connection and when the limit lifts, the head's Aether
        Review check shows the same as queued, and the run is created when the
        limit lifts), an MCP server the new run requires that is not connected
        409 mcp_server_not_connected, and a pull request Aether has not mirrored
        yet 503.

        - When no owner admits the caller, a viewer or billing member is refused
        with 403 org_role_insufficient and a member of a suspended organization
        with 403 org_suspended; an agent host's grant is refused with 403
        agent_host_route_not_allowed, and 503 answers when the membership check
        is unavailable.
      operationId: createPullRequestReviewRun
      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
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PRReviewRun'
          description: Created
        '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:
                anyOf:
                  - $ref: '#/components/schemas/PullRequestsErrorResponse'
                  - $ref: '#/components/schemas/McpServerNotConnectedErrorResponse'
          description: Conflict
        '410':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PullRequestsErrorResponse'
          description: Gone
        '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:
    PRReviewRun:
      additionalProperties: false
      properties:
        agent_type:
          $ref: '#/components/schemas/AgentType'
        created_at:
          format: date-time
          type: string
        duration_seconds:
          format: int64
          minimum: 0
          type: integer
        error:
          type: string
        head_sha:
          type: string
        model:
          minLength: 1
          type: string
        run_number:
          format: int64
          minimum: 1
          type: integer
        status:
          $ref: '#/components/schemas/ReviewRunStatus'
        task_id:
          format: uuid
          type: string
        trigger:
          $ref: '#/components/schemas/TaskReviewTrigger'
      required:
        - task_id
        - run_number
        - status
        - created_at
        - agent_type
        - model
      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
            - chat_settings_fixed
            - chats_not_addable
            - checkout_not_archivable
            - cli_upgrade_required
            - client_outdated
            - computer_cli_outdated
            - computer_starts_no_agents
            - computer_starts_no_forks
            - computer_unreachable
            - conflict
            - connection_creator_only
            - connection_harness_mismatch
            - connection_not_held
            - contents_write_required
            - continuation_failed
            - continuation_unavailable
            - control_forbidden
            - credential_kind_not_admitted
            - download_unsupported
            - 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
            - live_protocol_unsupported
            - main_chat_permanent
            - mcp_server_not_connected
            - merge_when_ready_requires_pr_review
            - message_not_queued
            - method_not_allowed
            - mode_forbidden
            - name_follows_session
            - 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
            - pending_input_answered
            - pr_automation_unsupported
            - pr_review_actor_required
            - pr_review_connection_spent
            - pr_review_publish_forbidden
            - precondition_failed
            - project_has_no_repository
            - project_required
            - pull_request_closed
            - pull_request_mirror_failed
            - pull_request_not_mirrored
            - question_answers
            - queued_stop_requires_discard
            - rate_limited
            - reasoning_effort_fixed
            - request_canceled
            - request_timeout
            - request_too_large
            - review_name_follows_pull_request
            - sandbox_deleted
            - sandbox_failed
            - sandbox_needs_message
            - 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_not_started
            - task_settings_changed
            - task_start_failed
            - task_start_pending
            - teleport_unavailable
            - terminal_chat_continuation_refused
            - too_many_live_connections
            - unauthenticated
            - unsigned_aether_head
            - unsigned_commit
            - unsupported_changes
            - unsupported_media_type
            - untyped_error
            - user_suspended
            - validation_failed
            - workspace_git_unavailable
            - workspace_gone
            - 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
    McpServerNotConnectedErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - mcp_server_not_connected
          type: string
        error:
          minLength: 1
          type: string
        servers:
          items:
            $ref: '#/components/schemas/McpServerNotConnected'
          minItems: 1
          type: array
      required:
        - error
        - code
        - servers
      type: object
    AgentType:
      description: >-
        The agent harness that runs a task, a profile or a connection:
        claude-code or claude_code is Claude Code, codex is Codex, opencode is
        OpenCode.
      enum:
        - codex
        - claude-code
        - opencode
        - claude_code
      type: string
    ReviewRunStatus:
      enum:
        - reviewing
        - completed
        - failed
        - cancelled
        - superseded
        - archived
      type: string
    TaskReviewTrigger:
      enum:
        - automatic
        - comment_command
        - manual
      type: string
    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
    McpServerNotConnected:
      additionalProperties: false
      properties:
        display_name:
          type: string
        key:
          type: string
        policy:
          enum:
            - creator
            - org
          type: string
        reason:
          enum:
            - not_connected
            - needs_reauth
          type: string
        repo:
          $ref: '#/components/schemas/McpServerRepoDeclaration'
      required:
        - key
        - display_name
        - policy
        - reason
      type: object
    McpServerRepoDeclaration:
      additionalProperties: false
      properties:
        cataloged:
          type: boolean
        file:
          enum:
            - .mcp.json
            - .codex/config.toml
          type: string
      required:
        - file
        - cataloged
      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.