oCoreoCore Docs
API Reference

Backups

List backup safety holds in every organization

Platform administrators only. Lists live holds across organizations, optionally for one environment (which may be archived). A hold on a shared physical host blocks every backup on that host until it is resolved.

GET
/admin/backup-holds

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Query Parameters

environment_idstring

Environment UUID

Format: "uuid"
pageinteger

Page number

per_pageinteger

Page size

curl -X GET "//api.ocore.dev/api/admin/backup-holds?environment_id=497f6eca-6276-4993-bfeb-53cbbbba6f08&page=0&per_page=0" \
  -H "Authorization: <token>"

OK

{
  "holds": [
    {
      "environmentId": "19f5cc2e-7657-437a-9268-83cd3d563563",
      "heldAt": "2019-08-24T14:15:22Z",
      "jobId": "9007199254740995",
      "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
      "remoteMarkedAt": "2019-08-24T14:15:22Z",
      "resolutionAvailable": true,
      "resolutionUnavailableReason": "host_identity_unverified",
      "status": "in_progress"
    }
  ],
  "total": 0
}

Verify and release a backup hold in any organization

Platform administrators only, for holds of archived environments or holds blocking a shared host. The same proof as the tenant endpoint is required; the audit entry is written to the hold's organization.

POST
/admin/backup-holds/{env_id}/{job_id}/resolve

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Request Body

application/jsonRequired

Explicit cleanup confirmation

confirmStopAndCleanupboolean

Path Parameters

env_idRequiredstring

Environment UUID

Format: "uuid"
job_idRequiredstring

Backup River job ID (decimal int64, as a string)

curl -X POST "//api.ocore.dev/api/admin/backup-holds/497f6eca-6276-4993-bfeb-53cbbbba6f08/<string>/resolve" \
  -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "confirmStopAndCleanup": true
  }'

OK

{
  "jobId": "string",
  "message": "string"
}

List hosts that cannot take a new backup

