CircleCI Job API

openapi: 3.2.0
info:
  title: CircleCI REST API v2 Job 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: Job
  description: Endpoints for retrieving job details, artifacts, and test metadata associated with pipeline jobs.
paths:
  /project/{project-slug}/job/{job-number}:
    get:
      operationId: getJob
      summary: Get job details
      description: Returns detailed information about a specific job, including its status, duration, and executor configuration.
      tags:
      - Job
      parameters:
      - $ref: '#/components/parameters/ProjectSlugParam'
      - $ref: '#/components/parameters/JobNumberParam'
      responses:
        '200':
          description: Successfully retrieved job details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /project/{project-slug}/job/{job-number}/cancel:
    post:
      operationId: cancelJob
      summary: Cancel a job
      description: Cancels a running job by its job number.
      tags:
      - Job
      parameters:
      - $ref: '#/components/parameters/ProjectSlugParam'
      - $ref: '#/components/parameters/JobNumberParam'
      responses:
        '200':
          description: Job cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /project/{project-slug}/{job-number}/artifacts:
    get:
      operationId: listJobArtifacts
      summary: List artifacts for a job
      description: Returns a paginated list of artifacts produced by a given job.
      tags:
      - Job
      parameters:
      - $ref: '#/components/parameters/ProjectSlugParam'
      - $ref: '#/components/parameters/JobNumberParam'
      responses:
        '200':
          description: Successfully retrieved artifacts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactList'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /project/{project-slug}/{job-number}/tests:
    get:
      operationId: listJobTests
      summary: List test metadata for a job
      description: Returns test metadata for a given job, collected from JUnit XML or similar test result files.
      tags:
      - Job
      parameters:
      - $ref: '#/components/parameters/ProjectSlugParam'
      - $ref: '#/components/parameters/JobNumberParam'
      responses:
        '200':
          description: Successfully retrieved test metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestList'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: A human-readable error message
    ArtifactList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Artifact'
          description: List of artifacts
        next_page_token:
          type: string
          description: Token for retrieving the next page
    MessageResponse:
      type: object
      properties:
        message:
          type: string
          description: A message describing the result of the operation
    TestMetadata:
      type: object
      properties:
        message:
          type: string
          description: The test message
        source:
          type: string
          description: The source of the test
        run_time:
          type: string
          description: The run time of the test
        file:
          type: string
          description: The file containing the test
        result:
          type: string
          description: The result of the test
        name:
          type: string
          description: The name of the test
        classname:
          type: string
          description: The class name of the test
    TestList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/TestMetadata'
          description: List of test metadata
        next_page_token:
          type: string
          description: Token for retrieving the next page
    Artifact:
      type: object
      properties:
        path:
          type: string
          description: The artifact path
        node_index:
          type: integer
          description: The node index that produced this artifact
        url:
          type: string
          format: uri
          description: URL to download the artifact
    Job:
      type: object
      properties:
        web_url:
          type: string
          format: uri
          description: URL to view the job in the CircleCI web app
        project:
          type: object
          properties:
            slug:
              type: string
              description: The project slug
            name:
              type: string
              description: The project name
            external_url:
              type: string
              format: uri
              description: External URL to the project
          description: The project this job belongs to
        parallel_runs:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
                description: The parallel run index
              status:
                type: string
                description: The status of this parallel run
          description: Parallel run information
        started_at:
          type: string
          format: date-time
          description: When the job started
        latest_workflow:
          type: object
          properties:
            id:
              type: string
              format: uuid
              description: The workflow ID
            name:
              type: string
              description: The workflow name
          description: The latest workflow this job is part of
        name:
          type: string
          description: The name of the job
        executor:
          type: object
          properties:
            type:
              type: string
              description: The executor type
            resource_class:
              type: string
              description: The resource class
          description: The executor configuration
        parallelism:
          type: integer
          description: The parallelism level
        status:
          type: string
          description: The current status of the job
        number:
          type: integer
          description: The job number
        pipeline:
          type: object
          properties:
            id:
              type: string
              format: uuid
              description: The pipeline ID
          description: The pipeline this job belongs to
        duration:
          type: integer
          description: The duration of the job in milliseconds
        created_at:
          type: string
          format: date-time
          description: When the job was created
        stopped_at:
          type: string
          format: date-time
          description: When the job stopped
  parameters:
    ProjectSlugParam:
      name: project-slug
      in: path
      required: true
      description: The project slug in the form vcs-slug/org-name/repo-name (e.g., gh/CircleCI-Public/api-preview-docs)
      schema:
        type: string
    JobNumberParam:
      name: job-number
      in: path
      required: true
      description: The number of the job
      schema:
        type: integer
  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/