Reference

API reference

The Umberfold client talks to one ingest endpoint. Everything below is served from this host.

Base URL

Requests go to the deployment you were given. This one ingests to Tokyo (kanto-1).

https://umberfold.cloud/v1

Authentication

Send a project key as a bearer token. A key can open sessions and read them; it cannot touch another project's.

Authorization: Bearer ufk.GMCFC7JYF90H1ZBCRBNM75GYDE

Endpoints

Method	Path	Purpose
POST	`/v1/sessions`	Open an ingest session for one file.
PUT	`/v1/sessions/{id}/parts/{n}`	Send one part. This is where the bytes are.
GET	`/v1/sessions/{id}`	Session state and the parts still missing: your resume point.
POST	`/v1/sessions/{id}/seal`	Finish the file, verify it, queue the edit copies.
GET	`/v1/sessions/{id}/copies`	List the edit copies for a sealed file.
GET	`/v1/sessions/{id}/copies/{name}`	Download one copy.

Open a session

One session per file. Give the size, and the SHA-256 if you already have it; the client computes it while it reads the card.

POST /v1/sessions
Content-Type: application/json

{
  "name": "A001C014_260912_R4TQ.mov",
  "size_bytes": 53687091200,
  "sha256": "096d373742f9a039c320a4737c2b3abe14a03569d26b949692e5dfe8cb1855fe",
  "part_size": 268435456
}

// 201 Created
{
  "id": "01M2AB97F0HX6XV8A99HSWY9BD",
  "part_size": 268435456,
  "parts": 200,
  "max_in_flight": 8,
  "expires_at": "2026-10-17T16:31:52Z"
}

Send parts

Parts are 64 MiB to 1 GiB. Keep up to eight in flight; the client sizes that window to the uplink. Each part carries its own checksum, and a part that fails it is rejected and costs only itself.

PUT /v1/sessions/01M2AB97F0HX6XV8A99HSWY9BD/parts/37
Content-Length: 268435456
X-Part-Xxh64: 4164d8399f767c45

// 204 No Content

A 20-minute card of 4K ProRes 422 HQ is about 100 GB. Allow several hours on a hotel connection; the client reports progress part by part and picks up after any interruption.

Resume

After a dropped connection, ask what is missing and send only that.

GET /v1/sessions/01M2AB97F0HX6XV8A99HSWY9BD

// 200 OK
{
  "id": "01M2AB97F0HX6XV8A99HSWY9BD",
  "state": "receiving",
  "parts": 200,
  "parts_received": 198,
  "missing": [38, 40],
  "bytes_received": 53150220288
}

Seal

Sealing checks the assembled file against the SHA-256 given at open, then queues the edit copies. Sealing with parts missing returns 409 and the list of what is missing.

POST /v1/sessions/01M2AB97F0HX6XV8A99HSWY9BD/seal

// 202 Accepted
{ "state": "verifying" }

Edit copies

Once a file is sealed, its copies are listed here and can be downloaded by name.

GET /v1/sessions/01M2AB97F0HX6XV8A99HSWY9BD/copies

// 200 OK
{
  "state": "ready",
  "copies": [
    { "name": "review-1080.mp4", "kind": "review", "size_bytes": 1342177280 },
    { "name": "frame-0001.jpg", "kind": "preview", "size_bytes": 2411724 }
  ]
}

Limits

Largest object	512 GB
Part size	64 MiB to 1 GiB
Parts in flight	8 per session
Open sessions	16 per project
Unsealed session	dropped 3 days after its last part
Originals after sealing	kept 14 days, then deleted

Command-line client

# once per machine
umberfold login --endpoint https://umberfold.cloud

# a whole card; run it again after any interruption
umberfold push /Volumes/A001 --parts 6
umberfold status

Errors

Errors are application/problem+json with type, title, status and detail.

Status	Meaning	What to do
401	No key sent, or a key that is not valid.	Check the bearer token. Keys belong to one project.
404	No such session, or it has expired.	Open a new session; parts already stored are not reused.
409	The session is sealed, or sealing found parts missing.	Read `missing` from the session and send those parts.
413	A part or the whole file is over the limits above.	Use a smaller part size, or split the file.
422	A part failed its checksum.	Send that part again.
429	Too many open sessions or requests from one key.	Wait for `Retry-After`; the client does this itself.
503	Ingest is briefly unavailable.	Retry with backoff. Stored parts are kept.

Health of this deployment is at /status.