openapi: 3.0.1
info:
  title: Bytebase API
  description: >-
    Bytebase exposes a Connect/gRPC API that is also served as a RESTful HTTP
    API via gRPC transcoding (google.api.http annotations). Every action in the
    Bytebase web console is backed by this API. This document models the core
    RESTful HTTP surface - instances, databases, projects, issues (schema
    change / migration), plans, rollouts, sheets, users, roles, groups, and
    project webhooks. Authentication uses a short-lived access token obtained
    by logging in with a service account; the token is supplied as a Bearer
    token in the Authorization header. The server URL is the base of your own
    self-hosted or cloud Bytebase deployment (the public demo is shown).
  termsOfService: https://www.bytebase.com/terms
  contact:
    name: Bytebase Support
    url: https://www.bytebase.com/docs/
  version: v1
servers:
  - url: https://demo.bytebase.com/v1
    description: Bytebase public demo (replace with your own deployment host)
security:
  - bearerAuth: []
tags:
  - name: Auth
  - name: Instances
  - name: Databases
  - name: Projects
  - name: Issues
  - name: Plans
  - name: Rollouts
  - name: Sheets
  - name: Users
  - name: Roles
  - name: Groups
  - name: Webhooks
paths:
  /auth/login:
    post:
      operationId: login
      tags: [Auth]
      summary: Exchange service-account credentials for an access token.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Access token issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
  /instances:
    get:
      operationId: listInstances
      tags: [Instances]
      summary: List database instances.
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: A page of instances.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListInstancesResponse'
    post:
      operationId: createInstance
      tags: [Instances]
      summary: Create (register) a database instance.
      parameters:
        - name: instanceId
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Instance'
      responses:
        '200':
          description: The created instance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
  /instances/{instance}:
    get:
      operationId: getInstance
      tags: [Instances]
      summary: Get a single instance.
      parameters:
        - $ref: '#/components/parameters/InstancePath'
      responses:
        '200':
          description: The requested instance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
    patch:
      operationId: updateInstance
      tags: [Instances]
      summary: Update an instance.
      parameters:
        - $ref: '#/components/parameters/InstancePath'
        - $ref: '#/components/parameters/UpdateMask'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Instance'
      responses:
        '200':
          description: The updated instance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
    delete:
      operationId: deleteInstance
      tags: [Instances]
      summary: Delete an instance.
      parameters:
        - $ref: '#/components/parameters/InstancePath'
      responses:
        '200':
          description: Instance deleted.
  /instances/{instance}/databases:
    get:
      operationId: listInstanceDatabases
      tags: [Databases]
      summary: List databases discovered on an instance.
      parameters:
        - $ref: '#/components/parameters/InstancePath'
      responses:
        '200':
          description: Databases on the instance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDatabasesResponse'
  /instances/{instance}/databases/{database}:
    get:
      operationId: getDatabase
      tags: [Databases]
      summary: Get a database.
      parameters:
        - $ref: '#/components/parameters/InstancePath'
        - name: database
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The requested database.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Database'
  /projects:
    get:
      operationId: listProjects
      tags: [Projects]
      summary: List projects.
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: A page of projects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListProjectsResponse'
    post:
      operationId: createProject
      tags: [Projects]
      summary: Create a project.
      parameters:
        - name: projectId
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Project'
      responses:
        '200':
          description: The created project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
  /projects/{project}:
    get:
      operationId: getProject
      tags: [Projects]
      summary: Get a project.
      parameters:
        - $ref: '#/components/parameters/ProjectPath'
      responses:
        '200':
          description: The requested project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
  /projects/{project}/issues:
    get:
      operationId: listIssues
      tags: [Issues]
      summary: List issues in a project.
      parameters:
        - $ref: '#/components/parameters/ProjectPath'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: A page of issues.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListIssuesResponse'
    post:
      operationId: createIssue
      tags: [Issues]
      summary: Create a schema-change / data-change issue.
      parameters:
        - $ref: '#/components/parameters/ProjectPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Issue'
      responses:
        '200':
          description: The created issue.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Issue'
  /projects/{project}/issues/{issue}:
    get:
      operationId: getIssue
      tags: [Issues]
      summary: Get an issue.
      parameters:
        - $ref: '#/components/parameters/ProjectPath'
        - name: issue
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The requested issue.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Issue'
  /projects/{project}/issues/{issue}:approve:
    post:
      operationId: approveIssue
      tags: [Issues]
      summary: Approve an issue at the current approval step.
      parameters:
        - $ref: '#/components/parameters/ProjectPath'
        - name: issue
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                comment:
                  type: string
      responses:
        '200':
          description: The approved issue.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Issue'
  /projects/{project}/plans:
    post:
      operationId: createPlan
      tags: [Plans]
      summary: Create a plan describing the proposed changes.
      parameters:
        - $ref: '#/components/parameters/ProjectPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Plan'
      responses:
        '200':
          description: The created plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plan'
  /projects/{project}/rollouts:
    post:
      operationId: createRollout
      tags: [Rollouts]
      summary: Create a rollout to execute a plan.
      parameters:
        - $ref: '#/components/parameters/ProjectPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Rollout'
      responses:
        '200':
          description: The created rollout.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rollout'
  /projects/{project}/rollouts/{rollout}:
    get:
      operationId: getRollout
      tags: [Rollouts]
      summary: Get a rollout and its stages/tasks.
      parameters:
        - $ref: '#/components/parameters/ProjectPath'
        - name: rollout
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The requested rollout.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rollout'
  /projects/{project}/sheets:
    post:
      operationId: createSheet
      tags: [Sheets]
      summary: Create a sheet (SQL statement) in a project.
      parameters:
        - $ref: '#/components/parameters/ProjectPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Sheet'
      responses:
        '200':
          description: The created sheet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sheet'
  /projects/{project}/webhooks:
    post:
      operationId: addWebhook
      tags: [Webhooks]
      summary: Add a webhook to a project.
      parameters:
        - $ref: '#/components/parameters/ProjectPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Webhook'
      responses:
        '200':
          description: The project with the added webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
  /users:
    get:
      operationId: listUsers
      tags: [Users]
      summary: List users.
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: A page of users.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListUsersResponse'
    post:
      operationId: createUser
      tags: [Users]
      summary: Create a user (or service account).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: The created user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /roles:
    get:
      operationId: listRoles
      tags: [Roles]
      summary: List custom and predefined roles.
      responses:
        '200':
          description: A list of roles.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListRolesResponse'
  /groups:
    get:
      operationId: listGroups
      tags: [Groups]
      summary: List user groups.
      responses:
        '200':
          description: A list of groups.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListGroupsResponse'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Access token obtained from POST /v1/auth/login using a service-account
        email and service key. Supplied as `Authorization: Bearer <token>`.
  parameters:
    PageSize:
      name: page_size
      in: query
      schema:
        type: integer
    PageToken:
      name: page_token
      in: query
      schema:
        type: string
    UpdateMask:
      name: update_mask
      in: query
      schema:
        type: string
      description: Comma-separated list of fields to update (FieldMask).
    InstancePath:
      name: instance
      in: path
      required: true
      schema:
        type: string
      description: Instance resource id (the segment after instances/).
    ProjectPath:
      name: project
      in: path
      required: true
      schema:
        type: string
      description: Project resource id (the segment after projects/).
  schemas:
    LoginRequest:
      type: object
      properties:
        email:
          type: string
          example: my-service-account@service.bytebase.com
        password:
          type: string
          description: The service account's service key.
        web:
          type: boolean
    LoginResponse:
      type: object
      properties:
        token:
          type: string
          description: Bearer access token used in the Authorization header.
        mfaTempToken:
          type: string
    Instance:
      type: object
      properties:
        name:
          type: string
          description: Resource name, e.g. instances/prod-mysql.
        title:
          type: string
        engine:
          type: string
          enum: [MYSQL, POSTGRES, TIDB, SNOWFLAKE, CLICKHOUSE, MONGODB, SQLITE, ORACLE, MSSQL, REDIS, SPANNER, REDSHIFT, MARIADB, OCEANBASE, DM, RISINGWAVE]
        externalLink:
          type: string
        dataSources:
          type: array
          items:
            $ref: '#/components/schemas/DataSource'
        state:
          type: string
          enum: [ACTIVE, DELETED]
    DataSource:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum: [ADMIN, READ_ONLY]
        host:
          type: string
        port:
          type: string
        username:
          type: string
    Database:
      type: object
      properties:
        name:
          type: string
          description: Resource name, e.g. instances/prod-mysql/databases/shop.
        syncState:
          type: string
          enum: [OK, NOT_FOUND]
        project:
          type: string
        schemaVersion:
          type: string
    Project:
      type: object
      properties:
        name:
          type: string
          description: Resource name, e.g. projects/shop.
        title:
          type: string
        key:
          type: string
        state:
          type: string
          enum: [ACTIVE, DELETED]
    Issue:
      type: object
      properties:
        name:
          type: string
          description: Resource name, e.g. projects/shop/issues/123.
        title:
          type: string
        type:
          type: string
          enum: [DATABASE_CHANGE, GRANT_REQUEST, DATABASE_EXPORT]
        status:
          type: string
          enum: [OPEN, DONE, CANCELED]
        description:
          type: string
        plan:
          type: string
          description: Resource name of the associated plan.
        rollout:
          type: string
          description: Resource name of the associated rollout.
    Plan:
      type: object
      properties:
        name:
          type: string
          description: Resource name, e.g. projects/shop/plans/123.
        title:
          type: string
        steps:
          type: array
          items:
            type: object
            properties:
              specs:
                type: array
                items:
                  type: object
    Rollout:
      type: object
      properties:
        name:
          type: string
          description: Resource name, e.g. projects/shop/rollouts/123.
        plan:
          type: string
        stages:
          type: array
          items:
            type: object
    Sheet:
      type: object
      properties:
        name:
          type: string
          description: Resource name, e.g. projects/shop/sheets/123.
        title:
          type: string
        content:
          type: string
          format: byte
          description: The SQL statement (base64-encoded over JSON transport).
    Webhook:
      type: object
      properties:
        name:
          type: string
        type:
          type: string
          enum: [SLACK, DISCORD, TEAMS, DINGTALK, FEISHU, WECOM, CUSTOM]
        title:
          type: string
        url:
          type: string
        notificationTypes:
          type: array
          items:
            type: string
    User:
      type: object
      properties:
        name:
          type: string
          description: Resource name, e.g. users/101.
        email:
          type: string
        title:
          type: string
        userType:
          type: string
          enum: [USER, SYSTEM_BOT, SERVICE_ACCOUNT]
        state:
          type: string
          enum: [ACTIVE, DELETED]
    Role:
      type: object
      properties:
        name:
          type: string
          description: Resource name, e.g. roles/tester.
        title:
          type: string
        description:
          type: string
        permissions:
          type: array
          items:
            type: string
    Group:
      type: object
      properties:
        name:
          type: string
          description: Resource name, e.g. groups/dba@example.com.
        title:
          type: string
        members:
          type: array
          items:
            type: object
    ListInstancesResponse:
      type: object
      properties:
        instances:
          type: array
          items:
            $ref: '#/components/schemas/Instance'
        nextPageToken:
          type: string
    ListDatabasesResponse:
      type: object
      properties:
        databases:
          type: array
          items:
            $ref: '#/components/schemas/Database'
        nextPageToken:
          type: string
    ListProjectsResponse:
      type: object
      properties:
        projects:
          type: array
          items:
            $ref: '#/components/schemas/Project'
        nextPageToken:
          type: string
    ListIssuesResponse:
      type: object
      properties:
        issues:
          type: array
          items:
            $ref: '#/components/schemas/Issue'
        nextPageToken:
          type: string
    ListUsersResponse:
      type: object
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/User'
        nextPageToken:
          type: string
    ListRolesResponse:
      type: object
      properties:
        roles:
          type: array
          items:
            $ref: '#/components/schemas/Role'
    ListGroupsResponse:
      type: object
      properties:
        groups:
          type: array
          items:
            $ref: '#/components/schemas/Group'