Redocly Scout API

openapi: 3.1.0
info:
  version: '1.0'
  title: Redocly Scout
  termsOfService: https://redocly.com/subscription-agreement
  contact:
    name: API Support
    email: team@redocly.com
  license:
    name: Redocly
    url: https://redocly.com/subscription-agreement
servers:
  - url: https://{host}/api
    variables:
      host:
        default: app.cba.au.redocly.com
        description: Server host.
    description: Production main server.
security:
  - UserCookie: []
tags:
  - name: Remotes
    description: Operations related to remotes.
  - name: Metadata
    description: Operations related to metadata.
  - name: Todos
    description: Operations related to todos.
  - name: Tasks
    description: Operations related to tasks.
  - name: Status
    description: Operations related to status.
paths:
  /orgs/{orgId}/projects/{projectId}/remotes:
    parameters:
      - $ref: '#/components/parameters/OrgId'
      - $ref: '#/components/parameters/ProjectId'
    post:
      tags:
        - Remotes
      operationId: upsertRemote
      summary: Upsert remote
      security:
        - ApiKey: []
        - UserCookie: []
      description: >-
        Upsert remote.

        If remote with the same `mountPath` and `type` already exists the remote
        object is returned.

        If the `type` doesn't match the existing remote, a 409 error is
        returned.

        Otherwise, a new remote is created.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRemote'
      responses:
        '201':
          description: Remote created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Remote'
        '400':
          $ref: '#/components/responses/BadRequestError'
  /orgs/{orgId}/projects/{projectId}/remotes/{remoteId}/push:
    parameters:
      - $ref: '#/components/parameters/OrgId'
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/RemoteId'
    post:
      tags:
        - Remotes
      operationId: pushToRemote
      summary: Push files to remote
      security:
        - ApiKey: []
      description: >-
        Push discovered files as a remote content.

        Files should be sent as a multipart/form-data.

        Commit details like commit message and author can be sent as a JSON
        object in the `commit` field.
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/RemotePush'
      responses:
        '200':
          description: Content pushed.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/PullRequest'
                  - type: object
                    required:
                      - branchName
                      - hasChanges
                    properties:
                      branchName:
                        type: string
                      hasChanges:
                        type: boolean
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /orgs/{orgId}/projects/{projectId}/scout/todos:
    post:
      tags:
        - Todos
      security:
        - ApiKey: []
      summary: Create a job todo
      description: >-
        Git provider webhook triggers Scout to create a job todo.

        Similarly, a lint job started or completed triggers jobs todo.

        Since Scout is stateless and distributed, this is the API for storing
        things to do.

        It's also a way to communicate with Scout by making jobs for it to do
        too (such as communicating status back to Git).

        Finally, it can be used to trigger Scout to update again in the case of
        a GitHub webhook outage.
      operationId: createTodo
      parameters:
        - $ref: '#/components/parameters/X-Redocly-Scout-Version'
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Job'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '400':
          $ref: '#/components/responses/BadRequestError'
    get:
      tags:
        - Todos
      security:
        - ApiKey: []
      summary: List all todos
      operationId: getAllTodos
      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:
    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'
  /orgs/{orgId}/projects/{projectId}/scout/status:
    post:
      tags:
        - Status
      security:
        - ApiKey: []
      summary: Push status
      description: Scout uses this to periodically report it's status back to main api.
      operationId: reportStatus
      parameters:
        - $ref: '#/components/parameters/X-Redocly-Scout-Version'
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Status'
      responses:
        '204':
          description: No content.
        '400':
          $ref: '#/components/responses/BadRequestError'
  /orgs/{orgId}/projects/{projectId}/scout/metadata/validate:
    post:
      tags:
        - Metadata
      security:
        - ApiKey: []
      summary: Get metadata validation result
      description: Validate api metadata against "metadataSchema" in project's config file.
      operationId: validateMetadata
      parameters:
        - $ref: '#/components/parameters/X-Redocly-Scout-Version'
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Metadata'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataValidationResult'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
components:
  schemas:
    GitProviderType:
      type: string
      format: enum
      description: Git provider type.
      enum:
        - GITHUB_CLOUD
        - GITHUB_SERVER
        - GITLAB_CLOUD
        - GITLAB_SELF_MANAGED
        - BITBUCKET_CLOUD
        - BITBUCKET_DATACENTER
        - AZURE
    CreateRemote:
      type: object
      required:
        - mountPath
        - type
      properties:
        mountPath:
          type: string
          description: Remote target path.
          example: apis/test/@v1
        type:
          type: string
          description: >-
            Remote type. TODO: Add discriminator by type and add other fields
            for GIT and URL remote types.
          enum:
            - CICD
            - GIT
            - URL
          example: CICD
        autoSync:
          type: boolean
          description: Auto sync changes to remote.
        autoMerge:
          type: boolean
          description: Auto merge changes from remote.
        createdAt:
          type: string
          readOnly: true
          examples:
            - '2023-06-07T00:00:00Z'
          format: date-time
        updatedAt:
          type: string
          readOnly: true
          examples:
            - '2023-06-07T00:00:00Z'
          format: date-time
        providerType:
          $ref: '#/components/schemas/GitProviderType'
        namespaceId:
          type: string
          readOnly: true
        repositoryId:
          type: string
          readOnly: true
        projectId:
          readOnly: true
          type:
            - string
            - 'null'
        mountBranchName:
          type: string
          readOnly: true
        contentPath:
          type: string
          readOnly: true
        credentialId:
          type: string
          readOnly: true
        branchName:
          type: string
          readOnly: true
        contentType:
          type: string
          readOnly: true
          enum:
            - FOLDER
            - FILE
          example: FILE
    Remote:
      allOf:
        - $ref: '#/components/schemas/CreateRemote'
        - type: object
          properties:
            id:
              type: string
              description: Remote ID.
              example: rem_01h2captefvs9bpg3v6twqqj9n
              readOnly: true
          required:
            - id
    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
    RemotePush:
      type: object
      required:
        - commit
        - jobId
      properties:
        commit:
          type: object
          description: Commit details.
          required:
            - message
            - author
          properties:
            namespace:
              type: string
              description: Git repo namespace (organization login for GitHub).
              example: Redocly
            repository:
              type: string
              description: Git repo name.
              example: redoc
            message:
              type: string
              description: Commit message.
              example: 'chore: Add new API'
            author:
              type: object
              required:
                - email
                - name
              properties:
                name:
                  description: Commit author name.
                  example: John Doe
                email:
                  type: string
                  description: Commit author email.
                  format: email
                  example: johndoe@example.com
                image:
                  type: string
                  description: >-
                    Commit author image URL.

                    If not provided, the default image is used.

                    If the image may not accessible, [data
                    url](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs)
                    can be used.
        jobId:
          type: string
          format: ulid
          description: ID of the `PROCESS_GIT_REPO` job, if any.
          example: job_01f1q3q1q1q1q1q1q1q1q1q1q1
        replace:
          type: boolean
          description: >-
            Whether to replace the existing files.

            If provided, all files from the remote are removed and the new files
            are added.

            If not provided, the existing files are kept and the new files are
            added, overwriting the existing files where they overlap.
          example: true
          default: false
        files:
          type: object
          description: Map of files to upload.
          additionalProperties:
            description: Files to push.
            type: string
            format: binary
    PullRequest:
      type: object
      properties:
        id:
          type: string
          format: ulid
          example: pr_01h1s5z6vf2mm1mz3hevnn9va7
          description: Pull request Id.
          readOnly: true
        number:
          description: Pull request number.
          type: integer
          example: 1
          readOnly: true
        branchName:
          description: Branch name.
          type: string
          example: main
          maxLength: 512
        title:
          description: PR title.
          type: string
          maxLength: 512
        description:
          description: PR description.
          type: string
        status:
          description: PR status.
          type: string
          default: OPEN
          enum:
            - OPEN
            - CLOSED
            - MERGED
        isDraft:
          description: Indicates whether or not the pull request is a draft.
          type: boolean
        reviewers:
          description: List of reviewers.
          type: array
          readOnly: true
          items:
            type: object
            properties:
              id:
                type: string
                format: ulid
                example: usr_01h1s5z6vf2mm1mz3hevnn9va7
                description: User id.
                readOnly: true
              firstName:
                description: User first name.
                type: string
                readOnly: true
              lastName:
                description: User last name.
                type: string
                readOnly: true
            required:
              - id
              - firstName
              - lastName
          default: []
        createdBy:
          description: User who create PR.
          type: object
          readOnly: true
          properties:
            id:
              type: string
              format: ulid
              example: usr_01h1s5z6vf2mm1mz3hevnn9va7
              description: User id.
              readOnly: true
            firstName:
              description: User first name.
              type: string
              readOnly: true
            lastName:
              description: User last name.
              type: string
              readOnly: true
          required:
            - id
            - firstName
            - lastName
        closedById:
          type: string
          format: ulid
          example: usr_01h1s5z6vf2mm1mz3hevnn9va7
          description: User id who close PR.
          readOnly: true
        mergedById:
          type: string
          format: ulid
          example: usr_01h1s5z6vf2mm1mz3hevnn9va7
          description: User id who merged PR.
          readOnly: true
        organizationId:
          description: Organization ID.
          type: string
          readOnly: true
        organization:
          description: Organization.
          properties:
            name:
              description: Organization name.
              type: string
        projectId:
          description: Project ID.
          type: string
          readOnly: true
        project:
          description: Project.
          type: object
          properties:
            name:
              description: Project name.
              type: string
        reviews:
          description: list of reviews.
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: ulid
                example: rev_01h1s5z6vf2mm1mz3hevnn9va7
              status:
                type: string
                enum:
                  - APPROVED
                  - REQUESTED_CHANGES
                  - COMMENTED
              userId:
                type: string
                format: ulid
                example: usr_01h1s5z6vf2mm1mz3hevnn9va7
              user:
                type: object
                properties:
                  id:
                    type: string
                    format: ulid
                    example: usr_01h1s5z6vf2mm1mz3hevnn9va7
                    description: User id.
                  firstName:
                    description: User first name.
                    type: string
                  lastName:
                    description: User last name.
                    type: string
        createdAt:
          description: Created date.
          type: string
          readOnly: true
          format: date-time
        updatedAt:
          description: Updated date.
          type: string
          readOnly: true
          format: date-time
      required:
        - id
        - number
        - branchName
        - commitHash
        - title
        - status
        - reviewers
        - createdAt
        - updatedAt
        - createdBy
    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
    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
    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.
    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
    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
    Status:
      type: object
      properties:
        hostname:
          type: string
          description: Hostname of Scout instance.
        pid:
          type: integer
          description: Process ID.
        version:
          type: string
          description: Scout version.
        disk:
          type: object
          description: Disk usage.
          properties:
            size:
              type: integer
              description: Total disk size.
            used:
              type: integer
              description: Used disk size.
            available:
              type: integer
              description: Available disk size.
            unit:
              type: string
              description: Disk size unit.
              enum:
                - B
                - KB
                - MB
                - GB
                - TB
              example: MB
          required:
            - size
            - used
            - available
            - unit
        jobs:
          type: object
          description: Scout jobs.
          properties:
            active:
              type: integer
              description: Number of active jobs.
            max:
              type: integer
              description: Maximum number of jobs.
          required:
            - active
            - max
      required:
        - hostname
        - pid
        - version
        - disk
        - jobs
    Metadata:
      type: object
      description: Any object shape.
      example:
        department: IT
    MetadataValidationResult:
      type: object
      properties:
        isValid:
          type: boolean
          example: false
        errors:
          type: array
          items:
            type: object
            properties:
              keyword:
                type: string
                description: Validation keyword.
              instancePath:
                type: string
                description: JSON Pointer to the location in the data instance.
                example: /prop/1/subProp
              schemaPath:
                type: string
                description: >-
                  JSON Pointer to the location of the failing keyword in the
                  schema.
              params:
                type: object
                description: Additional information about error.
                example:
                  missingProperty: owner
              propertyName:
                type: string
                description: Set for errors in `propertyNames` keyword schema.
              message:
                type: string
                description: Error message.
              schema:
                description: Value of the failing keyword in the schema.
              parentSchema:
                type: object
                description: Schema containing the keyword.
              data:
                description: Data validated by the keyword.
            required:
              - keyword
              - instancePath
              - schemaPath
              - params
            example:
              instancePath: ''
              schemaPath: '#/required'
              keyword: required
              params:
                missingProperty: owner
              message: must have required property 'owner'
          description: Array of metadata validation errors.
      required:
        - isValid
  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).
  parameters:
    OrgId:
      name: orgId
      description: Organization ID.
      required: true
      in: path
      schema:
        type: string
        example: acme-inc
    ProjectId:
      name: projectId
      description: Project ID.
      required: true
      in: path
      schema:
        type: string
        example: my-project
    RemoteId:
      name: remoteId
      description: ID of the remote.
      required: true
      in: path
      schema:
        type: string
        format: ulid
        example: rem_01h1s5z6vf2mm1mz3hevnn9va7
    X-Redocly-Scout-Version:
      name: x-redocly-scout-version


# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/redocly/refs/heads/main/openapi/redocly-scout-openapi.yaml