Reference · v1

Findes API

Base URL: https://findes.download/api/v1 · JSON responses · streaming uploads and downloads. The full OpenAPI 3.1 spec is available inside your console under Project → API → Specification.

Quickstart

# 1) stream a log batch
curl -sS -H "Authorization: Bearer $FINDES_TOKEN" \
     -H "Content-Type: application/x-ndjson" \
     --data-binary @events.ndjson \
     https://findes.download/api/v1/logs

# 2) upload a backup (any size, resumable)
curl -sS -H "Authorization: Bearer $FINDES_TOKEN" \
     -T backup-2026-10-19.tar \
     "https://findes.download/api/v1/backups?project=prod-db"

# 3) download an archive
curl -sSL -H "Authorization: Bearer $FINDES_TOKEN" \
     -o restore.tar https://findes.download/api/v1/archives/ar_1a2b3c4d5e

Authentication

All requests require a bearer token issued in the console (Settings → API tokens). Tokens are scoped per project and can be limited to ingest-only or restore-only. Send the token in the Authorization header:

Authorization: Bearer fin_live_xxxxxxxxxxxxxxxx

Treat tokens like passwords. Rotate at least every 90 days; revocation is immediate.

Ingest logs

POST /logs

Appends a batch of log events. The body is newline-delimited JSON (NDJSON) or raw text with a source query parameter. The batch is acknowledged once it is durably buffered.

Parameter	In	Description
`source`	query	Logical source name, e.g. `nginx-access`, `app.worker.1`. Defaults to the token's project.
`host`	query	Reporting hostname. Auto-detected from the agent if omitted.
`Content-Type`	header	`application/x-ndjson` or `text/plain`.

Response 201 Created

{
  "id": "lg_7f3ac91b2d",
  "received": 1048576,
  "events": 1204,
  "source": "nginx-access",
  "retentionDays": 30,
  "status": "accepted"
}

Upload a backup

POST /backups

Uploads a backup archive of any size. Uploads are chunked and resumable; an interrupted session can be continued for 48 hours using its id.

Parameter	In	Description
`project`	query	Target project slug. Required unless the token is bound to one project.
`X-Findes-Retention-Days`	header	Override retention for this archive (must not exceed the project maximum).
`X-Findes-Checksum-Sha256`	header	Optional hex SHA-256 of the payload; verified server-side on completion.

Response 201 Created

{
  "id": "ar_1a2b3c4d5e",
  "project": "prod-db",
  "received": 272629760,
  "compressedBytes": 272631808,
  "retentionDays": 90,
  "status": "sealed"
}

Download an archive

GET /archives/{id}

Streams a sealed archive as application/octet-stream (gzip container). Byte ranges are supported for partial restores. Decryption happens in flight — nothing touches server disk.

Parameter	In	Description
`id`	path	Archive id, e.g. `ar_1a2b3c4d5e`.
`Range`	header	Optional byte range, e.g. `bytes=0-1048575`.

Archive manifest

GET /archives/{id}/manifest

Metadata for an archive without downloading it.

{
  "id": "ar_1a2b3c4d5e",
  "project": "prod-db",
  "size": 272629760,
  "compressedBytes": 272631808,
  "compression": "gzip",
  "encrypted": true,
  "objects": 148,
  "created": "2026-10-19T02:15:44Z",
  "expires": "2027-01-17T02:15:44Z",
  "checksum": "sha256:9f2c…e41a"
}

Service status

GET /status

Public, unauthenticated component status. Also powers the status page.

Limits

Category	Limit
Control-plane requests	60 / min per token
Concurrent upload/download streams	2 per token
Limit increases	by request to support@findes.download

Exceeded limits return 429 with a Retry-After header.

Agents

The findes-agent CLI (Linux, macOS, Windows) is available from the console downloads page. Third-party shippers work out of the box:

# fluent-bit output
[OUTPUT]
    Name        http
    Match       *
    Host        findes.download
    Port        443
    TLS         On
    URI         /api/v1/logs
    Format      json_lines
    Header      Authorization Bearer $FINDES_TOKEN

Errors

Code	Error	Meaning
400	`bad_request`	Malformed parameters or body.
401	`invalid_credentials`	Missing, revoked or expired token.
403	`forbidden`	Token lacks the required scope.
404	`not_found`	Unknown resource.
429	`rate_limited`	See `Retry-After`.

Changelog

Version	Date	Notes
1.4.2	2026-09-08	Manifest now includes a top-level `checksum`.
1.4.0	2026-07-21	Resumable uploads; 48-hour upload sessions.
1.3.0	2026-05-02	Range downloads for partial restore.
1.2.0	2026-02-16	Per-upload retention override header.