OpenAPI 3.0 control-plane API for TiDB Data Migration, the platform that replicates MySQL-compatible upstreams into TiDB. Covers upstream source registration, relay log control, migration task lifecycle and status, task templates, table-structure operations and DM cluster master/worker membership. Served by dm-master in a self-managed DM deployment.
openapi: "3.0.0"
info:
title: DM OpenAPI DOC
version: "6.0.0"
externalDocs:
description: "DM OpenAPI DOC"
url: "https://docs.pingcap.com/zh/tidb-data-migration/stable"
servers:
- url: "https://you.domain.com/"
tags:
- name: source
description: source
externalDocs:
description: doc
url: "https://docs.pingcap.com/zh/tidb/stable/quick-start-create-source"
- name: task
description: task
externalDocs:
description: doc
url: "https://docs.pingcap.com/zh/tidb/stable/quick-start-with-dm"
- name: cluster
description: cluster
paths:
/api/v1/docs:
get:
tags:
- doc
summary: "get doc html"
operationId: "GetDocHTML"
responses:
"200":
description: HTML content
/api/v1/dm.json:
get:
tags:
- doc
summary: "get doc json"
operationId: "GetDocJSON"
responses:
"200":
description: json content
/api/v1/sources:
post:
tags:
- source
summary: "create and enable a new data source"
operationId: "DMAPICreateSource"
requestBody:
description: "request body"
content:
"application/json":
schema:
$ref: "#/components/schemas/CreateSourceRequest"
responses:
"201":
description: "success"
content:
"application/json":
schema:
$ref: "#/components/schemas/Source"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
get:
tags:
- source
summary: "get data source list"
operationId: "DMAPIGetSourceList"
parameters:
- name: "with_status"
in: query
required: false
description: "list source with status"
schema:
type: boolean
example: true
- name: "enable_relay"
in: query
required: false
description: "only return the enable-relay source"
schema:
type: boolean
example: true
responses:
"200":
description: "data source list"
content:
"application/json":
schema:
$ref: "#/components/schemas/GetSourceListResponse"
/api/v1/sources/{source-name}:
get:
tags:
- source
summary: "get source"
operationId: "DMAPIGetSource"
parameters:
- name: "source-name"
in: path
description: "globally unique data source name"
required: true
schema:
type: string
example: "mysql-01"
- name: "with_status"
in: query
required: false
description: "list source with status"
schema:
type: boolean
example: true
responses:
"200":
description: "source"
content:
"application/json":
schema:
$ref: "#/components/schemas/Source"
"404":
description: "source not found"
delete:
tags:
- source
summary: "delete a data source"
operationId: "DMAPIDeleteSource"
parameters:
- name: "source-name"
in: path
description: "globally unique data source name"
required: true
schema:
type: string
example: "mysql-01"
- name: "force"
in: query
required: false
description: "force stop source also stop the related tasks"
schema:
type: boolean
example: true
responses:
"204":
description: "success"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
put:
tags:
- source
summary: "update a data source"
operationId: "DMAPIUpdateSource"
parameters:
- name: "source-name"
in: path
description: "globally unique data source name"
required: true
schema:
type: string
example: "mysql-01"
requestBody:
required: true
content:
"application/json":
schema:
$ref: "#/components/schemas/UpdateSourceRequest"
responses:
"200":
description: "success"
content:
"application/json":
schema:
$ref: "#/components/schemas/Source"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
/api/v1/sources/{source-name}/status:
get:
tags:
- source
summary: "get the current status of the data source"
operationId: "DMAPIGetSourceStatus"
parameters:
- name: source-name
in: path
description: "globally unique data source name"
required: true
schema:
type: string
example: "mysql-replica-01"
responses:
"200":
description: "success"
content:
"application/json":
schema:
$ref: "#/components/schemas/GetSourceStatusResponse"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
/api/v1/sources/{source-name}/enable:
post:
tags:
- source
summary: "enable a data source"
operationId: "DMAPIEnableSource"
parameters:
- name: "source-name"
in: path
description: "globally unique data source name"
required: true
schema:
type: string
example: "mysql-01"
responses:
"200":
description: "success"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
/api/v1/sources/{source-name}/disable:
post:
tags:
- source
summary: "disable a data source"
operationId: "DMAPIDisableSource"
parameters:
- name: "source-name"
in: path
description: "globally unique data source name"
required: true
schema:
type: string
example: "mysql-01"
responses:
"200":
description: "success"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
/api/v1/sources/{source-name}/transfer:
post:
tags:
- source
summary: "transfer source to a free worker"
operationId: "DMAPITransferSource"
parameters:
- name: "source-name"
in: path
description: "globally unique data source name"
required: true
schema:
type: string
example: "mysql-01"
requestBody:
required: true
content:
"application/json":
schema:
$ref: "#/components/schemas/WorkerNameRequest"
responses:
"200":
description: "success"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
/api/v1/sources/{source-name}/relay/enable:
post:
tags:
- source
summary: "enable relay log function for the data source"
parameters:
- name: "source-name"
in: path
description: "globally unique data source name"
required: true
schema:
type: string
example: "mysql-01"
operationId: "DMAPIEnableRelay"
requestBody:
required: false
content:
"application/json":
schema:
$ref: "#/components/schemas/EnableRelayRequest"
responses:
"200":
description: "success"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
/api/v1/sources/{source-name}/relay/disable:
post:
tags:
- source
summary: "disable relay log function for the data source"
operationId: "DMAPIDisableRelay"
parameters:
- name: "source-name"
in: path
description: "globally unique data source name"
required: true
schema:
type: string
example: "mysql-01"
requestBody:
required: false
content:
"application/json":
schema:
$ref: "#/components/schemas/DisableRelayRequest"
responses:
"200":
description: "success"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
/api/v1/sources/{source-name}/relay/purge:
post:
tags:
- source
summary: "purge relay log"
operationId: "DMAPIPurgeRelay"
parameters:
- name: "source-name"
in: path
description: "globally unique data source name"
required: true
schema:
type: string
example: "mysql-01"
requestBody:
required: true
content:
"application/json":
schema:
$ref: "#/components/schemas/PurgeRelayRequest"
responses:
"200":
description: "success"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
/api/v1/sources/{source-name}/schemas:
get:
tags:
- source
summary: "get source schema list"
operationId: "DMAPIGetSourceSchemaList"
parameters:
- name: source-name
in: path
description: "source name"
required: true
schema:
type: string
example: "source-1"
responses:
"200":
description: "success"
content:
"application/json":
schema:
$ref: "#/components/schemas/SchemaNameList"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
/api/v1/sources/{source-name}/schemas/{schema-name}:
get:
tags:
- source
summary: "get source table list"
operationId: "DMAPIGetSourceTableList"
parameters:
- name: source-name
in: path
description: "source name"
required: true
schema:
type: string
example: "source-1"
- name: schema-name
in: path
description: "schema name"
required: true
schema:
type: string
example: "db1"
responses:
"200":
description: "success"
content:
application/json:
schema:
$ref: "#/components/schemas/TableNameList"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
/api/v1/tasks:
post:
tags:
- task
summary: "create a task"
operationId: "DMAPICreateTask"
requestBody:
description: "request body"
content:
"application/json":
schema:
$ref: "#/components/schemas/CreateTaskRequest"
responses:
"201":
description: "success"
content:
"application/json":
schema:
$ref: "#/components/schemas/OperateTaskResponse"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
get:
tags:
- task
summary: "get task list"
parameters:
- name: "with_status"
in: query
required: false
description: "get task with status"
schema:
type: boolean
example: true
- name: "stage"
in: query
required: false
description: "filter by task stage"
schema:
$ref: "#/components/schemas/TaskStage"
- name: source_name_list
in: query
required: false
description: "filter by source name"
schema:
$ref: "#/components/schemas/SourceNameList"
operationId: "DMAPIGetTaskList"
responses:
"200":
description: "task list"
content:
"application/json":
schema:
$ref: "#/components/schemas/GetTaskListResponse"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
/api/v1/tasks/{task-name}:
get:
tags:
- task
summary: "get a task"
parameters:
- name: task-name
in: path
description: "globally unique task name"
required: true
schema:
type: string
example: "task-1"
- name: "with_status"
in: query
required: false
description: "get task with status"
schema:
type: boolean
example: true
operationId: "DMAPIGetTask"
responses:
"200":
description: "task list"
content:
"application/json":
schema:
$ref: "#/components/schemas/Task"
"404":
description: "task not found"
delete:
tags:
- task
summary: "delete a task"
operationId: "DMAPIDeleteTask"
parameters:
- name: task-name
in: path
description: "globally unique task name"
required: true
schema:
type: string
example: "task-1"
- name: "force"
in: query
required: false
description: "force stop task even if some subtask is running"
schema:
type: boolean
example: true
- name: "keep_meta"
in: query
required: false
description: |-
Whether to keep downstream checkpoints and resumable internal metadata when deleting the task.
Optimistic shard DDL metadata is always removed.
With force=true, only already-persisted checkpoint state is retained; deletion does not flush the latest checkpoint.
Stop the task and wait for the stop operation to complete before deleting it when the latest checkpoint must be retained.
Only use keep_meta=true after all DM masters are upgraded, because older versions ignore unknown query parameters.
schema:
type: boolean
default: false
example: true
responses:
"204":
description: "success"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
put:
tags:
- task
summary: "update a task"
operationId: "DMAPIUpdateTask"
requestBody:
description: "request body"
content:
"application/json":
schema:
$ref: "#/components/schemas/UpdateTaskRequest"
parameters:
- name: task-name
in: path
description: "globally unique task name"
required: true
schema:
type: string
example: "task-1"
responses:
"200":
description: "success"
content:
"application/json":
schema:
$ref: "#/components/schemas/OperateTaskResponse"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
/api/v1/tasks/{task-name}/status:
get:
tags:
- task
summary: "get task status"
operationId: "DMAPIGetTaskStatus"
parameters:
- name: task-name
in: path
description: "globally unique task name"
required: true
schema:
type: string
example: "task-1"
- name: source_name_list
in: query
description: "source name list"
required: false
schema:
$ref: "#/components/schemas/SourceNameList"
responses:
"200":
description: "success"
content:
"application/json":
schema:
$ref: "#/components/schemas/GetTaskStatusResponse"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
/api/v1/tasks/{task-name}/start:
post:
tags:
- task
summary: "start a task"
operationId: "DMAPIStartTask"
parameters:
- name: task-name
in: path
description: "globally unique task name"
required: true
schema:
type: string
example: "task-1"
requestBody:
required: false
content:
"application/json":
schema:
$ref: "#/components/schemas/StartTaskRequest"
responses:
"200":
description: "success"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
/api/v1/tasks/{task-name}/stop:
post:
tags:
- task
summary: "stop a task"
operationId: "DMAPIStopTask"
parameters:
- name: task-name
in: path
description: "globally unique task name"
required: true
schema:
type: string
example: "task-1"
requestBody:
required: false
content:
"application/json":
schema:
$ref: "#/components/schemas/StopTaskRequest"
responses:
"200":
description: "success"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
/api/v1/tasks/{task-name}/sources/{source-name}/migrate_targets:
get:
tags:
- task
summary: "get task source table and target table route relation"
operationId: "DMAPIGetTaskMigrateTargets"
parameters:
- name: task-name
in: path
description: "globally unique task name"
required: true
schema:
type: string
example: "task-1"
- name: source-name
in: path
description: "source name"
required: true
schema:
type: string
example: "source-1"
- name: "schema_pattern"
in: query
required: false
schema:
type: string
example: "db*"
- name: "table_pattern"
in: query
required: false
schema:
type: string
example: "table*"
responses:
"200":
description: "success"
content:
"application/json":
schema:
$ref: "#/components/schemas/GetTaskMigrateTargetsResponse"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
/api/v1/tasks/{task-name}/sources/{source-name}/schemas:
get:
tags:
- task
summary: "get task source schema list"
operationId: "DMAPIGetSchemaListByTaskAndSource"
parameters:
- name: task-name
in: path
description: "globally unique task name"
required: true
schema:
type: string
example: "task-1"
- name: source-name
in: path
description: "source name"
required: true
schema:
type: string
example: "source-1"
responses:
"200":
description: "success"
content:
"application/json":
schema:
$ref: "#/components/schemas/SchemaNameList"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
/api/v1/tasks/{task-name}/sources/{source-name}/schemas/{schema-name}:
get:
tags:
- task
summary: "get task source table list"
operationId: "DMAPIGetTableListByTaskAndSource"
parameters:
- name: task-name
in: path
description: "globally unique task name"
required: true
schema:
type: string
example: "task-1"
- name: source-name
in: path
description: "source name"
required: true
schema:
type: string
example: "source-1"
- name: schema-name
in: path
description: "schema name"
required: true
schema:
type: string
example: "db1"
responses:
"200":
description: "success"
content:
application/json:
schema:
$ref: "#/components/schemas/TableNameList"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
/api/v1/tasks/{task-name}/sources/{source-name}/schemas/{schema-name}/{table-name}:
get:
tags:
- task
summary: "get task source table structure"
operationId: "DMAPIGetTableStructure"
parameters:
- name: task-name
in: path
description: "globally unique task name"
required: true
schema:
type: string
example: "task-1"
- name: source-name
in: path
description: "source name"
required: true
schema:
type: string
example: "source-1"
- name: schema-name
in: path
description: "schema name"
required: true
schema:
type: string
example: "db1"
- name: table-name
in: path
description: "table name"
required: true
schema:
type: string
example: "table1"
responses:
"200":
description: "success"
content:
application/json:
schema:
$ref: "#/components/schemas/GetTaskTableStructureResponse"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
put:
tags:
- task
summary: "operate task source table structure"
operationId: "DMAPIOperateTableStructure"
parameters:
- name: task-name
in: path
description: "globally unique task name"
required: true
schema:
type: string
example: "task-1"
- name: source-name
in: path
description: "source name"
required: true
schema:
type: string
example: "task-1"
- name: schema-name
in: path
description: "schema name"
required: true
schema:
type: string
example: "db1"
- name: table-name
in: path
description: "table name"
required: true
schema:
type: string
example: "table1"
requestBody:
required: true
content:
"application/json":
schema:
$ref: "#/components/schemas/OperateTaskTableStructureRequest"
responses:
"200":
description: "success"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
delete:
tags:
- task
summary: "delete task source table structure"
operationId: "DMAPIDeleteTableStructure"
parameters:
- name: task-name
in: path
description: "globally unique task name"
required: true
schema:
type: string
example: "task-1"
- name: source-name
in: path
description: "source name"
required: true
schema:
type: string
example: "source-1"
- name: schema-name
in: path
description: "schema name"
required: true
schema:
type: string
example: "db1"
- name: table-name
in: path
description: "table name"
required: true
schema:
type: string
example: "table1"
responses:
"204":
description: "success"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
/api/v1/tasks/converters:
post:
tags:
- task
summary: "Turn task into the format of a configuration file or vice versa."
operationId: "DMAPIConvertTask"
requestBody:
description: "if task is input this task will be converted to task_config file or vice versa"
content:
"application/json":
schema:
$ref: "#/components/schemas/ConverterTaskRequest"
responses:
"201":
description: "success"
content:
"application/json":
schema:
$ref: "#/components/schemas/ConverterTaskResponse"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
/api/v1/tasks/templates:
post:
tags:
- task
summary: "create task template"
operationId: "DMAPICreateTaskTemplate"
requestBody:
description: "request body"
content:
"application/json":
schema:
$ref: "#/components/schemas/Task"
responses:
"201":
description: "success"
content:
"application/json":
schema:
$ref: "#/components/schemas/Task"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
get:
tags:
- task
summary: "get task template list"
operationId: "DMAPIGetTaskTemplateList"
responses:
"200":
description: "task list"
content:
"application/json":
schema:
$ref: "#/components/schemas/GetTaskListResponse"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
/api/v1/tasks/templates/import:
post:
tags:
- task
summary: "import task template"
operationId: "DMAPIImportTaskTemplate"
requestBody:
description: "request body"
content:
"application/json":
schema:
$ref: "#/components/schemas/TaskTemplateRequest"
responses:
"202":
description: "success"
content:
"application/json":
schema:
$ref: "#/components/schemas/TaskTemplateResponse"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
/api/v1/tasks/templates/{task-name}:
get:
tags:
- task
summary: "get task template template"
operationId: "DMAPIGetTaskTemplate"
parameters:
- name: task-name
in: path
description: "globally unique task name"
required: true
schema:
type: string
example: "task-1"
responses:
"200":
description: "success"
content:
"application/json":
schema:
$ref: "#/components/schemas/Task"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
put:
tags:
- task
summary: "update task template template"
operationId: "DMAPUpdateTaskTemplate"
parameters:
- name: task-name
in: path
description: "globally unique task name"
required: true
schema:
type: string
example: "task-1"
responses:
"200":
description: "success"
content:
"application/json":
schema:
$ref: "#/components/schemas/Task"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
delete:
tags:
- task
summary: "delete task template template"
operationId: "DMAPIDeleteTaskTemplate"
parameters:
- name: task-name
in: path
description: "globally unique task name"
required: true
schema:
type: string
example: "task-1"
responses:
"204":
description: "success"
"400":
description: "failed"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorWithMessage"
/api/v1/cluster/info:
get:
tags:
- cluster
summary: "get cluster info such as cluster id"
operationId: "DMAPIGetClusterInfo"
responses:
"200":
description: "success"
content:
"application/json":
schema:
$ref: "#/components/schemas/GetClusterInfoResponse"
put:
tags:
- cluster
summary: "update cluster info."
operationId: "DMAPIUpdateClusterInfo"
requestBody:
description: "request body"
content:
"application/json":
schema:
$ref: "#/components/schemas/ClusterTopology"
responses:
"200":
description: "success"
content:
"application/json":
schema:
$ref: "#/components/schemas/GetClusterInfoResponse"
/api/v1/cluster/masters:
get:
tags:
- cluster
summary: "get cluster master node list"
operationId: "DMAPIGetClusterMasterList"
responses:
"200":
description: "success"
content:
"application/json":
schema:
$ref: "#/components/schemas/GetClusterMasterListResponse"
"400":
description: "failed"
content:
"application/json":
# --- truncated at 32 KB (66 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pingcap/refs/heads/main/openapi/pingcap-tidb-dm-openapi-original.yaml