FeaturesComparisonPricingDiscoveryDocs
Browse documentation

Getting Started

IntroductionFAQ

Setup Guides

Setup a Custom BotSecure BotCreate a ServerSetup Channel PermissionsCreate a Verify Message

Management

Bot ManagementSub-UsersWebhook Logs

Features

Pull MembersRestore ServerSnapshots

API Reference

AccountBotsServersMigrationsMembersSnapshotsFirewallAnalyticsWebhooks

Developer

Full API ReferenceAPI KeysWebhook Events
Documentation

Migrations

Migration status, history, estimates, start, stop, pause, and resume endpoints for owned RestoreCord servers.

Copy page

Overview

Migration endpoints expose active and historical member migration state, estimate eligible pull counts, and control member migration runs for owned or shared RestoreCord servers.

Endpoint
GET /api/v3/servers/status
Auth
Session or API key with READ_SERVERS
Purpose
Active migrations by default, or paginated migration history with history=true.
Endpoint
GET /api/v3/servers/{serverId}/migrations
Auth
Server owner or sub-user with pull_members
Purpose
Latest migration row for one server.
Endpoint
GET /api/v3/servers/{serverId}/migrations/status
Auth
Server owner or sub-user with pull_members
Purpose
Detailed latest migration progress for one server.
Endpoint
GET /api/v3/servers/{serverId}/migrations/estimate
Auth
Server owner or sub-user with pull_members
Purpose
Estimated eligible member count before starting a migration.
Endpoint
POST /api/v3/servers/{serverId}/migrations
Auth
Server owner or sub-user with pull_members
Purpose
Start or queue a member migration.
Endpoint
DELETE /api/v3/servers/{serverId}/migrations
Auth
Server owner or sub-user with pull_members
Purpose
Stop active migrations, or pause them with action=pause.
Endpoint
PATCH /api/v3/servers/{serverId}/migrations
Auth
Server owner or sub-user with pull_members
Purpose
Resume one paused migration.

Migration performance analytics remain documented on the Analytics page under GET /api/v3/servers/migrations/stats.

The server-scoped migration handlers validate owner/sub-user access in source. They currently do not call an additional API-key permission bit check, so integrations should still isolate these calls to keys intended for member-pull automation.

Migration Status

Return active migrations by default, or historical migrations with pagination when history=true.

GET/api/v3/servers/status

Get migration status

Returns active migration rows or paginated history for owned servers.

historyOptional
Location
query
Type
boolean
Default
false
When true, return completed/failed history with pagination.
pageOptional
Location
query
Type
number
Default
1
History mode page.
pageSizeOptional
Location
query
Type
number
Default
20
History mode page size, capped at 50.
searchOptional
Location
query
Type
string
History mode search string.
searchFieldOptional
Location
query
Type
string
Default
serverName
`serverName` or `targetGuildId`.
sortByOptional
Location
query
Type
string
Default
id
One of `id`, `successCount`, `failedCount`, `totalCount`, `startedAt`, `createdAt`.
sortOrderOptional
Location
query
Type
string
Default
desc
`asc` or `desc`.

API key permission: READ_SERVERS

Example response JSON
{
  "success": true,
  "migrations": [
    {
      "id": 77,
      "serverId": "42",
      "guildId": "111111111111111111",
      "sourceServerId": "42",
      "sourceGuildId": "111111111111111111",
      "targetGuildId": "222222222222222222",
      "serverName": "Community",
      "targetServerName": "New Community",
      "status": "PULLING",
      "success": 120,
      "attempted": 140,
      "total": 500,
      "failed": 2,
      "invalid": 18,
      "createdAt": "2026-06-07T10:30:00.000Z"
    }
  ],
  "total": 1
}

Server Migration Status

Return the latest migration row for one internal RestoreCord server id. The detailed status route includes an isActive flag and nested progress/count objects.

GET/api/v3/servers/{serverId}/migrations

Get latest server migration

Returns the most recent migration for one server.

serverIdRequired
Location
path
Type
string
Internal RestoreCord server id.
GET/api/v3/servers/{serverId}/migrations/status

