Automate Pulls with the API
Step-by-step recipe for running a RestoreCord member migration with an API key. Find the server and destination, estimate, start, watch progress, then pause, resume or stop.
Everything in the pull popup can be done with an API key: find your server and destination, estimate, start, watch, then pause, resume or stop. This page walks through the calls in order. Full request and response details are in the Migrations API.
All requests go to https://restorecord.com with your key in the Authorization header. See API Keys.
Permissions
| Call | API key permission |
|---|---|
GET /api/v3/servers | READ_SERVERS |
GET /api/v3/bots | READ_BOTS |
GET /api/v3/bots/{botId}/guilds | None checked |
| Estimate, start, pause, resume, stop | None checked |
GET /api/v3/servers/status | READ_SERVERS |
PUT /api/v3/servers/{serverId}/members/{userId} (one member) | SERVER_PULL |
The migration endpoints don't check a permission bit. Any valid key for an account that owns the server, or has Pull Members on it, can start and stop migrations. Keep keys that shouldn't do this away from automation, and use the key's IP allowlist.
Step by Step
Find the source server
GET /api/v3/servers lists your servers. Use the numeric id as serverId in every migration path, and note the server's customBotId.
Find the destination server
GET /api/v3/bots lists your bots. Find the bot whose id equals the server's customBotId, and use its clientId as botId.
GET /api/v3/bots/{botId}/guilds lists the Discord servers that bot is in. Use the destination's id as targetGuildId. If it's missing, invite the bot to that server first.
Pick a role
Use the Discord role ID of the role to give (in Discord, turn on Developer Mode, then right-click the role › Copy Role ID). The role must be below the bot's role. To give no role, send the destination server's own ID.
Estimate
GET /api/v3/servers/{serverId}/migrations/estimate?targetGuildId={targetGuildId}count is how many members are eligible after your filters; total is how many still authorize the bot. Add the same filter parameters you plan to start with. Members already in the destination are included in count. Up to 15 estimates per minute.
Start
POST /api/v3/servers/{serverId}/migrations
Content-Type: application/json
{
"targetGuildId": "222222222222222222",
"selectedRoles": ["333333333333333333"],
"customPullCount": 0,
"delayMin": 800,
"delayMax": 800
}A 201 response means the migration was created. migration.queued is true if it's waiting behind another migration for this server, and migration.targetMembersUnavailable is true if Server Members Intent is off. Up to 5 starts per minute.
Every option and its plan is in Pull Settings, with the matching field name.
Watch progress
GET /api/v3/servers/statusReturns your active migrations (and those that ended in the last 10 minutes) with status, success, attempted, total and the other counters. Find yours by serverId and targetGuildId, and keep its id for the next step. Poll every few seconds. Once it's gone from the active list, look it up with ?history=true.
On Business and Enterprise, GET /api/v3/servers/{serverId}/migrations/status returns the latest migration for one server with an isActive flag.
Pause, resume or stop
| Action | Request |
|---|---|
| Pause | DELETE /api/v3/servers/{serverId}/migrations?migrationId={id}&action=pause |
| Resume | PATCH /api/v3/servers/{serverId}/migrations?migrationId={id} |
| Stop | DELETE /api/v3/servers/{serverId}/migrations?migrationId={id} |
Without migrationId, pause and stop apply to every active migration for the server. Stopped migrations can't be resumed.
Good Practice for Scripts and AI Agents
- Estimate first. If
countis 0, starting returns No members found for migration. - Check the status, not the response message. A finished migration's
statusisSUCCESS(shown as Finished),FAILEDorSTOPPED. - Respect
429. Wait for theRetry-Afterheader before trying again. - Don't retry a
409. A migration start is already in progress for this server means a start is being processed; check the status instead of starting again. - Don't start duplicates. A second start for the same server is queued behind the first, not merged with it.
- Plan gates are partly silent. A delay range on Free, or a country filter below Business, is ignored rather than rejected. Quality filters below their plan are ignored too. Check Pull Settings before relying on an option.
leaveServermakes your bot leave the destination after a finished migration that reached its pull amount. It doesn't remove members.