Backup Management

List and trigger Postgres backups for a project. Backups are ordered by start time descending with a maximum of 50 entries returned.

Endpoint

/api/platform/projects/:id/backups

/api/platform/projects/:id/backups

Parameters

id

Response

// GET — List backups (max 50, ordered by started_at desc)
{
  backups: Array<{
    id: string
    projectId: string
    status: string          // "completed" | "failed" | "running"
    sizeBytes: number | null
    startedAt: string       // ISO 8601
    completedAt: string | null
    metadata: Record<string, unknown> | null
  }>
}

// POST — Trigger backup (202 Accepted)
{
  backup: {
    id: string
    projectId: string
    status: string          // "starting"
    startedAt: string
  }
}

Examples

# List backups
curl https://api.blueforge.studio/api/platform/projects/prj_xxx/backups \
  -H "Authorization: Bearer $BF_TENANT_KEY"

# Trigger a new backup
curl -X POST https://api.blueforge.studio/api/platform/projects/prj_xxx/backups \
  -H "Authorization: Bearer $BF_TENANT_KEY"

import { Client } from "@blueforge/client"

// List recent backups
const { backups } = await client.projects.backups.list("prj_xxx")
const latest = backups[0]
console.log(`Latest backup: ${latest.status} (${latest.startedAt})`)

// Trigger a backup
const { backup } = await client.projects.backups.trigger("prj_xxx")
console.log(`Backup ${backup.id} started at ${backup.startedAt}`)

Pitfalls

• Backup trigger (POST) is only available for projects with status

  "active"

  . Projects in

  "creating"

  or

  "deleted"

  state will reject the request.
• POST returns HTTP 202 (Accepted), not 201. The backup starts asynchronously — poll GET to check completion.
• The list endpoint returns a maximum of 50 backups. Pagination is not currently supported.
• The POST endpoint is not idempotent: each call initiates a new backup operation.

See also

• projects.get — Check project status before triggering backups
• Backups are managed at the project level; see the Platform API for database management details

Tested against

• @blueforge/platform-api: 2.4.1
• Last verified: 2026-07-15