openapi: 3.1.1
info:
  title: Core access-groups vcs API
  description: Core services for Scalar
  version: 1.0.1
  contact:
    name: Marc from Scalar
    url: https://scalar.com
    email: support@scalar.com
security:
- BearerAuth: []
tags:
- name: vcs
paths:
  /vcs/bitbucket/authorize:
    get:
      tags:
      - vcs
      description: Get and save a user Bitbucket token to their database object. This allows subsequent queries for Bitbucket data from the user scope.
      operationId: getvcsBitbucketAuthorize
      responses:
        '200':
          description: Default Response
          content:
            text/plain:
              schema:
                type: string
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400'
        '401':
          description: No auth
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404'
        '422':
          description: Invalid payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422'
        '500':
          description: Uncaught error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500'
      security: []
      parameters:
      - schema:
          type: string
        in: query
        name: code
        required: true
      - schema:
          type: string
        in: query
        name: state
        required: true
  /vcs/bitbucket/link/initiate:
    get:
      tags:
      - vcs
      description: Issue a signed OAuth state token for the Bitbucket user-authorization flow and return the Bitbucket authorize URL the client should redirect to. Optionally remembers a dashboard path to return the user to after the round-trip.
      operationId: getvcsBitbucketLinkInitiate
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                required:
                - url
                additionalProperties: false
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400'
        '401':
          description: No auth
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404'
        '422':
          description: Invalid payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422'
        '500':
          description: Uncaught error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500'
      parameters:
      - schema:
          type: string
        in: query
        name: redirect
        required: false
  /vcs/bitbucket/workspaces:
    get:
      tags:
      - vcs
      description: List the calling user's Bitbucket workspaces and the repositories they can write to. Used by the link-to-Bitbucket UI.
      operationId: getvcsBitbucketWorkspaces
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    uuid:
                      type: string
                    slug:
                      type: string
                    name:
                      type: string
                    iconUrl:
                      type: string
                    repos:
                      type: array
                      items:
                        type: object
                        properties:
                          uuid:
                            type: string
                          slug:
                            type: string
                          fullName:
                            type: string
                          defaultBranch:
                            type: string
                          isPrivate:
                            type: boolean
                          workspaceUuid:
                            type: string
                          workspaceSlug:
                            type: string
                        required:
                        - uuid
                        - slug
                        - fullName
                        - defaultBranch
                        - isPrivate
                        - workspaceUuid
                        - workspaceSlug
                        additionalProperties: false
                  required:
                  - uuid
                  - slug
                  - name
                  - repos
                  additionalProperties: false
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400'
        '401':
          description: No auth
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404'
        '422':
          description: Invalid payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422'
        '500':
          description: Uncaught error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500'
  /vcs/bitbucket/docs-project/{uid}/branches:
    get:
      tags:
      - vcs
      description: 'List branches on the Bitbucket repo backing a `provider: ''bitbucket''` DocsProject. Supports prefix search via the `query` param.'
      operationId: getvcsBitbucketDocsProjectUidBranches
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  branches:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        isDefault:
                          type: boolean
                      required:
                      - name
                      - isDefault
                      additionalProperties: false
                  hasMore:
                    type: boolean
                required:
                - branches
                - hasMore
                additionalProperties: false
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400'
        '401':
          description: No auth
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404'
        '422':
          description: Invalid payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422'
        '500':
          description: Uncaught error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500'
      parameters:
      - schema:
          type: string
        in: path
        name: uid
        required: true
      - schema:
          type: string
        in: query
        name: query
        required: false
      - schema:
          default: 1
          type: number
        in: query
        name: page
        required: true
      - schema:
          default: 100
          type: number
        in: query
        name: perPage
        required: true
  /vcs/bitbucket/disconnect-account:
    post:
      tags:
      - vcs
      description: Wipe the calling user's Bitbucket OAuth tokens. Any DocsProjects this user linked will lose their token and need to be re-linked or have the linker swap accounts on Bitbucket.
      operationId: postvcsBitbucketDisconnectAccount
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                required:
                - success
                additionalProperties: false
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400'
        '401':
          description: No auth
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404'
        '422':
          description: Invalid payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422'
        '500':
          description: Uncaught error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500'
  /vcs/github/disconnect-account:
    post:
      tags:
      - vcs
      description: Wipe the calling user's GitHub OAuth tokens. Any DocsProjects this user linked will lose their token; the user can reconnect at any time.
      operationId: postvcsGithubDisconnectAccount
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                required:
                - success
                additionalProperties: false
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400'
        '401':
          description: No auth
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404'
        '422':
          description: Invalid payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422'
        '500':
          description: Uncaught error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500'
components:
  schemas:
    '404':
      type: object
      properties:
        message:
          type: string
        code:
          type: string
      required:
      - message
      - code
    '401':
      type: object
      properties:
        message:
          type: string
        code:
          type: string
      required:
      - message
      - code
    '500':
      type: object
      properties:
        message:
          type: string
        code:
          type: string
      required:
      - message
      - code
    '400':
      type: object
      properties:
        message:
          type: string
        code:
          type: string
      required:
      - message
      - code
    '403':
      type: object
      properties:
        message:
          type: string
        code:
          type: string
      required:
      - message
      - code
    '422':
      type: object
      properties:
        message:
          type: string
        code:
          type: string
      required:
      - message
      - code
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT