dbmigratepro-com Migrations API

openapi: 3.2.0
info:
  title: DBMigratePro REST Migrations API
  version: 1.0.0
  summary: Migrate, convert, back up, and restore MySQL and PostgreSQL databases over HTTP.
  description: 'Everything the dashboard does, it does through this API — there is no privileged back

    channel — so a script or an AI agent can drive the whole product.


    **Authentication.** A personal API token from Settings → API Tokens, sent as

    `Authorization: Bearer `. Tokens are full-account: no endpoint currently checks a

    narrower ability. Requests are scoped to the token owner''s *acting team*, which

    `POST /api/teams/{team}/switch` changes — so the same token can see different resources

    over time.


    **Connection URLs are write-only.** Database URLs and storage secrets are encrypted at

    rest and never appear in a response. There is no read-back endpoint.


    **Rate limits, tiered by what an endpoint costs us** (per authenticated user, keyed on

    user id):


    - AI endpoints: 10/minute and 200/day — each call spends money on a model.

    - Probe endpoints (anything that dials a database you supply): 20/minute.

    - Reads: 300/minute. Writes: 60/minute. Token minting: 10/hour.

    - Restores are deliberately left out of the probe and write tiers — they inherit only the

    generous read limit above, because a restore has to work in the middle of an outage.

    Unauthenticated public reads are IP-limited instead.


    Each operation below carries an `x-rate-limit` field naming its tier.


    **Rules for agents.** Two are not negotiable. An agent must never complete a payment on

    a user''s behalf: when a run needs one, the response carries a `checkout_url` to hand

    back to the user, and the run starts by itself once they authorise it. And a destructive

    call — delete, reset — must be confirmed by the user first. A failed migration is never

    charged, and restores are never charged at all, so both are safe to explain plainly.


    This document is generated from the live route table. The narrative guides are at

    https://dbmigratepro.com/docs, and there is an MCP server for clients that speak it —

    see https://dbmigratepro.com/docs/mcp-setup.'
  contact:
    name: DBMigratePro support
    url: https://dbmigratepro.com/contact
servers:
- url: https://dbmigratepro.com
security:
- bearerAuth: []
tags:
- name: Migrations
paths:
  /api/migrations:
    get:
      operationId: getMigrations
      tags:
      - Migrations
      summary: List the current team's migrations
      security:
      - bearerAuth: []
      x-rate-limit: 300/minute
      responses:
        '200':
          description: Success.
        '401':
          description: Missing or invalid API token.
        '403':
          description: The resource belongs to another team, or the endpoint is admin-only.
        '404':
          description: No such resource.
        '429':
          description: Rate limit exceeded for this tier. Retry after the `Retry-After` header.
    post:
      operationId: postMigrations
      tags:
      - Migrations
      summary: Create a migration.
      security:
      - bearerAuth: []
      x-rate-limit: 60/minute
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                source_kind:
                  type: string
                  enum:
                  - url
                  nullable: true
                source_url:
                  type: string
                  maxLength: 2000
                target_url:
                  type: string
                  maxLength: 2000
                estimate_id:
                  type: integer
                  nullable: true
              required:
              - source_url
              - target_url
      responses:
        '200':
          description: Success.
        '201':
          description: Created, for the endpoints that create a resource.
        '401':
          description: Missing or invalid API token.
        '403':
          description: The resource belongs to another team, or the endpoint is admin-only.
        '404':
          description: No such resource.
        '422':
          description: Validation failed. The body carries `message` and `errors`.
        '429':
          description: Rate limit exceeded for this tier. Retry after the `Retry-After` header.
  /api/migrations/d1-import/presign:
    post:
      operationId: postMigrationsD1ImportPresign
      tags:
      - Migrations
      security:
      - bearerAuth: []
      x-rate-limit: 60/minute
      responses:
        '200':
          description: Success.
        '201':
          description: Created, for the endpoints that create a resource.
        '401':
          description: Missing or invalid API token.
        '403':
          description: The resource belongs to another team, or the endpoint is admin-only.
        '404':
          description: No such resource.
        '422':
          description: Validation failed. The body carries `message` and `errors`.
        '429':
          description: Rate limit exceeded for this tier. Retry after the `Retry-After` header.
      summary: Post migrations D1Import presign
      x-summary-source: derived
  /api/migrations/preflight:
    post:
      operationId: postMigrationsPreflight
      tags:
      - Migrations
      summary: 'Pre-flight a source and target pair: reachability, engines, measured size…'
      security:
      - bearerAuth: []
      x-rate-limit: 20/minute
      responses:
        '200':
          description: Success.
        '201':
          description: Created, for the endpoints that create a resource.
        '401':
          description: Missing or invalid API token.
        '403':
          description: The resource belongs to another team, or the endpoint is admin-only.
        '404':
          description: No such resource.
        '422':
          description: Validation failed. The body carries `message` and `errors`.
        '429':
          description: Rate limit exceeded for this tier. Retry after the `Retry-After` header.
  /api/migrations/self-hosted:
    post:
      operationId: postMigrationsSelfHosted
      tags:
      - Migrations
      security:
      - bearerAuth: []
      x-rate-limit: 60/minute
      responses:
        '200':
          description: Success.
        '201':
          description: Created, for the endpoints that create a resource.
        '401':
          description: Missing or invalid API token.
        '403':
          description: The resource belongs to another team, or the endpoint is admin-only.
        '404':
          description: No such resource.
        '422':
          description: Validation failed. The body carries `message` and `errors`.
        '429':
          description: Rate limit exceeded for this tier. Retry after the `Retry-After` header.
      summary: Post migrations self hosted
      x-summary-source: derived
  /api/migrations/{migration}:
    get:
      operationId: getMigrationsMigration
      tags:
      - Migrations
      summary: 'One migration: status, engines, measured size, cost, and recent log lines.'
      security:
      - bearerAuth: []
      x-rate-limit: 300/minute
      parameters:
      - name: migration
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
        '401':
          description: Missing or invalid API token.
        '403':
          description: The resource belongs to another team, or the endpoint is admin-only.
        '404':
          description: No such resource.
        '429':
          description: Rate limit exceeded for this tier. Retry after the `Retry-After` header.
    put:
      operationId: putMigrationsMigration
      tags:
      - Migrations
      summary: Update a migration's editable fields
      security:
      - bearerAuth: []
      x-rate-limit: 300/minute
      parameters:
      - name: migration
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                source_url:
                  type: string
                  maxLength: 2000
                target_url:
                  type: string
                  maxLength: 2000
                status:
                  type: string
                  enum:
                  - pending
                  - in_progress
                  - completed
                  - failed
                  - cancelled
      responses:
        '200':
          description: Success.
        '401':
          description: Missing or invalid API token.
        '403':
          description: The resource belongs to another team, or the endpoint is admin-only.
        '404':
          description: No such resource.
        '422':
          description: Validation failed. The body carries `message` and `errors`.
        '429':
          description: Rate limit exceeded for this tier. Retry after the `Retry-After` header.
    delete:
      operationId: deleteMigrationsMigration
      tags:
      - Migrations
      summary: Delete a migration. Irreversible — confirm with the user first
      security:
      - bearerAuth: []
      x-rate-limit: 300/minute
      parameters:
      - name: migration
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
        '401':
          description: Missing or invalid API token.
        '403':
          description: The resource belongs to another team, or the endpoint is admin-only.
        '404':
          description: No such resource.
        '429':
          description: Rate limit exceeded for this tier. Retry after the `Retry-After` header.
  /api/migrations/{migration}/backup-offer:
    get:
      operationId: getMigrationsMigrationBackupOffer
      tags:
      - Migrations
      security:
      - bearerAuth: []
      x-rate-limit: 20/minute
      parameters:
      - name: migration
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
        '401':
          description: Missing or invalid API token.
        '403':
          description: The resource belongs to another team, or the endpoint is admin-only.
        '404':
          description: No such resource.
        '429':
          description: Rate limit exceeded for this tier. Retry after the `Retry-After` header.
      summary: Get migrations migration backup offer
      x-summary-source: derived
    post:
      operationId: postMigrationsMigrationBackupOffer
      tags:
      - Migrations
      security:
      - bearerAuth: []
      x-rate-limit: 20/minute
      parameters:
      - name: migration
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
        '201':
          description: Created, for the endpoints that create a resource.
        '401':
          description: Missing or invalid API token.
        '403':
          description: The resource belongs to another team, or the endpoint is admin-only.
        '404':
          description: No such resource.
        '422':
          description: Validation failed. The body carries `message` and `errors`.
        '429':
          description: Rate limit exceeded for this tier. Retry after the `Retry-After` header.
      summary: Post migrations migration backup offer
      x-summary-source: derived
  /api/migrations/{migration}/checkout:
    post:
      operationId: postMigrationsMigrationCheckout
      tags:
      - Migrations
      summary: Get a fresh checkout link for a migration that is awaiting payment
      security:
      - bearerAuth: []
      x-rate-limit: 300/minute
      parameters:
      - name: migration
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
        '201':
          description: Created, for the endpoints that create a resource.
        '401':
          description: Missing or invalid API token.
        '403':
          description: The resource belongs to another team, or the endpoint is admin-only.
        '404':
          description: No such resource.
        '422':
          description: Validation failed. The body carries `message` and `errors`.
        '429':
          description: Rate limit exceeded for this tier. Retry after the `Retry-After` header.
  /api/migrations/{migration}/logs:
    get:
      operationId: getMigrationsMigrationLogs
      tags:
      - Migrations
      summary: The migration's timeline entries
      security:
      - bearerAuth: []
      x-rate-limit: 300/minute
      parameters:
      - name: migration
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
        '401':
          description: Missing or invalid API token.
        '403':
          description: The resource belongs to another team, or the endpoint is admin-only.
        '404':
          description: No such resource.
        '429':
          description: Rate limit exceeded for this tier. Retry after the `Retry-After` header.
    post:
      operationId: postMigrationsMigrationLogs
      tags:
      - Migrations
      security:
      - bearerAuth: []
      x-rate-limit: 300/minute
      parameters:
      - name: migration
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  maxLength: 10000
              required:
              - message
      responses:
        '200':
          description: Success.
        '201':
          description: Created, for the endpoints that create a resource.
        '401':
          description: Missing or invalid API token.
        '403':
          description: The resource belongs to another team, or the endpoint is admin-only.
        '404':
          description: No such resource.
        '422':
          description: Validation failed. The body carries `message` and `errors`.
        '429':
          description: Rate limit exceeded for this tier. Retry after the `Retry-After` header.
      summary: Post migrations migration logs
      x-summary-source: derived
  /api/migrations/{migration}/logs/{log}:
    get:
      operationId: getMigrationsMigrationLogsLog
      tags:
      - Migrations
      security:
      - bearerAuth: []
      x-rate-limit: 300/minute
      parameters:
      - name: migration
        in: path
        required: true
        schema:
          type: string
      - name: log
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
        '401':
          description: Missing or invalid API token.
        '403':
          description: The resource belongs to another team, or the endpoint is admin-only.
        '404':
          description: No such resource.
        '429':
          description: Rate limit exceeded for this tier. Retry after the `Retry-After` header.
      summary: Get migrations migration logs log
      x-summary-source: derived
    delete:
      operationId: deleteMigrationsMigrationLogsLog
      tags:
      - Migrations
      security:
      - bearerAuth: []
      x-rate-limit: 300/minute
      parameters:
      - name: migration
        in: path
        required: true
        schema:
          type: string
      - name: log
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
        '401':
          description: Missing or invalid API token.
        '403':
          description: The resource belongs to another team, or the endpoint is admin-only.
        '404':
          description: No such resource.
        '429':
          description: Rate limit exceeded for this tier. Retry after the `Retry-After` header.
      summary: Delete migrations migration logs log
      x-summary-source: derived
  /api/migrations/{migration}/reset:
    post:
      operationId: postMigrationsMigrationReset
      tags:
      - Migrations
      summary: Clean the target and run the migration again from the start
      security:
      - bearerAuth: []
      x-rate-limit: 60/minute
      parameters:
      - name: migration
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
        '201':
          description: Created, for the endpoints that create a resource.
        '401':
          description: Missing or invalid API token.
        '403':
          description: The resource belongs to another team, or the endpoint is admin-only.
        '404':
          description: No such resource.
        '422':
          description: Validation failed. The body carries `message` and `errors`.
        '429':
          description: Rate limit exceeded for this tier. Retry after the `Retry-After` header.
  /api/migrations/{migration}/retry:
    post:
      operationId: postMigrationsMigrationRetry
      tags:
      - Migrations
      summary: Re-queue a failed migration.
      security:
      - bearerAuth: []
      x-rate-limit: 60/minute
      parameters:
      - name: migration
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
        '201':
          description: Created, for the endpoints that create a resource.
        '401':
          description: Missing or invalid API token.
        '403':
          description: The resource belongs to another team, or the endpoint is admin-only.
        '404':
          description: No such resource.
        '422':
          description: Validation failed. The body carries `message` and `errors`.
        '429':
          description: Rate limit exceeded for this tier. Retry after the `Retry-After` header.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'A personal API token from Settings → API Tokens, sent as `Authorization: Bearer <token>`.'
externalDocs:
  description: Documentation
  url: https://dbmigratepro.com/docs