/systems/backups - Upload a configuration backup

POST /systems/backups
Basic auth

Stream a GPG-encrypted configuration snapshot to the backup store. The body is the ciphertext; SHA-256 is computed at ingest. The appliance authenticates with HTTP Basic auth using its system_key:system_secret.

Server-side limits enforced before/during ingest:

  • Per-system rate limit (default 6/min, 60/hour) — 429 Retry-After on hit
  • Per-system slot cap (default 10) — oldest pruned at retention
  • Per-system size cap (default 500 MiB total) — oldest pruned
  • Per-org aggregate quota (default 100 GiB) — 413 on hit
  • Per-upload size cap (default 2 GiB) — 413 on hit

Object key shape: {org_id}/{system_key}/{uuidv7}.{ext}. The appliance never picks the destination prefix; it is server-derived from the authenticated identity.

Headers

  • X-Filename string

    User-facing filename (sanitized server-side)

application/octet-stream

Body Required

string(binary) string(binary)

Responses

  • 201 application/json

    Backup stored

    Hide response attributes Show response attributes object
    • code integer
    • message string
    • data object

      Metadata describing a single configuration backup stored for a system.

      Hide data attributes Show data attributes object
      • id string

        Backup object ID (UUIDv7 plus original extension)

      • filename string

        User-facing filename as supplied by the appliance via X-Filename

      • size integer(int64)

        Object size in bytes

      • sha256 string

        Hex SHA-256 checksum computed at ingest; always present once the upload returns 201

      • mimetype string
      • uploaded_at string(date-time)

        Server-observed timestamp of the upload
  • 400 application/json

    Bad request - validation error

    Hide response attributes Show response attributes object
    • code integer

      HTTP error code

    • message string

      Error message

    • data object
      Hide data attributes Show data attributes object
      • type string

        Type of error

        Values are validation_error or external_api_error.

      • errors array[object]
        Hide errors attributes Show errors attributes object
        • key string

          Field name that failed validation

        • message string

          Error code or message

        • value string

          Value that failed validation

      • details

        Additional error details
  • 401 application/json

    Unauthorized - invalid or missing token

    Hide response attributes Show response attributes object
    • code integer
    • message string
    • data object | null
  • 413 application/json

    Payload too large

    Hide response attributes Show response attributes object
    • code integer

      HTTP error code

    • message string

      Error message

    • data object
      Hide data attributes Show data attributes object
      • type string

        Type of error

        Values are validation_error or external_api_error.

      • errors array[object]
        Hide errors attributes Show errors attributes object
        • key string

          Field name that failed validation

        • message string

          Error code or message

        • value string

          Value that failed validation

      • details

        Additional error details
  • 429

    Rate limit exceeded; retry after the time indicated by Retry-After.

  • 503

    Backup storage or org-quota service unavailable; retry later.

POST /systems/backups 
curl \
 --request POST 'https://collect.your-domain.com/api/systems/backups' \
 --user "username:password" \
 --header "Content-Type: application/octet-stream" \
 --header "X-Filename: daily-backup-2026-04-12.tar.gz.gpg" \
 --data-binary '@file'
Response examples (201) 
{
  "code": 201,
  "message": "backup stored",
  "data": {
    "id": "01934fab-bc33-7890-a1b2-c3d4e5f6a7b8.tar.gz",
    "filename": "daily-backup-2026-04-12.tar.gz",
    "size": 82944000,
    "sha256": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
    "mimetype": "application/gzip",
    "uploaded_at": "2026-04-12T02:15:00Z"
  }
}
Response examples (400) 
{
  "code": 400,
  "message": "validation failed",
  "data": {
    "type": "validation_error",
    "errors": [
      {
        "key": "username",
        "message": "required",
        "value": "string"
      }
    ]
  }
}
Response examples (401) 
{
  "code": 401,
  "message": "invalid token",
  "data": {}
}
Response examples (413) 
{
  "code": 400,
  "message": "validation failed",
  "data": {
    "type": "validation_error",
    "errors": [
      {
        "key": "username",
        "message": "required",
        "value": "string"
      }
    ]
  }
}