openapi: 3.2.0
info:
  version: '1.0'
  title: Redocly Scout Tasks API
  termsOfService: https://redocly.com/subscription-agreement
  contact:
    name: API Support
    email: team@redocly.com
  license:
    name: Redocly
    url: https://redocly.com/subscription-agreement
  description: Operations related to tasks.
servers:
- url: https://{host}/api
  variables:
    host:
      default: app.cba.au.redocly.com
      description: Server host.
  description: Production main server.
security:
- UserCookie: []
tags:
- name: Tasks
  description: Operations related to tasks.
paths:
  /orgs/{orgId}/projects/{projectId}/scout/tasks:
    post:
      tags:
      - Tasks
      security:
      - ApiKey: []
      summary: Process next job
      description: Retrieve and start the next available job.
      operationId: startNextJob
      parameters:
      - $ref: '#/components/parameters/X-Redocly-Scout-Version'
      - $ref: '#/components/parameters/OrgId'
      - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '204':
          description: No jobs available.
        '400':
          $ref: '#/components/responses/BadRequestError'
    get:
      tags:
      - Tasks
      security:
      - ApiKey: []
      summary: List all tasks
      operationId: getAllTasks
      parameters:
      - $ref: '#/components/parameters/X-Redocly-Scout-Version'
      - $ref: '#/components/parameters/OrgId'
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/After'
      - $ref: '#/components/parameters/Before'
      - $ref: '#/components/parameters/Sort'
      - $ref: '#/components/parameters/Filter'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobList'
        '400':
          $ref: '#/components/responses/BadRequestError'
  /orgs/{orgId}/projects/{projectId}/scout/tasks/{jobId}:
    get:
      tags:
      - Tasks
      security:
      - ApiKey: []
      summary: Get task
      description: Get task.
      operationId: getJobById
      parameters:
      - $ref: '#/components/parameters/X-Redocly-Scout-Version'
      - $ref: '#/components/parameters/OrgId'
      - $ref: '#/components/parameters/ProjectId'
      - name: jobId
        description: Job ID.
        required: true
        in: path
        schema:
          type: string
          format: ulid
          example: sjob_01h2t9ksv7vmsvbhh5ty40zctw
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
    patch:
      tags:
      - Tasks
      security:
      - ApiKey: []
      summary: Update job
      description: 'Scout sends this API request after completing a job.

        Supports only `PROCESSING` -> `COMPLETED` and `PROCESSING` -> `FAILED` transitions.'
      operationId: updateJob
      parameters:
      - $ref: '#/components/parameters/X-Redocly-Scout-Version'
      - $ref: '#/components/parameters/OrgId'
      - $ref: '#/components/parameters/ProjectId'
      - name: jobId
        description: Job ID.
        required: true
        in: path
        schema:
          type: string
          format: ulid
          example: sjob_01h2t9ksv7vmsvbhh5ty40zctw
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchJob'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
components:
  parameters:
    Limit:
      name: limit
      in: query
      required: false
      schema:
        description: 'Use to return a number of results per page.

          If there is more data, use in combination with `after` to page through the data.'
        type: integer
        minimum: 1
        maximum: 100
        default: 10
    Filter:
      name: filter
      in: query
      required: false
      schema:
        description: 'Filters the collection items. This field requires a special format.


          For more information, see

          [Using filter with collections](#section/Using-filter-with-collections).'
        type: string
        example: status:approved,pending updatedAt:2020-01-01..2022-01-01
    After:
      name: after
      in: query
      required: false
      schema:
        type: string
        description: Use the `endCursor` as a value for the `after` parameter to get the next page.
        example: a25fgaksjf23la==
    Sort:
      name: sort
      in: query
      required: false
      schema:
        description: 'This list is currently not sortable by other properties.

          It is sorted by the id descending (`-id`) by default.

          To reverse the sort order, use `id` as the value.'
        type: string
        default: -id
    Before:
      name: before
      in: query
      required: false
      schema:
        type: string
        description: Use the `startCursor` as a value for the `before` parameter to get the next page.
        example: bfg23aksjf23zb1==
    OrgId:
      name: orgId
      description: Organization ID.
      required: true
      in: path
      schema:
        type: string
        example: acme-inc
    X-Redocly-Scout-Version:
      name: x-redocly-scout-version
      description: Scout version.
      required: false
      in: header
      schema:
        type: string
        example: 1.0.0
    ProjectId:
      name: projectId
      description: Project ID.
      required: true
      in: path
      schema:
        type: string
        example: my-project
  schemas:
    JobList:
      type: object
      properties:
        object:
          type: string
          const: list
        page:
          $ref: '#/components/schemas/Page'
        items:
          type: array
          minItems: 0
          items:
            $ref: '#/components/schemas/Job'
      required:
      - object
      - page
      - items
    PatchJob:
      type: object
      properties:
        status:
          type: string
          enum:
          - COMPLETED
          - FAILED
          description: Job status.
        metadata:
          $ref: '#/components/schemas/JobMetadata'
      required:
      - status
    Page:
      type: object
      properties:
        endCursor:
          type:
          - string
          - 'null'
          description: 'Use with the `after` query parameter to load the next page of data.

            When `null`, there is no data.

            The cursor is opaque and internal structure is subject to change.'
        startCursor:
          type:
          - string
          - 'null'
          description: 'Use with the `before` query parameter to load the previous page of data.

            When `null`, there is no data.

            The cursor is opaque and internal structure is subject to change.'
        hasNextPage:
          type: boolean
          description: Indicates if there is a next page with items.
        hasPrevPage:
          type: boolean
          description: Indicates if there is a previous page with items.
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
          description: Value showing how many items are in the page limit.
        total:
          type: integer
          description: Count of items across all pages.
          minimum: 0
      required:
      - endCursor
      - startCursor
      - hasNextPage
      - hasPrevPage
      - limit
      - total
    JobMetadata:
      type: object
      description: Additional information about job.
      properties:
        scoutVersion:
          type: string
          description: Scout version.
          example: 1.0.0
          readOnly: true
        errorMessage:
          type: string
          description: Error message, if any.
        errorStack:
          type: string
          description: Error stack trace, if any.
    Problem:
      type: object
      title: Problem
      properties:
        type:
          type: string
          format: uri-reference
          description: 'URI reference that uniquely identifies the problem type only in the context of the provided API. Opposed to the specification in RFC 9457 (formerly RFC 7807), it is neither recommended to be dereferenceable and point to a human-readable documentation nor globally unique for the problem type.

            '
          default: about:blank
          example: /some/uri-reference
        title:
          type: string
          description: 'Short summary of the problem type. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.

            '
          example: some title for the error situation
        status:
          type: integer
          format: int32
          description: 'HTTP status code generated by the origin server for this occurrence of the problem.

            '
          minimum: 100
          exclusiveMaximum: 600
          example: 400
        detail:
          type: string
          description: 'Human readable explanation specific to this occurrence of the problem that is helpful to locate the problem and give advice on how to proceed. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.

            '
          example: some description for the error situation
        instance:
          type: string
          format: uri-reference
          description: 'URI reference that identifies the specific occurrence of the problem, e.g. by adding a fragment identifier or sub-path to the problem type. May be used to locate the root of this problem in the source code.

            '
          example: /some/uri-reference#specific-occurrence-context
        object:
          type: string
          const: problem
      required:
      - type
      - title
      - status
      - object
    GitCommitCheck:
      type: object
      properties:
        name:
          type: string
          description: Check name.
          example: Scorecard - Compliance API
        status:
          type: string
          enum:
          - IN_PROGRESS
          - SUCCESS
          - FAILED
          description: Git commit status.
        description:
          type: string
          description: Git commit status description.
        targetUrl:
          type: string
          description: Git commit status target URL.
      required:
      - name
      - status
    Job:
      type: object
      properties:
        id:
          type: string
          format: ulid
          description: ID of the job.
          readOnly: true
          example: sjob_01h2t9ksv7vmsvbhh5ty40zctw
        status:
          readOnly: true
          type: string
          enum:
          - PENDING
          - PROCESSING
          - COMPLETED
          - FAILED
          description: Job status.
        type:
          type: string
          enum:
          - PROCESS_GIT_REPO
          - UPDATE_STATUS
          description: Type of job.
        organizationId:
          description: Organization ID.
          type: string
          readOnly: true
        projectId:
          description: Project ID.
          type: string
          readOnly: true
        providerId:
          description: Git provider identifier (appId for GitHub).
          type: string
        providerType:
          type: string
          enum:
          - GITHUB_CLOUD
          - GITHUB_SERVER
          - GITLAB_CLOUD
          - GITLAB_SELF_MANAGED
          - BITBUCKET_CLOUD
          - BITBUCKET_DATACENTER
          - AZURE
          description: Git provider type.
        namespaceId:
          type: string
          description: Git repo namespace id (organization login for GitHub).
        repositoryId:
          type: string
          description: Git repo id.
        branch:
          type: string
          description: Git branch name.
        commitSha:
          type: string
          description: Git commit SHA.
        isMainBranch:
          type: boolean
          default: false
          description: True if branch is main.
        prId:
          type: string
          description: Git pull request ID.
        attempts:
          type: integer
          description: Number of attempts to process the job.
          readOnly: true
        parentJobId:
          type: string
          description: ID of the parent job, if any.
          format: ulid
          example: sjob_01h2t9ksv7vmsvbhh5ty40zctw
        checks:
          type: array
          description: Commit status checks.
          items:
            $ref: '#/components/schemas/GitCommitCheck'
        metadata:
          $ref: '#/components/schemas/JobMetadata'
        startedAt:
          type: string
          format: date-time
          description: Job start date.
          readOnly: true
        createdAt:
          type: string
          format: date-time
          description: Job creation date.
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          description: Job last update date.
          readOnly: true
      required:
      - id
      - status
      - type
      - providerType
      - namespaceId
      - repositoryId
      - branch
      - commitSha
      - attempts
      - createdAt
      - updatedAt
  responses:
    NotFoundError:
      description: Resource not found.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    BadRequestError:
      description: Bad Request.
      content:
        application/problem+json:
          schema:
            description: Invalid credentials.
            $ref: '#/components/schemas/Problem'
  securitySchemes:
    UserCookie:
      type: apiKey
      in: cookie
      name: accessToken
      description: Default authentication scheme for interaction between browser and API.
    ApiKey:
      type: http
      scheme: bearer
      description: 'API key is required to access the API.

        You can get your API key from the [BlueHarvest dashboard](https://app.blueharvest.cloud).'
x-pagination: none