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

Snapshots

Snapshot creation, listing, metadata, deletion, restoration, migration, preview, and pending role restoration endpoints.

Copy page

Overview

Snapshots are Discord server backups. Creation requires CREATE_BACKUPS and restore/delete operations generally require RESTORE_BACKUPS. Sub-user access is supported by local server helpers for snapshot creation and management where the source route allows it.

Endpoint
POST /api/v3/servers/{serverId}/snapshots
Purpose
Start snapshot creation
Permission
CREATE_BACKUPS
Endpoint
GET /api/v3/snapshots
Purpose
List accessible snapshots
Permission
RESTORE_BACKUPS
Endpoint
GET|PATCH|DELETE /api/v3/snapshots/{snapshotId}
Purpose
Read/update/delete snapshot metadata
Permission
RESTORE_BACKUPS for GET/DELETE, CREATE_BACKUPS for PATCH
Endpoint
POST /api/v3/snapshots/{snapshotId}/restore
Purpose
Start restore
Permission
RESTORE_BACKUPS
Endpoint
POST /api/v3/snapshots/{snapshotId}/migrate
Purpose
Migrate legacy v0 snapshot
Permission
CREATE_BACKUPS
Endpoint
POST /api/v3/snapshots/{snapshotId}/preview and GET /api/v3/snapshots/{snapshotId}/preview/attachment/{...path}
Purpose
Preview snapshot data/assets
Permission
Authenticated snapshot access
Endpoint
DELETE /api/v3/snapshots/pending-roles/{guildId} and POST /api/v3/snapshots/pending-roles/{guildId}/restore
Purpose
Manage pending role restoration
Permission
RESTORE_BACKUPS

Snapshot create, restore, and migrate are asynchronous. A successful API response means the job was started, not that the backup or restore has finished.

Create Snapshot

Start a snapshot job for one server. The handler validates access, checks the server owner's snapshot limit, resolves the server owner's bot, applies plan-based attachment/message limits, and calls the snapshot service.

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

Create snapshot

Starts an asynchronous snapshot job.

serverIdRequired
Location
path
Type
string
Internal RestoreCord server id.
snapshotNameRequired
Location
body
Type
string
1-100 characters.
snapshotDescriptionOptional
Location
body
Type
string | null
Optional description, max 500 characters.
attachmentModeOptional
Location
body
Type
number
Default
0
0-2. Free/Premium are forced to 0 in source.
enableEmojiBackupOptional
Location
body
Type
boolean
Default
true
Only honored for Enterprise owners.
messageCountOptional
Location
body
Type
number
Default
50
Clamped to the owner's plan message limit.
excludedChannelsOptional
Location
body
Type
string[]
Default
[]
Discord channel ids to skip.
Example request JSON
{
  "snapshotName": "Before launch",
  "snapshotDescription": "Pre-launch backup",
  "attachmentMode": 1,
  "enableEmojiBackup": true,
  "messageCount": 250,
  "excludedChannels": ["333333333333333333"]
}
Example response JSON
{
  "success": true,
  "message": "Snapshot creation started successfully.",
  "snapshotId": "snap_abc123"
}

List Snapshots

List snapshots owned by the account plus snapshots from shared servers where the user has snapshot permissions.

GET/api/v3/snapshots

List snapshots

Returns accessible snapshot metadata.

Example response JSON
{
  "success": true,
  "snapshots": [
    {
      "id": 5,
      "snapshotId": "snap_abc123",
      "snapshotName": "Before launch",
      "snapshotDescription": "Pre-launch backup",
      "sourceGuildId": "123456789012345678",
      "totalChannels": 32,
      "totalRoles": 18,
      "totalMembers": 1200,
      "totalMessages": 5000,
      "totalAttachments": 100,
      "totalEmojis": 25,
      "pinned": false,
      "version": 1,
      "createdAt": "2026-06-07T10:30:00.000Z",
      "updatedAt": "2026-06-07T10:30:00.000Z",
      "isOwner": true,
      "canManage": true
    }
  ],
  "total": 1,
  "subscription": {
    "role": "business",
    "canCreateSnapshots": true
  }
}

Snapshot Details

GET/api/v3/snapshots/{snapshotId}

Get snapshot

Returns one snapshot's metadata.

snapshotIdRequired
Location
path
Type
string
Snapshot id string, not the internal numeric id.
PATCH/api/v3/snapshots/{snapshotId}

Update snapshot

Update snapshot name, description, or pinned state.

snapshotIdRequired
Location
path
Type
string
Snapshot id string.
snapshotNameOptional
Location
body
Type
string
1-100 characters.
snapshotDescriptionOptional
Location
body
Type
string | null
Max 500 characters.
pinnedOptional
Location
body
Type
boolean
Pinned state.
DELETE/api/v3/snapshots/{snapshotId}

Delete snapshot

Delete snapshot metadata and request snapshot-storage cleanup.

snapshotIdRequired
Location
path
Type
string
Snapshot id string.

The delete route rejects legacy v0 snapshots until they are migrated to the latest format.

Restore Snapshot

Start a restore job into a target Discord server. The caller can provide either an owned bot token or a botId that the server can resolve through access helpers.

POST/api/v3/snapshots/{snapshotId}/restore

Restore snapshot

Starts an asynchronous snapshot restore job.

snapshotIdRequired
Location
path
Type
string
Snapshot id string.
guildIdRequired
Location
body
Type
string
Target Discord guild id.
botTokenOptional
Location
body
Type
string
Owned bot token. Either `botToken` or `botId` is required.
botIdOptional
Location
body
Type
string
Bot client id accessible with snapshot management permission.
restoreMessageCountOptional
Location
body
Type
number
Default
100
Clamped to plan restore limit.
clearServerOptional
Location
body
Type
boolean
Default
false
Whether the restore service should clear the target server first.
Example request JSON
{
  "guildId": "222222222222222222",
  "botId": "555555555555555555",
  "restoreMessageCount": 250,
  "clearServer": false
}
Example response JSON
{
  "success": true,
  "message": "Snapshot restoration started successfully.",
  "data": {
    "success": true,
    "jobId": "restore_abc123"
  }
}

Restore Error Mapping

Service error
NO_ADMIN_PERMISSION, NOT_IN_GUILD, ACCESS_DENIED
API error
403 INSUFFICIENT_PERMISSIONS
Service error
GUILD_NOT_FOUND
API error
404 NOT_FOUND
Service error
INVALID_TOKEN, INVALID_TOKEN_FORMAT, NOT_A_BOT, UNAUTHORIZED, FORBIDDEN
API error
401 INVALID_CREDENTIALS
Service error
Other unsuccessful service response
API error
502 EXTERNAL_SERVICE_ERROR

Migrate Snapshot

Start a migration for an older v0 snapshot. The migrated snapshot remains attributed to the snapshot/server owner.

POST/api/v3/snapshots/{snapshotId}/migrate

Migrate snapshot

Starts a v0-to-current snapshot migration job.

snapshotIdRequired
Location
path
Type
string
Snapshot id string.
Example response JSON
{
  "success": true,
  "message": "Snapshot migration started successfully."
}

Preview and Attachments

Local routes also include preview endpoints for snapshot content and preview attachments. They are authenticated snapshot-access helpers used by the UI.

Endpoint
POST /api/v3/snapshots/{snapshotId}/preview
Purpose
Preview snapshot structure/content
Notes
Body may include optional channelId; response shape is produced by the snapshot service.
Endpoint
GET /api/v3/snapshots/{snapshotId}/preview/attachment/{...path}
Purpose
Fetch a preview attachment asset
Notes
Path is a catch-all attachment path.

The preview handlers are intentionally documented conservatively because they serve snapshot-service data and assets rather than a small stable JSON object.

Pending Role Restore

Pending role restore endpoints manage role-restoration data saved during snapshot restore flows.

DELETE/api/v3/snapshots/pending-roles/{guildId}

Delete pending role restore

Cancel and delete pending role restoration data for a target guild/snapshot.

guildIdRequired
Location
path
Type
string
Discord guild id.
snapshotIdRequired
Location
query
Type
string
Snapshot id associated with pending role data.
POST/api/v3/snapshots/pending-roles/{guildId}/restore

Start pending role restore

Begin restoring roles from previously saved pending data.

guildIdRequired
Location
path
Type
string
Discord guild id.
snapshotIdRequired
Location
body
Type
string
Snapshot id to restore roles from.
  • The bot in pending data must still be in the target server.
  • Only one role restore should run at a time for a server.
  • The endpoints require snapshot restore/manage access.

Status and Errors

Status/code
200
When it appears
Successful list, read, update, delete, restore start, migration start, preview, or role-restore action.
Status/code
201
When it appears
Snapshot creation started.
Status/code
400 INVALID_INPUT / VALIDATION_ERROR
When it appears
Missing snapshot id, invalid server id, invalid body, latest-version migration attempt, or v0 delete attempt.
Status/code
401 INVALID_CREDENTIALS
When it appears
Invalid bot token or restore-service token error.
Status/code
403 INSUFFICIENT_PERMISSIONS / RESOURCE_LIMIT_EXCEEDED
When it appears
Missing API key permission, missing server access, bot lacks access/admin, or snapshot limit reached.
Status/code
404 NOT_FOUND
When it appears
Snapshot, server, or bot not found.
Status/code
409 RESOURCE_IN_USE
When it appears
Another snapshot creation is already in progress.
Status/code
429 RATE_LIMITED
When it appears
Snapshot or restore service rate limited.
Status/code
502 EXTERNAL_SERVICE_ERROR / 503 SERVICE_UNAVAILABLE
When it appears
Snapshot, restore, or migration service unavailable or returned an unexpected error.