CircleCI Workflow API

openapi: 3.2.0
info:
  title: CircleCI REST API v2 Workflow API
  description: The CircleCI REST API v2 provides programmatic access to CircleCI services for managing pipelines, projects, workflows, jobs, and users. Developers can trigger pipelines, retrieve build status, manage contexts and environment variables, and access usage reports. The API uses token-based authentication via a Circle-Token header and returns JSON responses. It supports operations for project configuration, workflow management, artifact retrieval, and insights into build performance.
  version: '2.0'
  contact:
    name: CircleCI Support
    url: https://support.circleci.com
  termsOfService: https://circleci.com/terms-of-service/
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://circleci.com/api/v2
  description: CircleCI Production API
security:
- apiToken: []
tags:
- name: Workflow
  description: Endpoints for retrieving workflow details, managing workflow status, and rerunning workflows.
paths:
  /workflow/{id}:
    get:
      operationId: getWorkflow
      summary: Get a workflow by ID
      description: Returns a workflow by its unique identifier, including its status, pipeline ID, and timing information.
      tags:
      - Workflow
      parameters:
      - $ref: '#/components/parameters/WorkflowIdParam'
      responses:
        '200':
          description: Successfully retrieved workflow
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Workflow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /workflow/{id}/approve/{approval_request_id}:
    post:
      operationId: approveWorkflowJob
      summary: Approve a workflow job
      description: Approves a pending approval job in a workflow, allowing the workflow to continue execution.
      tags:
      - Workflow
      parameters:
      - $ref: '#/components/parameters/WorkflowIdParam'
      - name: approval_request_id
        in: path
        required: true
        description: The ID of the approval request to approve
        schema:
          type: string
          format: uuid
      responses:
        '202':
          description: Approval accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /workflow/{id}/cancel:
    post:
      operationId: cancelWorkflow
      summary: Cancel a workflow
      description: Cancels a running workflow and all of its running jobs.
      tags:
      - Workflow
      parameters:
      - $ref: '#/components/parameters/WorkflowIdParam'
      responses:
        '202':
          description: Workflow cancellation accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /workflow/{id}/rerun:
    post:
      operationId: rerunWorkflow
      summary: Rerun a workflow
      description: Reruns a workflow. Optionally, specific jobs can be selected for rerun, and SSH access can be enabled for debugging.
      tags:
      - Workflow
      parameters:
      - $ref: '#/components/parameters/WorkflowIdParam'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                jobs:
                  type: array
                  items:
                    type: string
                    format: uuid
                  description: List of job IDs to rerun. If empty, all jobs will be rerun.
                from_failed:
                  type: boolean
                  description: Whether to rerun only from failed jobs
                enable_ssh:
                  type: boolean
                  description: Whether to enable SSH access for the rerun
                sparse_tree:
                  type: boolean
                  description: Whether to rerun only the specified jobs and their dependencies
      responses:
        '202':
          description: Workflow rerun accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RerunWorkflowResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /workflow/{id}/job:
    get:
      operationId: listWorkflowJobs
      summary: List jobs for a workflow
      description: Returns a list of jobs associated with a given workflow.
      tags:
      - Workflow
      parameters:
      - $ref: '#/components/parameters/WorkflowIdParam'
      responses:
        '200':
          description: Successfully retrieved workflow jobs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowJobList'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Workflow:
      type: object
      properties:
        pipeline_id:
          type: string
          format: uuid
          description: The ID of the pipeline this workflow belongs to
        id:
          type: string
          format: uuid
          description: The unique identifier of the workflow
        name:
          type: string
          description: The name of the workflow
        project_slug:
          type: string
          description: The project slug
        status:
          type: string
          enum:
          - success
          - running
          - not_run
          - failed
          - error
          - failing
          - on_hold
          - canceled
          - unauthorized
          description: The current status of the workflow
        started_by:
          type: string
          format: uuid
          description: The ID of the user who started the workflow
        pipeline_number:
          type: integer
          description: The pipeline number
        created_at:
          type: string
          format: date-time
          description: When the workflow was created
        stopped_at:
          type: string
          format: date-time
          description: When the workflow stopped
    RerunWorkflowResponse:
      type: object
      properties:
        workflow_id:
          type: string
          format: uuid
          description: The ID of the rerun workflow
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: A human-readable error message
    MessageResponse:
      type: object
      properties:
        message:
          type: string
          description: A message describing the result of the operation
    WorkflowJobList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowJob'
          description: List of workflow jobs
        next_page_token:
          type: string
          description: Token for retrieving the next page
    WorkflowJob:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the job
        name:
          type: string
          description: The name of the job
        type:
          type: string
          enum:
          - build
          - approval
          description: The type of job
        status:
          type: string
          description: The status of the job
        job_number:
          type: integer
          description: The job number
        started_at:
          type: string
          format: date-time
          description: When the job started
        stopped_at:
          type: string
          format: date-time
          description: When the job stopped
        dependencies:
          type: array
          items:
            type: string
            format: uuid
          description: IDs of jobs this job depends on
  parameters:
    WorkflowIdParam:
      name: id
      in: path
      required: true
      description: The unique identifier of the workflow
      schema:
        type: string
        format: uuid
  securitySchemes:
    apiToken:
      type: apiKey
      in: header
      name: Circle-Token
      description: Personal API token for authenticating with the CircleCI API. Generate tokens in your CircleCI account settings.
    basicAuth:
      type: http
      scheme: basic
      description: HTTP basic authentication using a personal API token as the username with an empty password.
externalDocs:
  description: CircleCI API v2 Documentation
  url: https://circleci.com/docs/api/v2/