List your lab's albums, read what's inside an export and download every production file.
An export is an album a photographer has sent to your lab. It keeps one
reference for its whole life. Every time the photographer submits a new
version, the export gets a new revision, numbered upwards. You always
produce from one exact revision.
GET /exports lists your lab's exports, newest first. Use limit for the page
size (1 to 100, default 50) and follow nextCursor until it is null.
Filters narrow the list down, and they combine with AND:
| Filter | Matches exports where |
|---|---|
downloadable=true | The current revision can be downloaded now. |
received=true | You recorded a receipt for the downloadable revision (receivedAt set). |
confirmed=true | Your lab confirmed the order identifiers (labOrder.confirmedByLab). |
locked=true | Your lab confirmed the order and holds the lock (lockedAt set). |
updatedSince=<ISO datetime> | updatedAt is at or after this time. |
orderNumber=<value> | labOrder.orderNumber equals the value exactly. |
externalOrderId=<value> | labOrder.externalOrderId equals the value exactly. |
The most useful one to start with: downloadable=true&received=false is your
"to do" list. It shows everything you can fetch and haven't received yet.
A few details worth knowing:
false matches
everything true doesn't. That includes exports without an order or without
a downloadable revision.updatedSince accepts Z or an offset. URL-encode a + offset as %2B.Use GET /exports/{reference} for one export with all its revisions.
References are forgiving: either case works, and spaces, hyphens and
underscores are ignored.
Every list item and export detail carries the same summary. Events carry it too, though older ones can lack some fields (see Follow changes):
| Field | Meaning |
|---|---|
reference, albumId | The export's reference and the album it came from. |
albumTitle | The photographer's title from the newest revision, even one that failed to render. It can include a client's name. |
createdAt | When the album was set up for your lab, usually when the photographer created it. |
updatedAt | The latest change to the export, its order or its newest revision. |
downloadableRevision | The revision you can download now, or null. |
availableAt, downloadableUntil | When that revision became available and the last moment to download it. Null when nothing is downloadable. |
receivedAt | When you recorded receiving that revision, or null. |
lockedAt | When your lab locked the album for production, or null. |
correctionOpen | The photographer is preparing a correction. |
latestRevision | The newest revision's number and status, or null. |
photographer | { id, displayName }, or null while no revision is visible. |
labOrder | The order details, or null when there are none. |
About the photographer. displayName is the name frozen on the newest
visible revision, so a revision that failed to render doesn't count. It can be
null when the photographer has no name set. id stays the same for that photographer within
your lab, so you can group their albums. It becomes null when they are no
longer your lab's customer in Spreadu, for example after deleting their
account. Email addresses and other contact details are never included.
This one trips people up, so here it is plainly:
labOrder.orderedQuantity and orderedQuantityUnit are the album's
length, in pages or spreads. Not the number of books.orderedLength carries the same value as { count, unit } and reads more
clearly in new code. The two older fields stay.orderedCopies is how many books the photographer wants printed, from 1
to 999, or null.Photographers enter copies when they create the album or later in the editor's order settings, under the same rules as the order number. It's information for you. Spreadu never enforces it.
labOrder shows the order as it is now. Each revision's order shows what was
frozen when that revision was submitted: { orderedLength, orderedCopies }, or
null when the album had no order then. Produce from the revision you
downloaded.
Only the current revision can be downloaded, and only while it's available and not expired. Revision numbers can skip a number when an attempt failed to render.
A revision has parts, the individual production files, and packages,
the ZIP and, for PDF output, the combined PDF. Live v1 exports currently
contain an INNER part. The cover-and-inner test scenario also gives you a
COVER part. Handle every part you receive explicitly. Previews aren't
production files and never show up here. When a revision can't be downloaded,
its files and packages are empty.
POST /api/print-lab/v1/exports/{reference}/download-urls
Content-Type: application/json
{ "revision": 2, "fileIds": ["<file-id>"] }Leave out fileIds to get every production file and package in that revision,
or pass up to 500 IDs. If one ID doesn't belong to the revision, or the revision
can't be downloaded, the whole request is refused.
Spreadu logs issued links against the API key, not a person: once per key and file, for as long as that key's link to the file is valid. Issuing a link doesn't prove a download finished. A receipt does.
expiresAt.sizeBytes and checksumSha256.Range requests.
If a link expires midway, request new links for the files still missing and
continue each partial file from its last byte. The
reference integrations do exactly that.Product, spec, output and geometry all come from the frozen revision. Later edits to the album don't change them.
geometry copies the stored inner specification without rounding. It's null
when the revision has no valid stored specification, and optional dimensions
that are missing are null on their own. Fields ending in Px are pixels, and
pixels are the authority:
| Field | Meaning in the frozen inner specification |
|---|---|
dpi | Resolution used to interpret the stored dimensions. |
widthPx, heightPx | Inner layout width and height. |
pageWidthPx, pageHeightPx | Width and height of a single page, when present. |
trimWidthPx, trimHeightPx | Trim width and height, when present. |
innerBleedPx | Bleed at the inner edge, when present. |
outerBleedPx | Bleed at the outer edge, when present. |
spineWidthPx | Spine width, when present. |
geometry.mm repeats each dimension in millimetres, without the Px suffix:
width, height, pageWidth, pageHeight, trimWidth, trimHeight,
innerBleed, outerBleed and spineWidth. Each value is px / dpi * 25.4,
rounded to 0.1 mm, and null where the pixel value is null. mm itself is null
only when the stored DPI isn't positive.
For example, at 300 DPI, widthPx: 7200 is width: 609.6.
Cover parts are simpler. A COVER part's geometry comes from the cover
specification and has only widthPx, heightPx, spineWidthPx and
outerBleedPx, which holds the cover's bleed. Every other field is null.
Use millimetres for people and pixels for machines. And don't swap in live catalog measurements for the frozen geometry: the frozen values are what the photographer designed.
Allow analytics to help us improve these docs? We measure page visits and outgoing links. No session recordings. Privacy policy