Skip to content

Keeper API v1

JSON API of keeper-api, used by the web console and the keeper CLI (ADR 0012). This document is the source of truth: the Go DTOs and the CLI client in internal/apiv1 are generated from it (make generate), and keeper-api validates every request against it.

Authentication: behind Cloudflare Access every request carries an Access JWT (Cf-Access-Jwt-Assertion, cf-access-token or the CF_Authorization cookie). Roles, lowest first: viewer, operator, restorer, restorer-admin. Each operation names the role it needs in x-keeper-role.

Storage formats (manifest, inventory, tags, previews) are returned as stored (ADR 0006).

License: Proprietary

Servers

Description URL
/api/v1 /api/v1

meta

GET /whoami

The authenticated principal and the server version

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key

Responses

{
    "principal": {
        "id": "string",
        "email": "string",
        "groups": [
            "string"
        ],
        "role": "viewer",
        "orgs": [
            "string"
        ],
        "projects": [
            "string"
        ],
        "service": true
    },
    "version": "string",
    "externalURL": "string"
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "required": [
        "principal",
        "version",
        "externalURL"
    ],
    "properties": {
        "principal": {
            "$ref": "#/components/schemas/Principal"
        },
        "version": {
            "type": "string"
        },
        "externalURL": {
            "type": "string"
        }
    }
}

Refer to the common response description: Error.

GET /openapi.yaml

This document

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key

Responses

Schema of the response body 
{
    "type": "object",
    "description": "An OpenAPI 3.0 document"
}

Refer to the common response description: Error.

GET /settings

Stores, policies and catalog state (read-only)

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key

Responses

{
    "stores": [
        {
            "name": "string",
            "endpoint": "string",
            "region": "string",
            "bucket": "string",
            "prefix": "string",
            "readOnly": true,
            "phase": "string",
            "message": "string"
        }
    ],
    "policies": [
        {
            "namespace": "string",
            "name": "string",
            "store": "string",
            "schedule": "string",
            "retention": "string",
            "pitr": true,
            "verify": "string"
        }
    ],
    "version": "string",
    "catalog": {
        "targets": 0,
        "backups": 0,
        "version": 16
    }
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "required": [
        "stores",
        "policies",
        "version",
        "catalog"
    ],
    "properties": {
        "stores": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/Store"
            }
        },
        "policies": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/Policy"
            }
        },
        "version": {
            "type": "string"
        },
        "catalog": {
            "$ref": "#/components/schemas/CatalogState"
        }
    }
}

Refer to the common response description: Error.

targets

GET /targets

Targets with last backup, PITR window and health

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key
env query string No
health query No
org query string No
project query string No
q query string No Free-text search

Responses

{
    "targets": [
        {
            "namespace": "string",
            "name": "string",
            "engine": "string",
            "org": "string",
            "project": "string",
            "env": "string",
            "policy": "string",
            "phase": "string",
            "message": "string",
            "suspended": true,
            "lastFull": null,
            "lastSuccess": "2022-04-13T15:42:05.901Z",
            "nextRun": "2022-04-13T15:42:05.901Z",
            "pitr": true,
            "windows": [
                {
                    "from": "2022-04-13T15:42:05.901Z",
                    "to": "2022-04-13T15:42:05.901Z"
                }
            ],
            "gaps": 0,
            "chainBroken": true,
            "lagSeconds": 78,
            "storedBytes": 104,
            "backups": 0,
            "segments": 0,
            "lastVerification": "2022-04-13T15:42:05.901Z",
            "health": "ok",
            "healthReason": "string",
            "running": "string",
            "onlyInStore": true,
            "store": "string"
        }
    ],
    "catalogVersion": 190
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "required": [
        "targets",
        "catalogVersion"
    ],
    "properties": {
        "targets": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/Target"
            }
        },
        "catalogVersion": {
            "type": "integer",
            "format": "int64"
        }
    }
}

Refer to the common response description: Error.

GET /targets/{ns}/{name}

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key
name path No
ns path No

Responses

{
    "target": {
        "namespace": "string",
        "name": "string",
        "engine": "string",
        "org": "string",
        "project": "string",
        "env": "string",
        "policy": "string",
        "phase": "string",
        "message": "string",
        "suspended": true,
        "lastFull": null,
        "lastSuccess": "2022-04-13T15:42:05.901Z",
        "nextRun": "2022-04-13T15:42:05.901Z",
        "pitr": true,
        "windows": [
            {
                "from": "2022-04-13T15:42:05.901Z",
                "to": "2022-04-13T15:42:05.901Z"
            }
        ],
        "gaps": 0,
        "chainBroken": true,
        "lagSeconds": 24,
        "storedBytes": 241,
        "backups": 0,
        "segments": 0,
        "lastVerification": "2022-04-13T15:42:05.901Z",
        "health": "ok",
        "healthReason": "string",
        "running": "string",
        "onlyInStore": true,
        "store": "string"
    },
    "spec": {},
    "status": {}
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "required": [
        "target"
    ],
    "properties": {
        "target": {
            "$ref": "#/components/schemas/Target"
        },
        "spec": {
            "type": "object",
            "description": "The BackupTarget's spec (see the CRD)",
            "additionalProperties": true,
            "x-go-type": "keeperv1.BackupTargetSpec",
            "x-go-type-import": {
                "name": "keeperv1",
                "path": "github.com/republic-global/keeper/api/v1alpha1"
            },
            "x-go-type-skip-optional-pointer": false
        },
        "status": {
            "type": "object",
            "description": "The BackupTarget's status (see the CRD)",
            "additionalProperties": true,
            "x-go-type": "keeperv1.BackupTargetStatus",
            "x-go-type-import": {
                "name": "keeperv1",
                "path": "github.com/republic-global/keeper/api/v1alpha1"
            },
            "x-go-type-skip-optional-pointer": false
        }
    }
}

Refer to the common response description: Error.

POST /targets/{ns}/{name}/suspend

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key
name path No
ns path No

Request body

