openapi: 3.1.0
info:
  title: PlanetScale Platform Backups Deploy Requests API
  description: The PlanetScale Platform API provides programmatic access to manage PlanetScale serverless MySQL-compatible databases. It allows developers to create and manage databases, branches, deploy requests, passwords, backups, service tokens, organization members, teams, bouncers, and billing data. The API supports authentication via service tokens and OAuth, enabling integration into CI/CD pipelines and infrastructure-as-code workflows.
  version: 1.0.0
  contact:
    name: PlanetScale Support
    url: https://support.planetscale.com
  termsOfService: https://planetscale.com/legal/tos
  license:
    name: Proprietary
    url: https://planetscale.com/legal/tos
servers:
- url: https://api.planetscale.com/v1
  description: PlanetScale Production API
security:
- serviceToken: []
tags:
- name: Deploy Requests
  description: Manage deploy requests for applying schema changes from development branches to production, including creating, reviewing, queueing, and completing deployments.
paths:
  /organizations/{organization}/databases/{database}/deploy-requests:
    get:
      operationId: listDeployRequests
      summary: List deploy requests
      description: Returns a list of all deploy requests for a specific database.
      tags:
      - Deploy Requests
      parameters:
      - $ref: '#/components/parameters/OrganizationParam'
      - $ref: '#/components/parameters/DatabaseParam'
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response with list of deploy requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DeployRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createDeployRequest
      summary: Create a deploy request
      description: Creates a new deploy request to merge schema changes from a development branch into the target branch.
      tags:
      - Deploy Requests
      parameters:
      - $ref: '#/components/parameters/OrganizationParam'
      - $ref: '#/components/parameters/DatabaseParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - branch
              properties:
                branch:
                  type: string
                  description: The name of the source branch containing schema changes.
                into_branch:
                  type: string
                  description: The name of the target branch to deploy into. Defaults to the production branch.
                notes:
                  type: string
                  description: Notes or description for the deploy request.
      responses:
        '201':
          description: Deploy request created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeployRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /organizations/{organization}/databases/{database}/deploy-requests/{deploy_request_number}:
    get:
      operationId: getDeployRequest
      summary: Get a deploy request
      description: Returns details about a specific deploy request, including its status, schema changes, and deployment history.
      tags:
      - Deploy Requests
      parameters:
      - $ref: '#/components/parameters/OrganizationParam'
      - $ref: '#/components/parameters/DatabaseParam'
      - $ref: '#/components/parameters/DeployRequestNumberParam'
      responses:
        '200':
          description: Successful response with deploy request details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeployRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: closeDeployRequest
      summary: Close a deploy request
      description: Closes an open deploy request without deploying the changes.
      tags:
      - Deploy Requests
      parameters:
      - $ref: '#/components/parameters/OrganizationParam'
      - $ref: '#/components/parameters/DatabaseParam'
      - $ref: '#/components/parameters/DeployRequestNumberParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                state:
                  type: string
                  description: The desired state of the deploy request.
                  enum:
                  - closed
      responses:
        '200':
          description: Deploy request closed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeployRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /organizations/{organization}/databases/{database}/deploy-requests/{deploy_request_number}/deploy:
    post:
      operationId: queueDeployRequest
      summary: Queue a deploy request
      description: Queues a deploy request for deployment, applying the schema changes to the target branch.
      tags:
      - Deploy Requests
      parameters:
      - $ref: '#/components/parameters/OrganizationParam'
      - $ref: '#/components/parameters/DatabaseParam'
      - $ref: '#/components/parameters/DeployRequestNumberParam'
      responses:
        '200':
          description: Deploy request queued successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeployRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /organizations/{organization}/databases/{database}/deploy-requests/{deploy_request_number}/reviews:
    get:
      operationId: listDeployRequestReviews
      summary: List deploy request reviews
      description: Returns a list of reviews for a specific deploy request.
      tags:
      - Deploy Requests
      parameters:
      - $ref: '#/components/parameters/OrganizationParam'
      - $ref: '#/components/parameters/DatabaseParam'
      - $ref: '#/components/parameters/DeployRequestNumberParam'
      responses:
        '200':
          description: Successful response with list of reviews
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DeployRequestReview'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: reviewDeployRequest
      summary: Review a deploy request
      description: Submits a review for a deploy request, approving or requesting changes.
      tags:
      - Deploy Requests
      parameters:
      - $ref: '#/components/parameters/OrganizationParam'
      - $ref: '#/components/parameters/DatabaseParam'
      - $ref: '#/components/parameters/DeployRequestNumberParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - state
              properties:
                state:
                  type: string
                  description: The review state.
                  enum:
                  - approved
                  - changes_requested
                  - commented
                body:
                  type: string
                  description: The review comment body.
      responses:
        '201':
          description: Review submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeployRequestReview'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /organizations/{organization}/databases/{database}/deploy-requests/{deploy_request_number}/skip-revert:
    post:
      operationId: skipDeployRequestRevert
      summary: Skip revert period
      description: Skips the revert period for a completed deploy request, finalizing the schema changes.
      tags:
      - Deploy Requests
      parameters:
      - $ref: '#/components/parameters/OrganizationParam'
      - $ref: '#/components/parameters/DatabaseParam'
      - $ref: '#/components/parameters/DeployRequestNumberParam'
      responses:
        '200':
          description: Revert period skipped successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeployRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /organizations/{organization}/databases/{database}/deploy-requests/{deploy_request_number}/complete-revert:
    post:
      operationId: completeDeployRequestRevert
      summary: Complete a revert
      description: Completes a revert of a deployed schema change, rolling back to the previous schema.
      tags:
      - Deploy Requests
      parameters:
      - $ref: '#/components/parameters/OrganizationParam'
      - $ref: '#/components/parameters/DatabaseParam'
      - $ref: '#/components/parameters/DeployRequestNumberParam'
      responses:
        '200':
          description: Revert completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeployRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /organizations/{organization}/databases/{database}/deploy-queue:
    get:
      operationId: getDeployQueue
      summary: Get the deploy queue
      description: Returns the current deploy queue for a database, showing pending and active deployments.
      tags:
      - Deploy Requests
      parameters:
      - $ref: '#/components/parameters/OrganizationParam'
      - $ref: '#/components/parameters/DatabaseParam'
      responses:
        '200':
          description: Successful response with deploy queue
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DeployRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    DeployRequestReview:
      type: object
      description: A review submitted for a deploy request.
      properties:
        id:
          type: string
          description: The unique identifier of the review.
        state:
          type: string
          description: The review state.
          enum:
          - approved
          - changes_requested
          - commented
        body:
          type: string
          description: The review comment body.
        actor:
          type: object
          description: The user who submitted the review.
          properties:
            id:
              type: string
              description: The user ID.
            display_name:
              type: string
              description: The display name of the user.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the review was created.
    DeployRequest:
      type: object
      description: A deploy request for applying schema changes from a development branch to a target branch.
      properties:
        id:
          type: string
          description: The unique identifier of the deploy request.
        number:
          type: integer
          description: The deploy request number within the database.
        branch:
          type: string
          description: The name of the source branch with schema changes.
        into_branch:
          type: string
          description: The name of the target branch to deploy into.
        state:
          type: string
          description: The current state of the deploy request.
          enum:
          - open
          - closed
          - pending
          - queued
          - in_progress
          - complete
          - complete_pending_revert
          - complete_reverted
          - complete_error
        approved:
          type: boolean
          description: Whether the deploy request has been approved.
        deployment:
          type: object
          description: Information about the active or completed deployment.
          properties:
            state:
              type: string
              description: The state of the deployment.
            started_at:
              type: string
              format: date-time
              description: The timestamp when deployment started.
            finished_at:
              type: string
              format: date-time
              description: The timestamp when deployment finished.
        notes:
          type: string
          description: Notes or description for the deploy request.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the deploy request was created.
        updated_at:
          type: string
          format: date-time
          description: The timestamp when the deploy request was last updated.
        closed_at:
          type: string
          format: date-time
          description: The timestamp when the deploy request was closed.
        html_url:
          type: string
          format: uri
          description: The URL to the deploy request in the PlanetScale dashboard.
    Error:
      type: object
      description: An error response from the PlanetScale API.
      properties:
        code:
          type: string
          description: A machine-readable error code.
        message:
          type: string
          description: A human-readable error message.
  responses:
    Unauthorized:
      description: Authentication failed. The service token or OAuth token is missing, invalid, or lacks the required permissions.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: The request was well-formed but contains invalid parameters or violates business rules.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    PageParam:
      name: page
      in: query
      required: false
      description: The page number for pagination.
      schema:
        type: integer
        minimum: 1
        default: 1
    DeployRequestNumberParam:
      name: deploy_request_number
      in: path
      required: true
      description: The number of the deploy request.
      schema:
        type: string
    PerPageParam:
      name: per_page
      in: query
      required: false
      description: The number of results per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
    OrganizationParam:
      name: organization
      in: path
      required: true
      description: The name of the organization.
      schema:
        type: string
    DatabaseParam:
      name: database
      in: path
      required: true
      description: The name of the database.
      schema:
        type: string
  securitySchemes:
    serviceToken:
      type: apiKey
      in: header
      name: Authorization
      description: Service token authentication. Use the format 'ServiceToken {token_id}:{token_value}' in the Authorization header.
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 bearer token authentication. Obtain tokens via the PlanetScale OAuth authorization code flow.
externalDocs:
  description: PlanetScale API Documentation
  url: https://planetscale.com/docs/api/reference/getting-started-with-planetscale-api