openapi: 3.2.0
info:
  title: AutoGPT Agent Server Executions API
  summary: AutoGPT Agent Server
  description: This server is used to execute agents that are created by the AutoGPT system.
  version: '0.1'
tags:
- name: Executions
paths:
  /api/review/action:
    post:
      tags:
      - Executions
      summary: Process Review Action
      description: Process reviews with approve or reject actions.
      operationId: postV2ProcessReviewAction
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReviewRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReviewResponse'
        '401':
          $ref: '#/components/responses/HTTP401NotAuthenticatedError'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearerJWT: []
  /api/review/execution/{graph_exec_id}:
    get:
      tags:
      - Executions
      summary: Get Pending Reviews for Execution
      description: 'Get all pending reviews for a specific graph execution.


        Retrieves all reviews with status "WAITING" for the specified graph execution

        that belong to the authenticated user. Results are ordered by creation time

        (oldest first) to preserve review order within the execution.


        Args:

        graph_exec_id: ID of the graph execution to get reviews for

        user_id: Authenticated user ID from security dependency


        Returns:

        List of pending review objects for the specified execution


        Raises:

        HTTPException:

        - 404: If the graph execution doesn''t exist or isn''t owned by this user

        - 500: If authentication fails or database error occurs


        Note:

        Only returns reviews owned by the authenticated user for security.

        Reviews with invalid status are excluded with warning logs.'
      operationId: getV2GetPendingReviewsForExecution
      security:
      - HTTPBearerJWT: []
      parameters:
      - name: graph_exec_id
        in: path
        required: true
        schema:
          type: string
          title: Graph Exec Id
      responses:
        '200':
          description: List of pending reviews for the execution
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PendingHumanReviewModel'
                title: Response Getv2Get Pending Reviews For Execution
        '401':
          $ref: '#/components/responses/HTTP401NotAuthenticatedError'
        '404':
          description: Graph execution not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Server error
          content:
            application/json: {}
      x-operation-id-source: normalized
      x-operation-id-original: getV2Get pending reviews for execution
  /api/review/pending:
    get:
      tags:
      - Executions
      summary: Get Pending Reviews
      description: 'Get all pending reviews for the current user.


        Retrieves all reviews with status "WAITING" that belong to the authenticated user.

        Results are ordered by creation time (newest first).


        Args:

        user_id: Authenticated user ID from security dependency


        Returns:

        List of pending review objects with status converted to typed literals


        Raises:

        HTTPException: If authentication fails or database error occurs


        Note:

        Reviews with invalid status values are logged as warnings but excluded

        from results rather than failing the entire request.'
      operationId: getV2GetPendingReviews
      security:
      - HTTPBearerJWT: []
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number (1-indexed)
          default: 1
          title: Page
        description: Page number (1-indexed)
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Number of reviews per page
          default: 25
          title: Page Size
        description: Number of reviews per page
      responses:
        '200':
          description: List of pending reviews
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PendingHumanReviewModel'
                title: Response Getv2Get Pending Reviews
        '401':
          $ref: '#/components/responses/HTTP401NotAuthenticatedError'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Server error
          content:
            application/json: {}
      x-operation-id-source: normalized
      x-operation-id-original: getV2Get pending reviews
