The OpenAPI document reports its version in info.version. It's 1.3 today.
Expect additions. Your client should tolerate unknown fields, enum values,
event types and operations.
No surprises within v1. From v1.3 on, changes within v1 are additive: new
fields, values, event types and operations, without changing what existing
ones do.
Upgrading from before v1.3?
v1.3 changed some behaviour an existing client could have relied on. Those
changes were made while a single pilot lab used the API. Read the v1.3 entry
below, and follow this changelog whenever you upgrade your integration.
Behaviour changes an existing client could have relied on:
nextCursor always advances: a page shorter than limit moves it to the end
of the stream, also when the page is empty. Before, an empty page returned
the cursor unchanged.
A cursor ahead of the stream answers 410 CURSOR_EXPIRED. Before, it returned
an empty page.
An unknown types value, including ping, answers 400 BAD_REQUEST. Before,
it matched nothing.
A wait beyond the lab's five live waits per API process is held for its
wait time and then read once. Before, it returned an empty page at once. Closing the connection
now ends a wait.
Every error body is JSON in one shape, { defined, code, status, message, data? }.
413 is PAYLOAD_TOO_LARGE instead of plain text, an unknown path or method
is 404 NOT_FOUND instead of { "error": "Not found" }, 429 adds
defined, code and status next to its older fields, and faults during
admission answer 500 INTERNAL_SERVER_ERROR.
X-RateLimit-* describe the most constrained bucket that counted the request.
Before, they described the last limiter that ran.
Spreadu-Mode is test only when a test key authenticated the request. A
refused key of either shape, and an IP rate limit before authentication, now
answer live.
IPv6 addresses in the same /64 share one IP allowance.
One webhook endpoint receives at most two requests at a time, test pings
included. Extra deliveries wait for a slot.
If one event's body cannot be built, only the later events of that export
wait behind it; other exports' events continue. Order across exports can
differ from occurrence order in that case.
A stored event body with a field outside the published schema is served
without that field. Before, such a body failed its feed page and its webhook
delivery.
The request log in the Lab Portal's API settings shows a burst refused by the
lab or simulator allowance as one 429 RATE_LIMITED entry per key and
allowance for the rest of that allowance's minute, so a burst refused by
both can show two. Before, every refused request had its own entry.
A client regenerated from document version 1.3 gets renamed types: responses
and request bodies that were unnamed now have names, webhook callbacks have
their own webhook-events tag, and types is sent as a repeated parameter.
Additions:
deadDeliveries on every webhook endpoint, and an email to the lab when a
live delivery gives up after eight attempts.
Named types, a description for every field and parameter, and examples in
the reference. Event list items reference the named event types with a
discriminator on type.
Every operation in the reference declares the platform errors it can return,
PAYLOAD_TOO_LARGE, RATE_LIMITED and INTERNAL_SERVER_ERROR, with their
JSON bodies and the X-RateLimit-* headers.
Test mode corrections. These change test-mode behaviour too:
The readiness checklist counts a webhook only when a real event, not a ping,
gets a 2xx answer, and a secret rotation only when an API key performs it.
The correction scenario ends when your integration confirms revision 1
before the automatic correction runs.
Simulator order fields accept the same values as live: orderNumber and
externalOrderId take 1 to 120 characters after trimming (they took up to
100 and 200), and orderNumber rejects control characters.
Test exports are removed 30 days after their latest activity, not 30 days
after creation.
While Test mode is paused, your test keys stay listed in API settings and you
can revoke them. Opening the Test view no longer creates the test
environment.
The downloads changed too. The Postman and Bruno collections read a fresh
feed first and then continue from the saved cursor, and generate a new
Idempotency-Key for every simulator command. Both declare the API key only
in the test environment, as a secret variable, and send an empty
orderNumber until you set it. The reference integrations stream and resume
downloads without a total time limit, and every download ends: five retries
in a row that reach no new byte stop it, and so does a sixth restart of one
file from its first byte. They take each file's name, size and checksum from
the export detail and refuse download URLs that disagree with it. Before
building a path, they refuse a name from the API that could leave the
download directory or, on macOS or Windows, reach another file or a device,
and a revision that lists one file name twice.
Added Test mode: keys beginning spreadu_lab_test_ act only on your lab's
isolated test environment.
GET /me returns mode, "live" or "test", and every response carries
Spreadu-Mode.
Added seven simulator operations for test keys with sandbox:manage:
POST /sandbox/exports, POST /sandbox/exports/{reference}/revisions,
.../withdraw, .../expiring, .../expire,
PUT /sandbox/exports/{reference}/order and POST /sandbox/reset.
Simulator writes accept an optional Idempotency-Key of 1 to 128 printable
ASCII characters without spaces. A replay carries Idempotency-Replayed: true;
reusing a key for another operation or body answers IDEMPOTENCY_CONFLICT.
Added the error codes SANDBOX_BUSY, TEST_MODE_REQUIRED,
SANDBOX_STATE_CONFLICT, SANDBOX_EXPORT_LIMIT, IDEMPOTENCY_CONFLICT and
SANDBOX_EXPORT_LOCKED. SANDBOX_BUSY can also come from confirmation,
download URLs, receipts, unlock and secret rotation in test mode.
Simulator requests have their own allowance of 60 per minute per lab.
Added PUT /exports/{reference}/receipt and the export.received event.
Added createdAt, updatedAt, availableAt, downloadableUntil,
receivedAt and photographer to the export summary.
Added the locked, confirmed, received, updatedSince, orderNumber
and externalOrderId filters to GET /exports.
Added labOrder.orderedLength and labOrder.orderedCopies, and each
revision's frozen order and receivedAt. orderedQuantity is the album
length, not copies.
Added geometry.mm, every dimension in millimetres.
Added data.downloadableRevision to REVISION_NOT_DOWNLOADABLE.
Added webhook management by API key: GET /webhooks, POST /webhooks,
PATCH and DELETE /webhooks/{webhookId}, secret rotation and tests, with
the webhooks:manage scope.
Photographers can enter a number of copies, and they see when the lab
received the files.
Each operation now declares only the errors it can return, and the OpenAPI
document names its shapes and uses the absolute production server URL.