Backups and jobs API

Servers API
MCP guide

See the API guide for authentication and retries, or the endpoint index for other resources. All paths below are relative to your dashboard host.

Get backup policy

GET /api/v1/projects/{projectId}/backup-policies/{policyId}

Read a backup policy without commands or storage credentials.

Permission: backups:read · Team member.

MCP: get_backup_policy.

Path parameters

Field Type Required Details
projectId string Yes Min 1; max 128 characters.
policyId string Yes Min 1; max 128 characters.

Query parameters

None.

Response: HTTP 200.

Field Type Required Details
id string Yes Min 1; max 128 characters.
name string Yes Min 1; max 100 characters.
environmentId string Yes Min 1 characters.
enabled boolean Yes —
schedule object Yes —
schedule.cron string Yes —
destination object Yes —
destination.storageId string No Min 1 characters.
destination.prefix string No max 512 characters.
retention object Yes —
retention.local object Yes —
retention.local.count integer Yes Min 0; max 10000.
retention.local.days integer Yes Min 0; max 3650.
retention.local.maxStorageGb number Yes Min 0; max 100000.
retention.remote object Yes —
retention.remote.enabled boolean Yes —
retention.remote.count integer Yes Min 0; max 10000.
retention.remote.days integer Yes Min 0; max 3650.
retention.remote.maxStorageGb number Yes Min 0; max 100000.
volumes object Yes —
volumes.mode string Yes "none", "allNamed", "selected".
volumes.names string[] Yes Each item: Pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]*$. Min 1; max 128 characters.
databaseDumps object[] Yes max 100 items.
databaseDumps[].service string Yes Pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]*$. Min 1; max 128 characters.
databaseDumps[].engine string Yes "postgres", "mysql", "mariadb", "mongo".
databaseDumps[].database string Yes Default: "". max 128 characters.
projectId string Yes Min 1; max 128 characters.
settingsVersion integer Yes Min 1.

List backups

GET /api/v1/projects/{projectId}/backups

List backup status metadata. Storage credentials and internal manifests are excluded.

Permission: backups:read · Team member.

MCP: list_backups.

Path parameters

Field Type Required Details
projectId string Yes Min 1; max 128 characters.

Query parameters

Field Type Required Details
limit integer No Default: 25. Min 1; max 100.
cursor string No Min 1; max 2048 characters.
environmentId string No Min 1; max 128 characters.

Response: HTTP 200.

Field Type Required Details
items object[] Yes max 100 items.
items[].id string Yes Min 1; max 128 characters.
items[].projectId string Yes Min 1; max 128 characters.
items[].environmentId string Yes Min 1; max 128 characters.
items[].deploymentId string or null Yes Min 1; max 128 characters.
items[].serverId string or null Yes Min 1; max 128 characters.
items[].status string Yes "queued", "running", "succeeded", "failed", "canceled".
items[].createdAt string Yes UTC ISO 8601 timestamp.
items[].startedAt string or null Yes UTC ISO 8601 timestamp.
items[].finishedAt string or null Yes UTC ISO 8601 timestamp.
nextCursor string or null Yes —

Get backup

GET /api/v1/backups/{backupRunId}

Read backup status by immutable backup run ID.

Permission: backups:read · Team member.

MCP: get_backup.

Path parameters

Field Type Required Details
backupRunId string Yes Min 1; max 128 characters.

Query parameters

None.

Response: HTTP 200.

Field Type Required Details
id string Yes Min 1; max 128 characters.
projectId string Yes Min 1; max 128 characters.
environmentId string Yes Min 1; max 128 characters.
deploymentId string or null Yes Min 1; max 128 characters.
serverId string or null Yes Min 1; max 128 characters.
status string Yes "queued", "running", "succeeded", "failed", "canceled".
createdAt string Yes UTC ISO 8601 timestamp.
startedAt string or null Yes UTC ISO 8601 timestamp.
finishedAt string or null Yes UTC ISO 8601 timestamp.

List backup artifacts

GET /api/v1/backups/{backupRunId}/artifacts

List restore artifact identifiers, types, sizes, and checksums. Object keys and credentials are excluded.

Permission: backups:read · Team member.

MCP: list_backup_artifacts.

Path parameters

Field Type Required Details
backupRunId string Yes Min 1; max 128 characters.

Query parameters

Field Type Required Details
limit integer No Default: 25. Min 1; max 100.
cursor string No Min 1; max 2048 characters.

Response: HTTP 200.

Field Type Required Details
items object[] Yes max 100 items.
items[].id string Yes Min 1; max 128 characters.
items[].type string Yes "manifest", "volume", "database".
items[].storage string Yes "local", "remote".
items[].sizeBytes number Yes Min 0.
items[].checksumSha256 string Yes —
items[].createdAt string Yes UTC ISO 8601 timestamp.
nextCursor string or null Yes —

List backup policies

GET /api/v1/projects/{projectId}/backup-policies

List policy identifiers and enabled state. Database connection secrets are excluded.

Permission: backups:read · Team member.

MCP: list_backup_policies.

Path parameters

Field Type Required Details
projectId string Yes Min 1; max 128 characters.

Query parameters

Field Type Required Details
limit integer No Default: 25. Min 1; max 100.
cursor string No Min 1; max 2048 characters.

Response: HTTP 200.

Field Type Required Details
items object[] Yes max 100 items.
items[].id string Yes Min 1; max 128 characters.
items[].name string Yes —
items[].environmentId string Yes Min 1; max 128 characters.
items[].enabled boolean Yes —
items[].createdAt string Yes UTC ISO 8601 timestamp.
nextCursor string or null Yes —

List backup storage

GET /api/v1/backup-storage

List team storage destination metadata without access keys. Unavailable to project-restricted credentials.

Permission: backups:read · Team member · Workspace-wide access required.

MCP: list_backup_storage.

Query parameters

Field Type Required Details
limit integer No Default: 25. Min 1; max 100.
cursor string No Min 1; max 2048 characters.

Response: HTTP 200.

Field Type Required Details
items object[] Yes max 100 items.
items[].id string Yes Min 1; max 128 characters.
items[].settingsVersion integer Yes Min 1.
items[].name string Yes —
items[].bucket string Yes —
items[].region string Yes —
items[].endpoint string or null Yes —
items[].createdAt string Yes UTC ISO 8601 timestamp.
nextCursor string or null Yes —

Get job

GET /api/v1/jobs/{jobId}

Read an asynchronous backup or restore job status without its credential-bearing payload.

Permission: backups:read · Team member.

MCP: get_job.

Path parameters

Field Type Required Details
jobId string Yes Min 1; max 128 characters.

Query parameters

None.

Response: HTTP 200.

Field Type Required Details
id string Yes Min 1; max 128 characters.
projectId string Yes Min 1; max 128 characters.
type string Yes —
status string Yes —
createdAt string Yes UTC ISO 8601 timestamp.
finishedAt string or null Yes UTC ISO 8601 timestamp.

Read job logs

GET /api/v1/jobs/{jobId}/logs

Read bounded backup or restore output. Logs may contain application secrets.

Permission: logs:read · Team member.

MCP: read_job_logs.

Path parameters

Field Type Required Details
jobId string Yes Min 1; max 128 characters.

Query parameters

Field Type Required Details
limit integer No Default: 25. Min 1; max 100.
cursor string No Min 1; max 2048 characters.

Response: HTTP 200.

Field Type Required Details
items object[] Yes max 100 items.
items[].position integer Yes Min 0.
items[].content string Yes max 65536 characters.
items[].createdAt string Yes UTC ISO 8601 timestamp.
items[].truncated boolean Yes —
nextCursor string or null Yes —
retentionMayHaveRemovedEarlierEntries boolean Yes Exactly true.

Run backup

POST /api/v1/projects/{projectId}/backups

Queue a manual run of an enabled backup policy.

Permission: backups:write · Owner/admin.

MCP: run_backup.

Path parameters

Field Type Required Details
projectId string Yes Min 1; max 128 characters.

JSON body

Field Type Required Details
environmentId string Yes Min 1; max 128 characters.
policyId string No Required when the environment has multiple enabled policies. Min 1; max 128 characters.

