{ "openapi": "3.0.3", "info": { "title": "Faciotech Backup API", "description": "The control-plane REST API behind Faciotech Backup: authenticate, connect sources, configure storage and schedules, trigger and inspect backups, request restores, read the audit trail, and pull usage/health reports. Every resource below is tenant-scoped and policy-gated -- a token only ever sees/affects data in the workspace named by the X-Tenant-Id header, for a tenant the authenticated user actually belongs to.", "version": "1.0.0", "contact": { "name": "Faciotech", "url": "https://vault.faciotech.com/contact" } }, "servers": [ { "url": "https://vault.faciotech.com/api", "description": "Control-plane API" } ], "tags": [ { "name": "Auth", "description": "Obtain and revoke a bearer token." }, { "name": "Sources", "description": "What gets backed up: cPanel accounts, databases, file trees, WordPress sites, the standalone agent, and manual uploads." }, { "name": "Storage Targets", "description": "Where backups are stored: managed or bring-your-own object storage." }, { "name": "Schedules", "description": "Recurring backup jobs -- frequency, retention, and the pause/resume lifecycle." }, { "name": "Backups", "description": "Backup records: list, inspect, and manually trigger a run." }, { "name": "Restore Jobs", "description": "One-click restore requests against a verified, restorable backup." }, { "name": "Agent Installs", "description": "Standalone-agent enrollment for push (bare-server) sources." }, { "name": "Audit", "description": "The workspace's append-only activity log." }, { "name": "Reports", "description": "Usage, storage-by-source, failures, and recent-activity summaries." } ], "security": [ [ { "bearerAuth": [], "tenantHeader": [] } ] ], "paths": { "/auth/login": { "post": { "tags": [ "Auth" ], "summary": "Exchange email + password for a bearer token", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" } } } } } }, "responses": { "201": { "description": "Token issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "example": "1|abcdef1234567890..." }, "token_type": { "type": "string", "example": "Bearer" } } } } } }, "422": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/auth/logout": { "post": { "tags": [ "Auth" ], "summary": "Revoke the caller's current token", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Logged out", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Logged out." } } } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/me": { "get": { "tags": [ "Auth" ], "summary": "The caller, and the tenants they may act for", "description": "Call this immediately after /auth/login. Every tenant-scoped endpoint requires an X-Tenant-Id header; this is where a client learns which value to send. Only ACTIVE tenants are listed, so any id returned here is one the caller can actually use.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The authenticated principal", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "is_admin": { "type": "boolean" }, "tenants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "operator", "viewer" ] } } } } } } } } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sources": { "get": { "tags": [ "Sources" ], "summary": "List this workspace's sources", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } } } } }, "201": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "203": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Sources" ], "summary": "Connect a new source", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "type", "channel" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "type": { "type": "string", "enum": [ "cpanel", "directadmin", "db", "files", "push", "postgresql", "wordpress", "manual" ] }, "channel": { "type": "string", "enum": [ "hosting", "reseller", "saas" ] }, "credentials": { "type": "object", "description": "Shape varies by `type` -- e.g. host/username/api_token for cpanel. Sealed at rest, never echoed back." } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Source" } } } }, "202": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "203": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "204": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "205": { "description": "Validation failed, or this plan's source limit was reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/sources/{source}": { "get": { "tags": [ "Sources" ], "summary": "Get a source", "parameters": [ { "name": "source", "in": "path", "required": true, "description": "Resource id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Source" } } } }, "201": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "203": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Sources" ], "summary": "Update a source", "parameters": [ { "name": "source", "in": "path", "required": true, "description": "Resource id", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "channel": { "type": "string", "enum": [ "hosting", "reseller", "saas" ] }, "status": { "type": "string", "enum": [ "active", "paused", "error" ] }, "credentials": { "type": "object" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Source" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "423": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "424": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "425": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Sources" ], "summary": "Delete a source", "parameters": [ { "name": "source", "in": "path", "required": true, "description": "Resource id", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "205": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "206": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "207": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sources/{source}/test-connection": { "post": { "tags": [ "Sources" ], "summary": "Verify a cPanel source's stored credentials still work", "parameters": [ { "name": "source", "in": "path", "required": true, "description": "The source's id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Ping result", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "422": { "description": "Not a cpanel source, or no credentials configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "424": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "425": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/storage-targets": { "get": { "tags": [ "Storage Targets" ], "summary": "List this workspace's storage targets", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StorageTarget" } } } } }, "201": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "203": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Storage Targets" ], "summary": "Add a storage target", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "kind", "provider", "bucket" ], "properties": { "kind": { "type": "string", "enum": [ "managed", "byo" ] }, "provider": { "type": "string", "enum": [ "s3", "b2", "wasabi", "gcs", "microsoft365" ] }, "bucket": { "type": "string", "maxLength": 255, "description": "The bucket name. For provider=microsoft365 this carries the Graph DRIVE ID of the SharePoint document library or OneDrive instead (e.g. b!...)." }, "prefix": { "type": "string", "maxLength": 255 }, "region": { "type": "string", "nullable": true, "description": "Required for b2 and wasabi (it is part of the endpoint hostname). Not used by microsoft365." }, "is_default": { "type": "boolean" }, "credentials": { "type": "object", "description": "BYO destination credentials, sealed at rest and never echoed back. S3-compatible providers: {access_key_id, secret_access_key, use_path_style_endpoint?}. provider=microsoft365 instead: {tenant_id, client_id, client_secret} from an app registration in the CUSTOMER's Entra tenant." } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageTarget" } } } }, "202": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "203": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "204": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/storage-targets/{storageTarget}": { "get": { "tags": [ "Storage Targets" ], "summary": "Get a storage target", "parameters": [ { "name": "storageTarget", "in": "path", "required": true, "description": "Resource id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageTarget" } } } }, "201": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "203": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Storage Targets" ], "summary": "Update a storage target", "parameters": [ { "name": "storageTarget", "in": "path", "required": true, "description": "Resource id", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "s3", "b2", "wasabi", "gcs", "microsoft365" ] }, "bucket": { "type": "string", "maxLength": 255 }, "prefix": { "type": "string" }, "region": { "type": "string", "nullable": true }, "is_default": { "type": "boolean" }, "credentials": { "type": "object" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageTarget" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "423": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "424": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "425": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Storage Targets" ], "summary": "Delete a storage target", "parameters": [ { "name": "storageTarget", "in": "path", "required": true, "description": "Resource id", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "205": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "206": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "207": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/storage-targets/{storageTarget}/verify": { "post": { "tags": [ "Storage Targets" ], "summary": "Verify a storage target's stored credentials actually reach its destination", "description": "Read-only probe of a key that is never written. A pass proves credentials, addressing and reachability. It does NOT prove write permission -- a read-only key or a Microsoft app registration consented for read but not write passes this and still fails at backup time.", "parameters": [ { "name": "storageTarget", "in": "path", "required": true, "description": "The storage target's id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verification passed", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "note": { "type": "string" } } } } } }, "422": { "description": "Verification failed; `error` names the operation and what the provider said", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string" } } } } } }, "423": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "424": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "425": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/schedules": { "get": { "tags": [ "Schedules" ], "summary": "List this workspace's schedules", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Schedule" } } } } }, "201": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "203": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Schedules" ], "summary": "Create a schedule", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "source_id", "storage_target_id", "frequency" ], "properties": { "source_id": { "type": "string" }, "storage_target_id": { "type": "string" }, "frequency": { "type": "string", "enum": [ "hourly", "daily", "weekly" ] }, "cron": { "type": "string", "nullable": true }, "retention_daily": { "type": "integer", "minimum": 0, "default": 7 }, "retention_weekly": { "type": "integer", "minimum": 0, "default": 4 }, "retention_monthly": { "type": "integer", "minimum": 0, "default": 12 }, "window_start": { "type": "string", "example": "02:00", "nullable": true }, "enabled": { "type": "boolean", "default": true } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Schedule" } } } }, "202": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "203": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "204": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "205": { "description": "Validation failed, this plan's job limit was reached, or the frequency isn't allowed on this plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/schedules/{schedule}": { "get": { "tags": [ "Schedules" ], "summary": "Get a schedule", "parameters": [ { "name": "schedule", "in": "path", "required": true, "description": "Resource id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Schedule" } } } }, "201": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "203": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Schedules" ], "summary": "Update a schedule", "parameters": [ { "name": "schedule", "in": "path", "required": true, "description": "Resource id", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "frequency": { "type": "string", "enum": [ "hourly", "daily", "weekly" ] }, "cron": { "type": "string", "nullable": true }, "retention_daily": { "type": "integer", "minimum": 0 }, "retention_weekly": { "type": "integer", "minimum": 0 }, "retention_monthly": { "type": "integer", "minimum": 0 }, "window_start": { "type": "string", "nullable": true }, "enabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Schedule" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "423": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "424": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "425": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Schedules" ], "summary": "Delete a schedule", "parameters": [ { "name": "schedule", "in": "path", "required": true, "description": "Resource id", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "205": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "206": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "207": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/schedules/{schedule}/pause": { "post": { "tags": [ "Schedules" ], "summary": "Pause a schedule", "parameters": [ { "name": "schedule", "in": "path", "required": true, "description": "Resource id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Schedule" } } } }, "201": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "203": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/schedules/{schedule}/resume": { "post": { "tags": [ "Schedules" ], "summary": "Resume a paused schedule", "parameters": [ { "name": "schedule", "in": "path", "required": true, "description": "Resource id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Schedule" } } } }, "201": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "203": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/backups": { "get": { "tags": [ "Backups" ], "summary": "List this workspace's backups (paginated)", "parameters": [ { "name": "source_id", "in": "query", "required": false, "description": "Filter to backups of one source.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of backups", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Backup" } }, "links": { "type": "object", "properties": { "first": { "type": "string", "nullable": true }, "last": { "type": "string", "nullable": true }, "prev": { "type": "string", "nullable": true }, "next": { "type": "string", "nullable": true } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } } } } } } } }, "201": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "203": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Backups" ], "summary": "Trigger a manual backup for a source", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "source_id" ], "properties": { "source_id": { "type": "string" }, "storage_target_id": { "type": "string", "description": "Defaults to the workspace's default storage target." } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Backup" } } } }, "202": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "203": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "204": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "205": { "description": "This source type can't be triggered manually, or no storage target is configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/backups/{backup}/legal-hold": { "post": { "tags": [ "Backups" ], "summary": "Place a legal hold on a backup", "description": "Preserves the backup past its retention. The pruner refuses to delete anything held. A shorter hold NEVER shortens a longer existing one: two matters can cover the same evidence and the shorter order does not cancel the longer. A reason is required -- an audit line saying only that a hold was placed answers nothing at discovery.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "until", "reason" ], "properties": { "until": { "type": "string", "format": "date-time" }, "reason": { "type": "string", "minLength": 3, "maxLength": 500 } } } } } }, "responses": { "200": { "description": "Hold placed", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "backup_id": { "type": "string", "format": "uuid" }, "locked_until": { "type": "string", "format": "date-time" } } } } } } } }, "403": { "description": "Not permitted for this role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Missing reason or a date in the past", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Backups" ], "summary": "Lift a legal hold", "description": "Refused with 403 when the workspace is in compliance mode: a hold that can be lifted by whoever an attacker compromised was never a guarantee.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 3, "maxLength": 500 } } } } } }, "responses": { "200": { "description": "Hold lifted", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Compliance mode, or not permitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/backups/search": { "get": { "tags": [ "Backups" ], "summary": "Find a file across the backup history", "description": "Answers \"which backup has this file, and when did it last change?\". Searches the CATALOG (artifact names, sizes, hashes), never content -- backups are sealed before they leave the customer machine. changed_since_previous marks the versions that actually differ, so a list of 40 identical copies with different dates becomes a short list of real revisions. Pruned backups are excluded: their bytes are gone, and offering them would imply a restore that cannot happen.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Substring of the file name. LIKE metacharacters are matched literally." }, { "name": "source_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Matching versions, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "backup_id": { "type": "string", "format": "uuid" }, "source_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "bytes": { "type": "integer" }, "taken_at": { "type": "string", "format": "date-time", "nullable": true }, "restorable": { "type": "boolean" }, "changed_since_previous": { "type": "boolean" } } } }, "truncated": { "type": "boolean" } } } } } }, "422": { "description": "Missing search term", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/backups/{backup}": { "get": { "tags": [ "Backups" ], "summary": "Get a backup", "parameters": [ { "name": "backup", "in": "path", "required": true, "description": "Resource id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Backup" } } } }, "201": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "203": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/restore-jobs": { "get": { "tags": [ "Restore Jobs" ], "summary": "List this workspace's restore jobs", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RestoreJob" } } } } }, "201": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "203": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Restore Jobs" ], "summary": "Request a one-click restore of a verified backup", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "backup_id", "mode" ], "properties": { "backup_id": { "type": "string" }, "mode": { "type": "string", "enum": [ "files", "db", "full", "to_new_location" ] }, "target_ref": { "type": "string", "nullable": true, "description": "Required only for mode=to_new_location." } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreJob" } } } }, "202": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "203": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "204": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "205": { "description": "The backup is not restorable yet (unverified or expired)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "206": { "description": "Restore isn't supported yet for this backup's source type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/restore-jobs/{restoreJob}": { "get": { "tags": [ "Restore Jobs" ], "summary": "Get a restore job", "parameters": [ { "name": "restoreJob", "in": "path", "required": true, "description": "Resource id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreJob" } } } }, "201": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "203": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent-installs": { "get": { "tags": [ "Agent Installs" ], "summary": "List this workspace's standalone-agent installs", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgentInstall" } } } } }, "201": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "203": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent-installs/enrollment-token": { "post": { "tags": [ "Agent Installs" ], "summary": "Issue a one-time enrollment token for a push (bare-server) source", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "source_id" ], "properties": { "source_id": { "type": "string" }, "label": { "type": "string", "nullable": true } } } } } }, "responses": { "201": { "description": "Token issued -- shown exactly once", "content": { "application/json": { "schema": { "type": "object", "properties": { "install_id": { "type": "string" }, "token": { "type": "string", "description": "One-time, 30-minute-TTL token. Never retrievable again after this response." }, "expires_at": { "type": "string", "format": "date-time" } } } } } }, "202": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "203": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "204": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent-installs/{agentInstall}/revoke": { "post": { "tags": [ "Agent Installs" ], "summary": "Revoke an agent install", "parameters": [ { "name": "agentInstall", "in": "path", "required": true, "description": "Resource id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentInstall" } } } }, "201": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "203": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/audit/export": { "get": { "tags": [ "Audit" ], "summary": "Export the audit trail with its tamper-evidence", "description": "Every entry ships with entry_hash and previous_hash, so an auditor holding the file can recompute the chain and needs to trust nothing we say. The response also declares the chain state at export time: if the log has been tampered with, chain.intact is false and chain.broken_at names the first bad entry. An export that hid its own break would launder the tampering.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Audit entries plus chain state", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "recorded_at": { "type": "string", "format": "date-time" }, "action": { "type": "string" }, "metadata": { "type": "object" }, "entry_hash": { "type": "string" }, "previous_hash": { "type": "string", "nullable": true } } } }, "chain": { "type": "object", "properties": { "intact": { "type": "boolean" }, "entries_checked": { "type": "integer" }, "broken_at": { "type": "string", "nullable": true }, "detail": { "type": "string", "nullable": true } } }, "truncated": { "type": "boolean" } } } } } }, "403": { "description": "No membership in the header tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/audit": { "get": { "tags": [ "Audit" ], "summary": "This workspace's append-only activity log (paginated)", "responses": { "200": { "description": "A page of audit entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEntry" } }, "links": { "type": "object", "properties": { "first": { "type": "string", "nullable": true }, "last": { "type": "string", "nullable": true }, "prev": { "type": "string", "nullable": true }, "next": { "type": "string", "nullable": true } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } } } } } } } }, "201": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "203": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reports/summary": { "get": { "tags": [ "Reports" ], "summary": "30-day backup summary", "responses": { "200": { "description": "Total/succeeded/failed backup counts, success rate, storage used, and a 14-day daily trend.", "content": { "application/json": { "schema": { "type": "object", "description": "Total/succeeded/failed backup counts, success rate, storage used, and a 14-day daily trend." } } } }, "201": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "203": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reports/storage": { "get": { "tags": [ "Reports" ], "summary": "Storage usage by source", "responses": { "200": { "description": "Bytes used and backup count per source, plus the workspace total.", "content": { "application/json": { "schema": { "type": "object", "description": "Bytes used and backup count per source, plus the workspace total." } } } }, "201": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "203": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reports/failures": { "get": { "tags": [ "Reports" ], "summary": "Failed backups", "responses": { "200": { "description": "Currently-failed backups grouped by source, plus the most recent failures.", "content": { "application/json": { "schema": { "type": "object", "description": "Currently-failed backups grouped by source, plus the most recent failures." } } } }, "201": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "203": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reports/activity": { "get": { "tags": [ "Reports" ], "summary": "Recent activity feed", "responses": { "200": { "description": "Audit-log and notification rows merged into one feed, newest first.", "content": { "application/json": { "schema": { "type": "object", "description": "Audit-log and notification rows merged into one feed, newest first." } } } }, "201": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Missing/invalid X-Tenant-Id, or the caller's role doesn't allow this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "203": { "description": "Unknown id, or it belongs to a different workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Sanctum personal access token", "description": "A personal access token created on the API Access page (Settings \u2192 API Access) or POST /auth/login. Sent as `Authorization: Bearer `." }, "tenantHeader": { "type": "apiKey", "in": "header", "name": "X-Tenant-Id", "description": "The workspace (tenant) id this request acts on. The authenticated user must have a Membership in this tenant, and the tenant must be active -- otherwise every endpoint below fails closed with 403, never a partial or cross-tenant result." } }, "schemas": { "Error": { "type": "object", "properties": { "message": { "type": "string" } } }, "ValidationError": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "Source": { "type": "object", "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "cpanel", "directadmin", "db", "files", "push", "postgresql", "wordpress", "manual" ] }, "channel": { "type": "string", "enum": [ "hosting", "reseller", "saas" ] }, "status": { "type": "string", "enum": [ "active", "paused", "error" ] }, "has_credentials": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "StorageTarget": { "type": "object", "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "managed", "byo" ] }, "provider": { "type": "string", "enum": [ "s3", "b2", "wasabi", "gcs" ] }, "bucket": { "type": "string" }, "prefix": { "type": "string", "nullable": true }, "region": { "type": "string", "nullable": true }, "is_default": { "type": "boolean" }, "has_credentials": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Schedule": { "type": "object", "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "source_id": { "type": "string" }, "storage_target_id": { "type": "string" }, "frequency": { "type": "string", "enum": [ "hourly", "daily", "weekly" ] }, "cron": { "type": "string", "nullable": true }, "retention_daily": { "type": "integer" }, "retention_weekly": { "type": "integer" }, "retention_monthly": { "type": "integer" }, "window_start": { "type": "string", "nullable": true }, "enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Backup": { "type": "object", "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "source_id": { "type": "string" }, "storage_target_id": { "type": "string" }, "agent_install_id": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "running", "uploaded", "verified", "failed", "expired" ] }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "finished_at": { "type": "string", "format": "date-time", "nullable": true }, "bytes": { "type": "integer" }, "manifest_sha256": { "type": "string", "nullable": true }, "verified_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "is_restorable": { "type": "boolean" }, "error": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "RestoreJob": { "type": "object", "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "backup_id": { "type": "string" }, "mode": { "type": "string", "enum": [ "files", "db", "full", "to_new_location" ] }, "status": { "type": "string", "enum": [ "pending", "running", "done", "failed" ] }, "initiated_by": { "type": "string", "nullable": true }, "target_ref": { "type": "string", "nullable": true }, "finished_at": { "type": "string", "format": "date-time", "nullable": true }, "error": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "AgentInstall": { "type": "object", "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "source_id": { "type": "string" }, "label": { "type": "string", "nullable": true }, "public_key_ref": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "active", "revoked" ] }, "enrolled_at": { "type": "string", "format": "date-time", "nullable": true }, "last_seen_at": { "type": "string", "format": "date-time", "nullable": true }, "agent_version": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AuditEntry": { "type": "object", "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "actor_type": { "type": "string", "enum": [ "user", "system" ] }, "actor_id": { "type": "string", "nullable": true }, "action": { "type": "string", "example": "backup.triggered" }, "subject_type": { "type": "string", "nullable": true }, "subject_id": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } } } }