swagger: '2.0'
info:
  title: GitLab access_requests jobs API
  version: v4
  description: Operations related to access requests
host: gitlab.com
produces:
- application/json
tags:
- name: jobs
  description: Operations about jobs
paths:
  /api/v4/runners/{id}/jobs:
    get:
      summary: List runner's jobs
      description: List jobs that are being processed or were processed by the specified runner. The list of jobs is limited to projects where the user has at least the Reporter role.
      produces:
      - application/json
      parameters:
      - in: path
        name: id
        description: The ID of a runner
        type: integer
        format: int32
        required: true
      - in: query
        name: system_id
        description: System ID associated with the runner manager
        type: string
        required: false
      - in: query
        name: status
        description: Status of the job
        type: string
        enum:
        - created
        - waiting_for_resource
        - preparing
        - waiting_for_callback
        - pending
        - running
        - success
        - failed
        - canceling
        - canceled
        - skipped
        - manual
        - scheduled
        required: false
      - in: query
        name: order_by
        description: Order by `id`
        type: string
        enum:
        - id
        required: false
      - in: query
        name: sort
        description: Sort by `asc` or `desc` order. Specify `order_by` as well, including for `id`
        type: string
        default: desc
        enum:
        - asc
        - desc
        required: false
      - in: query
        name: cursor
        description: Cursor for obtaining the next set of records
        type: string
        required: false
      - in: query
        name: page
        description: Current page number
        type: integer
        format: int32
        default: 1
        required: false
        example: 1
      - in: query
        name: per_page
        description: Number of items per page
        type: integer
        format: int32
        default: 20
        required: false
        example: 20
      responses:
        '200':
          description: List jobs running on a runner
          schema:
            $ref: '#/definitions/API_Entities_Ci_JobBasicWithProject'
        '401':
          description: Unauthorized
        '403':
          description: No access granted
        '404':
          description: Runner not found
      tags:
      - jobs
      operationId: getApiV4RunnersIdJobs
  /api/v4/jobs/request:
    post:
      description: Request a job
      produces:
      - application/json
      consumes:
      - application/json
      parameters:
      - name: postApiV4JobsRequest
        in: body
        required: true
        schema:
          $ref: '#/definitions/postApiV4JobsRequest'
      responses:
        '201':
          description: Job was scheduled
        '204':
          description: No job for Runner
        '403':
          description: Forbidden
        '409':
          description: Conflict
        '422':
          description: Runner is orphaned
        '429':
          description: Too Many Requests
      tags:
      - jobs
      operationId: postApiV4JobsRequest
  /api/v4/jobs/{id}:
    put:
      description: Update a job
      produces:
      - application/json
      consumes:
      - application/json
      parameters:
      - in: path
        name: id
        description: Job's ID
        type: integer
        format: int32
        required: true
      - name: putApiV4JobsId
        in: body
        required: true
        schema:
          $ref: '#/definitions/putApiV4JobsId'
      responses:
        '200':
          description: Job was updated
        '202':
          description: Update accepted
        '400':
          description: Unknown parameters
        '403':
          description: Forbidden
        '409':
          description: Conflict
        '429':
          description: Too Many Requests
      tags:
      - jobs
      operationId: putApiV4JobsId
  /api/v4/jobs/{id}/trace:
    patch:
      description: Append a patch to the job trace
      produces:
      - application/json
      consumes:
      - application/json
      parameters:
      - in: path
        name: id
        description: Job's ID
        type: integer
        format: int32
        required: true
      - name: patchApiV4JobsIdTrace
        in: body
        required: true
        schema:
          $ref: '#/definitions/patchApiV4JobsIdTrace'
      responses:
        '202':
          description: Trace was patched
        '400':
          description: Missing Content-Range header
        '403':
          description: Forbidden
        '416':
          description: Range not satisfiable
        '429':
          description: Too Many Requests
      tags:
      - jobs
      operationId: patchApiV4JobsIdTrace
  /api/v4/jobs/{id}/artifacts/authorize:
    post:
      description: Authorize uploading job artifact
      produces:
      - application/json
      consumes:
      - application/json
      parameters:
      - in: path
        name: id
        description: Job's ID
        type: integer
        format: int32
        required: true
      - name: postApiV4JobsIdArtifactsAuthorize
        in: body
        required: true
        schema:
          $ref: '#/definitions/postApiV4JobsIdArtifactsAuthorize'
      responses:
        '200':
          description: Upload allowed
        '403':
          description: Forbidden
        '405':
          description: Artifacts support not enabled
        '413':
          description: File too large
        '429':
          description: Too Many Requests
      tags:
      - jobs
      operationId: postApiV4JobsIdArtifactsAuthorize
  /api/v4/jobs/{id}/artifacts:
    post:
      description: Upload a job artifact
      produces:
      - application/json
      consumes:
      - application/json
      parameters:
      - in: path
        name: id
        description: Job's ID
        type: integer
        format: int32
        required: true
      - name: postApiV4JobsIdArtifacts
        in: body
        required: true
        schema:
          $ref: '#/definitions/postApiV4JobsIdArtifacts'
      responses:
        '201':
          description: Artifact uploaded
        '400':
          description: Bad request
        '403':
          description: Forbidden
        '405':
          description: Artifacts support not enabled
        '413':
          description: File too large
        '429':
          description: Too Many Requests
      tags:
      - jobs
      operationId: postApiV4JobsIdArtifacts
    get:
      description: Download the artifacts file for job
      produces:
      - application/json
      parameters:
      - in: path
        name: id
        description: Job's ID
        type: integer
        format: int32
        required: true
      - in: query
        name: token
        description: Job's authentication token
        type: string
        required: false
      - in: query
        name: direct_download
        description: Perform direct download from remote storage instead of proxying artifacts
        type: boolean
        default: false
        required: false
      responses:
        '200':
          description: Download allowed
        '302':
          description: Found
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Artifact not found
        '429':
          description: Too Many Requests
      tags:
      - jobs
      operationId: getApiV4JobsIdArtifacts