Platform administrators only. Lists environments whose backups wait on their host although no hold row backs the wait: the host inventory is not clear (for example a host-operation record no operation of the organization owns, which may be another organization's on a shared host), or another hold on the host is overdue. Each entry names the server, the kind, and the host job directory or operation to check. An entry clears automatically once the next backup finds the host clear.

GET
/admin/backup-host-blocks

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Query Parameters

pageinteger

Page number

per_pageinteger

Page size

curl -X GET "//api.ocore.dev/api/admin/backup-host-blocks?page=0&per_page=0" \
  -H "Authorization: <token>"

OK

{
  "blocks": [
    {
      "alertId": "a9367074-b5c3-42c4-9be4-be129f43577e",
      "environmentId": "19f5cc2e-7657-437a-9268-83cd3d563563",
      "jobDirId": "-1000000000000000000",
      "kind": "unverified_host_inventory",
      "operationType": "string",
      "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
      "serverHost": "string",
      "serverId": "10d2345a-e43d-463d-830e-4f5b19b60d41",
      "serverName": "string",
      "since": "2019-08-24T14:15:22Z"
    }
  ],
  "total": 0
}

List backup alerts

Returns backup alerts for the organization, optionally filtered by dismissed status.

GET
/backup-alerts

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Query Parameters

is_dismissedboolean

Filter by dismissed status (default false)

limitinteger

Results per page (default 50, max 100)

curl -X GET "//api.ocore.dev/api/backup-alerts?is_dismissed=true&limit=0" \
  -H "Authorization: <token>"

OK

{
  "alerts": [
    {
      "alertType": "string",
      "backupId": "string",
      "createdAt": "string",
      "environmentId": "string",
      "id": "string",
      "isRead": true,
      "message": "string",
      "severity": "string",
      "updatedAt": "string"
    }
  ],
  "total": 0
}

Get backup alert count

Returns the count of unread and undismissed backup alerts for the organization.

GET
/backup-alerts/count

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

curl -X GET "//api.ocore.dev/api/backup-alerts/count" \
  -H "Authorization: <token>"

OK

{
  "undismissed": 0,
  "unread": 0
}

Dismiss a backup alert

Marks a backup alert as dismissed so it no longer appears in active alerts.

POST
/backup-alerts/{id}/dismiss

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Path Parameters

idRequiredstring

Alert UUID

curl -X POST "//api.ocore.dev/api/backup-alerts/<string>/dismiss" \
  -H "Authorization: <token>"

OK

{
  "message": "string"
}

Mark a backup alert as read

Marks a backup alert as read without dismissing it.

POST
/backup-alerts/{id}/read

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Path Parameters

idRequiredstring

Alert UUID

curl -X POST "//api.ocore.dev/api/backup-alerts/<string>/read" \
  -H "Authorization: <token>"

OK

{
  "message": "string"
}

Get cron expression presets

Returns a list of common cron expression presets for backup scheduling.

GET
/backup-schedule/presets

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

curl -X GET "//api.ocore.dev/api/backup-schedule/presets" \
  -H "Authorization: <token>"

OK

[
  {
    "cron": "string",
    "label": "string"
  }
]

Get backup details

Returns a single backup's details including size, status, and destination info.

GET
/backups/{id}

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Path Parameters

idRequiredstring

Backup UUID

curl -X GET "//api.ocore.dev/api/backups/<string>" \
  -H "Authorization: <token>"

OK

{
  "backupType": "string",
  "completedAt": "string",
  "configChecksum": "string",
  "createdAt": "string",
  "dbChecksum": "string",
  "environmentId": "string",
  "environmentName": "string",
  "environmentType": "string",
  "errorMessage": "string",
  "filestoreChecksum": "string",
  "gfsTiers": [
    "string"
  ],
  "id": "string",
  "recoveryEvidence": {
    "artifactChecksums": {
      "property1": "string",
      "property2": "string"
    },
    "artifactPaths": {
      "property1": "string",
      "property2": "string"
    },
    "blockingSteps": [
      "string"
    ],
    "canWriteCleanSuccess": true,
    "missingEvidence": [
      "string"
    ],
    "missingSteps": [
      "string"
    ],
    "operation": "string",
    "optionalFailedSteps": [
      "string"
    ],
    "progress": {},
    "reason": "string",
    "remoteCopyState": "string",
    "requiredSteps": [
      "string"
    ],
    "status": "string",
    "whyGreen": [
      "string"
    ],
    "whyNotGreen": [
      "string"
    ]
  },
  "remotePaths": {
    "property1": "string",
    "property2": "string"
  },
  "sizeBytes": 0,
  "startedAt": "string",
  "status": "string"
}

Delete a backup

Marks a backup for deletion and enqueues async cleanup from all storage destinations.

DELETE
/backups/{id}

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Path Parameters

idRequiredstring

Backup UUID

curl -X DELETE "//api.ocore.dev/api/backups/<string>" \
  -H "Authorization: <token>"

OK

{
  "message": "Backup deleted"
}

Stream backup progress (SSE)

Streams backup progress events as Server-Sent Events until the backup completes or fails.

GET
/backups/{id}/progress

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Path Parameters

idRequiredstring

Backup UUID

curl -X GET "//api.ocore.dev/api/backups/<string>/progress" \
  -H "Authorization: <token>"

SSE stream of backup progress

Trigger a backup restore

Validates the restore target and enqueues an asynchronous restore job. Requests with pitrTimestamp are rejected with PITR_UNAVAILABLE until physical base-backup metadata is available. A production target environment also requires the restore:production permission (Owner and Admin); manage:environments alone is refused with 403.

POST
/backups/{id}/restore

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Request Body

application/jsonRequired

Restore target configuration

backupIdstring
newEnvironmentNamestring

reserved for disabled targetType="new"

pitrTimestampstring

optional point-in-time recovery target

targetEnvironmentIdstring

required if targetType="other"

targetTypestring

"same" or "other" ("new" is disabled until orchestration exists)

Path Parameters

idRequiredstring

Backup UUID

curl -X POST "//api.ocore.dev/api/backups/<string>/restore" \
  -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "backupId": "string",
    "newEnvironmentName": "string",
    "pitrTimestamp": "string",
    "targetEnvironmentId": "string",
    "targetType": "string"
  }'

Accepted

{
  "backupId": "string",
  "message": "string",
  "operationId": "string",
  "restoreLogId": "string",
  "status": "string",
  "target": "string",
  "targetEnvironmentId": "string",
  "targetInstanceId": "string"
}

Stream restore progress (SSE)

Streams restore progress events as Server-Sent Events until the restore completes or fails.

GET
/backups/{id}/restore/progress

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Path Parameters

idRequiredstring

Backup UUID

curl -X GET "//api.ocore.dev/api/backups/<string>/restore/progress" \
  -H "Authorization: <token>"

SSE stream of restore progress

List unresolved backup safety holds

Returns running and verification-required holds for one organization-owned environment, including archived environments. Job IDs are strings to preserve int64 precision.

GET
/environments/{env_id}/backup-holds

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Path Parameters

env_idRequiredstring

Environment UUID

Format: "uuid"

Query Parameters

pageinteger

Page number

per_pageinteger

Page size

curl -X GET "//api.ocore.dev/api/environments/497f6eca-6276-4993-bfeb-53cbbbba6f08/backup-holds?page=0&per_page=0" \
  -H "Authorization: <token>"

OK