Get detailed migration status

Returns progress and active-state details for the latest migration.

serverIdRequired
Location
path
Type
string
Internal RestoreCord server id.
Example response JSON
{
  "success": true,
  "migration": {
    "id": 77,
    "guildId": "111111111111111111",
    "migrationGuildId": "222222222222222222",
    "status": "PULLING",
    "isActive": true,
    "progress": {
      "total": 500,
      "attempted": 140,
      "percentage": 28
    },
    "counts": {
      "success": 120,
      "banned": 0,
      "maxGuilds": 0,
      "invalid": 18,
      "failed": 2,
      "blacklisted": 0,
      "inServer": 0
    },
    "timestamps": {
      "created": "2026-06-07T10:30:00.000Z",
      "updated": "2026-06-07T10:40:00.000Z"
    }
  }
}

Estimate Migration

Estimate how many authorized members are eligible before starting a migration. Query filters mirror the start route's quality filters, with plan gates applied by the handler.

GET/api/v3/servers/{serverId}/migrations/estimate

Estimate migration

Returns eligible and total member counts for one server.

serverIdRequired
Location
path
Type
string
Internal RestoreCord source server id.
countryCodeOptional
Location
query
Type
string
Optional two-letter country code filter.
targetGuildIdOptional
Location
query
Type
string
Target Discord guild id used by some quality filters.
maxChurnRateOptional
Location
query
Type
number
Business+ quality filter.
minRetentionDaysOptional
Location
query
Type
number
Enterprise quality filter.
maxActivityIntervalOptional
Location
query
Type
number
Enterprise quality filter.
minDaysSinceLeftOptional
Location
query
Type
number
Business+ quality filter.
includeUnknownMembersOptional
Location
query
Type
boolean
Default
true
When false, exclude members missing quality data.
Example response JSON
{
  "success": true,
  "count": 500,
  "total": 620
}

Start Migration

Start or queue a member migration from one RestoreCord source server into a target Discord guild. The route validates the target guild, bot token, selected roles, member eligibility, queue state, and Discord invite status before calling the migration service.

POST/api/v3/servers/{serverId}/migrations

Start migration

Starts or queues a member migration.

serverIdRequired
Location
path
Type
string
Internal RestoreCord source server id.
targetGuildIdRequired
Location
body
Type
string
Target Discord guild id.
selectedRolesRequired
Location
body
Type
string[]
One or more target Discord role ids to assign.
nicknameOptional
Location
body
Type
string | null
Optional nickname template, max 32 characters.
countryCodeOptional
Location
body
Type
string | null
Optional two-letter country code filter.
customPullCountOptional
Location
body
Type
number
Default
0
0 means use the eligible member pool; otherwise cap at 50,000.
delayMinOptional
Location
body
Type
number
Minimum per-member delay in milliseconds, 100-30000.
delayMaxOptional
Location
body
Type
number
Maximum per-member delay in milliseconds, 100-30000.
leaveServerOptional
Location
body
Type
boolean
Default
false
Remove migrated members again after the flow completes.
startImmediatelyOptional
Location
body
Type
boolean
Default
false
Enterprise queue bypass when another migration is already running.
startTimeOptional
Location
body
Type
number
Delay start by 0-168 hours.
memberPerGroupOptional
Location
body
Type
number
Optional group size, 1-1000.
delayBetweenGroupsOptional
Location
body
Type
number
Milliseconds between groups, 1800000-43200000.
includeUnknownMembersOptional
Location
body
Type
boolean
Default
true
Include members missing quality metrics.
Example request JSON
{
  "targetGuildId": "222222222222222222",
  "selectedRoles": ["333333333333333333"],
  "nickname": "%USER%",
  "customPullCount": 250,
  "delayMin": 700,
  "delayMax": 1200,
  "leaveServer": false,
  "includeUnknownMembers": true
}
Example response JSON
{
  "success": true,
  "message": "Started Pull Process, this will take around 4 minutes",
  "migration": {
    "totalMembers": 250,
    "estimatedTime": "4 minutes",
    "queued": false,
    "queueTimeout": 0
  }
}