definitions:
  API_Entities_CustomAttribute:
    type: object
    properties:
      key:
        type: string
        example: foo
      value:
        type: string
        example: bar
    required:
    - key
    - value
    description: API_Entities_CustomAttribute model
  postApiV4JobsRequest:
    type: object
    properties:
      token:
        type: string
        description: Runner's authentication token
      system_id:
        type: string
        description: Runner's system identifier
      last_update:
        type: string
        description: Runner's queue last_update token
      info:
        type: object
        description: Runner's metadata
        properties:
          name:
            type: string
            description: Runner's name
          version:
            type: string
            description: Runner's version
          revision:
            type: string
            description: Runner's revision
          platform:
            type: string
            description: Runner's platform
          architecture:
            type: string
            description: Runner's architecture
          executor:
            type: string
            description: Runner's executor
          features:
            type: object
            description: Runner's features
          config:
            type: object
            description: Runner's config
            properties:
              gpus:
                type: string
                description: GPUs enabled
          labels:
            type: object
            description: Runner's labels
      session:
        type: object
        description: Runner's session data
        properties:
          url:
            type: string
            description: Session's url
          certificate:
            type: string
            description: Session's certificate
          authorization:
            type: string
            description: Session's authorization
    required:
    - token
    description: Request a job
  API_Entities_Ci_PipelineBasic:
    type: object
    properties:
      id:
        type: integer
        format: int32
        example: 1
      iid:
        type: integer
        format: int32
        example: 2
      project_id:
        type: integer
        format: int32
        example: 3
      sha:
        type: string
        example: 0ec9e58fdfca6cdd6652c083c9edb53abc0bad52
      ref:
        type: string
        example: feature-branch
      status:
        type: string
        example: success
      source:
        type: string
        example: push
      created_at:
        type: string
        format: date-time
        example: '2022-10-21T16:49:48.000+02:00'
      updated_at:
        type: string
        format: date-time
        example: '2022-10-21T16:49:48.000+02:00'
      web_url:
        type: string
        example: https://gitlab.example.com/gitlab-org/gitlab-foss/-/pipelines/61
    required:
    - id
    - iid
    - project_id
    - sha
    - ref
    - status
    - source
    - created_at
    - updated_at
    - web_url
    description: API_Entities_Ci_PipelineBasic model
  patchApiV4JobsIdTrace:
    type: object
    properties:
      token:
        type: string
        description: Job's authentication token
      debug_trace:
        type: boolean
        description: Enable or disable the debug trace
    description: Append a patch to the job trace
  postApiV4JobsIdArtifacts:
    type: object
    properties:
      file:
        type: file
        description: The artifact file to store (generated by Multipart middleware)
      token:
        type: string
        description: Job's authentication token
      expire_in:
        type: string
        description: Specify when artifact should expire
      artifact_type:
        type: string
        description: The type of artifact
        enum:
        - archive
        - metadata
        - trace
        - junit
        - sast
        - dependency_scanning
        - container_scanning
        - dast
        - codequality
        - license_scanning
        - performance
        - metrics
        - metrics_referee
        - network_referee
        - lsif
        - dotenv
        - cobertura
        - terraform
        - accessibility
        - cluster_applications
        - secret_detection
        - requirements
        - coverage_fuzzing
        - browser_performance
        - load_performance
        - api_fuzzing
        - cluster_image_scanning
        - cyclonedx
        - requirements_v2
        - annotations
        - repository_xray
        - jacoco
        - scip
        - sarif
        - environment_key
        default: archive
      artifact_format:
        type: string
        description: The format of artifact
        enum:
        - raw
        - zip
        - gzip
        default: zip
      metadata:
        type: file
        description: The artifact metadata to store (generated by Multipart middleware)
      accessibility:
        type: string
        description: Specify accessibility level of artifact private/public
    required:
    - file
    description: Upload a job artifact
  API_Entities_Commit:
    type: object
    properties:
      id:
        type: string
        example: 2695effb5807a22ff3d138d593fd856244e155e7
      short_id:
        type: string
        example: 2695effb
      created_at:
        type: string
        format: date-time
        example: '2017-07-26T11:08:53.000+02:00'
      parent_ids:
        type: array
        items:
          type: string
        example:
        - 2a4b78934375d7f53875269ffd4f45fd83a84ebe
      title:
        type: string
        example: Initial commit
      message:
        type: string
        example: Initial commit
      author_name:
        type: string
        example: John Smith
      author_email:
        type: string
        example: john@example.com
      authored_date:
        type: string
        format: date-time
        example: '2012-05-28T04:42:42-07:00'
      committer_name:
        type: string
        example: Jack Smith
      committer_email:
        type: string
        example: jack@example.com
      committed_date:
        type: string
        format: date-time
        example: '2012-05-28T04:42:42-07:00'
      trailers:
        type: object
        example:
          Merged-By: Jane Doe janedoe@gitlab.com
      extended_trailers:
        type: object
        example:
          Signed-off-by:
          - John Doe <johndoe@gitlab.com>
          - Jane Doe <janedoe@gitlab.com>
      web_url:
        type: string
        example: https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746
    required:
    - id
    - short_id
    - created_at
    - parent_ids
    - title
    - message
    - author_name
    - author_email
    - authored_date
    - committer_name
    - committer_email
    - committed_date
    - trailers
    - extended_trailers
    - web_url
    description: API_Entities_Commit model
  API_Entities_ProjectIdentity:
    type: object
    properties:
      id:
        type: integer
        format: int32
        example: 1
      description:
        type: string
        example: desc
      name:
        type: string
        example: project1
      name_with_namespace:
        type: string
        example: John Doe / project1
      path:
        type: string
        example: project1
      path_with_namespace:
        type: string
        example: namespace1/project1
      created_at:
        type: string
        format: date-time
        example: '2020-05-07T04:27:17.016Z'
    required:
    - id
    - description
    - name
    - name_with_namespace
    - path
    - path_with_namespace
    - created_at
  postApiV4JobsIdArtifactsAuthorize:
    type: object
    properties:
      token:
        type: string
        description: Job's authentication token
      filesize:
        type: integer
        format: int32
        description: Size of artifact file
      artifact_type:
        type: string
        description: The type of artifact
        enum:
        - archive
        - metadata
        - trace
        - junit
        - sast
        - dependency_scanning
        - container_scanning
        - dast
        - codequality
        - license_scanning
        - performance
        - metrics
        - metrics_referee
        - network_referee
        - lsif
        - dotenv
        - cobertura
        - terraform
        - accessibility
        - cluster_applications
        - secret_detection
        - requirements
        - coverage_fuzzing
        - browser_performance
        - load_performance
        - api_fuzzing
        - cluster_image_scanning
        - cyclonedx
        - requirements_v2
        - annotations
        - repository_xray
        - jacoco
        - scip
        - sarif
        - environment_key
        default: archive
    description: Authorize uploading job artifact
  putApiV4JobsId:
    type: object
    properties:
      token:
        type: string
        description: Job's authentication token
      state:
        type: string
        description: 'Job''s status: running, success, failed'
      checksum:
        type: string
        description: Job's trace CRC32 checksum
      failure_reason:
        type: string
        description: Job's failure_reason
      output:
        type: object
        description: Build log state
        properties:
          checksum:
            type: string
            description: Job's trace CRC32 checksum
          bytesize:
            type: integer
            format: int32
            description: Job's trace size in bytes
      exit_code:
        type: integer
        format: int32
        description: Job's exit code
    required:
    - token
    description: Update a job
  API_Entities_User:
    type: object
    properties:
      id:
        type: integer
        format: int32
        example: 1
      username:
        type: string
        example: admin
      public_email:
        type: string
        example: john@example.com
      name:
        type: string
        example: Administrator
      state:
        type: string
        example: active
      locked:
        type: boolean
      avatar_url:
        type: string
        example: https://gravatar.com/avatar/1
      avatar_path:
        type: string
        example: /user/avatar/28/The-Big-Lebowski-400-400.png
      custom_attributes:
        type: array
        items:
          $ref: '#/definitions/API_Entities_CustomAttribute'
      web_url:
        type: string
        example: https://gitlab.example.com/root
      created_at:
        type: string
      bio:
        type: string
      location:
        type: string
      linkedin:
        type: string
      twitter:
        type: string
      discord:
        type: string
      website_url:
        type: string
      github:
        type: string
      job_title:
        type: string
      pronouns:
        type: string
      organization:
        type: string
      bot:
        type: boolean
      work_information:
        type: string
      followers:
        type: string
      following:
        type: string
      is_followed:
        type: string
      local_time:
        type: string
    required:
    - id
    - username
    - public_email
    - name
    - state
    - locked
    - avatar_url
    - web_url
    - bio
    - location
    - linkedin
    - twitter
    - discord
    - website_url
    - github
    - job_title
    - pronouns
    - organization
    - bot
    - work_information
    - local_time
  API_Entities_Ci_JobBasicWithProject:
    type: object
    properties:
      id:
        type: integer
        format: int32
        example: 1
      status:
        type: string
        example: waiting_for_resource
      stage:
        type: string
        example: deploy
      name:
        type: string
        example: deploy_to_production
      ref:
        type: string
        example: main
      tag:
        type: boolean
      coverage:
        type: number
        format: float
        example: 98.29
      allow_failure:
        type: boolean
      created_at:
        type: string
        format: date-time
        example: '2015-12-24T15:51:21.880Z'
      started_at:
        type: string
        format: date-time
        example: '2015-12-24T17:54:30.733Z'
      finished_at:
        type: string
        format: date-time
        example: '2015-12-24T17:54:31.198Z'
      erased_at:
        type: string
        format: date-time
        example: '2015-12-24T18:00:29.728Z'
      duration:
        type: number
        format: float
        example: 0.465
        description: Time spent running
      queued_duration:
        type: number
        format: float
        example: 0.123
        description: Time spent enqueued
      user:
        $ref: '#/definitions/API_Entities_User'
      commit:
        $ref: '#/definitions/API_Entities_Commit'
      pipeline:
        $ref: '#/definitions/API_Entities_Ci_PipelineBasic'
      failure_reason:
        type: string
        example: script_failure
      web_url:
        type: string
        example: https://example.com/foo/bar/-/jobs/1
      project:
        $ref: '#/definitions/API_Entities_ProjectIdentity'
    required:
    - id
    - status
    - stage
    - name
    - ref
    - tag
    - coverage
    - allow_failure
    - created_at
    - started_at
    - finished_at
    - erased_at
    - duration
    - queued_duration
    - user
    - commit
    - pipeline
    - web_url
    - project
    description: API_Entities_Ci_JobBasicWithProject model
securityDefinitions:
  access_token_header:
    type: apiKey
    name: PRIVATE-TOKEN
    in: header
  access_token_query:
    type: apiKey
    name: private_token
    in: query