Backups

List an environment's backups and obtain presigned download URLs for the database dump, filestore archive, and manifest — all over your API key.

Base URL: https://api.oec.sh/api/public/v1

Backup Status Values

Status	Meaning
`pending`	Queued, has not started yet.
`running`	Backup is being created.
`completed`	Backup finished and download URLs can be issued.
`failed`	Backup failed (see `error_message` on the backup object).
`cancelled`	Backup was cancelled.

Only completed backups can be downloaded.

Backup Type Values

Type	Meaning
`manual`	Triggered on demand from the dashboard or an admin action.
`scheduled`	Created by the environment's backup policy.
`pre_deploy`	Snapshot taken automatically before a deployment.

List Backups for an Environment

GET /environments/{env_id}/backups

Returns the environment's backups in reverse-chronological order.

Path Parameters

Parameter	Type	Description
`env_id`	UUID	The environment ID.

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status (`pending`, `running`, `completed`, `failed`, `cancelled`).
`backup_type`	string	Filter by type (`manual`, `scheduled`, `pre_deploy`).
`page`	integer	Page number, starts at 1. Default: `1`.
`page_size`	integer	Results per page. Min `1`, max `100`. Default: `20`.

Response — 200 OK

{
  "items": [
    {
      "id": "9c2ad33c-7e5d-4d23-8f8c-9c3c5dc6c1f1",
      "environment_id": "5a296461-9222-40da-91f5-9e912890dc1b",
      "status": "completed",
      "backup_type": "scheduled",
      "database_size": 432198144,
      "filestore_size": 211345920,
      "total_size": 643544064,
      "compressed_size": 218657280,
      "started_at": "2026-05-22T18:00:00Z",
      "completed_at": "2026-05-22T18:04:32Z",
      "duration_seconds": 272,
      "expires_at": "2026-06-21T18:04:32Z",
      "is_verified": true,
      "verified_at": "2026-05-22T18:05:01Z",
      "notes": null,
      "created_at": "2026-05-22T18:00:00Z"
    }
  ],
  "total": 31,
  "page": 1,
  "page_size": 20,
  "total_pages": 2
}

Example

# All completed backups for an environment
curl "https://api.oec.sh/api/public/v1/environments/YOUR_ENV_ID/backups?status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Download URLs

GET /backups/{backup_id}/download

Returns presigned URLs for the database dump, filestore archive, and manifest. The backup must be in completed status.

URLs are time-limited. Choose a TTL between 5 minutes and 24 hours via the expires_in parameter. Treat the URLs as one-time tokens — anyone with the URL can download the file until it expires.

Path Parameters

Parameter	Type	Description
`backup_id`	UUID	The backup ID.

Query Parameters

Parameter	Type	Description
`expires_in`	integer	URL validity in seconds. Min `300` (5 minutes), max `86400` (24 hours). Default: `3600` (1 hour).

Response — 200 OK

{
  "backup_id": "9c2ad33c-7e5d-4d23-8f8c-9c3c5dc6c1f1",
  "database_url": "https://storage.example.com/.../dump.sql?X-Amz-Signature=...",
  "filestore_url": "https://storage.example.com/.../filestore.tar.gz?X-Amz-Signature=...",
  "manifest_url": "https://storage.example.com/.../manifest.json?X-Amz-Signature=...",
  "expires_in": 3600,
  "expires_at": "2026-05-23T03:45:55Z",
  "use_streaming": false
}

When use_streaming is true, the storage provider cannot issue presigned URLs directly (e.g. some GCP configurations); the URLs returned will stream through the platform instead.

Errors

Status	Reason
`400`	Backup is not in `completed` status, so no downloadable files exist yet.
`404`	Backup not found, or the API key's scope does not cover this backup's organization or project.

Example

# Get URLs valid for 24 hours
curl "https://api.oec.sh/api/public/v1/backups/YOUR_BACKUP_ID/download?expires_in=86400" \
  -H "Authorization: Bearer YOUR_API_KEY"
 
# Then download with the returned URL (no auth header needed — the URL is presigned)
curl -o dump.sql "<database_url from response>"

Common Pattern: Latest Backup for an Environment

# 1. Find the most recent completed backup
BACKUP_ID=$(curl -s "https://api.oec.sh/api/public/v1/environments/YOUR_ENV_ID/backups?status=completed&page_size=1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  | jq -r '.items[0].id')
 
# 2. Get download URLs
curl "https://api.oec.sh/api/public/v1/backups/$BACKUP_ID/download?expires_in=3600" \
  -H "Authorization: Bearer YOUR_API_KEY"

Environments Deploy Actions