CircleCI Job API

openapi: 3.1.0
info:
  title: CircleCI REST API v1 Artifact Job API
  description: The CircleCI REST API v1 is the legacy API that provides access to build information, project details, and user data. While still available, CircleCI recommends migrating to the v2 API for newer features and improved functionality. The v1 API supports operations for retrieving build details, triggering builds, managing SSH keys, and accessing test metadata. Authentication is handled through API tokens passed as query parameters or HTTP headers.
  version: '1.1'
  contact:
    name: CircleCI Support
    url: https://support.circleci.com
  termsOfService: https://circleci.com/terms-of-service/
servers:
- url: https://circleci.com/api/v1.1
  description: CircleCI Production API v1.1
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:
    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
    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
    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
    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
    MessageResponse:
      type: object
      properties:
        message:
          type: string
          description: A message describing the result of the operation
    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
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: A human-readable error message
  parameters:
    JobNumberParam:
      name: job-number
      in: path
      required: true
      description: The number of the job
      schema:
        type: integer
    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
  securitySchemes:
    apiToken:
      type: apiKey
      in: header
      name: Circle-Token
      description: Personal API token for authenticating with the CircleCI API. Can also be passed as a query parameter.
externalDocs:
  description: CircleCI API v1 Reference
  url: https://circleci.com/docs/api/v1/