components:
  schemas:
    PendingHumanReviewModel:
      properties:
        node_exec_id:
          type: string
          title: Node Exec Id
          description: Node execution ID (primary key)
        node_id:
          type: string
          title: Node Id
          description: Node definition ID (for grouping)
          default: ''
        user_id:
          type: string
          title: User Id
          description: User ID associated with the review
        graph_exec_id:
          type: string
          title: Graph Exec Id
          description: Graph execution ID
        graph_id:
          type: string
          title: Graph Id
          description: Graph ID
        graph_version:
          type: integer
          title: Graph Version
          description: Graph version
        payload:
          anyOf:
          - additionalProperties: true
            type: object
          - items: {}
            type: array
          - type: string
          - type: integer
          - type: number
          - type: boolean
          - type: 'null'
          title: Payload
          description: The actual data payload awaiting review
        instructions:
          anyOf:
          - type: string
          - type: 'null'
          title: Instructions
          description: Instructions or message for the reviewer
        editable:
          type: boolean
          title: Editable
          description: Whether the reviewer can edit the data
        status:
          $ref: '#/components/schemas/ReviewStatus'
          description: Review status
        review_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Review Message
          description: Optional message from the reviewer
        expert_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Expert Id
          description: Expert attributed to the requesting run
        expert_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Expert Name
        expert_avatar_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Expert Avatar Url
        agent_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Name
          description: Display name of the agent that requested the review
        library_agent_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Library Agent Id
          description: For run deep links
        session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
          description: Chat session id for copilot run_block reviews
        was_edited:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Was Edited
          description: Whether the data was modified during review
        processed:
          type: boolean
          title: Processed
          description: Whether the review result has been processed by the execution engine
          default: false
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the review was created
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
          description: When the review was last updated
        reviewed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Reviewed At
          description: When the review was completed
      type: object
      required:
      - node_exec_id
      - user_id
      - graph_exec_id
      - graph_id
      - graph_version
      - payload
      - editable
      - status
      - created_at
      title: PendingHumanReviewModel
      description: "Response model for pending human review data.\n\nRepresents a human review request that is awaiting user action.\nContains all necessary information for a user to review and approve\nor reject data from a Human-in-the-Loop block execution.\n\nAttributes:\n    id: Unique identifier for the review record\n    user_id: ID of the user who must perform the review\n    node_exec_id: ID of the node execution that created this review\n    node_id: ID of the node definition (for grouping reviews from same node)\n    graph_exec_id: ID of the graph execution containing the node\n    graph_id: ID of the graph template being executed\n    graph_version: Version number of the graph template\n    payload: The actual data payload awaiting review\n    instructions: Instructions or message for the reviewer\n    editable: Whether the reviewer can edit the data\n    status: Current review status (WAITING, APPROVED, or REJECTED)\n    review_message: Optional message from the reviewer\n    created_at: Timestamp when review was created\n    updated_at: Timestamp when review was last modified\n    reviewed_at: Timestamp when review was completed (if applicable)"
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ReviewRequest:
      properties:
        reviews:
          items:
            $ref: '#/components/schemas/ReviewItem'
          type: array
          title: Reviews
          description: All reviews with their approval status, data, and messages
      type: object
      required:
      - reviews
      title: ReviewRequest
      description: 'Request model for processing ALL pending reviews for an execution.


        This request must include ALL pending reviews for a graph execution.

        Each review will be either approved (with optional data modifications)

        or rejected (data ignored). The execution will resume only after ALL reviews are processed.


        Each review item can individually specify whether to auto-approve future executions

        of the same block via the `auto_approve_future` field on ReviewItem.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ReviewItem:
      properties:
        node_exec_id:
          type: string
          title: Node Exec Id
          description: Node execution ID to review
        approved:
          type: boolean
          title: Approved
          description: Whether this review is approved (True) or rejected (False)
        message:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Message
          description: Optional review message
        reviewed_data:
          anyOf:
          - additionalProperties: true
            type: object
          - items: {}
            type: array
          - type: string
          - type: integer
          - type: number
          - type: boolean
          - type: 'null'
          title: Reviewed Data
          description: Optional edited data (ignored if approved=False)
        auto_approve_future:
          type: boolean
          title: Auto Approve Future
          description: If true and this review is approved, future executions of this same block (node) will be automatically approved. This only affects approved reviews.
          default: false
      type: object
      required:
      - node_exec_id
      - approved
      title: ReviewItem
      description: Single review item for processing.
    ReviewStatus:
      type: string
      enum:
      - WAITING
      - APPROVED
      - REJECTED
      title: ReviewStatus
    ReviewResponse:
      properties:
        approved_count:
          type: integer
          title: Approved Count
          description: Number of reviews successfully approved
        rejected_count:
          type: integer
          title: Rejected Count
          description: Number of reviews successfully rejected
        failed_count:
          type: integer
          title: Failed Count
          description: Number of reviews that failed processing
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if operation failed
      type: object
      required:
      - approved_count
      - rejected_count
      - failed_count
      title: ReviewResponse
      description: Response from review endpoint.
  responses:
    HTTP401NotAuthenticatedError:
      description: Authentication required
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
  securitySchemes:
    APIKeyAuthenticator-X-Postmark-Webhook-Token:
      type: apiKey
      in: header
      name: X-Postmark-Webhook-Token
    HTTPBearer:
      type: http
      scheme: bearer
    HTTPBearerJWT:
      type: http
      scheme: bearer
      bearerFormat: jwt