Skip to content

Create Workspace Restore Api

POST
/workspace/restore

Restore a completed backup of this workspace as this key (its write grants apply): a dry run unless dry_run is false.

Authorizations

Parameters

Header Parameters

X-Target-Org-Id
Any of:
string

Request Body required

Restore one completed backup of THIS workspace, by id. A record or report that is missing is added; one that exists is UPDATED to the backup’s values where they differ, through the same checks as an edit (an archived record the backup holds live is unarchived). Objects, fields, relationships, process lists, grants and links are only added. Nothing that exists is ever deleted or archived.

dry_run defaults to true: every step and check runs and is rolled back, and the counts say exactly what a restore would add, update and leave unchanged. A real restore must send dry_run: false.

object
backup_id
required
string format: uuid
dry_run

True (the default) writes nothing; send false to restore.

boolean
default: true

Responses

202

Successful Response

object
data
required
object
backup_id
Any of:
string format: uuid
completed_at
Any of:
string format: date-time
conflict_count
integer
conflict_offset
integer
conflicts

One page of the receipt.

Array<object>

One receipt line: the refused item (section and id; for a field error the field slug), a stable code, why it was refused and what fixes it. Never a value from the archive.

object
code
required
string
field
Any of:
string
fix
string
""
id
Any of:
string
section
required
string
why
string
""
conflicts_truncated

More conflicts happened than the receipt keeps (the first 5,000); conflict_count is exact.

boolean
counts

Per archive section. A dry run’s counts are what the restore would do now.

object
key
additional properties

What a restore did (or, for a dry run, would do) with one archive section. Every row of the section is counted exactly once: created + updated + unchanged + conflicts + skipped is the section’s rows in the backup.

object
conflicts
integer
created

Not in the workspace by id: added.

integer
skipped

Not restored by design (e.g. schema from a restricted archive).

integer
unchanged

In the workspace by id and left exactly as it is: it already holds the backup’s values, or its section is only added.

integer
updated

In the workspace by id with other values: written back to the backup’s values (records and reports only; every other section is only added, so this stays 0 there).

integer
created_at
required
string format: date-time
dry_run
required
boolean
error_code
Any of:
string
heartbeat_at
Any of:
string format: date-time
id
required
string format: uuid
note

What a restore adds, updates and never touches, in one sentence.

string
default: Records and reports are matched by id: a missing one is added, and one that exists is updated to the backup's values where they differ (one archived now but live in the backup is unarchived). Objects, fields, relationships, process lists, grants and links are only added: one that exists is left as it is. Nothing that exists is deleted or archived, and calculated values are recomputed, never restored.
requested_by
Any of:

Who asked. name and kind are shown to a workspace administrator only (anyone else lists only their own jobs and reads is_you); name is the member’s display name, None for an API key or an unknown member.

object
is_you
required
boolean
kind
Any of:
string
Allowed values: member api_key
name
Any of:
string
scope
Any of:
string
Allowed values: complete restricted
started_at
Any of:
string format: date-time
status
required
string
Allowed values: pending running completed failed expired
totals

counts summed over every section.

object
conflicts
integer
created

Not in the workspace by id: added.

integer
skipped

Not restored by design (e.g. schema from a restricted archive).

integer
unchanged

In the workspace by id and left exactly as it is: it already holds the backup’s values, or its section is only added.

integer
updated

In the workspace by id with other values: written back to the backup’s values (records and reports only; every other section is only added, so this stays 0 there).

integer
pagination
Any of:
object
has_next
required

Whether there are more pages

boolean
limit
required

Items per page

integer
next_cursor
Any of:
string
notes
Any of:
Array<string>
page
required

Current page number (1-indexed)

integer
total
required

Total number of items

integer
total_available
Any of:
integer
total_is_lower_bound
Any of:
boolean

422

Validation Error

object
detail
Array<object>
object
loc
required
Array
msg
required
string
type
required
string