openapi: 3.1.0
info:
  title: PlanetScale Platform Backups 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: Backups
  description: Manage database branch backups, including listing, creating, and retrieving backup details.
paths:
  /organizations/{organization}/databases/{database}/branches/{branch}/backups:
    get:
      operationId: listBackups
      summary: List backups
      description: Returns a list of all backups for a specific branch.
      tags:
      - Backups
      parameters:
      - $ref: '#/components/parameters/OrganizationParam'
      - $ref: '#/components/parameters/DatabaseParam'
      - $ref: '#/components/parameters/BranchParam'
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response with list of backups
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Backup'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createBackup
      summary: Create a backup
      description: Creates a new backup of the specified branch.
      tags:
      - Backups
      parameters:
      - $ref: '#/components/parameters/OrganizationParam'
      - $ref: '#/components/parameters/DatabaseParam'
      - $ref: '#/components/parameters/BranchParam'
      responses:
        '201':
          description: Backup created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Backup'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /organizations/{organization}/databases/{database}/branches/{branch}/backups/{backup_id}:
    get:
      operationId: getBackup
      summary: Get a backup
      description: Returns details about a specific backup.
      tags:
      - Backups
      parameters:
      - $ref: '#/components/parameters/OrganizationParam'
      - $ref: '#/components/parameters/DatabaseParam'
      - $ref: '#/components/parameters/BranchParam'
      - $ref: '#/components/parameters/BackupIdParam'
      responses:
        '200':
          description: Successful response with backup details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Backup'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteBackup
      summary: Delete a backup
      description: Deletes a specific backup.
      tags:
      - Backups
      parameters:
      - $ref: '#/components/parameters/OrganizationParam'
      - $ref: '#/components/parameters/DatabaseParam'
      - $ref: '#/components/parameters/BranchParam'
      - $ref: '#/components/parameters/BackupIdParam'
      responses:
        '204':
          description: Backup deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  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'
    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
    BackupIdParam:
      name: backup_id
      in: path
      required: true
      description: The ID of the backup.
      schema:
        type: string
    BranchParam:
      name: branch
      in: path
      required: true
      description: The name of the branch.
      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
  schemas:
    Backup:
      type: object
      description: A backup of a database branch.
      properties:
        id:
          type: string
          description: The unique identifier of the backup.
        name:
          type: string
          description: The name of the backup.
        state:
          type: string
          description: The current state of the backup.
          enum:
          - pending
          - running
          - success
          - failed
        size:
          type: integer
          description: The size of the backup in bytes.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the backup was created.
        updated_at:
          type: string
          format: date-time
          description: The timestamp when the backup was last updated.
        completed_at:
          type: string
          format: date-time
          description: The timestamp when the backup completed.
        expires_at:
          type: string
          format: date-time
          description: The timestamp when the backup expires.
    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.
  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