Assets

Paginated list of the caller's assets, newest-created first. Every filter is optional and they compose: ?tag=cat&mime=image/jpeg&minWidth=2000.

Each row is an AssetSummary — what an asset is called, what it is, how it is labelled and published, and when it expires. The image facts, metadata and lineage are only on GET /api/v1/assets/{id}. To walk a whole library, follow meta.nextCursor as cursor rather than counting pages: a cursor page counts nothing. A chain job's intermediate products are left out unless includeIntermediate=true.

USE THIS WHEN:

• Listing a view (all, published) or one collection
• Filtering by tag, MIME type, pixel dimensions, capture date or source operation
• Free-text search over the name and camera make/model

DO NOT USE WHEN:

• Retrieving a single asset by ID → use GET /api/v1/assets/{id}
• Listing the collections that exist → use GET /api/v1/assets/collections

One page of rows; meta carries hasMore and nextCursor

Every collection your assets are in, one row each: the name, how many assets are in it and when the latest one was created — most recently added to first. count is the total GET /api/v1/assets?collection= reports for that name. q narrows the list to names containing it, case-insensitively. A chain job's intermediates are not counted and their job: collections are not listed.

USE THIS WHEN:

• Finding out which collections exist before filtering or submitting into one
• Checking a collection name's spelling (a misspelt name is simply a new collection)

DO NOT USE WHEN:

• Listing the assets in a collection → use GET /api/v1/assets?collection=

One page of collections; meta carries hasMore and nextCursor

Moves every one of your assets in from to to, in one statement — the way to rename a collection, or with to: "" to take its assets out of any collection. Renaming onto a name that is already in use merges the two. updated is how many assets moved; a name nothing is in moves nothing and is not an error. Both names are checked like any other collection name, and a chain job's job: collections cannot be renamed.

USE THIS WHEN:

• Renaming, merging or dissolving a collection

DO NOT USE WHEN:

• Moving some assets, not all of a collection → use POST /api/v1/assets/update with collection

What moved

Deletes multiple assets and queues their stored objects for removal. Final — there is no trash and no restore. IDs that are not yours, or no longer exist, are skipped without an error: deleted lists what was actually deleted. A published asset's publicUrl stops answering within about two minutes.

USE THIS WHEN:

• Deleting specific assets by IDs

DO NOT USE WHEN:

• Letting assets lapse on their own → do nothing; each is deleted at its expiresAt

What was deleted

Creates one asset per staged object whose bytes were PUT to the staged URL.

Send only what the caller knows: which staged object, the file's name and, optionally, a collection and tags — [{"objectId": "…", "name": "photo.jpg", "collection": "shoot-01"}]. The type comes from the name's extension (the rule stage-upload signed the PUT with); size, dimensions and SHA-1 are measured by ingest; the source is always upload. Every asset starts PROCESSING — poll POST /api/v1/assets/status until it is DONE.

Every item is checked before any is written, so one bad item fails the whole request and creates nothing. At most 500 objects per request. The asset limit is checked here, and this is the check that counts — stage-upload's is advisory.

USE THIS WHEN:

• Finalizing file uploads after uploading to staged URLs (single or batch)

DO NOT USE WHEN:

• Staging the upload → use POST /api/v1/assets/stage-upload
• The image is at a public URL → use POST /api/v1/assets/from-url

One new asset per object, in request order

Fetches each public image URL here, stores it and creates an asset — the same asset an upload creates, in PROCESSING until ingest has written dimensions and metadata.

One result per URL, in request order: {url, id, status, name} or {url, error} with the usual code / retryable / param. A private or unresolvable address, a URL that is not an image (unsupported_format), a body over the limit or a host that fails for now (provider_unavailable, retryable) fails that URL only. As on POST /api/v1/assets/upload, the same bytes are the same asset: bytes the account already holds as a DONE asset (same SHA-1) come back as that asset with existing: true, and so does a URL whose bytes an earlier URL of the same request already brought in — nothing new is stored, and a duplicate keeps its own name, collection and tags. So a URL that landed can be sent again; an Idempotency-Key still replays the whole answer, the rows that failed included.

LIMITS: at most 20 URLs per call; each body at most 25 MB; redirects are not followed; the asset count for all URLs is checked before anything is fetched. A response that declares a type that is not an image (and a URL with no image extension), or a length over the limit, is refused before its body is read. The call shares the synchronous endpoints' concurrency: over your account's → 429 rate_limited, the node full → 503 provider_unavailable; both retryable, with Retry-After.

USE THIS WHEN:

• The image is somewhere on the internet and you want an asset_id for a job

DO NOT USE WHEN:

• You hold the bytes → POST /api/v1/assets/upload (one file, up to 25 MB), or POST /api/v1/assets/stage-upload → PUT → finish-upload for larger files and batches
• You only want one image transformed and back → POST /api/v1/images/transform with {"url": …}

One result per URL, in request order — a refused URL is a result with error, not a failed request; bytes you already hold are that asset, existing: true

Signs URLs for the preview renditions (400 px wide WebP) of up to 100 of your assets in one call, each valid for 15 minutes (ttlSeconds), and reports each asset's ingest status alongside. IDs that are not yours are left out rather than reported. A read that is a POST only because a page of ids does not fit a query string, so it takes no Idempotency-Key — a replay would hand back stale signatures.

USE THIS WHEN:

• Painting thumbnails for a listing page (one call per page, not one per image)

DO NOT USE WHEN:

• Waiting for assets to finish ingest → POST /api/v1/assets/status (nothing signed, no audit row)
• You want the full-size bytes → GET /api/v1/assets/{id}/content
• You want a stable public URL → publish the asset and use publicUrl