{
  "holds": [
    {
      "environmentId": "19f5cc2e-7657-437a-9268-83cd3d563563",
      "heldAt": "2019-08-24T14:15:22Z",
      "jobId": "9007199254740995",
      "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
      "remoteMarkedAt": "2019-08-24T14:15:22Z",
      "resolutionAvailable": true,
      "resolutionUnavailableReason": "host_identity_unverified",
      "status": "in_progress"
    }
  ],
  "total": 0
}

Verify and release an orphaned backup hold

Requires restore:production permission, an explicit confirmation, a terminal River job past its worst-case lifetime, and proof the host has no active dump or transfer readers. Staging cleanup and an audit entry are required before the hold is released. Unreachable or ambiguous hosts remain blocked; a 409 names the reason and, where useful, the host job directory or operation to check.

POST
/environments/{env_id}/backup-holds/{job_id}/resolve

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Request Body

application/jsonRequired

Explicit cleanup confirmation

confirmStopAndCleanupboolean

Path Parameters

env_idRequiredstring

Environment UUID

Format: "uuid"
job_idRequiredstring

Backup River job ID (decimal int64, as a string)

curl -X POST "//api.ocore.dev/api/environments/497f6eca-6276-4993-bfeb-53cbbbba6f08/backup-holds/<string>/resolve" \
  -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "confirmStopAndCleanup": true
  }'

OK

{
  "jobId": "string",
  "message": "string"
}

Get backup schedule

Returns the current backup schedule for the environment, or 404 if no schedule exists.

GET
/environments/{env_id}/backup-schedule

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Path Parameters

env_idRequiredstring

Environment UUID

curl -X GET "//api.ocore.dev/api/environments/<string>/backup-schedule" \
  -H "Authorization: <token>"

OK

{
  "dbCron": "string",
  "dbFrequency": "string",
  "destinationIds": [
    "string"
  ],
  "enabled": true,
  "environmentId": "string",
  "fullCron": "string",
  "fullFrequency": "string",
  "id": "string",
  "nextDbBackupAt": "string",
  "nextFullBackupAt": "string",
  "paused": true,
  "retainDaily": 0,
  "retainDailyDays": 0,
  "retainDbDaily": 0,
  "retainDbHourly": 0,
  "retainDbMonthly": 0,
  "retainDbWeekly": 0,
  "retainFullDaily": 0,
  "retainFullHourly": 0,
  "retainFullMonthly": 0,
  "retainFullWeekly": 0,
  "retainHourly": 0,
  "retainHourlyDays": 0,
  "retainMonthly": 0,
  "retainMonthlyDays": 0,
  "retainWeekly": 0,
  "retainWeeklyDays": 0,
  "timezone": "string",
  "walApplyPending": true,
  "walArchiveMessage": "string",
  "walArchiveStatus": "string",
  "walEnabled": true,
  "walLastArchivedAt": "string",
  "walObservedAt": "string",
  "walRetentionDays": 0
}

Create or update backup schedule

Creates or updates the automated backup schedule for the environment including frequency, retention, and PITR settings.

PUT
/environments/{env_id}/backup-schedule

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Request Body

application/jsonRequired

Schedule configuration

dbCronstring
dbFrequencystring
destinationIdsarray<string>
enabledboolean
fullCronstring
fullFrequencystring
pausedboolean
retainDailyinteger
retainDailyDaysinteger
retainDbDailyinteger
retainDbHourlyinteger
retainDbMonthlyinteger
retainDbWeeklyinteger
retainFullDailyinteger
retainFullHourlyinteger
retainFullMonthlyinteger
retainFullWeeklyinteger
retainHourlyinteger
retainHourlyDaysinteger
retainMonthlyinteger
retainMonthlyDaysinteger
retainWeeklyinteger
retainWeeklyDaysinteger
timezonestring
walEnabledboolean
walRetentionDaysinteger

Path Parameters

env_idRequiredstring

Environment UUID

curl -X PUT "//api.ocore.dev/api/environments/<string>/backup-schedule" \
  -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "dbCron": "string",
    "dbFrequency": "string",
    "destinationIds": [
      "string"
    ],
    "enabled": true,
    "fullCron": "string",
    "fullFrequency": "string",
    "paused": true,
    "retainDaily": 0,
    "retainDailyDays": 0,
    "retainDbDaily": 0,
    "retainDbHourly": 0,
    "retainDbMonthly": 0,
    "retainDbWeekly": 0,
    "retainFullDaily": 0,
    "retainFullHourly": 0,
    "retainFullMonthly": 0,
    "retainFullWeekly": 0,
    "retainHourly": 0,
    "retainHourlyDays": 0,
    "retainMonthly": 0,
    "retainMonthlyDays": 0,
    "retainWeekly": 0,
    "retainWeeklyDays": 0,
    "timezone": "string",
    "walEnabled": true,
    "walRetentionDays": 0
  }'

OK