Send Idempotency-Key as a header, not a body field.

Response: HTTP 202.

Field Type Required Details
backupRunId string Yes Min 1; max 128 characters.
agentJobId string Yes Min 1; max 128 characters.
statusUrl string Yes —

Restore backup

POST /api/v1/backups/{backupRunId}/restore

Queue a destructive restore into the current environment. Requires administrator role and explicit confirmation.

Permission: backups:restore · Owner/admin.

MCP: restore_backup.

Path parameters

Field Type Required Details
backupRunId string Yes Min 1; max 128 characters.

JSON body

Field Type Required Details
confirmation string Yes Exactly "restore".
artifacts object[] Yes Min 1; max 100 items.
artifacts[].artifactId string Yes when type=volume Min 1 characters.
artifacts[].type string Yes when type=volume Exactly "volume".
artifacts[].targetVolume string Yes when type=volume Pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]*$. Min 1; max 128 characters.
artifacts[].artifactId string Yes when type=database Min 1 characters.
artifacts[].type string Yes when type=database Exactly "database".
artifacts[].targetService string Yes when type=database Pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]*$. Min 1; max 128 characters.

Send Idempotency-Key as a header, not a body field.

Response: HTTP 202.

Field Type Required Details
agentJobId string Yes Min 1; max 128 characters.
statusUrl string Yes —

Create backup policy

POST /api/v1/projects/{projectId}/backup-policies

Create a backup policy. Requires current administrator role.

Permission: backups:write · Owner/admin.

MCP: create_backup_policy.

Path parameters

Field Type Required Details
projectId string Yes Min 1; max 128 characters.

JSON body

Field Type Required Details
name string Yes Min 1; max 100 characters.
environmentId string Yes Min 1 characters.
enabled boolean Yes —
schedule object Yes —
schedule.cron string Yes —
destination object Yes —
destination.storageId string No Min 1 characters.
destination.prefix string No max 512 characters.
retention object Yes —
retention.local object Yes —
retention.local.count integer Yes Min 0; max 10000.
retention.local.days integer Yes Min 0; max 3650.
retention.local.maxStorageGb number Yes Min 0; max 100000.
retention.remote object Yes —
retention.remote.enabled boolean Yes —
retention.remote.count integer Yes Min 0; max 10000.
retention.remote.days integer Yes Min 0; max 3650.
retention.remote.maxStorageGb number Yes Min 0; max 100000.
volumes object Yes —
volumes.mode string Yes "none", "allNamed", "selected".
volumes.names string[] Yes Each item: Pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]*$. Min 1; max 128 characters.
databaseDumps object[] Yes —
databaseDumps[].service string Yes Pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]*$. Min 1; max 128 characters.
databaseDumps[].engine string Yes "postgres", "mysql", "mariadb", "mongo".
databaseDumps[].database string No Default: "". max 128 characters.

Send Idempotency-Key as a header, not a body field.

Response: HTTP 201.

Field Type Required Details
policyId string Yes Min 1; max 128 characters.
projectId string Yes Min 1; max 128 characters.
settingsVersion integer Yes Min 1.

Update backup policy

PUT /api/v1/projects/{projectId}/backup-policies/{policyId}

Replace a backup policy using its current settings version. Requires current administrator role.

Permission: backups:write · Owner/admin.

MCP: update_backup_policy.

Path parameters

Field Type Required Details
projectId string Yes Min 1; max 128 characters.
policyId string Yes Min 1; max 128 characters.

JSON body

Field Type Required Details
name string Yes Min 1; max 100 characters.
environmentId string Yes Min 1 characters.
enabled boolean Yes —
schedule object Yes —
schedule.cron string Yes —
destination object Yes —
destination.storageId string No Min 1 characters.
destination.prefix string No max 512 characters.
retention object Yes —
retention.local object Yes —
retention.local.count integer Yes Min 0; max 10000.
retention.local.days integer Yes Min 0; max 3650.
retention.local.maxStorageGb number Yes Min 0; max 100000.
retention.remote object Yes —
retention.remote.enabled boolean Yes —
retention.remote.count integer Yes Min 0; max 10000.
retention.remote.days integer Yes Min 0; max 3650.
retention.remote.maxStorageGb number Yes Min 0; max 100000.
volumes object Yes —
volumes.mode string Yes "none", "allNamed", "selected".
volumes.names string[] Yes Each item: Pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]*$. Min 1; max 128 characters.
databaseDumps object[] Yes —
databaseDumps[].service string Yes Pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]*$. Min 1; max 128 characters.
databaseDumps[].engine string Yes "postgres", "mysql", "mariadb", "mongo".
databaseDumps[].database string No Default: "". max 128 characters.
settingsVersion integer Yes Min 1.

Send Idempotency-Key as a header, not a body field.

Response: HTTP 200.

Field Type Required Details
policyId string Yes Min 1; max 128 characters.
projectId string Yes Min 1; max 128 characters.
settingsVersion integer Yes Min 1.

Delete backup policy

DELETE /api/v1/projects/{projectId}/backup-policies/{policyId}

Remove a backup policy without deleting retained backup runs. Requires current administrator role.

Permission: backups:write · Owner/admin.

MCP: delete_backup_policy.

Path parameters

Field Type Required Details
projectId string Yes Min 1; max 128 characters.
policyId string Yes Min 1; max 128 characters.

JSON body

Field Type Required Details
confirmation string Yes Exactly "delete-policy".
settingsVersion integer Yes Min 1.

Send Idempotency-Key as a header, not a body field.

Response: HTTP 200.

Field Type Required Details
policyId string Yes Min 1; max 128 characters.
projectId string Yes Min 1; max 128 characters.
settingsVersion integer Yes Min 1.

Create backup storage

POST /api/v1/backup-storage

Create a team backup destination. Secret access keys are write-only. Requires current administrator role.

Permission: backups:write · Owner/admin · Workspace-wide access required.

MCP: Not exposed.

JSON body

Field Type Required Details
name string Yes Min 1; max 100 characters.
bucket string Yes Pattern: ^[a-z0-9][a-z0-9.-]*[a-z0-9]$. Min 3; max 63 characters.
region string Yes Min 1; max 100 characters.
endpoint string Yes Exactly "". or uri.
accessKeyId string Yes Min 1; max 256 characters.
secretAccessKey string Yes max 1024 characters.

Send Idempotency-Key as a header, not a body field.

Response: HTTP 201.

Field Type Required Details
storageId string Yes Min 1; max 128 characters.
settingsVersion integer Yes Min 1.

Update backup storage

PUT /api/v1/backup-storage/{storageId}

Rename or rotate credentials of a team backup destination. Bucket, region, and endpoint are immutable.

Permission: backups:write · Owner/admin · Workspace-wide access required.

MCP: Not exposed.

Path parameters

Field Type Required Details
storageId string Yes Min 1; max 128 characters.

JSON body

Field Type Required Details
name string Yes Min 1; max 100 characters.
bucket string Yes Pattern: ^[a-z0-9][a-z0-9.-]*[a-z0-9]$. Min 3; max 63 characters.
region string Yes Min 1; max 100 characters.
endpoint string Yes Exactly "". or uri.
accessKeyId string Yes Min 1; max 256 characters.
secretAccessKey string Yes max 1024 characters.
settingsVersion integer Yes Min 1.

Send Idempotency-Key as a header, not a body field.

Response: HTTP 200.

Field Type Required Details
storageId string Yes Min 1; max 128 characters.
settingsVersion integer Yes Min 1.

Delete backup storage

DELETE /api/v1/backup-storage/{storageId}

Delete an unreferenced backup destination. Policies, active backups, and retained remote artifacts prevent deletion.

Permission: backups:write · Owner/admin · Workspace-wide access required.

MCP: Not exposed.

Path parameters

Field Type Required Details
storageId string Yes Min 1; max 128 characters.

JSON body

Field Type Required Details
settingsVersion integer Yes Min 1.
confirmation string Yes Exactly "delete-storage".

Send Idempotency-Key as a header, not a body field.

Response: HTTP 200.

Field Type Required Details
storageId string Yes Min 1; max 128 characters.
settingsVersion integer Yes Min 1.