{
    "reason": "string"
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body 
{
    "type": "object",
    "additionalProperties": false,
    "properties": {
        "reason": {
            "type": "string",
            "maxLength": 1000
        }
    }
}

Responses

Refer to the common response description: Action.

Refer to the common response description: Error.

POST /targets/{ns}/{name}/resume

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key
name path No
ns path No

Request body

{
    "reason": "string"
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body 
{
    "type": "object",
    "additionalProperties": false,
    "properties": {
        "reason": {
            "type": "string",
            "maxLength": 1000
        }
    }
}

Responses

Refer to the common response description: Action.

Refer to the common response description: Error.

backups

GET /targets/{ns}/{name}/backups

Versions of a target, newest first

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key
limit query integer No
name path No
ns path No

Responses

{
    "target": "string",
    "backups": [
        {
            "id": "string",
            "target": "string",
            "time": "2022-04-13T15:42:05.901Z",
            "completed": "2022-04-13T15:42:05.901Z",
            "engine": "string",
            "mode": "string",
            "serverVersion": "string",
            "reason": "string",
            "rawBytes": 19,
            "storedBytes": 148,
            "durationSeconds": 10.12,
            "tiers": [
                "string"
            ],
            "pinned": true,
            "pinReason": "string",
            "verified": true,
            "verifyFailed": true,
            "tables": 0,
            "rowsEstimate": 29,
            "schemaHash": "string",
            "migrationVersion": "string",
            "position": "string",
            "databases": [
                "string"
            ],
            "warnings": [
                "string"
            ],
            "store": "string"
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "required": [
        "target",
        "backups"
    ],
    "properties": {
        "target": {
            "type": "string"
        },
        "backups": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/Backup"
            }
        }
    }
}

Refer to the common response description: Error.

POST /targets/{ns}/{name}/backup-now

Trigger a full backup

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key
name path No
ns path No

Request body

{
    "reason": "string"
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body 
{
    "type": "object",
    "additionalProperties": false,
    "properties": {
        "reason": {
            "type": "string",
            "maxLength": 1000
        }
    }
}

Responses

Refer to the common response description: Action.

Refer to the common response description: Error.

GET /backups/{id}

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key
id path string No

Responses

{
    "backup": {
        "id": "string",
        "target": "string",
        "time": "2022-04-13T15:42:05.901Z",
        "completed": "2022-04-13T15:42:05.901Z",
        "engine": "string",
        "mode": "string",
        "serverVersion": "string",
        "reason": "string",
        "rawBytes": 265,
        "storedBytes": 97,
        "durationSeconds": 10.12,
        "tiers": [
            "string"
        ],
        "pinned": true,
        "pinReason": "string",
        "verified": true,
        "verifyFailed": true,
        "tables": 0,
        "rowsEstimate": 68,
        "schemaHash": "string",
        "migrationVersion": "string",
        "position": "string",
        "databases": [
            "string"
        ],
        "warnings": [
            "string"
        ],
        "store": "string"
    },
    "manifest": {
        "version": 0,
        "id": "string",
        "kind": "string",
        "engine": "string",
        "mode": "string",
        "target": {
            "namespace": "string",
            "name": "string",
            "org": "string",
            "project": "string",
            "env": "string",
            "uid": "string"
        },
        "policy": "string",
        "reason": "string",
        "server": {
            "version": "string",
            "major": 0,
            "host": "string",
            "systemID": "string",
            "settings": {},
            "sizeBytes": 279
        },
        "startedAt": "2022-04-13T15:42:05.901Z",
        "completedAt": "2022-04-13T15:42:05.901Z",
        "consistentAt": "2022-04-13T15:42:05.901Z",
        "position": {
            "startLSN": "string",
            "endLSN": "string",
            "timeline": 0,
            "startWAL": "string",
            "binlogFile": "string",
            "binlogPos": 108,
            "gtidSet": "string"
        },
        "databases": [
            "string"
        ],
        "objects": [
            {
                "key": "string",
                "size": 117,
                "sha256": "string",
                "rawSize": 113,
                "role": "string",
                "database": "string",
                "format": "string",
                "name": "string",
                "compression": "zstd"
            }
        ],
        "tools": {},
        "recipients": [
            "string"
        ],
        "inventory": {
            "databases": 0,
            "tables": 0,
            "rowsEstimate": 42,
            "bytes": 79,
            "schemaHash": "string",
            "migrationVersion": "string"
        },
        "tiers": [
            "string"
        ],
        "stats": {
            "rawBytes": 117,
            "storedBytes": 133,
            "durationSeconds": 10.12,
            "postpones": 0,
            "warnings": [
                "string"
            ],
            "throughputMBps": 10.12
        },
        "keeperVersion": "string",
        "scope": {}
    },
    "tags": {
        "tiers": [
            "string"
        ],
        "pinned": true,
        "pinReason": "string",
        "pinExpires": "2022-04-13T15:42:05.901Z",
        "pinnedBy": "string",
        "verified": true,
        "verifiedAt": "2022-04-13T15:42:05.901Z",
        "verifyRTOSeconds": 10.12,
        "verifyFailed": true,
        "updatedAt": "2022-04-13T15:42:05.901Z"
    }
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "required": [
        "backup",
        "manifest",
        "tags"
    ],
    "properties": {
        "backup": {
            "$ref": "#/components/schemas/Backup"
        },
        "manifest": {
            "$ref": "#/components/schemas/Manifest"
        },
        "tags": {
            "$ref": "#/components/schemas/Tags"
        }
    }
}

Refer to the common response description: Error.

GET /backups/{id}/inventory

What the database looked like (needs the store's catalog identity)

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key
id path string No

Responses

{
    "collectedAt": "2022-04-13T15:42:05.901Z",
    "engine": "string",
    "server": {
        "version": "string",
        "major": 0,
        "host": "string",
        "systemID": "string",
        "settings": {},
        "sizeBytes": 200
    },
    "databases": [
        {
            "name": "string",
            "sizeBytes": 226,
            "oid": 0,
            "extensions": [
                "string"
            ],
            "schemas": [
                "string"
            ],
            "tables": [
                {
                    "schema": "string",
                    "name": "string",
                    "kind": "string",
                    "rowsEstimate": 88,
                    "exactRows": 69,
                    "totalBytes": 65,
                    "tableBytes": 234,
                    "indexBytes": 17,
                    "toastBytes": 136,
                    "columns": [
                        {
                            "name": "string",
                            "type": "string",
                            "nullable": true,
                            "default": "string"
                        }
                    ],
                    "primaryKey": [
                        "string"
                    ],
                    "indexes": [
                        {
                            "name": "string",
                            "columns": [
                                "string"
                            ],
                            "unique": true,
                            "def": "string"
                        }
                    ],
                    "foreignKeys": [
                        {
                            "name": "string",
                            "columns": [
                                "string"
                            ],
                            "refTable": "string",
                            "refColumns": [
                                "string"
                            ]
                        }
                    ],
                    "fingerprint": "string",
                    "activity": {
                        "inserts": 225,
                        "updates": 177,
                        "deletes": 286,
                        "lastAutovacuum": "2022-04-13T15:42:05.901Z"
                    },
                    "relfilenode": 0,
                    "oid": 0
                }
            ],
            "views": [
                "string"
            ],
            "routines": [
                "string"
            ],
            "migrationTable": "string",
            "migrationVersion": "string",
            "schemaHash": "string"
        }
    ],
    "schemaHash": "string",
    "notes": [
        "string"
    ],
    "extra": {}
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "description": "What a database looked like at backup time (no row data)",
    "x-go-type": "model.Inventory",
    "x-go-type-import": {
        "path": "github.com/republic-global/keeper/internal/model"
    },
    "required": [
        "collectedAt",
        "engine",
        "server",
        "databases",
        "schemaHash"
    ],
    "properties": {
        "collectedAt": {
            "type": "string",
            "format": "date-time"
        },
        "engine": {
            "type": "string"
        },
        "server": {
            "$ref": "#/components/schemas/ServerInfo"
        },
        "databases": {
            "type": "array",
            "nullable": true,
            "items": {
                "type": "object",
                "required": [
                    "name",
                    "sizeBytes",
                    "tables",
                    "schemaHash"
                ],
                "properties": {
                    "name": {
                        "type": "string"
                    },
                    "sizeBytes": {
                        "type": "integer",
                        "format": "int64"
                    },
                    "oid": {
                        "type": "integer"
                    },
                    "extensions": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "schemas": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "tables": {
                        "type": "array",
                        "nullable": true,
                        "items": {
                            "type": "object",
                            "required": [
                                "name",
                                "rowsEstimate",
                                "totalBytes",
                                "columns",
                                "fingerprint"
                            ],
                            "properties": {
                                "schema": {
                                    "type": "string"
                                },
                                "name": {
                                    "type": "string"
                                },
                                "kind": {
                                    "type": "string"
                                },
                                "rowsEstimate": {
                                    "type": "integer",
                                    "format": "int64"
                                },
                                "exactRows": {
                                    "type": "integer",
                                    "format": "int64"
                                },
                                "totalBytes": {
                                    "type": "integer",
                                    "format": "int64"
                                },
                                "tableBytes": {
                                    "type": "integer",
                                    "format": "int64"
                                },
                                "indexBytes": {
                                    "type": "integer",
                                    "format": "int64"
                                },
                                "toastBytes": {
                                    "type": "integer",
                                    "format": "int64"
                                },
                                "columns": {
                                    "type": "array",
                                    "nullable": true,
                                    "items": {
                                        "type": "object",
                                        "required": [
                                            "name",
                                            "type",
                                            "nullable"
                                        ],
                                        "properties": {
                                            "name": {
                                                "type": "string"
                                            },
                                            "type": {
                                                "type": "string"
                                            },
                                            "nullable": {
                                                "type": "boolean"
                                            },
                                            "default": {
                                                "type": "string"
                                            }
                                        }
                                    }
                                },
                                "primaryKey": {
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                },
                                "indexes": {
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "required": [
                                            "name"
                                        ],
                                        "properties": {
                                            "name": {
                                                "type": "string"
                                            },
                                            "columns": {
                                                "type": "array",
                                                "items": {
                                                    "type": "string"
                                                }
                                            },
                                            "unique": {
                                                "type": "boolean"
                                            },
                                            "def": {
                                                "type": "string"
                                            }
                                        }
                                    }
                                },
                                "foreignKeys": {
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "required": [
                                            "name",
                                            "columns",
                                            "refTable",
                                            "refColumns"
                                        ],
                                        "properties": {
                                            "name": {
                                                "type": "string"
                                            },
                                            "columns": {
                                                "type": "array",
                                                "nullable": true,
                                                "items": {
                                                    "type": "string"
                                                }
                                            },
                                            "refTable": {
                                                "type": "string"
                                            },
                                            "refColumns": {
                                                "type": "array",
                                                "nullable": true,
                                                "items": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                },
                                "fingerprint": {
                                    "type": "string"
                                },
                                "activity": {
                                    "type": "object",
                                    "properties": {
                                        "inserts": {
                                            "type": "integer",
                                            "format": "int64"
                                        },
                                        "updates": {
                                            "type": "integer",
                                            "format": "int64"
                                        },
                                        "deletes": {
                                            "type": "integer",
                                            "format": "int64"
                                        },
                                        "lastAutovacuum": {
                                            "type": "string",
                                            "format": "date-time"
                                        }
                                    }
                                },
                                "relfilenode": {
                                    "type": "integer"
                                },
                                "oid": {
                                    "type": "integer"
                                }
                            }
                        }
                    },
                    "views": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "routines": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "migrationTable": {
                        "type": "string"
                    },
                    "migrationVersion": {
                        "type": "string"
                    },
                    "schemaHash": {
                        "type": "string"
                    }
                }
            }
        },
        "schemaHash": {
            "type": "string"
        },
        "notes": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "extra": {
            "type": "object",
            "additionalProperties": {
                "type": "string"
            }
        }
    }
}

Refer to the common response description: Error.

GET /backups/{id}/diff/{other}

Schema, row and size changes between two versions, and the segments in between

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key
id path string No
other path string No

Responses

{
    "from": {
        "id": "string",
        "target": "string",
        "time": "2022-04-13T15:42:05.901Z",
        "completed": "2022-04-13T15:42:05.901Z",
        "engine": "string",
        "mode": "string",
        "serverVersion": "string",
        "reason": "string",
        "rawBytes": 35,
        "storedBytes": 148,
        "durationSeconds": 10.12,
        "tiers": [
            "string"
        ],
        "pinned": true,
        "pinReason": "string",
        "verified": true,
        "verifyFailed": true,
        "tables": 0,
        "rowsEstimate": 20,
        "schemaHash": "string",
        "migrationVersion": "string",
        "position": "string",
        "databases": [
            "string"
        ],
        "warnings": [
            "string"
        ],
        "store": "string"
    },
    "to": null,
    "diff": {
        "tablesAdded": [
            "string"
        ],
        "tablesDropped": [
            "string"
        ],
        "tablesRenamed": [
            {
                "from": "string",
                "to": "string"
            }
        ],
        "columns": [
            {
                "table": "string",
                "added": [
                    "string"
                ],
                "removed": [
                    "string"
                ],
                "typeChanged": [
                    "string"
                ],
                "indexAdded": [
                    "string"
                ],
                "indexDropped": [
                    "string"
                ]
            }
        ],
        "rows": [
            {
                "table": "string",
                "rowsBefore": 21,
                "rowsAfter": 223,
                "rowsPct": 10.12,
                "sizeBefore": 245,
                "sizeAfter": 203
            }
        ],
        "sizeBefore": 187,
        "sizeAfter": 276,
        "migrationBefore": "string",
        "migrationAfter": "string",
        "schemaChanged": true,
        "lines": [
            "string"
        ],
        "databasesAdded": [
            "string"
        ],
        "databasesDropped": [
            "string"
        ]
    },
    "segments": [
        {
            "version": 0,
            "engine": "string",
            "name": "string",
            "seq": 136,
            "timeline": 0,
            "server": "string",
            "key": "string",
            "size": 36,
            "sha256": "string",
            "rawSize": 74,
            "partial": true,
            "startPos": "string",
            "endPos": "string",
            "firstTime": "2022-04-13T15:42:05.901Z",
            "lastTime": "2022-04-13T15:42:05.901Z",
            "commits": 254,
            "tables": {},
            "ddl": [
                "string"
            ],
            "previewsKey": "string",
            "uploadedAt": "2022-04-13T15:42:05.901Z",
            "chainID": "string",
            "explanation": "string",
            "target": "string"
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "required": [
        "from",
        "to",
        "diff",
        "segments"
    ],
    "properties": {
        "from": {
            "$ref": "#/components/schemas/Backup"
        },
        "to": {
            "$ref": "#/components/schemas/Backup"
        },
        "diff": {
            "$ref": "#/components/schemas/Diff"
        },
        "segments": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/Segment"
            }
        }
    }
}

Refer to the common response description: Error.

POST /backups/{id}/pin

Retention hold

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key
id path string No

Request body

{
    "reason": "string",
    "expires": "string"
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body 
{
    "type": "object",
    "additionalProperties": false,
    "properties": {
        "reason": {
            "type": "string",
            "maxLength": 1000
        },
        "expires": {
            "type": "string",
            "description": "Pin duration (30d) or RFC3339 time; empty: forever"
        }
    }
}

Responses

Refer to the common response description: Action.

Refer to the common response description: Error.

POST /backups/{id}/unpin

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key
id path string No

Request body

{
    "reason": "string"
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body 
{
    "type": "object",
    "additionalProperties": false,
    "properties": {
        "reason": {
            "type": "string",
            "maxLength": 1000
        }
    }
}

Responses

Refer to the common response description: Action.

Refer to the common response description: Error.

changes

GET /targets/{ns}/{name}/segments

Change-stream segments of a target, newest first

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key
limit query integer No
name path No
ns path No
since query string No A duration back from now (2h, 3d) or an RFC3339 time

Responses

{
    "target": "string",
    "since": "2022-04-13T15:42:05.901Z",
    "segments": [
        {
            "version": 0,
            "engine": "string",
            "name": "string",
            "seq": 245,
            "timeline": 0,
            "server": "string",
            "key": "string",
            "size": 268,
            "sha256": "string",
            "rawSize": 218,
            "partial": true,
            "startPos": "string",
            "endPos": "string",
            "firstTime": "2022-04-13T15:42:05.901Z",
            "lastTime": "2022-04-13T15:42:05.901Z",
            "commits": 299,
            "tables": {},
            "ddl": [
                "string"
            ],
            "previewsKey": "string",
            "uploadedAt": "2022-04-13T15:42:05.901Z",
            "chainID": "string",
            "explanation": "string",
            "target": "string"
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "required": [
        "target",
        "since",
        "segments"
    ],
    "properties": {
        "target": {
            "type": "string"
        },
        "since": {
            "type": "string",
            "format": "date-time"
        },
        "segments": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/Segment"
            }
        }
    }
}

Refer to the common response description: Error.

GET /segments

Segments across visible targets, newest first

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key
limit query integer No
since query string No A duration back from now (2h, 3d) or an RFC3339 time
target query string No namespace/name

Responses

{
    "since": "2022-04-13T15:42:05.901Z",
    "segments": [
        {
            "version": 0,
            "engine": "string",
            "name": "string",
            "seq": 283,
            "timeline": 0,
            "server": "string",
            "key": "string",
            "size": 248,
            "sha256": "string",
            "rawSize": 257,
            "partial": true,
            "startPos": "string",
            "endPos": "string",
            "firstTime": "2022-04-13T15:42:05.901Z",
            "lastTime": "2022-04-13T15:42:05.901Z",
            "commits": 257,
            "tables": {},
            "ddl": [
                "string"
            ],
            "previewsKey": "string",
            "uploadedAt": "2022-04-13T15:42:05.901Z",
            "chainID": "string",
            "explanation": "string",
            "target": "string"
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "required": [
        "since",
        "segments"
    ],
    "properties": {
        "since": {
            "type": "string",
            "format": "date-time"
        },
        "segments": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/Segment"
            }
        }
    }
}

Refer to the common response description: Error.

GET /segments/{ns}/{name}/{seg}/previews

Masked row previews of a segment

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key
name path No
ns path No
seg path string No Segment name

Responses

{
    "segment": "string",
    "previews": {
        "tables": {}
    }
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "required": [
        "segment",
        "previews"
    ],
    "properties": {
        "segment": {
            "type": "string"
        },
        "previews": {
            "$ref": "#/components/schemas/Previews"
        }
    }
}

Refer to the common response description: Error.

restores

GET /targets/{ns}/{name}/plan

The restore plan for a backup or a point in time (a dry run)

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key
at query string No RFC3339 time (second resolution), or latest
backup query string No Backup ID
name path No
ns path No

Responses

{
    "baseBackupID": "string",
    "baseTime": "2022-04-13T15:42:05.901Z",
    "segments": 0,
    "targetTime": "2022-04-13T15:42:05.901Z",
    "effectiveTime": "2022-04-13T15:42:05.901Z",
    "bytes": 293,
    "restorable": true,
    "reason": "string",
    "windows": [
        {
            "from": "2022-04-13T15:42:05.901Z",
            "to": "2022-04-13T15:42:05.901Z"
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "required": [
        "baseBackupID",
        "baseTime",
        "segments",
        "effectiveTime",
        "bytes",
        "restorable"
    ],
    "properties": {
        "baseBackupID": {
            "type": "string",
            "x-go-name": "BaseBackupID"
        },
        "baseTime": {
            "type": "string",
            "format": "date-time"
        },
        "segments": {
            "type": "integer"
        },
        "targetTime": {
            "type": "string",
            "format": "date-time",
            "x-go-type-skip-optional-pointer": false
        },
        "effectiveTime": {
            "type": "string",
            "format": "date-time"
        },
        "bytes": {
            "type": "integer",
            "format": "int64"
        },
        "restorable": {
            "type": "boolean"
        },
        "reason": {
            "type": "string"
        },
        "windows": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/Window"
            }
        }
    }
}

Refer to the common response description: Error.

POST /targets/{ns}/{name}/verify

Run a verification restore now

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key
name path No
ns path No

Request body

{
    "reason": "string"
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body 
{
    "type": "object",
    "additionalProperties": false,
    "properties": {
        "reason": {
            "type": "string",
            "maxLength": 1000
        }
    }
}

Responses

Refer to the common response description: Action.

Refer to the common response description: Error.

GET /restores

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key

Responses

{
    "restores": [
        {
            "namespace": "string",
            "name": "string",
            "target": "string",
            "mode": "sandbox",
            "phase": "string",
            "message": "string",
            "requestedBy": "string",
            "created": "2022-04-13T15:42:05.901Z",
            "sandbox": "string",
            "plan": null,
            "progress": null,
            "checks": [
                {
                    "name": "string",
                    "passed": true,
                    "message": "string"
                }
            ],
            "downloadURL": "string",
            "downloadExpires": "2022-04-13T15:42:05.901Z",
            "durationSeconds": 145,
            "source": {
                "backupID": "string",
                "time": "2022-04-13T15:42:05.901Z",
                "latest": true,
                "targetNamespace": "string"
            },
            "destination": {
                "mode": null,
                "sandboxTTL": "string",
                "expose": true,
                "deleteAfter": true,
                "database": "string",
                "host": "string",
                "tables": [
                    "string"
                ]
            }
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "required": [
        "restores"
    ],
    "properties": {
        "restores": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/Restore"
            }
        }
    }
}

Refer to the common response description: Error.

POST /restores

Create a Restore (sandbox, new database, in place or download)

Description

The role depends on the mode: sandbox needs operator, new and download need restorer, in-place needs restorer-admin plus confirm equal to the target name. The plan is checked first: a time outside the restorable windows is refused with 422 and the windows.

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key

Request body

{
    "target": "string",
    "at": "string",
    "backupID": "string",
    "mode": "sandbox",
    "ttl": "string",
    "expose": true,
    "confirm": "string",
    "host": "string",
    "port": 0,
    "database": "string",
    "credentialsSecret": "string",
    "skipSafetyBackup": true,
    "tables": [
        "string"
    ],
    "reason": "string"
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body 
{
    "type": "object",
    "additionalProperties": false,
    "required": [
        "target"
    ],
    "properties": {
        "target": {
            "type": "string",
            "pattern": "^[^/]+/[^/]+$",
            "description": "namespace/name"
        },
        "at": {
            "type": "string",
            "description": "RFC3339 time or latest (default latest)"
        },
        "backupID": {
            "type": "string"
        },
        "mode": {
            "$ref": "#/components/schemas/RestoreMode"
        },
        "ttl": {
            "$ref": "#/components/schemas/Duration"
        },
        "expose": {
            "type": "boolean"
        },
        "confirm": {
            "type": "string",
            "description": "In place: the target name"
        },
        "host": {
            "type": "string",
            "description": "New database: server host"
        },
        "port": {
            "type": "integer",
            "minimum": 1,
            "maximum": 65535
        },
        "database": {
            "type": "string"
        },
        "credentialsSecret": {
            "type": "string",
            "description": "Admin credentials secret (new, in-place)"
        },
        "skipSafetyBackup": {
            "type": "boolean"
        },
        "tables": {
            "type": "array",
            "items": {
                "type": "string"
            },
            "maxItems": 1000
        },
        "reason": {
            "type": "string",
            "maxLength": 1000
        }
    }
}

Responses

Refer to the common response description: Action.

Refer to the common response description: Error.

GET /restores/{ns}/{name}

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key
name path No
ns path No

Responses

{
    "restore": {
        "namespace": "string",
        "name": "string",
        "target": "string",
        "mode": "sandbox",
        "phase": "string",
        "message": "string",
        "requestedBy": "string",
        "created": "2022-04-13T15:42:05.901Z",
        "sandbox": "string",
        "plan": null,
        "progress": null,
        "checks": [
            {
                "name": "string",
                "passed": true,
                "message": "string"
            }
        ],
        "downloadURL": "string",
        "downloadExpires": "2022-04-13T15:42:05.901Z",
        "durationSeconds": 92,
        "source": {
            "backupID": "string",
            "time": "2022-04-13T15:42:05.901Z",
            "latest": true,
            "targetNamespace": "string"
        },
        "destination": {
            "mode": null,
            "sandboxTTL": "string",
            "expose": true,
            "deleteAfter": true,
            "database": "string",
            "host": "string",
            "tables": [
                "string"
            ]
        }
    }
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "required": [
        "restore"
    ],
    "properties": {
        "restore": {
            "$ref": "#/components/schemas/Restore"
        }
    }
}

Refer to the common response description: Error.

POST /restores/{ns}/{name}/cancel

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key
name path No
ns path No

Request body

{
    "reason": "string"
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body 
{
    "type": "object",
    "additionalProperties": false,
    "properties": {
        "reason": {
            "type": "string",
            "maxLength": 1000
        }
    }
}

Responses

Refer to the common response description: Action.

Refer to the common response description: Error.

sandboxes

GET /sandboxes

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key

Responses

{
    "sandboxes": [
        {
            "name": "string",
            "engine": "string",
            "owner": "string",
            "phase": "string",
            "message": "string",
            "namespace": "string",
            "host": "string",
            "port": 0,
            "database": "string",
            "expires": "2022-04-13T15:42:05.901Z",
            "ready": "2022-04-13T15:42:05.901Z",
            "route": "string",
            "target": "string",
            "backupID": "string",
            "time": "2022-04-13T15:42:05.901Z",
            "sizeLimit": "string",
            "restore": "string",
            "created": "2022-04-13T15:42:05.901Z",
            "connect": "string",
            "inCluster": "string"
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "required": [
        "sandboxes"
    ],
    "properties": {
        "sandboxes": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/Sandbox"
            }
        }
    }
}

Refer to the common response description: Error.

GET /sandboxes/{name}

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key
name path No

Responses

{
    "sandbox": {
        "name": "string",
        "engine": "string",
        "owner": "string",
        "phase": "string",
        "message": "string",
        "namespace": "string",
        "host": "string",
        "port": 0,
        "database": "string",
        "expires": "2022-04-13T15:42:05.901Z",
        "ready": "2022-04-13T15:42:05.901Z",
        "route": "string",
        "target": "string",
        "backupID": "string",
        "time": "2022-04-13T15:42:05.901Z",
        "sizeLimit": "string",
        "restore": "string",
        "created": "2022-04-13T15:42:05.901Z",
        "connect": "string",
        "inCluster": "string"
    }
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "required": [
        "sandbox"
    ],
    "properties": {
        "sandbox": {
            "$ref": "#/components/schemas/Sandbox"
        }
    }
}

Refer to the common response description: Error.

DELETE /sandboxes/{name}

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key
name path No

Responses

Refer to the common response description: Action.

Refer to the common response description: Error.

GET /sandboxes/{name}/credentials

Reveal the sandbox credentials (owner or restorer-admin; audited)

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key
name path No

Responses

{
    "username": "string",
    "password": "string",
    "host": "string",
    "port": 0,
    "database": "string",
    "engine": "string",
    "route": "string"
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "required": [
        "username",
        "password",
        "host",
        "port",
        "database",
        "engine"
    ],
    "properties": {
        "username": {
            "type": "string"
        },
        "password": {
            "type": "string"
        },
        "host": {
            "type": "string"
        },
        "port": {
            "type": "integer"
        },
        "database": {
            "type": "string"
        },
        "engine": {
            "type": "string"
        },
        "route": {
            "type": "string"
        }
    }
}

Refer to the common response description: Error.

POST /sandboxes/{name}/extend

Extend the TTL (capped at the policy maximum)

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key
name path No

Request body

{
    "by": "string",
    "reason": "string"
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body 
{
    "type": "object",
    "additionalProperties": false,
    "properties": {
        "by": {
            "$ref": "#/components/schemas/Duration"
        },
        "reason": {
            "type": "string",
            "maxLength": 1000
        }
    }
}

Responses

Refer to the common response description: Action.

Refer to the common response description: Error.

POST /sandboxes/{name}/query

Run SQL on a sandbox (read-only by default, 30 s, 1,000 rows; audited)

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key
format query string No
name path No

Request body

{
    "sql": "string",
    "database": "string",
    "write": true,
    "limit": 0
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body 
{
    "type": "object",
    "additionalProperties": false,
    "required": [
        "sql"
    ],
    "properties": {
        "sql": {
            "type": "string",
            "minLength": 1,
            "maxLength": 262144
        },
        "database": {
            "type": "string"
        },
        "write": {
            "type": "boolean",
            "description": "Run outside a read-only transaction (sandboxes only)"
        },
        "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000
        }
    }
}

Responses

{
    "columns": [
        "string"
    ],
    "rows": [
        [
            "string"
        ]
    ],
    "truncated": true,
    "ms": 63,
    "command": "string",
    "affected": 22,
    "masked": [
        "string"
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "required": [
        "columns",
        "rows",
        "truncated",
        "ms"
    ],
    "properties": {
        "columns": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "rows": {
            "type": "array",
            "items": {
                "type": "array",
                "items": {
                    "type": "string"
                }
            }
        },
        "truncated": {
            "type": "boolean"
        },
        "ms": {
            "type": "integer",
            "format": "int64",
            "x-go-name": "Millis"
        },
        "command": {
            "type": "string"
        },
        "affected": {
            "type": "integer",
            "format": "int64"
        },
        "masked": {
            "type": "array",
            "items": {
                "type": "string"
            },
            "description": "Columns masked by the target's mask rules"
        }
    }
}


"string"
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "string"
}

Refer to the common response description: Error.

GET /sandboxes/{name}/tables

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key
database query string No
name path No

Responses

{
    "tables": [
        {
            "schema": "string",
            "name": "string",
            "rowsEstimate": 19,
            "bytes": 187,
            "columns": [
                "string"
            ],
            "fullName": "string"
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "required": [
        "tables"
    ],
    "properties": {
        "tables": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/TableInfo"
            }
        }
    }
}

Refer to the common response description: Error.

GET /sandboxes/{name}/tables/{table}

The first 50 rows of a table, masked

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key
name path No
table path string No [schema.]table

Responses

{
    "columns": [
        "string"
    ],
    "rows": [
        [
            "string"
        ]
    ],
    "truncated": true,
    "ms": 36,
    "command": "string",
    "affected": 155,
    "masked": [
        "string"
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "required": [
        "columns",
        "rows",
        "truncated",
        "ms"
    ],
    "properties": {
        "columns": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "rows": {
            "type": "array",
            "items": {
                "type": "array",
                "items": {
                    "type": "string"
                }
            }
        },
        "truncated": {
            "type": "boolean"
        },
        "ms": {
            "type": "integer",
            "format": "int64",
            "x-go-name": "Millis"
        },
        "command": {
            "type": "string"
        },
        "affected": {
            "type": "integer",
            "format": "int64"
        },
        "masked": {
            "type": "array",
            "items": {
                "type": "string"
            },
            "description": "Columns masked by the target's mask rules"
        }
    }
}

Refer to the common response description: Error.

activity

GET /activity

Recent and running backups and restores, newest first

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key
limit query integer No

Responses

{
    "backups": [
        {
            "namespace": "string",
            "name": "string",
            "target": "string",
            "phase": "string",
            "message": "string",
            "reason": "string",
            "backupID": "string",
            "created": "2022-04-13T15:42:05.901Z",
            "bytes": 194,
            "durationSeconds": 94,
            "progress": null
        }
    ],
    "restores": [
        {
            "namespace": "string",
            "name": "string",
            "target": "string",
            "mode": "sandbox",
            "phase": "string",
            "message": "string",
            "requestedBy": "string",
            "created": "2022-04-13T15:42:05.901Z",
            "sandbox": "string",
            "plan": null,
            "progress": null,
            "checks": [
                {
                    "name": "string",
                    "passed": true,
                    "message": "string"
                }
            ],
            "downloadURL": "string",
            "downloadExpires": "2022-04-13T15:42:05.901Z",
            "durationSeconds": 14,
            "source": {
                "backupID": "string",
                "time": "2022-04-13T15:42:05.901Z",
                "latest": true,
                "targetNamespace": "string"
            },
            "destination": {
                "mode": null,
                "sandboxTTL": "string",
                "expose": true,
                "deleteAfter": true,
                "database": "string",
                "host": "string",
                "tables": [
                    "string"
                ]
            }
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "required": [
        "backups",
        "restores"
    ],
    "properties": {
        "backups": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/BackupRun"
            }
        },
        "restores": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/Restore"
            }
        }
    }
}

Refer to the common response description: Error.

GET /audit

Recent audit events of this replica, newest first

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key
action query string No
limit query integer No
user query string No

Responses

{
    "events": [
        {
            "time": "2022-04-13T15:42:05.901Z",
            "user": "string",
            "role": "string",
            "action": "string",
            "target": "string",
            "object": "string",
            "outcome": "ok",
            "from": "string",
            "detail": {}
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "required": [
        "events"
    ],
    "properties": {
        "events": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/AuditEvent"
            }
        }
    }
}

Refer to the common response description: Error.

GET /events

Server-sent events (backup, restore, sandbox, target, catalog), coalesced every 500 ms

Input parameters

Parameter In Type Default Nullable Description
accessCookie cookie string N/A No API key
accessToken header string N/A No API key
accessJWT header string N/A No API key

Responses

"string"
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "string"
}

Refer to the common response description: Error.

Schemas

ActionResult

Name Type Description
kind string
link string Console page of the result
message string
name string
namespace string

Activity

Name Type Description
backups Array<BackupRun>
restores Array<Restore>

AuditEvent

Name Type Description
action string
detail
from string
object string
outcome string
role string
target string
time string(date-time)
user string

AuditList

Name Type Description
events Array<AuditEvent>

Backup

Name Type Description
completed string(date-time)
databases Array<string>
durationSeconds number(double)
engine string
id string
migrationVersion string
mode string
pinned boolean
pinReason string
position string
rawBytes integer(int64)
reason string
rowsEstimate integer(int64)
schemaHash string
serverVersion string
store string
storedBytes integer(int64)
tables integer
target string
tiers Array<string>
time string(date-time) Consistent at
verified boolean
verifyFailed boolean
warnings Array<string>

BackupDetail

Name Type Description
backup Backup
manifest Manifest
tags Tags

BackupList

Name Type Description
backups Array<Backup>
target string

BackupRef

Type:

BackupRun

Name Type Description
backupID string
bytes integer(int64)
created string(date-time)
durationSeconds integer(int64)
message string
name string
namespace string
phase string
progress ProgressRef
reason string
target string

CatalogState

Name Type Description
backups integer
targets integer
version integer(int64)

CheckResult

Name Type Description
message string
name string
passed boolean

ColumnChange

Name Type Description
added Array<string>
indexAdded Array<string>
indexDropped Array<string>
removed Array<string>
table string
typeChanged Array<string>

Diff

Name Type Description
columns Array<ColumnChange>
databasesAdded Array<string>
databasesDropped Array<string>
lines Array<string>
migrationAfter string
migrationBefore string
rows Array<RowDelta>
schemaChanged boolean
sizeAfter integer(int64)
sizeBefore integer(int64)
tablesAdded Array<string>
tablesDropped Array<string>
tablesRenamed Array<Rename>

DiffResult

Name Type Description
diff Diff
from Backup
segments Array<Segment>
to Backup

Duration

Type: string

Error

Name Type Description
error string

Event

Name Type Description
bytes integer(int64)
kind string
message string
name string
namespace string
phase string
stage string
version integer(int64)

ExtendRequest

Name Type Description
by Duration
reason string

Health

Type: string

Inventory

Name Type Description
collectedAt string(date-time)
databases Array<Properties: name, sizeBytes, oid, extensions, schemas, tables, views, routines, migrationTable, migrationVersion, schemaHash>
engine string
extra
notes Array<string>
schemaHash string
server ServerInfo

K8sName

Type: string

Manifest

Name Type Description
completedAt string(date-time)
consistentAt string(date-time)
databases Array<string>
engine string
id string
inventory Properties: databases, tables, rowsEstimate, bytes, schemaHash, migrationVersion
keeperVersion string
kind string
mode string
objects Array<Properties: key, size, sha256, rawSize, role, database, format, name, compression>
policy string
position Properties: startLSN, endLSN, timeline, startWAL, binlogFile, binlogPos, gtidSet
reason string
recipients Array<string>
scope
server ServerInfo
startedAt string(date-time)
stats Properties: rawBytes, storedBytes, durationSeconds, postpones, warnings, throughputMBps
target Properties: namespace, name, org, project, env, uid
tiers Array<string>
tools
version integer

PinRequest

Name Type Description
expires string Pin duration (30d) or RFC3339 time; empty: forever
reason string

Plan

Name Type Description
baseBackupID string
baseTime string(date-time)
bytes integer(int64)
effectiveTime string(date-time)
reason string
restorable boolean
segments integer
targetTime string(date-time)
windows Array<Window>

Policy

Name Type Description
name string
namespace string
pitr boolean
retention string daily/weekly/monthly/yearly counts
schedule string
store string
verify string

Previews

Name Type Description
tables

PreviewsResult

Name Type Description
previews Previews
segment string

Principal

Name Type Description
email string
groups Array<string>
id string
orgs Array<string>
projects Array<string>
role string
service boolean

Progress

Name Type Description
bytes integer(int64)
stage string
totalBytes integer(int64)
updatedAt string(date-time)

ProgressRef

Type:

QueryRequest

Name Type Description
database string
limit integer
sql string
write boolean Run outside a read-only transaction (sandboxes only)

QueryResult

Name Type Description
affected integer(int64)
columns Array<string>
command string
masked Array<string> Columns masked by the target's mask rules
ms integer(int64)
rows Array<Array<string>>
truncated boolean

ReasonRequest

Name Type Description
reason string

Rename

Name Type Description
from string
to string

Restore

Name Type Description
checks Array<CheckResult>
created string(date-time)
destination RestoreDestination
downloadExpires string(date-time)
downloadURL string
durationSeconds integer(int64)
message string
mode RestoreMode
name string
namespace string
phase string
plan RestorePlanRef
progress ProgressRef
requestedBy string
sandbox string
source RestoreSource
target string

RestoreDestination

Name Type Description
database string New database: its name
deleteAfter boolean
expose boolean
host string New database: server host
mode RestoreMode
sandboxTTL string
tables Array<string>

RestoreDetail

Name Type Description
restore Restore

RestoreList

Name Type Description
restores Array<Restore>

RestoreMode

Type: string

RestorePlan

Name Type Description
baseBackupID string
bytes integer(int64)
message string
segments integer
targetTime string(date-time)

RestorePlanRef

Type:

RestoreRequest

Name Type Description
at string RFC3339 time or latest (default latest)
backupID string
confirm string In place: the target name
credentialsSecret string Admin credentials secret (new, in-place)
database string
expose boolean
host string New database: server host
mode RestoreMode
port integer
reason string
skipSafetyBackup boolean
tables Array<string>
target string namespace/name
ttl Duration

RestoreSource

Name Type Description
backupID string
latest boolean
targetNamespace string
time string(date-time)

RowDelta

Name Type Description
rowsAfter integer(int64)
rowsBefore integer(int64)
rowsPct number(double)
sizeAfter integer(int64)
sizeBefore integer(int64)
table string

Sandbox

Name Type Description
backupID string
connect string CLI command that opens the tunnel
created string(date-time)
database string
engine string
expires string(date-time)
host string
inCluster string host:port inside the cluster
message string
name string
namespace string
owner string
phase string
port integer
ready string(date-time)
restore string
route string
sizeLimit string
target string
time string(date-time)

SandboxCredentials

Name Type Description
database string
engine string
host string
password string
port integer
route string
username string

SandboxDetail

Name Type Description
sandbox Sandbox

SandboxList

Name Type Description
sandboxes Array<Sandbox>

Segment

Name Type Description
chainID string
commits integer(int64)
ddl Array<string>
endPos string
engine string
explanation string
firstTime string(date-time)
key string
lastTime string(date-time)
name string
partial boolean
previewsKey string
rawSize integer(int64)
seq integer(int64)
server string
sha256 string
size integer(int64)
startPos string
tables
target string
timeline integer
uploadedAt string(date-time)
version integer

SegmentList

Name Type Description
segments Array<Segment>
since string(date-time)

ServerInfo

Name Type Description
host string
major integer
settings
sizeBytes integer(int64)
systemID string
version string

Settings

Name Type Description
catalog CatalogState
policies Array<Policy>
stores Array<Store>
version string

Store

Name Type Description
bucket string
endpoint string
message string
name string
phase string
prefix string
readOnly boolean
region string

TableChange

Name Type Description
deletes integer(int64)
inserts integer(int64)
truncates integer(int64)
updates integer(int64)

TableInfo

Name Type Description
bytes integer(int64)
columns Array<string>
fullName string
name string
rowsEstimate integer(int64)
schema string

TableList

Name Type Description
tables Array<TableInfo>

Tags

Name Type Description
pinExpires string(date-time)
pinned boolean
pinnedBy string
pinReason string
tiers Array<string>
updatedAt string(date-time)
verified boolean
verifiedAt string(date-time)
verifyFailed boolean
verifyRTOSeconds number(double)

Target

Name Type Description
backups integer
chainBroken boolean
engine string
env string
gaps integer
health Health
healthReason string
lagSeconds integer(int64)
lastFull BackupRef
lastSuccess string(date-time)
lastVerification string(date-time)
message string
name string
namespace string
nextRun string(date-time)
onlyInStore boolean
org string
phase string
pitr boolean
policy string
project string
running string
segments integer
store string
storedBytes integer(int64)
suspended boolean
windows Array<Window>

TargetDetail

Name Type Description
spec The BackupTarget's spec (see the CRD)
status The BackupTarget's status (see the CRD)
target Target

TargetList

Name Type Description
catalogVersion integer(int64)
targets Array<Target>

TargetSegmentList

Name Type Description
segments Array<Segment>
since string(date-time)
target string

Whoami

Name Type Description
externalURL string
principal Principal
version string

Window

Name Type Description
from string(date-time)
to string(date-time)

Common responses

This section describes common responses that are reused across operations.

Action

The write was accepted

{
    "message": "string",
    "kind": "string",
    "namespace": "string",
    "name": "string",
    "link": "string"
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "required": [
        "message"
    ],
    "properties": {
        "message": {
            "type": "string"
        },
        "kind": {
            "type": "string"
        },
        "namespace": {
            "type": "string"
        },
        "name": {
            "type": "string"
        },
        "link": {
            "type": "string",
            "description": "Console page of the result"
        }
    }
}

Error

Error (400 invalid request, 401 unauthenticated, 403 role, 404, 409, 422 not restorable, 5xx)

{
    "error": "string"
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "required": [
        "error"
    ],
    "properties": {
        "error": {
            "type": "string"
        }
    }
}

Common parameters

This section describes common parameters that are reused across operations.

Namespace

Name In Type Default Nullable Description
ns path None No

Name

Name In Type Default Nullable Description
name path None No

BackupID

Name In Type Default Nullable Description
id path string No

Since

Name In Type Default Nullable Description
since query string No

At

Name In Type Default Nullable Description
at query string No

Security schemes

Name Type Scheme Description
accessJWT apiKey
accessToken apiKey
accessCookie apiKey

Tags

Name Description
targets
backups
changes
restores
sandboxes
activity
meta

Using the document

Every Keeper serves this document at /api/v1/openapi.yaml; generate a client in any language from it (the keeper CLI uses one generated with oapi-codegen). Requests are validated against it, and each operation needs at least the role in its x-keeper-role (roles). Errors are {"error": "…"} with an HTTP status.