{
  "dbCron": "string",
  "dbFrequency": "string",
  "destinationIds": [
    "string"
  ],
  "enabled": true,
  "environmentId": "string",
  "fullCron": "string",
  "fullFrequency": "string",
  "id": "string",
  "nextDbBackupAt": "string",
  "nextFullBackupAt": "string",
  "paused": true,
  "retainDaily": 0,
  "retainDailyDays": 0,
  "retainDbDaily": 0,
  "retainDbHourly": 0,
  "retainDbMonthly": 0,
  "retainDbWeekly": 0,
  "retainFullDaily": 0,
  "retainFullHourly": 0,
  "retainFullMonthly": 0,
  "retainFullWeekly": 0,
  "retainHourly": 0,
  "retainHourlyDays": 0,
  "retainMonthly": 0,
  "retainMonthlyDays": 0,
  "retainWeekly": 0,
  "retainWeeklyDays": 0,
  "timezone": "string",
  "walApplyPending": true,
  "walArchiveMessage": "string",
  "walArchiveStatus": "string",
  "walEnabled": true,
  "walLastArchivedAt": "string",
  "walObservedAt": "string",
  "walRetentionDays": 0
}

Preview retention policy impact

Simulates retention policy changes and returns which backups would be deleted.

POST
/environments/{env_id}/backup-schedule/retention-preview

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Request Body

application/jsonRequired

Proposed retention settings

retainDailyinteger
retainDailyDaysinteger
retainDbDailyinteger
retainDbHourlyinteger
retainDbMonthlyinteger
retainDbWeeklyinteger
retainFullDailyinteger
retainFullHourlyinteger
retainFullMonthlyinteger
retainFullWeeklyinteger
retainHourlyinteger
retainHourlyDaysinteger
retainMonthlyinteger
retainMonthlyDaysinteger
retainWeeklyinteger
retainWeeklyDaysinteger

Path Parameters

env_idRequiredstring

Environment UUID

curl -X POST "//api.ocore.dev/api/environments/<string>/backup-schedule/retention-preview" \
  -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "retainDaily": 0,
    "retainDailyDays": 0,
    "retainDbDaily": 0,
    "retainDbHourly": 0,
    "retainDbMonthly": 0,
    "retainDbWeekly": 0,
    "retainFullDaily": 0,
    "retainFullHourly": 0,
    "retainFullMonthly": 0,
    "retainFullWeekly": 0,
    "retainHourly": 0,
    "retainHourlyDays": 0,
    "retainMonthly": 0,
    "retainMonthlyDays": 0,
    "retainWeekly": 0,
    "retainWeeklyDays": 0
  }'

OK

{
  "items": [
    {
      "backupId": "string",
      "backupType": "string",
      "createdAt": "string",
      "gfsTiers": [
        "string"
      ],
      "reason": "string",
      "sizeBytes": 0
    }
  ],
  "totalSizeBytes": 0
}

List environment backups

Returns backups for the environment with optional status/type filters and pagination.

GET
/environments/{env_id}/backups

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Path Parameters

env_idRequiredstring

Environment UUID

Query Parameters

statusstring

Filter by backup status

typestring

Filter by backup type

limitinteger

Results per page (default 20, max 100)

offsetinteger

Offset for pagination

curl -X GET "//api.ocore.dev/api/environments/<string>/backups?status=%3Cstring%3E&type=%3Cstring%3E&limit=0&offset=0" \
  -H "Authorization: <token>"

OK

{
  "backups": [
    {
      "backupType": "string",
      "completedAt": "string",
      "configChecksum": "string",
      "createdAt": "string",
      "dbChecksum": "string",
      "environmentId": "string",
      "environmentName": "string",
      "environmentType": "string",
      "errorMessage": "string",
      "filestoreChecksum": "string",
      "gfsTiers": [
        "string"
      ],
      "id": "string",
      "recoveryEvidence": {
        "artifactChecksums": {
          "property1": "string",
          "property2": "string"
        },
        "artifactPaths": {
          "property1": "string",
          "property2": "string"
        },
        "blockingSteps": [
          "string"
        ],
        "canWriteCleanSuccess": true,
        "missingEvidence": [
          "string"
        ],
        "missingSteps": [
          "string"
        ],
        "operation": "string",
        "optionalFailedSteps": [
          "string"
        ],
        "progress": {},
        "reason": "string",
        "remoteCopyState": "string",
        "requiredSteps": [
          "string"
        ],
        "status": "string",
        "whyGreen": [
          "string"
        ],
        "whyNotGreen": [
          "string"
        ]
      },
      "remotePaths": {
        "property1": "string",
        "property2": "string"
      },
      "sizeBytes": 0,
      "startedAt": "string",
      "status": "string"
    }
  ],
  "total": 0
}

Trigger a manual backup

Creates a backup record and enqueues an asynchronous backup job for the environment.

POST
/environments/{env_id}/backups

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Request Body

application/jsonRequired

Backup configuration (type, label, destination)

typestring

"db", "full" or "base" (physical base backup for point-in-time recovery; needs WAL archiving)

Path Parameters

env_idRequiredstring

Environment UUID

curl -X POST "//api.ocore.dev/api/environments/<string>/backups" \
  -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "db"
  }'

Accepted

{
  "backupId": "string",
  "message": "string"
}

Get PITR coverage

Returns what point-in-time recovery can reach: the recoverable ranges formed by physical base backups and continuous, cluster-keyed archived WAL, the base backups that anchor them, and explicit gaps where WAL is missing. available=false with reasonCode=physical_base_metadata_unavailable (no base backup yet) or reasonCode=wal_coverage_unavailable (WAL does not yet make a base consistent). Logical pg_dump backups are never reported as bases.

GET
/environments/{env_id}/pitr-coverage

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Path Parameters

env_idRequiredstring

Environment UUID

curl -X GET "//api.ocore.dev/api/environments/<string>/pitr-coverage" \
  -H "Authorization: <token>"

OK

{
  "available": true,
  "baseBackups": [
    {
      "backupId": "eb7cea43-10b2-42dd-8819-ab9aed37565f",
      "timestamp": "2019-08-24T14:15:22Z"
    }
  ],
  "earliestRecoverable": "2019-08-24T14:15:22Z",
  "gaps": [
    {
      "end": "2019-08-24T14:15:22Z",
      "start": "2019-08-24T14:15:22Z"
    }
  ],
  "latestRecoverable": "2019-08-24T14:15:22Z",
  "message": "string",
  "reasonCode": "string",
  "walRanges": [
    {
      "end": "2019-08-24T14:15:22Z",
      "start": "2019-08-24T14:15:22Z"
    }
  ]
}

List point-in-time recoveries

Returns the environment's 20 most recent point-in-time recoveries.

GET
/environments/{env_id}/pitr-restores

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Path Parameters

env_idRequiredstring

Environment UUID

curl -X GET "//api.ocore.dev/api/environments/<string>/pitr-restores" \
  -H "Authorization: <token>"

OK

{
  "restores": [
    {
      "baseBackupId": "string",
      "createdAt": "string",
      "databaseName": "string",
      "environmentId": "string",
      "errorMessage": "string",
      "id": "string",
      "previousDatabaseName": "string",
      "promotedAt": "string",
      "recoveredLastCommitAt": "string",
      "recoveryStoppedBeforeAt": "string",
      "resolution": {
        "activeColor": "string",
        "configuredDatabase": "string",
        "databases": [
          {
            "acceptsConnections": true,
            "identity": "string",
            "name": "string",
            "oid": 0,
            "role": "string"
          }
        ],
        "error": "string",
        "inspectedAt": "string",
        "keepLiveAllowed": true,
        "keepLiveReason": "string",
        "liveMatchesRecovery": true,
        "liveOid": 0,
        "maintenanceHeld": true,
        "originalOid": 0,
        "previousCandidate": "string",
        "promotionMarker": true,
        "recoveredOid": 0,
        "restorePreviousAllowed": true,
        "restorePreviousReason": "string"
      },
      "resolvedAs": "string",
      "status": "string",
      "targetTime": "string",
      "updatedAt": "string",
      "verifiedTableCount": 0
    }
  ]
}

Start a point-in-time recovery

Recovers the environment's database to targetTime in a separate scratch PostgreSQL cluster on the same server: a physical base backup plus archived WAL, replayed until just before the first transaction after targetTime. The live database is not touched; promote the verified recovery to replace it. Refused (PITR_TARGET_NOT_COVERED) when no base backup with continuous WAL reaches targetTime, and while another recovery of the environment is active or another operation holds the instance.

POST
/environments/{env_id}/pitr-restores

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Request Body

application/jsonRequired

Target time

targetTimeRequiredstring

Path Parameters

env_idRequiredstring

Environment UUID

curl -X POST "//api.ocore.dev/api/environments/<string>/pitr-restores" \
  -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "targetTime": "string"
  }'

Accepted

{
  "baseBackupId": "string",
  "createdAt": "string",
  "databaseName": "string",
  "environmentId": "string",
  "errorMessage": "string",
  "id": "string",
  "previousDatabaseName": "string",
  "promotedAt": "string",
  "recoveredLastCommitAt": "string",
  "recoveryStoppedBeforeAt": "string",
  "resolution": {
    "activeColor": "string",
    "configuredDatabase": "string",
    "databases": [
      {
        "acceptsConnections": true,
        "identity": "string",
        "name": "string",
        "oid": 0,
        "role": "string"
      }
    ],
    "error": "string",
    "inspectedAt": "string",
    "keepLiveAllowed": true,
    "keepLiveReason": "string",
    "liveMatchesRecovery": true,
    "liveOid": 0,
    "maintenanceHeld": true,
    "originalOid": 0,
    "previousCandidate": "string",
    "promotionMarker": true,
    "recoveredOid": 0,
    "restorePreviousAllowed": true,
    "restorePreviousReason": "string"
  },
  "resolvedAs": "string",
  "status": "string",
  "targetTime": "string",
  "updatedAt": "string",
  "verifiedTableCount": 0
}

Get a point-in-time recovery

GET
/environments/{env_id}/pitr-restores/{restore_id}

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Path Parameters

env_idRequiredstring

Environment UUID

restore_idRequiredstring

Recovery UUID

curl -X GET "//api.ocore.dev/api/environments/<string>/pitr-restores/<string>" \
  -H "Authorization: <token>"

OK

{
  "baseBackupId": "string",
  "createdAt": "string",
  "databaseName": "string",
  "environmentId": "string",
  "errorMessage": "string",
  "id": "string",
  "previousDatabaseName": "string",
  "promotedAt": "string",
  "recoveredLastCommitAt": "string",
  "recoveryStoppedBeforeAt": "string",
  "resolution": {
    "activeColor": "string",
    "configuredDatabase": "string",
    "databases": [
      {
        "acceptsConnections": true,
        "identity": "string",
        "name": "string",
        "oid": 0,
        "role": "string"
      }
    ],
    "error": "string",
    "inspectedAt": "string",
    "keepLiveAllowed": true,
    "keepLiveReason": "string",
    "liveMatchesRecovery": true,
    "liveOid": 0,
    "maintenanceHeld": true,
    "originalOid": 0,
    "previousCandidate": "string",
    "promotionMarker": true,
    "recoveredOid": 0,
    "restorePreviousAllowed": true,
    "restorePreviousReason": "string"
  },
  "resolvedAs": "string",
  "status": "string",
  "targetTime": "string",
  "updatedAt": "string",
  "verifiedTableCount": 0
}

Discard or cancel a point-in-time recovery

Cancels a queued or running recovery, or discards a verified or failed one, and removes its scratch cluster and staged data from the server. The live database is not touched.

POST
/environments/{env_id}/pitr-restores/{restore_id}/discard

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Path Parameters

env_idRequiredstring

Environment UUID

restore_idRequiredstring

Recovery UUID

curl -X POST "//api.ocore.dev/api/environments/<string>/pitr-restores/<string>/discard" \
  -H "Authorization: <token>"

Accepted

{
  "baseBackupId": "string",
  "createdAt": "string",
  "databaseName": "string",
  "environmentId": "string",
  "errorMessage": "string",
  "id": "string",
  "previousDatabaseName": "string",
  "promotedAt": "string",
  "recoveredLastCommitAt": "string",
  "recoveryStoppedBeforeAt": "string",
  "resolution": {
    "activeColor": "string",
    "configuredDatabase": "string",
    "databases": [
      {
        "acceptsConnections": true,
        "identity": "string",
        "name": "string",
        "oid": 0,
        "role": "string"
      }
    ],
    "error": "string",
    "inspectedAt": "string",
    "keepLiveAllowed": true,
    "keepLiveReason": "string",
    "liveMatchesRecovery": true,
    "liveOid": 0,
    "maintenanceHeld": true,
    "originalOid": 0,
    "previousCandidate": "string",
    "promotionMarker": true,
    "recoveredOid": 0,
    "restorePreviousAllowed": true,
    "restorePreviousReason": "string"
  },
  "resolvedAs": "string",
  "status": "string",
  "targetTime": "string",
  "updatedAt": "string",
  "verifiedTableCount": 0
}

Promote a verified point-in-time recovery

Replaces the live database with the verified recovery. Requires the restore:production permission (Owner and Admin), confirmOverwrite=true and confirmDatabaseName equal to the recovery's database name. Refused unless the recovery is verified and the live database (color and name) is still the one bound when the recovery was requested. The staged decrypted data is removed first; the host must have room for the dump and a temporary copy, and the live archiver must be healthy. The recovered dump is restored beside the live database with --exit-on-error and must reproduce the recovery's exact row-count fingerprint; only then is the live database fenced and renamed aside (kept, named in previousDatabaseName) and Odoo restarted. Files in the filestore are not rewound.

POST
/environments/{env_id}/pitr-restores/{restore_id}/promote

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Request Body

application/jsonRequired

Confirmation

confirmDatabaseNamestring
confirmOverwriteboolean

Path Parameters

env_idRequiredstring

Environment UUID

restore_idRequiredstring

Recovery UUID

curl -X POST "//api.ocore.dev/api/environments/<string>/pitr-restores/<string>/promote" \
  -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "confirmDatabaseName": "string",
    "confirmOverwrite": true
  }'

Accepted

{
  "baseBackupId": "string",
  "createdAt": "string",
  "databaseName": "string",
  "environmentId": "string",
  "errorMessage": "string",
  "id": "string",
  "previousDatabaseName": "string",
  "promotedAt": "string",
  "recoveredLastCommitAt": "string",
  "recoveryStoppedBeforeAt": "string",
  "resolution": {
    "activeColor": "string",
    "configuredDatabase": "string",
    "databases": [
      {
        "acceptsConnections": true,
        "identity": "string",
        "name": "string",
        "oid": 0,
        "role": "string"
      }
    ],
    "error": "string",
    "inspectedAt": "string",
    "keepLiveAllowed": true,
    "keepLiveReason": "string",
    "liveMatchesRecovery": true,
    "liveOid": 0,
    "maintenanceHeld": true,
    "originalOid": 0,
    "previousCandidate": "string",
    "promotionMarker": true,
    "recoveredOid": 0,
    "restorePreviousAllowed": true,
    "restorePreviousReason": "string"
  },
  "resolvedAs": "string",
  "status": "string",
  "targetTime": "string",
  "updatedAt": "string",
  "verifiedTableCount": 0
}

Inspect or resolve a point-in-time promotion that needs attention

For a recovery in needs_attention (a promotion that stopped mid-swap). Requires restore:production (Owner and Admin). Databases are identified by OID: before its first rename the swap records the OIDs of the original live database and of the recovered copy. action=inspect queues a read-only inspection of the server: the database, _restore_tmp and pre_restore* with their OIDs and whether they accept connections, the promotion's OID record, what odoo.conf points at, and whether maintenance mode is on; the result appears as the recovery's resolution, with the resolutions it allows. action=keep_live (the live database is correct) clears its fence, checks it accepts connections, restarts Odoo, lifts maintenance and releases the lock; allowed only when odoo.conf still names the recovery's database, it exists, and it is the original or the recovered copy. action=restore_previous renames the original (by OID, under a _pre_restore name) back to the live name under the swap's fence, moving a recovered copy in the live name to a fresh _pre_restore name, then restarts Odoo and lifts maintenance; allowed only when the live name is absent or is the recovered copy (by OID). Both need confirmDatabaseName and an inspection from the last 15 minutes, and refuse if a fresh inspection differs from it. action=dismiss (with confirmDatabaseName) closes the recovery without touching any database, removing the scratch copy and alerts; only once the promotion's hold on the instance has been released (PITR_HOLD_ACTIVE otherwise). Anything ambiguous is refused with the inspected state.

POST
/environments/{env_id}/pitr-restores/{restore_id}/resolve

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Request Body

application/jsonRequired

Resolution

actionstring
confirmDatabaseNamestring

Path Parameters

env_idRequiredstring

Environment UUID

restore_idRequiredstring

Recovery UUID

curl -X POST "//api.ocore.dev/api/environments/<string>/pitr-restores/<string>/resolve" \
  -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "string",
    "confirmDatabaseName": "string"
  }'

Accepted

{
  "baseBackupId": "string",
  "createdAt": "string",
  "databaseName": "string",
  "environmentId": "string",
  "errorMessage": "string",
  "id": "string",
  "previousDatabaseName": "string",
  "promotedAt": "string",
  "recoveredLastCommitAt": "string",
  "recoveryStoppedBeforeAt": "string",
  "resolution": {
    "activeColor": "string",
    "configuredDatabase": "string",
    "databases": [
      {
        "acceptsConnections": true,
        "identity": "string",
        "name": "string",
        "oid": 0,
        "role": "string"
      }
    ],
    "error": "string",
    "inspectedAt": "string",
    "keepLiveAllowed": true,
    "keepLiveReason": "string",
    "liveMatchesRecovery": true,
    "liveOid": 0,
    "maintenanceHeld": true,
    "originalOid": 0,
    "previousCandidate": "string",
    "promotionMarker": true,
    "recoveredOid": 0,
    "restorePreviousAllowed": true,
    "restorePreviousReason": "string"
  },
  "resolvedAs": "string",
  "status": "string",
  "targetTime": "string",
  "updatedAt": "string",
  "verifiedTableCount": 0
}

Apply WAL archiving to the running database

Recreates only the environment's PostgreSQL container so its archive_mode matches the schedule's walEnabled. PostgreSQL restarts: Odoo loses its database for roughly 10 to 60 seconds. Odoo's configuration and container are not changed. Requires confirmDatabaseRestart; refused while another operation holds the instance, and refused when enabling without a backup destination.

POST
/environments/{env_id}/wal-archiving/apply

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Request Body

application/jsonRequired

Confirmation

confirmDatabaseRestartboolean

Path Parameters

env_idRequiredstring

Environment UUID

curl -X POST "//api.ocore.dev/api/environments/<string>/wal-archiving/apply" \
  -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "confirmDatabaseRestart": true
  }'

Accepted

{
  "jobId": 0,
  "message": "string"
}

List environment restore logs

Returns restore logs where the target or source environment matches the given environment.

GET
/environments/{environmentId}/restore-logs

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Path Parameters

environmentIdRequiredstring

Environment UUID

curl -X GET "//api.ocore.dev/api/environments/<string>/restore-logs" \
  -H "Authorization: <token>"

OK

{
  "restoreLogs": [
    {
      "backupId": "string",
      "completedAt": "string",
      "createdAt": "string",
      "errorMessage": "string",
      "id": "string",
      "performedBy": "string",
      "recoveryEvidence": {
        "artifactChecksums": {
          "property1": "string",
          "property2": "string"
        },
        "artifactPaths": {
          "property1": "string",
          "property2": "string"
        },
        "blockingSteps": [
          "string"
        ],
        "canWriteCleanSuccess": true,
        "missingEvidence": [
          "string"
        ],
        "missingSteps": [
          "string"
        ],
        "operation": "string",
        "optionalFailedSteps": [
          "string"
        ],
        "progress": {},
        "reason": "string",
        "remoteCopyState": "string",
        "requiredSteps": [
          "string"
        ],
        "status": "string",
        "whyGreen": [
          "string"
        ],
        "whyNotGreen": [
          "string"
        ]
      },
      "sourceEnvironmentId": "string",
      "sourceEnvironmentName": "string",
      "startedAt": "string",
      "status": "string",
      "targetEnvironmentId": "string",
      "targetEnvironmentName": "string",
      "targetType": "string"
    }
  ],
  "total": 0
}

List project backups

Returns all backups across all environments in the project with environment metadata.

GET
/projects/{projectId}/backups

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Path Parameters

projectIdRequiredstring

Project UUID

Query Parameters

statusstring

Filter by backup status

limitinteger

Results per page (default 50, max 100)

offsetinteger

Offset for pagination

curl -X GET "//api.ocore.dev/api/projects/<string>/backups?status=%3Cstring%3E&limit=0&offset=0" \
  -H "Authorization: <token>"

OK

{
  "backups": [
    null
  ],
  "total": 0
}

Stream restore operation progress

Streams Server-Sent Events for a restore operation keyed by restore log ID.

GET
/restore-logs/{restoreLogId}/progress

Authorization

Authorization<token>

JWT Bearer token (format: Bearer {token})

In: header

Path Parameters

restoreLogIdRequiredstring

Restore log UUID

curl -X GET "//api.ocore.dev/api/restore-logs/<string>/progress" \
  -H "Authorization: <token>"

SSE stream of restore progress

Download backup component

Streams a decrypted backup component without buffering. Browser navigation uses the authenticated session; API clients may use their session cookie, oCore API key, or a legacy one-time token.

GET
/backups/{id}/download

Authorization

access_token<token>

Browser session JWT sent as the access_token cookie.

In: cookie

Authorization<token>

oCore API key sent as Authorization: Bearer ocore_. JWT bearer tokens are not accepted for these operations.

In: header

token<token>

Short-lived one-time token returned by the backup download preparation endpoint

In: query

Path Parameters

idRequiredstring

Backup ID (UUID)

Query Parameters

componentstring

Backup component

Default: "db"Value in: "db" | "filestore" | "config"
organization_idstring

Selected organization for session-authenticated browser downloads

tokenstring

Legacy short-lived one-time download token

curl -X GET "//api.ocore.dev/api/backups/<string>/download?component=db&organization_id=%3Cstring%3E&token=%3Cstring%3E" \
  -H "access_token: <token>"

OK

"string"

Prepare backup download

Validates the selected tenant, completed backup, and requested component before returning a session-authenticated URL for a browser-native download.

POST
/backups/{id}/download-token

Authorization

access_token<token>

Browser session JWT sent as the access_token cookie.

In: cookie

Authorization<token>

oCore API key sent as Authorization: Bearer ocore_. JWT bearer tokens are not accepted for these operations.

In: header

Path Parameters

idRequiredstring

Backup ID (UUID)

Query Parameters

componentstring

Backup component

Default: "db"Value in: "db" | "filestore" | "config"
curl -X POST "//api.ocore.dev/api/backups/<string>/download-token?component=db" \
  -H "access_token: <token>"

OK

{
  "download_url": "/api/backups/550e8400-e29b-41d4-a716-446655440000/download?component=db&organization_id=550e8400-e29b-41d4-a716-446655440001"
}

Was this page helpful?
Edit on GitHub

Storage Browser

Previous Page

Backup Destinations

Next Page