Stop or Pause Migration

Stop active migrations for a server, or pause them with action=pause. When migrationId is omitted, the database update applies to all active migrations for that server.

DELETE/api/v3/servers/{serverId}/migrations

Stop migration

Stops active server migrations or pauses them with action=pause.

serverIdRequired
Location
path
Type
string
Internal RestoreCord source server id.
migrationIdOptional
Location
query
Type
number
Optional migration row id.
actionOptional
Location
query
Type
string
Default
stop
Use `pause` to preserve service state for resume; default behavior stops.
Example response JSON
{
  "success": true,
  "message": "Migration stopped successfully."
}
Example response JSON
{
  "success": true,
  "message": "Migration paused successfully."
}

Resume Migration

Resume one paused migration. The handler requires a paused migration row and a Business or Enterprise server owner plan.

PATCH/api/v3/servers/{serverId}/migrations

Resume migration

Resumes one paused migration.

serverIdRequired
Location
path
Type
string
Internal RestoreCord source server id.
migrationIdRequired
Location
query
Type
number
Paused migration row id.
Example response JSON
{
  "success": true,
  "message": "Migration resumed successfully."
}

Response Fields

Field
migrations[].id
Type
number
Notes
Internal migration row id.
Field
migrations[].serverId
Type
string
Notes
Internal RestoreCord source server id in the status response.
Field
migrations[].guildId
Type
string
Notes
Source server Discord guild id.
Field
migrations[].sourceServerId
Type
string
Notes
Internal RestoreCord source server id.
Field
migrations[].sourceGuildId
Type
string
Notes
Source server Discord guild id.
Field
migrations[].targetGuildId
Type
string
Notes
Target migration Discord guild id.
Field
migrations[].serverName
Type
string
Notes
RestoreCord server name when available.
Field
migrations[].targetServerName
Type
string | null
Notes
Target Discord guild name when fetched or cached.
Field
migrations[].status
Type
string
Notes
Migration state such as WAITING, PENDING, PULLING, SUCCESS, FAILED, STOPPED, or PAUSED.
Field
migrations[].success
Type
number
Notes
Members successfully migrated.
Field
migrations[].attempted
Type
number
Notes
Attempted member operations.
Field
migrations[].total
Type
number
Notes
Total planned member count when known.
Field
migrations[].queue
Type
array | undefined
Notes
Active queue preview, present only for PULLING rows from the all-server status endpoint.
Field
pagination
Type
object | undefined
Notes
Present in history mode with page, pageSize, total, and maxPages.
Field
migration.queued
Type
boolean | undefined
Notes
Start response flag indicating whether the new migration was queued.
Field
migration.queueTimeout
Type
number | undefined
Notes
Queue cooldown in seconds when a migration was queued.

Status and Errors

Status/code
200
When it appears
Migration status/history, estimate, stop, pause, or resume returned.
Status/code
201
When it appears
Migration start request accepted.
Status/code
400 INVALID_INPUT / VALIDATION_ERROR
When it appears
Invalid pagination, sort, search, server id, target guild id, role id, body field, or Discord invite-disabled state.
Status/code
401 UNAUTHORIZED / INVALID_CREDENTIALS
When it appears
Missing auth, invalid auth, or invalid bot token.
Status/code
403 FORBIDDEN / INSUFFICIENT_PERMISSIONS
When it appears
API key lacks READ_SERVERS for all-server status, sub-user lacks pull access, owner plan gate, or bot lacks target-server access/role permissions.
Status/code
404 NOT_FOUND
When it appears
Server, bot, migration, target guild, or eligible members not found.
Status/code
429 RATE_LIMITED
When it appears
Migration status, start, resume, or estimate rate limit reached.
Status/code
502 EXTERNAL_SERVICE_ERROR / 503 SERVICE_UNAVAILABLE
When it appears
Migration service unavailable or returned an unsuccessful response.
Status/code
500 INTERNAL_SERVER_ERROR
When it appears
Unexpected database or service failure.