Step one of the three-step upload (stage → PUT the bytes to each returned url → finish-upload). The bytes go straight to the object store, never through this API, which is what lets it take up to 500 files of up to 100 MB in one call.

Each url is signed for one PUT, valid for 60 minutes, with the contentType it answers (read from fileName's extension) and a Content-Length equal to the fileSize you declared — the object store refuses any other. A file this service does not take (no image extension it accepts, or over 100 MB) comes back with error set and no url; the rest of the batch is staged. A sha1Hash matching a DONE asset you already hold sets exists and existingAssetId: reuse that asset, or upload anyway. A staged object that is never finished is deleted after a day.

The asset limit is checked here against the files it would stage, and again by finish-upload, which is the check that counts.

USE THIS WHEN:

• You have many files, or one over 25 MB (call this first, then PUT to the returned URL, then call finish-upload)

DO NOT USE WHEN:

• You hold one image of up to 25 MB → POST /api/v1/assets/upload does it in one call
• The image is at a public URL → POST /api/v1/assets/from-url
• Finalizing an upload → use POST /api/v1/assets/finish-upload

One entry per file, in request order: a signed url, or an error

Where a batch of your assets is in ingest, in one call — the poll after an upload or a URL ingest, instead of GET /api/v1/assets/{id} per asset per tick. PROCESSING is still running; DONE and FAILED are final. width and height appear once ingest has measured them.

Nothing is signed and nothing is written to the audit log: the answer is your own assets' progress, and IDs that are not yours are absent rather than reported. A POST only because a batch of ids does not fit a query string, so it takes no Idempotency-Key — a replay would answer a stale status.

USE THIS WHEN:

• Waiting for uploaded or URL-ingested assets to finish (poll every one or two seconds)

DO NOT USE WHEN:

• You need the whole asset → GET /api/v1/assets/{id} once it is DONE
• You want the bytes → GET /api/v1/assets/{id}/content

Updates the published status, the collection and the tags of multiple assets. Each field you send is applied to every listed asset; a field you omit is left alone. collection: "" takes the assets out of their collection; tags replaces the whole list ([] clears it). IDs that are not yours are skipped without an error: the answer is the assets that were updated, as full records with the change applied.

published: true gives each asset its publicUrl, the full-size image on the CDN; published: false takes it down within about two minutes.

USE THIS WHEN:

• Publishing or unpublishing one or more assets
• Putting assets in a different collection
• Tagging assets so GET /api/v1/assets?tag= finds them again

DO NOT USE WHEN:

• Permanently deleting assets → use POST /api/v1/assets/delete
• Renaming a whole collection → use POST /api/v1/assets/collections/rename

The updated assets, in request order

Stores the request body as an asset in one call: the bytes are the body, the parameters are the query string. Send the image as the raw body with its own Content-Type (image/jpeg, image/png, …) and a Content-Length, or as multipart/form-data with a file part. The asset is created in PROCESSING and reaches DONE once ingest has written dimensions and metadata — poll POST /api/v1/assets/status or subscribe to the webhook.

The type is the declared Content-Type when it is an image type this product takes, else the extension of name (or the multipart file name); neither → 400 unsupported_format. Bytes the account already holds as a DONE asset (same SHA-1) come back as that asset with existing: true and nothing new is stored.

LIMITS: one file per call, at most 25 MB (413 payload_too_large); a raw body needs Content-Length (400 invalid_param). Over this node's concurrent-upload capacity → 503 provider_unavailable with Retry-After, retryable. No Idempotency-Key (contract §3): the same bytes are the same asset, so re-sending is already safe.

USE THIS WHEN:

• You hold one image of up to 25 MB and want an asset_id for a job

DO NOT USE WHEN:

• The file is over 25 MB, or you have many → POST /api/v1/assets/stage-upload, PUT, then finish-upload (the bytes then go straight to the object store)
• The image is at a public URL → POST /api/v1/assets/from-url
• You only want one image transformed and back → POST /api/v1/images/transform

The image: raw bytes with their own Content-Type, or a multipart form with a file part

The asset: new (PROCESSING), or the DONE one you already hold for the same bytes (existing: true)

One asset's full record: the list row's fields plus image (type, pixel size, bytes, SHA-1 and the facts ingest derived), metadata (what exiftool read), takenAt and, for anything a job made, lineage. While the asset is PROCESSING its image facts are not measured yet.

USE THIS WHEN:

• Reading one asset's full record (image facts, metadata, lineage), typically once it is DONE
• Resolving a known asset ID

DO NOT USE WHEN:

• Listing assets → use GET /api/v1/assets
• Waiting for ingest to finish → POST /api/v1/assets/status polls a batch in one call
• You want the bytes → GET /api/v1/assets/{id}/content

The asset

Deletes an asset and queues its stored objects for removal. There is no trash and no restore: the delete is final. A retry with the same Idempotency-Key replays the answer; without one, a second delete is 404 asset_not_found. A published asset's publicUrl stops answering within about two minutes.

USE THIS WHEN:

• Permanently removing one asset file by ID

DO NOT USE WHEN:

• Deleting multiple assets at once → use POST /api/v1/assets/delete
• Letting an asset lapse on its own → do nothing; it is deleted at its expiresAt

Deleted; no body

Redirects (302) to a signed URL for the asset's own bytes, valid for 5 minutes. The asset does NOT need to be published — this is the private read path. The redirect is Cache-Control: private, no-store: the URL is the credential, so follow it and do not keep it.

USE THIS WHEN:

• Fetching your own asset's bytes from a script, SDK or CLI
• Previewing an asset you do not want on a public URL

DO NOT USE WHEN:

• You want a stable, cacheable, public URL → publish the asset (POST /api/v1/assets/update with published=true) and use publicUrl

Redirect (Location) to the signed URL for the bytes. Follow it (curl -L).