Redocly Remotes API

openapi: 3.2.0
info:
  version: '1.0'
  title: Redocly Scout Remotes 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 remotes.
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.
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'
components:
  schemas:
    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
    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
    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
    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
    GitProviderType:
      type: string
      format: enum
      description: Git provider type.
      enum:
      - GITHUB_CLOUD
      - GITHUB_SERVER
      - GITLAB_CLOUD
      - GITLAB_SELF_MANAGED
      - BITBUCKET_CLOUD
      - BITBUCKET_DATACENTER
      - AZURE
    Remote:
      allOf:
      - $ref: '#/components/schemas/CreateRemote'
      - type: object
        properties:
          id:
            type: string
            description: Remote ID.
            example: rem_01h2captefvs9bpg3v6twqqj9n
            readOnly: true
        required:
        - id
  parameters:
    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
    OrgId:
      name: orgId
      description: Organization ID.
      required: true
      in: path
      schema:
        type: string
        example: acme-inc
  responses:
    BadRequestError:
      description: Bad Request.
      content:
        application/problem+json:
          schema:
            description: Invalid credentials.
            $ref: '#/components/schemas/Problem'
    NotFoundError:
      description: Resource not found.
      content:
        application/problem+json:
          schema:
            $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