openapi.yml

openapi: "3.0.2"
info:
  title: Comfy API
  version: "1.0"
servers:
  - url: https://api.comfy.org
paths:
  /users:
    get:
      summary: Get information about the calling user.
      operationId: getUser
      security:
        - BearerAuth: [ ]
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"

        "404":
          description: Not Found
        "401":
          description: Unauthorized
  /upload-artifact:
    post:
      summary: Receive artifacts (output files) from the ComfyUI GitHub Action
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                repo:
                  type: string
                  description: Repository name
                job_id:
                  type: string
                  description: Unique identifier for the job
                run_id:
                  type: string
                  description: Unique identifier for the run
                os:
                  type: string
                  description: Operating system used in the run
                cuda_version:
                  type: string
                  description: Cuda version.
                bucket_name:
                  type: string
                  description: The name of the bucket where the output files are stored
                output_files_gcs_paths:
                  type: string
                  description: A comma separated string that contains GCS path(s) to output files. eg. gs://bucket-name/output, gs://bucket-name/output2
                comfy_logs_gcs_path:
                  type: string
                  description: The path to ComfyUI logs. eg. gs://bucket-name/logs
                comfy_run_flags:
                  type: string
                  description: The flags used in the comfy run
                commit_hash:
                  type: string
                commit_time:
                  type: string
                  description: The time of the commit in the format of "YYYY-MM-DDTHH:MM:SSZ" (2016-10-10T00:00:00Z)
                commit_message:
                  type: string
                  description: The commit message
                workflow_name:
                  type: string
                  description: The name of the workflow
                branch_name:
                  type: string
                start_time:
                  type: integer
                  format: int64
                  description: The start time of the job as a Unix timestamp.
                end_time:
                  type: integer
                  format: int64
                  description: The end time of the job as a Unix timestamp.
                avg_vram:
                  type: integer
                  description: The average amount of VRAM used in the run.
                peak_vram:
                  type: integer
                  description: The peak amount of VRAM used in the run.
                pr_number:
                  type: string
                  description: The pull request number
                author:
                  type: string
                  description: The author of the commit
                job_trigger_user:
                  type: string
                  description: The user who triggered the job
                python_version:
                  type: string
                  description: The python version used in the run
                pytorch_version:
                  type: string
                  description: The pytorch version used in the run
                machine_stats:
                  $ref: "#/components/schemas/MachineStats"
                status:
                  $ref: "#/components/schemas/WorkflowRunStatus"
              required:
                - repo
                - job_id
                - run_id
                - os
                - commit_hash
                - commit_time
                - commit_message
                - branch_name
                - workflow_name
                - start_time
                - end_time
                - pr_number
                - python_version
                - job_trigger_user
                - author
                - status

      responses:
        '200':
          description: Successfully received the artifact details
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '400':
          description: Invalid request
        '500':
          description: Internal server error
  /gitcommit:
    get:
      summary: Retrieve CI data for a given commit
      description: Returns all runs, jobs, job results, and storage files associated with a given commit.
      parameters:
        - in: query
          name: commitId
          required: false
          schema:
            type: string
          description: The ID of the commit to fetch data for.
        - in: query
          name: operatingSystem
          required: false
          schema:
            type: string
          description: The operating system to filter the CI data by.
        - in: query
          name: workflowName
          required: false
          schema:
            type: string
          description: The name of the workflow to filter the CI data by.
        - in: query
          name: branch
          required: false
          schema:
            type: string
          description: The branch of the gitcommit to filter the CI data by.
        - in: query
          name: page
          required: false
          schema:
            type: integer
            default: 1
          description: The page number to retrieve.
        - in: query
          name: pageSize
          required: false
          schema:
            type: integer
            default: 10
          description: The number of items to include per page.
        - in: query
          name: repoName
          required: false
          schema:
            type: string
            default: comfyanonymous/ComfyUI
          description: The repo to filter by.
      responses:
        '200':
          description: An object containing runs, jobs, job results, and storage files
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobResults:
                    type: array
                    items:
                      $ref: '#/components/schemas/ActionJobResult'
                  totalNumberOfPages:
                    type: integer
        '404':
          description: Commit not found
        '500':
          description: Internal server error
  /gitcommitsummary:
    get:
      summary: Retrieve a summary of git commits
      description: Returns a summary of git commits, including status, start time, and end time.
      parameters:
        - in: query
          name: repoName
          required: false
          schema:
            type: string
            default: comfyanonymous/ComfyUI
          description: The repository name to filter the git commits by.
        - in: query
          name: branchName
          required: false
          schema:
            type: string
          description: The branch name to filter the git commits by.
        - in: query
          name: page
          required: false
          schema:
            type: integer
            default: 1
          description: The page number to retrieve.
        - in: query
          name: pageSize
          required: false
          schema:
            type: integer
            default: 10
          description: The number of items to include per page.
      responses:
        '200':
          description: Successfully retrieved git commit summaries
          content:
            application/json:
              schema:
                type: object
                properties:
                  commitSummaries:
                    type: array
                    items:
                      $ref: '#/components/schemas/GitCommitSummary'
                  totalNumberOfPages:
                    type: integer
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
  /workflowresult/{workflowResultId}:
    get:
      summary: Retrieve a specific commit by ID
      operationId: getWorkflowResult
      parameters:
        - in: path
          name: workflowResultId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Commit details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionJobResult'
        '404':
          description: Commit not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /branch:
    get:
      summary: Retrieve all distinct branches for a given repo
      description: Returns all branches for a given repo.
      parameters:
        - in: query
          name: repo_name
          required: true
          schema:
            type: string
            default: comfyanonymous/ComfyUI
          description: The repo to filter by.
      responses:
        '200':
          description: An array of branches
          content:
            application/json:
              schema:
                type: object
                properties:
                  branches:
                    type: array
                    items:
                      type: string
        '404':
          description: Repo not found
        '500':
          description: Internal server error

  /users/publishers/:
    get:
      summary: Retrieve all publishers for a given user
      operationId: listPublishersForUser
      tags:
        - Publishers
      responses:
        '200':
          description: A list of publishers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Publisher'
        '400':
          description: Bad request, invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /publishers/{publisherId}/permissions:
    get:
      summary: Retrieve permissions the user has for a given publisher
      operationId: getPermissionOnPublisher
      tags:
        - Publishers
      parameters:
        - in: path
          name: publisherId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A list of permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  canEdit:
                    type: boolean
        '400':
          description: Bad request, invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /publishers/validate:
    get:
      summary: Validate if a publisher username is available
      description: Checks if the publisher username is already taken.
      operationId: validatePublisher
      tags:
        - Publishers
      parameters:
        - in: query
          name: username
          schema:
            type: string
          description: The publisher username to validate.
          required: true
      responses:
        '200':
          description: Username validation result
          content:
            application/json:
              schema:
                type: object
                properties:
                  isAvailable:
                    type: boolean
                    description: True if the username is available, false otherwise.
        '400':
          description: Invalid input, such as missing username in the query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /publishers:
    post:
      summary: Create a new publisher
      operationId: createPublisher
      security:
        - BearerAuth: [ ]
      tags:
        - Publishers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Publisher'
      responses:
        '201':
          description: Publisher created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Publisher'
        '400':
          description: Bad request, invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    get:
      summary: Retrieve all publishers
      operationId: listPublishers
      tags:
        - Publishers
      responses:
        '200':
          description: A list of publishers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Publisher'
        '400':
          description: Bad request, invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /publishers/{publisherId}:
    get:
      summary: Retrieve a publisher by ID
      operationId: getPublisher
      tags:
        - Publishers
      parameters:
        - in: path
          name: publisherId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Publisher retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Publisher'
        '404':
          description: Publisher not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    put:
      summary: Update a publisher
      operationId: updatePublisher
      security:
        - BearerAuth: [ ]
      tags:
        - Publishers
      parameters:
        - in: path
          name: publisherId
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Publisher'
      responses:
        '200':
          description: Publisher updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Publisher'
        '400':
          description: Bad request, invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '404':
          description: Publisher not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    delete:
      summary: Delete a publisher
      operationId: deletePublisher
      security:
        - BearerAuth: [ ]
      tags:
        - Publishers
      parameters:
        - in: path
          name: publisherId
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Publisher deleted successfully
        '404':
          description: Publisher not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /publishers/{publisherId}/ban:
    post:
      summary: Ban a publisher
      operationId: BanPublisher
      parameters:
        - in: path
          name: publisherId
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Publisher Banned Successfully
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Publisher not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /publishers/{publisherId}/nodes:
    post:
      summary: Create a new custom node
      operationId: createNode
      tags:
        - Nodes
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: publisherId
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Node'
      responses:
        '201':
          description: Node created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Node'
        '400':
          description: Bad request, invalid input data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      summary: Retrieve all nodes
      operationId: listNodesForPublisher
      security:
        - BearerAuth: [ ]
      tags:
        - Nodes
      parameters:
        - in: path
          name: publisherId
          required: true
          schema:
            type: string
        - in: query
          name: include_banned
          description: Number of nodes to return per page
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: List of all nodes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Node'
        '400':
          description: Bad request, invalid input data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /publishers/{publisherId}/nodes/{nodeId}:
    put:
      summary: Update a specific node
      operationId: updateNode
      tags:
        - Nodes
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: publisherId
          required: true
          schema:
            type: string
        - in: path
          name: nodeId
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Node'
      responses:
        '200':
          description: Node updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Node'
        '400':
          description: Bad request, invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Node not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      summary: Delete a specific node
      operationId: deleteNode
      tags:
        - Nodes
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: publisherId
          required: true
          schema:
            type: string
        - in: path
          name: nodeId
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Node deleted successfully
        '404':
          description: Node not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'


  /publishers/{publisherId}/nodes/{nodeId}/permissions:
    get:
      summary: Retrieve permissions the user has for a given publisher
      operationId: getPermissionOnPublisherNodes
      tags:
        - Publishers
      parameters:
        - in: path
          name: publisherId
          required: true
          schema:
            type: string
        - in: path
          name: nodeId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A list of permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  canEdit:
                    type: boolean
        '400':
          description: Bad request, invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /publishers/{publisherId}/nodes/{nodeId}/versions:
    post:
      summary: Publish a new version of a node
      operationId: publishNodeVersion
      tags:
        - Versions
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: publisherId
          required: true
          schema:
            type: string
        - in: path
          name: nodeId
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                personal_access_token:
                  type: string
                node_version:
                  $ref: '#/components/schemas/NodeVersion'
                node:
                  $ref: '#/components/schemas/Node'
              required:
                - node
                - node_version
                - personal_access_token
      responses:
        '201':
          description: New version published successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  signedUrl:
                    type: string
                    description: The signed URL to upload the node version token.
                  node_version:
                    $ref: '#/components/schemas/NodeVersion'
        '400':
          description: Bad request, invalid input data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /publishers/{publisherId}/nodes/{nodeId}/versions/{versionId}:
    delete:
      summary: Unpublish (delete) a specific version of a node
      operationId: deleteNodeVersion
      tags:
        - Versions
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: publisherId
          required: true
          schema:
            type: string
        - in: path
          name: nodeId
          required: true
          schema:
            type: string
        - in: path
          name: versionId
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Version unpublished (deleted) successfully
        '403':
          description: Version does not belong to the publisher
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Version not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Version not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      summary: Update changelog and deprecation status of a node version
      operationId: updateNodeVersion
      description: Update only the changelog and deprecated status of a specific version of a node.
      tags:
        - Versions
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: publisherId
          required: true
          schema:
            type: string
        - in: path
          name: nodeId
          required: true
          schema:
            type: string
        - in: path
          name: versionId
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NodeVersionUpdateRequest'
      responses:
        '200':
          description: Version updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodeVersion'
        '400':
          description: Bad request, invalid input data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Version not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /publishers/{publisherId}/nodes/{nodeId}/ban:
    post:
      summary: Ban a publisher's Node
      operationId: BanPublisherNode
      parameters:
        - in: path
          name: publisherId
          required: true
          schema:
            type: string
        - in: path
          name: nodeId
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Node Banned Successfully
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Publisher or Node not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /publishers/{publisherId}/tokens:
    post:
      summary: Create a new personal access token
      operationId: createPersonalAccessToken
      security:
        - BearerAuth: [ ]
      tags:
        - Token Management
      parameters:
        - in: path
          name: publisherId
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonalAccessToken'
      responses:
        '201':
          description: Token created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: The newly created personal access token.
        '400':
          description: Bad request, invalid input data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'


    get:
      summary: Retrieve all personal access tokens for a publisher
      operationId: listPersonalAccessTokens
      security:
        - BearerAuth: [ ]
      tags:
        - Token Management
      parameters:
        - in: path
          name: publisherId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of all personal access tokens
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PersonalAccessToken'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No tokens found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /publishers/{publisherId}/tokens/{tokenId}:
    delete:
      summary: Delete a specific personal access token
      operationId: deletePersonalAccessToken
      security:
        - BearerAuth: [ ]
      tags:
        - Token Management
      parameters:
        - in: path
          name: publisherId
          required: true
          schema:
            type: string
        - in: path
          name: tokenId
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Token deleted successfully
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Token not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /nodes/search:
    get:
      summary: Retrieves a list of nodes
      description: Returns a paginated list of nodes across all publishers.
      operationId: searchNodes
      tags:
        - Nodes
      parameters:
        - in: query
          name: page
          description: Page number of the nodes list
          required: false
          schema:
            type: integer
            default: 1
        - in: query
          name: limit
          description: Number of nodes to return per page
          required: false
          schema:
            type: integer
            default: 10
        - in: query
          name: search
          description: Keyword to search the nodes
          required: false
          schema:
            type: string
        - in: query
          name: include_banned
          description: Number of nodes to return per page
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: A paginated list of nodes
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of nodes available
                  nodes:
                    type: array
                    items:
                      $ref: '#/components/schemas/Node'
                  page:
                    type: integer
                    description: Current page number
                  limit:
                    type: integer
                    description: Maximum number of nodes per page
                  totalPages:
                    type: integer
                    description: Total number of pages available
        '400':
          description: Invalid input, object invalid
        '404':
          description: Not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /nodes/reindex:
    post:
      summary: Reindex all nodes for searching.
      operationId: reindexNodes
      tags:
        - Nodes
      parameters:
        - in: query
          name: max_batch
          description: Maximum number of nodes to send to algolia at a time 
          required: false
          schema:
            type: integer
        - in: query
          name: min_age
          description: Minimum interval from the last time the nodes were indexed to algolia
          required: false
          schema:
            type: string 
            x-go-type: time.Duration
      responses:
        '200':
          description: Reindex completed successfully.
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /nodes:
    get:
      summary: Retrieves a list of nodes
      description: Returns a paginated list of nodes across all publishers.
      operationId: listAllNodes
      tags:
        - Nodes
      parameters:
        - in: query
          name: page
          description: Page number of the nodes list
          required: false
          schema:
            type: integer
            default: 1
        - in: query
          name: limit
          description: Number of nodes to return per page
          required: false
          schema:
            type: integer
            default: 10
        - in: query
          name: include_banned
          description: Number of nodes to return per page
          required: false
          schema:
            type: boolean
        - in: query
          name: timestamp
          description: Retrieve nodes created or updated after this timestamp (ISO 8601 format)
          required: false
          schema:
            type: string
            format: date-time
        - in: query
          name: latest
          description: Whether to fetch fresh result from database or use cached one if false
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: A paginated list of nodes
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of nodes available
                  nodes:
                    type: array
                    items:
                      $ref: '#/components/schemas/Node'
                  page:
                    type: integer
                    description: Current page number
                  limit:
                    type: integer
                    description: Maximum number of nodes per page
                  totalPages:
                    type: integer
                    description: Total number of pages available
        '400':
          description: Invalid input, object invalid
        '404':
          description: Not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /nodes/{nodeId}:
    get:
      summary: Retrieve a specific node by ID
      description: Returns the details of a specific node.
      operationId: getNode
      tags:
        - Nodes
      parameters:
        - in: path
          name: nodeId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Node details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Node'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Node not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /nodes/{nodeId}/reviews:
    post:
      summary: Add review to a specific version of a node
      operationId: postNodeReview
      tags:
        - Nodes
      parameters:
        - in: path
          name: nodeId
          required: true
          schema:
            type: string
        - in: query
          name: star
          description: number of star given to the node version
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Detailed information about a specific node
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Node'
        '400':
          description: Bad Request
        '404':
          description: Node version not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /nodes/{nodeId}/install:
    get:
      summary: Returns a node version to be installed.
      description: Retrieves the node data for installation, either the latest or a specific version.
      operationId: installNode
      tags:
        - Nodes
      parameters:
        - in: path
          name: nodeId
          required: true
          description: The unique identifier of the node.
          schema:
            type: string
        - in: query
          name: version
          required: false
          description: Specific version of the node to retrieve. If omitted, the latest version is returned.
          schema:
            type: string
            pattern: '^\d+\.\d+\.\d+$'
      responses:
        '200':
          description: Node data returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodeVersion'
        '400':
          description: Invalid input, such as a bad version format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Node not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /nodes/{nodeId}/versions:
    get:
      summary: List all versions of a node
      operationId: listNodeVersions
      tags:
        - Versions
      parameters:
        - in: path
          name: nodeId
          required: true
          schema:
            type: string
        - in: query
          name: statuses
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/NodeVersionStatus'
        # parameter to include status_reason, default to false
        - in: query
          name: include_status_reason
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: List of all node versions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NodeVersion'
        '403':
          description: Node banned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Node not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /nodes/{nodeId}/versions/{versionId}:
    get:
      summary: Retrieve a specific version of a node
      operationId: getNodeVersion
      tags:
        - Versions
      parameters:
        - in: path
          name: nodeId
          required: true
          schema:
            type: string
        - in: path
          name: versionId
          description: The version of the node. (Not a UUID).
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Detailed information about a specific node version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodeVersion'
        '404':
          description: Node version not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /versions:
    get:
      summary: List all node versions given some filters.
      operationId: listAllNodeVersions
      tags:
        - Versions
      parameters:
        - in: query
          name: nodeId
          required: false
          schema:
            type: string
        - in: query
          name: statuses
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              $ref: '#/components/schemas/NodeVersionStatus'
        # parameter to include status_reason, default to false
        - in: query
          name: include_status_reason
          required: false
          schema:
            type: boolean
            default: false
        - in: query
          name: page
          required: false
          schema:
            type: integer
            default: 1
          description: The page number to retrieve.
        - in: query
          name: pageSize
          required: false
          schema:
            type: integer
            default: 10
          description: The number of items to include per page.
      responses:
        '200':
          description: List of all node versions
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of node versions available
                  versions:
                    type: array
                    items:
                      $ref: '#/components/schemas/NodeVersion'
                  page:
                    type: integer
                    description: Current page number
                  pageSize:
                    type: integer
                    description: Maximum number of node versions per page. Maximum is 100.
                  totalPages:
                    type: integer
                    description: Total number of pages available
        '400':
          description: Invalid input, object invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Node banned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /admin/nodes/{nodeId}/versions/{versionNumber}:
    put:
      summary: Admin Update Node Version Status
      operationId: adminUpdateNodeVersion
      description: Only admins can approve a node version.
      tags:
        - Versions
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: nodeId
          required: true
          schema:
            type: string
        - in: path
          name: versionNumber
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  $ref: "#/components/schemas/NodeVersionStatus"
                status_reason:
                  type: string
                  description: The reason for the status change.

      responses:
        '200':
          description: Version updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodeVersion'
        '400':
          description: Bad request, invalid input data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Version not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /security-scan:
    get:
      summary: Security Scan
      operationId: securityScan
      description: Pull all pending node versions and conduct security scans.
      parameters:
        - in: query
          name: minAge
          required: false
          schema:
            type: string
            x-go-type: time.Duration
        - in: query
          name: maxNodes
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Scan completed successfully
        '400':
          description: Bad request, invalid input data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /nodes/{nodeId}/versions/{version}/comfy-nodes:
    post:
      summary: create comfy-nodes for certain node
      operationId: CreateComfyNodes
      tags:
        - ComfyNodes
      parameters:
        - in: path
          name: nodeId
          required: true
          schema:
            type: string
        - in: path
          name: version
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                success:
                  type: boolean
                reason:
                  type: string 
                cloud_build_info:
                  $ref: '#/components/schemas/ComfyNodeCloudBuildInfo'
                nodes:
                  additionalProperties:
                    $ref: '#/components/schemas/ComfyNode'
      responses:
        '204':
          description: Comy Nodes created successfully
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Version not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Existing Comfy Nodes exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /nodes/{nodeId}/versions/{version}/comfy-nodes/{comfyNodeId}:
    get:
      summary: get specify comfy-node based on its id
      operationId: GetComfyNode
      tags:
        - ComfyNodes
      parameters:
        - in: path
          name: nodeId
          required: true
          schema:
            type: string
        - in: path
          name: version
          required: true
          schema:
            type: string
        - in: path
          name: comfyNodeId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Comy Nodes created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComfyNode'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Version not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /comfy-nodes/backfill:
    post:
      summary: trigger comfy nodes backfill
      operationId: ComfyNodesBackfill
      tags:
        - ComfyNodes
      parameters:
        - in: query
          name: max_node
          required: false
          schema:
            type: integer
            default: 10
      responses:
        '204':
          description: Backfill triggered
        '400':
          description: Bad request, invalid input data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    PersonalAccessToken:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the GitCommit
        name:
          type: string
          description: Required. The name of the token. Can be a simple description.
        description:
          type: string
          description: Optional. A more detailed description of the token's intended use.
        createdAt:
          type: string
          format: date-time
          description: "[Output Only]The date and time the token was created."
        token:
          type: string
          description: "[Output Only]. The personal access token. Only returned during creation."
    GitCommit:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the GitCommit
        commit_hash:
          type: string
          description: The hash of the commit
        commit_name:
          type: string
          description: The name of the commit
        branch_name:
          type: string
          description: The branch where the commit was made
        author:
          type: string
          description: The author of the commit
        timestamp:
          type: string
          format: date-time
          description: The timestamp when the commit was made
    GitCommitSummary:
      type: object
      properties:
        commit_hash:
          type: string
          description: The hash of the commit
        commit_name:
          type: string
          description: The name of the commit
        branch_name:
          type: string
          description: The branch where the commit was made
        author:
          type: string
          description: The author of the commit
        timestamp:
          type: string
          format: date-time
          description: The timestamp when the commit was made
        status_summary:
          type: object
          description: A map of operating system to status pairs
          additionalProperties:
            type: string
    User:
      type: object
      properties:
        id:
          type: string
          description: The unique id for this user.
        email:
          type: string
          description: The email address for this user.
        name:
          type: string
          description: The name for this user.
        isApproved:
          type: boolean
          description: Indicates if the user is approved.
        isAdmin:
          type: boolean
          description: Indicates if the user has admin privileges.
    PublisherUser:
      type: object
      properties:
        id:
          type: string
          description: The unique id for this user.
        email:
          type: string
          description: The email address for this user.
        name:
          type: string
          description: The name for this user.
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
      required:
        - error
        - message
    ActionJobResult:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the job result
        workflow_name:
          type: string
          description: Name of the workflow
        operating_system:
          type: string
          description: Operating system used
        python_version:
          type: string
          description: PyTorch version used
        pytorch_version:
          type: string
          description: PyTorch version used
        action_run_id:
          type: string
          description: Identifier of the run this result belongs to
        action_job_id:
          type: string
          description: Identifier of the job this result belongs to
        cuda_version:
          type: string
          description: CUDA version used
        branch_name:
          type: string
          description: Name of the relevant git branch
        commit_hash:
          type: string
          description: The hash of the commit
        commit_id:
          type: string
          description: The ID of the commit
        commit_time:
          type: integer
          format: int64
          description: The Unix timestamp when the commit was made
        commit_message:
          type: string
          description: The message of the commit
        comfy_run_flags:
          type: string
          description: The comfy run flags. E.g. `--low-vram`
        git_repo:
          type: string
          description: The repository name
        pr_number:
          type: string
          description: The pull request number
        start_time:
          type: integer
          format: int64
          description: The start time of the job as a Unix timestamp.
        end_time:
          type: integer
          format: int64
          description: The end time of the job as a Unix timestamp.
        avg_vram:
          type: integer
          description: The average VRAM used by the job
        peak_vram:
          type: integer
          description: The peak VRAM used by the job
        job_trigger_user:
          type: string
          description: The user who triggered the job.
        author:
          type: string
          description: The author of the commit
        machine_stats:
          $ref: "#/components/schemas/MachineStats"
        status:
          $ref: "#/components/schemas/WorkflowRunStatus"
        storage_file:
          $ref: "#/components/schemas/StorageFile"
    StorageFile:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the storage file
        file_path:
          type: string
          description: Path to the file in storage
        public_url:
          type: string
          description: Public URL
    Publisher:
      type: object
      properties:
        name:
          type: string
        id:
          type: string
          description: The unique identifier for the publisher. It's akin to a username. Should be lowercase.
        description:
          type: string
        website:
          type: string
        support:
          type: string
        source_code_repo:
          type: string
        logo:
          type: string
          description: URL to the publisher's logo.
        createdAt:
          type: string
          format: date-time
          description: The date and time the publisher was created.
        members:
          type: array
          items:
            $ref: "#/components/schemas/PublisherMember"
          description: A list of members in the publisher.
        status:
          $ref: "#/components/schemas/PublisherStatus"
          description: The status of the publisher.
    PublisherMember:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the publisher member.
        user:
          $ref: "#/components/schemas/PublisherUser"
          description: The user associated with this publisher member.
        role:
          type: string
          description: The role of the user in the publisher.
    Node:
      type: object
      properties:
        id:
          type: string
          description: "The unique identifier of the node."
        name:
          type: string
          description: The display name of the node.
        category:
          type: string
          description: The category of the node.
        description:
          type: string
        author:
          type: string
        license:
          type: string
          description: The path to the LICENSE file in the node's repository.
        icon:
          type: string
          description: URL to the node's icon.
        repository:
          type: string
          description: URL to the node's repository.
        tags:
          type: array
          items:
            type: string
        latest_version:
          $ref: "#/components/schemas/NodeVersion"
          description: The latest version of the node.
        rating:
          type: number
          description: The average rating of the node.
        downloads:
          type: integer
          description: The number of downloads of the node.
        publisher:
          $ref: "#/components/schemas/Publisher"
          description: The publisher of the node.
        status:
          $ref: "#/components/schemas/NodeStatus"
          description: The status of the node.
        status_detail:
          type: string
          description: The status detail of the node.
    NodeVersion:
      type: object
      properties:
        id:
          type: string
        version:
          type: string
          description: The version identifier, following semantic versioning. Must be unique for the node.
        createdAt:
          type: string
          format: date-time
          description: The date and time the version was created.
        changelog:
          type: string
          description: Summary of changes made in this version
        dependencies:
          type: array
          items:
            type: string
          description: A list of pip dependencies required by the node.
        downloadUrl:
          type: string
          description: "[Output Only] URL to download this version of the node"
        deprecated:
          type: boolean
          description: Indicates if this version is deprecated.
        status:
          $ref: "#/components/schemas/NodeVersionStatus"
          description: The status of the node version.
        status_reason:
          type: string
          description: The reason for the status change.
        node_id:
          type: string
          description: The unique identifier of the node.
    ComfyNode:
      type: object
      properties:
        comfy_node_id:
          type: string
          description: Unique identifier for the node
        category:
          type: string
          description: UI category where the node is listed, used for grouping nodes.
        description:
          type: string
          description: Brief description of the node's functionality or purpose.
        input_types:
          type: string
          description: Defines input parameters
        deprecated:
          type: boolean
          description: Indicates if the node is deprecated. Deprecated nodes are hidden in the UI.
        experimental:
          type: boolean
          description: Indicates if the node is experimental, subject to changes or removal.
        output_is_list:
          type: array
          items:
            type: boolean
          description: Boolean values indicating if each output is a list.
        return_names:
          type: string
          description: Names of the outputs for clarity in workflows.
        return_types:
          type: string
          description: Specifies the types of outputs produced by the node.
        function:
          type: string
          description: Name of the entry-point function to execute the node.
    ComfyNodeCloudBuildInfo:
      type: object
      properties: 
        project_id:
          type: string
        project_number:
          type: string
        location:
          type: string
        build_id:
          type: string
    Error:
      type: object
      properties:
        message:
          type: string
          description: A clear and concise description of the error.
        details:
          type: array
          items:
            type: string
          description: Optional detailed information about the error or hints for resolving it.
    # ======= Request body Definitions =======================
    NodeVersionUpdateRequest:
      type: object
      properties:
        changelog:
          type: string
          description: The changelog describing the version changes.
        deprecated:
          type: boolean
          description: Whether the version is deprecated.
    # Enum of Node Status
    NodeStatus:
      type: string
      enum:
        - NodeStatusActive
        - NodeStatusDeleted
        - NodeStatusBanned
    # Enum of Node Version Status
    NodeVersionStatus:
      type: string
      enum:
        - NodeVersionStatusActive
        - NodeVersionStatusDeleted
        - NodeVersionStatusBanned
        - NodeVersionStatusPending
        - NodeVersionStatusFlagged
    PublisherStatus:
      type: string
      enum:
        - PublisherStatusActive
        - PublisherStatusBanned
    WorkflowRunStatus:
      type: string
      enum:
        - WorkflowRunStatusStarted
        - WorkflowRunStatusFailed
        - WorkflowRunStatusCompleted
    MachineStats:
      type: object
      properties:
        machine_name:
          type: string
          description: Name of the machine.
        os_version:
          type: string
          description: The operating system version. eg. Ubuntu Linux 20.04
        gpu_type:
          type: string
          description: The GPU type. eg. NVIDIA Tesla K80
        cpu_capacity:
          type: string
          description: Total CPU on the machine.
        initial_cpu:
          type: string
          description: Initial CPU available before the job starts.
        memory_capacity:
          type: string
          description: Total memory on the machine.
        initial_ram:
          type: string
          description: Initial RAM available before the job starts.
        vram_time_series:
          type: object
          description: Time series of VRAM usage.
        disk_capacity:
          type: string
          description: Total disk capacity on the machine.
        initial_disk:
          type: string
          description: Initial disk available before the job starts.
        pip_freeze:
          type: string
          description: The pip freeze output
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT