# /systems/backups - Upload a configuration backup

**POST /systems/backups**

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.



## Servers
- Collect API server (port 8081): https://collect.your-domain.com/api (Collect API server (port 8081))


## Authentication methods
- Basic auth


## Parameters
### Headers
- **X-Filename** (string)
  User-facing filename (sanitized server-side)



### Body: application/octet-stream (string(binary))

string(binary)

## Responses
### 201
Backup stored

#### Body: application/json (object)
- **code** (integer)

- **message** (string)

- **data** (object)
  Metadata describing a single configuration backup stored for a system.

### 400
Bad request - validation error

#### Body: application/json (object)
- **code** (integer)
  HTTP error code
- **message** (string)
  Error message
- **data** (object)


### 401
Unauthorized - invalid or missing token

#### Body: application/json (object)
- **code** (integer)

- **message** (string)

- **data** (object | null)


### 413
Payload too large

#### Body: application/json (object)
- **code** (integer)
  HTTP error code
- **message** (string)
  Error message
- **data** (object)


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

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


[Powered by Bump.sh](https://bump.sh)