The machine API

POST /v1/transfers (open)

Books a row per file and hands back an upload address for each. Nothing is visible to anybody until close: there is no half-sent delivery a client could stumble onto.

POST /v1/transfers
{
  "name": "Shot 020, version 12",
  "message": "First pass, notes welcome",   // optional
  "expiresInDays": 7,                       // required: 3, 7, 14 or 30
  "passphrase": null,                       // optional
  "idempotencyKey": "one-per-attempt",      // required
  "files": [
    { "filename": "020_v012.mov", "bytes": 812000000, "folder": "renders/sh020" }
  ]
}

→ 201 (or 200 if idempotencyKey matches an earlier open)
{
  "id": "…",
  "expiresAt": "2026-10-01T12:00:00.000Z",
  "files": [{
    "id": "…", "filename": "020_v012.mov", "bytes": 812000000, "status": "uploading",
    "upload": { "url": "…", "method": "PUT", "expiresInSeconds": 3600 },
    "chunked": { "uploadId": "…", "partSize": 33554432, "partCount": 25 }
  }],
  "partsUrl": "/v1/transfers/…/parts",
  "completeUrl": "/v1/transfers/…/complete"
}

expiresInDays has no default on purpose, an expiry nobody chose could leave a client's files reachable longer than the sender meant, and that is the one direction a deadline must never drift. idempotencyKey is required too: a retried open returns the same delivery instead of mailing a client two links to the same files.

folder is optional, per file, and it is where a delivery differs from a drop: the folder is a string here because it only describes a zip, and it may be set at the open because nothing in the product has to look at it before the delivery is closed.

PUT <upload address>

The bytes, straight to storage, this app never sees them. Small files go up in one PUT to the address the open call gave you. A file with a chunked block goes up in parts instead (below); the same open answer already told you which.

POST /v1/transfers/:id/parts (a large file, in pieces)

For any file with a chunked block. Ask this before every stretch of sending, including the first, there is no separate resume call, resuming is asking this question again with the same uploadId after a connection drops. Storage's own record of what arrived is the answer, never what a caller claims.

POST /v1/transfers/:id/parts
{ "fileId": "…", "uploadId": "…", "bytes": 812000000 }

→ 200
{
  "fileId": "…", "partSize": 33554432, "partCount": 25,
  "done": [1, 2, 3],
  "storedBytes": 100663296,
  "parts": [{ "partNumber": 4, "url": "…" }, /* up to 100 */],
  "more": true
}

Send up to a handful of parts at once, four in parallel is about three times the throughput of one at a time on an ordinary line, because each part opens its own connection and the wait to open it, not the bandwidth, is what dominates.

POST /v1/transfers/:id/complete (close it)

An empty body is enough: this call asks storage which multipart upload is standing on each file's key and joins it itself. There is no separate finish step to look for. Safe to call twice, a file that is already landed is skipped, and the same link comes back.

POST /v1/transfers/:id/complete
{}

→ 200
{
  "id": "…",
  "link": "https://app.kadrenta.com/s/…",
  "expiresAt": "2026-10-01T12:00:00.000Z",
  "passphrase": false,
  "bytes": 812000000,
  "files": [{ "id": "…", "filename": "020_v012.mov", "bytes": 812000000, "folder": "renders/sh020" }]
}

GET /v1/transfers/:id (read back)

The one thing a key may read about itself: whether the delivery is still good, when it ends, and whether, and when, it has been picked up. Never who picked it up, and never a list of a studio's other deliveries.

GET /v1/transfers/:id

→ 200
{
  "id": "…", "status": "ready", "expiresAt": "…",
  "files": [ /* … */ ],
  "downloads": { "count": 1, "lastAt": "2026-09-24T16:40:00.000Z" }
}

DELETE /v1/transfers/:id (take it back)

Withdraws the delivery. Asking twice is a success, not a refusal: a script that lost the answer and asks again gets told the same thing, changed or not.

GET /v1/projects (which jobs you may reach)

GET /v1/projects

→ 200
{ "projects": [{ "id": "…", "name": "Winter campaign", "client": "Northline", "archived": false }] }

archived is true once the job itself is archived. Its dock still holds every file that was ever put there; it just no longer counts as an active job. Added 30-09-2026, additive: a caller that does not read this field sees no other change.

GET /v1/projects/:projectId/folders (the folders already there)

GET /v1/projects/:projectId/folders

→ 200
{ "folders": ["renders", "renders/sh020", "plates"] }

Every folder already in this job's dock, as a full path (renders/sh020), so a pipeline can offer a folder to drop into rather than guessing the exact spelling of one that already exists. Read-only: it never creates a folder, that happens on close below.

POST /v1/projects/:projectId/files (open a drop)

POST /v1/projects/:projectId/files
{
  "files": [{ "filename": "sh020_v012.exr", "bytes": 44000000 }],
  "openOperationKey": "a-uuid-per-open"      // optional
}

→ 201 (or 200 if openOperationKey matches an earlier open: the same files come back)
{
  "projectId": "…",
  "files": [{
    "id": "…", "filename": "sh020_v012.exr", "bytes": 44000000, "status": "uploading",
    "upload": { "url": "…", "method": "PUT", "expiresInSeconds": 3600 }
  }],
  "partsUrl": "/v1/projects/…/files/parts",
  "completeUrl": "/v1/projects/…/files/complete"
}

There is no drop id. A drop is not a thing with a life the way a delivery is, it is three calls about a job, and the only thing that carries between them is the file ids this answer hands you. Keep those, and there is nothing else to lose.

POST /v1/projects/:projectId/files/parts (a large file, in pieces)

The same question as the delivery road's /parts, on this job's files.

POST /v1/projects/:projectId/files/complete (land them in the dock)

POST /v1/projects/:projectId/files/complete
{ "files": [{ "fileId": "…", "folder": "renders/sh020" }] }

→ 200
{
  "projectId": "…", "landed": 1, "bytes": 44000000,
  "files": [{ "id": "…", "filename": "sh020_v012.exr", "bytes": 44000000, "folder": "renders/sh020" }]
}

The body is required here, unlike a delivery's close: a drop remembers nothing between calls, so you name what you sent. folder is a real folder in the job's dock, made if it does not exist yet, up to ten levels deep, checked before anything lands so a bad path never leaves ready files hanging with nowhere to show.

Review drafts and shot versions (early access)

Early access: ask us to switch it on for your studio.

Once a render has landed in a job's dock, the same key can put it up for your team: as the next round of an internal review, or as the next version under a shot. It is a draft, always. A key can never publish a round, make a share link, move a review to the client, or mail anybody; those stay a click in the studio, by a person.

It needs a key made with the reach "Bin, review drafts and shot versions", which only shows on Studio settings → Delivery keys once early access is on. Keys you already have keep exactly what they do. Every address below answers not_permitted for any other key.

The file has to be one this key uploaded itself, into the dock of the same job, with /v1/projects/:projectId/files and its /complete. Use the file id that call handed back. Shots and review tracks are named by id, never by name: which render belongs to which shot is your pipeline's lookup.

GET /v1/projects/:projectId/shots (turn a shot number into an id)

A pipeline usually knows a shot by its NUMBER, out of a render's own filename (BICPEN_010_v003.mp4), never by its uuid. This lists every shot on a job, grouped by breakdown, so a pipeline that wants to see the whole thing first can. Most pipelines never need to call it: the by-number address below does the same lookup itself.

GET /v1/projects/:projectId/shots

→ 200
{
  "films": [{
    "id": "…", "name": "Main film",
    "shots": [
      { "id": "…", "number": "010", "kind": "shot", "name": "Opening drone" },
      { "id": "…", "number": "020", "kind": "shot", "name": null },
      { "id": "…", "number": "EDIT", "kind": "edit", "name": null }
    ]
  }]
}

POST /v1/projects/:projectId/shots/by-number/:number/versions (the next version, by shot number)

The same address as POST /v1/shots/:shotId/versions below, with the shot named by its number on this job instead of its id. Only ordinary numbered shots resolve here, not an R&D breakdown's own numbers.

POST /v1/projects/:projectId/shots/by-number/010/versions
{ "media_file_id": "…" }

→ 201
{ "version": { "id": "…", "shot_id": "…", "project_id": "…", "media_kind": "video", "version": 3 } }

A number unique to one breakdown on this job resolves on its own. A job with more than one breakdown can have the same number twice (a main cut and an R&D pass, say): that answers ambiguous_shot_number (409) with every breakdown that has one, and the retry carries film_id in the body.

→ 409
{ "error": "ambiguous_shot_number",
  "candidates": [{ "film_id": "…", "film_name": "Main film" }, { "film_id": "…", "film_name": "R&D" }],
  "message": "More than one breakdown on this job has a shot with that number…" }

PATCH /v1/projects/:projectId/shots/:shotId (a shot's code, status and columns)

Changes only what the body names: code (null takes it off), status (one of the breakdown's own statuses, by id or by label in any case) and fields (the breakdown's own columns, by field id, as GET .../shots lists them under field_definitions; null empties one). The values are judged by the same rules as the shot page: a choice takes one of its option ids, a person somebody on the studio's team by id, frames a whole number or a timecode, a date YYYY-MM-DD. The answer is the shot as GET hands it out, plus changed. GET on the same address reads one shot.

PATCH /v1/projects/:projectId/shots/:shotId
{ "status": "in progress", "fields": { "<field id>": 112 } }

→ 200
{ "film_id": "…",
  "shot": { "id": "…", "number": "010", "code": null, "label": "010", "kind": "shot",
            "name": "Opening drone",
            "status": { "id": "…", "label": "In progress", "category": "active" },
            "fields": { "<field id>": 112 } },
  "changed": ["status", "Frames"] }

A status the breakdown does not have is never made: it answers invalid_value (422) with valid_statuses, the labels there are. A field id that is not one of the breakdown's columns answers the same with valid_fields. One refused part refuses the whole call, so nothing is half written. Each change lands on the project's activity like a change on the shot page.

→ 422
{ "error": "invalid_value", "field": "status",
  "valid_statuses": ["Waiting", "In progress", "Approved"],
  "message": "That value is not one this shot's breakdown takes…" }

PATCH /v1/projects/:projectId/shots/by-code/:code does the same with the shot named by its code (or its number label when it has none), with film_id in the body when two breakdowns on the job use that code; GET there takes ?film_id=. A key or a person may make 500 shot changes a day; a call that changed nothing does not count.

POST /v1/review/rounds (a draft round on an internal review)

POST /v1/review/rounds
{ "media_file_id": "…", "project_id": "…", "shot_id": "…", "title": "Shot 020" }

→ 201
{
  "review_item": { "id": "…", "project_id": "…", "shot_id": "…",
                   "audience": "internal", "started_here": true },
  "round": { "id": "…", "version": 1, "published": false }
}

Give review_item_id to add a round to an internal track that already exists, or project_id and title to start one (shot_id is optional and hangs the track on that shot; shot_number + optional film_id names the same shot by its number instead, the same resolution POST .../shots/by-number/:number/versions uses). A shot has one internal track: naming a shot that already has one puts the round there, and started_here says false. A track that is already the client's answers not_found; a key only ever works on internal tracks. Any field not listed here is refused with invalid_body, so there is no field that publishes or shares by accident.

POST /v1/shots/:shotId/versions (the next version under a shot)

POST /v1/shots/:shotId/versions
{ "media_file_id": "…" }

→ 201
{ "version": { "id": "…", "shot_id": "…", "project_id": "…", "media_kind": "video", "version": 3 } }

The number follows the shot's own series for that kind of file, and a number once taken is never reused. No caption and no note: those are a click on the shot page.

GET /v1/review/rounds/:roundId (how your round stands)

GET /v1/review/rounds/:roundId

→ 200
{ "round": { "id": "…", "version": 1, "published": false, "verdict": "none" } }

Only a round this key put up itself; any other id answers not_found. verdict is one of none, requested, needs_work or approved. Nothing else comes back: not the remarks, not who decided, not the other rounds.