Build and prove your lab integration with generated albums and the real API.
Test mode is your lab's own sandbox. It comes with generated album exports that you can create, correct, expire and reset whenever you like. Everything else is real: the same API, the same signed downloads, the same event feed and the same webhook delivery as live mode. You're testing the real thing.
Nothing you do in Test mode touches a photographer's album or sends notifications to photographers or your lab.
You need an active lab, permission to manage its API settings, and a terminal
with curl, jq and uuidgen.
In Lab Portal → Lab settings → API, switch to Test and create a key with
Full access. That includes sandbox:manage for the simulator and
webhooks:manage for webhooks. Copy the key while it is on screen. Spreadu
can't show it again.
Every active lab can start in Test mode right away. Live access is a separate step that comes later.
Test mode paused?
API settings tell you when it is. Your test keys stay listed so you can revoke them, but new test keys, endpoints and exports are off until Spreadu turns Test mode back on. Write to [email protected] if you're waiting on it.
Test and live use the same base URL. The key decides the mode: test keys begin
spreadu_lab_test_, live keys begin spreadu_lab_. Test keys can't read live
exports, and live keys can't run the simulator.
export API="https://api.spreadu.com/api/print-lab/v1"
export SPREADU_KEY="<your-test-key>"
curl --fail-with-body -sS "$API/me" \
-H "Authorization: Bearer $SPREADU_KEY" | jq '{mode, lab, key}'Look for "mode": "test". Every authenticated response also carries a
Spreadu-Mode header.
In Test mode, lab describes your test environment, not your live lab. It has
its own ID, a slug beginning sandbox- and your lab's name followed by
"(test)". It also has its own request allowance, so test traffic never eats
into your live lab's.
Your test environment appears the first time you create a test key, a test endpoint or run a simulator action. Just opening the Test view creates nothing.
Play photographer and send yourself an album. Each new command gets its own
Idempotency-Key, which lets you retry safely: send the same request with the
same key and you get the same export back, not a second one.
export COMMAND_ID="$(uuidgen)"
CREATED=$(curl --fail-with-body -sS -X POST "$API/sandbox/exports" \
-H "Authorization: Bearer $SPREADU_KEY" \
-H "Idempotency-Key: $COMMAND_ID" \
-H "Content-Type: application/json" \
-d '{"scenario":"spreads-jpg"}')
export REFERENCE=$(printf '%s' "$CREATED" | jq -r '.reference')
printf '%s\n' "$CREATED" | jqYou get the export's reference and revision straight away. The files are
generated in the background, and export.available announces them.
Try it: send the exact same request again with the same COMMAND_ID. You get
the same export. The same key with a different body or operation answers
IDEMPOTENCY_CONFLICT.
Read the export until downloadableRevision is 1. Give it a moment between
reads. PREPARING is normal, not a failure.
curl --fail-with-body -sS "$API/exports/$REFERENCE" \
-H "Authorization: Bearer $SPREADU_KEY" | jqIn a real integration you would rather list everything that is ready and not received yet:
curl --fail-with-body -sS "$API/exports?downloadable=true&received=false&limit=100" \
-H "Authorization: Bearer $SPREADU_KEY" | jqEach item has a reference and a downloadableRevision. Follow nextCursor
until it is null.
Ask for download links for that exact revision:
curl --fail-with-body -sS -X POST "$API/exports/$REFERENCE/download-urls" \
-H "Authorization: Bearer $SPREADU_KEY" \
-H "Content-Type: application/json" \
-d '{"revision":1}' > download-urls.jsonYou get every production file and package, each with its file details and a
url. The links expire at expiresAt, 15 minutes after your request, so
download right away. Save each file under its filename and compare its byte
size with file.sizeBytes and its SHA-256 with file.checksumSha256. This loop
checks the SHA-256:
mkdir -p "$REFERENCE"
jq -r '.files[] | [.url, .file.filename, .file.checksumSha256] | @tsv' download-urls.json |
while IFS=$'\t' read -r url name sha; do
curl -sS --fail "$url" -o "$REFERENCE/$name"
echo "$sha $REFERENCE/$name" | sha256sum -c - # on macOS: shasum -a 256 -c -
doneEvery line should end in OK. For big revisions, use a client that resumes
interrupted downloads, like the reference integrations.
Once every checksum matches, record the receipt:
curl --fail-with-body -sS -X PUT "$API/exports/$REFERENCE/receipt" \
-H "Authorization: Bearer $SPREADU_KEY" \
-H "Content-Type: application/json" -d '{"revision":1}'The response includes reference, revision, receivedAt and changed. The
export now drops out of received=false. Calling it again is safe: you get
changed: false and the original receivedAt.
The feed now holds export.requested, export.available and
export.received. Keep the returned nextCursor as a string and pass it to
the next call, also after an empty page:
curl --fail-with-body -sS "$API/events" \
-H "Authorization: Bearer $SPREADU_KEY" > events.json
CURSOR=$(jq -r '.nextCursor' events.json)
curl --fail-with-body -sS "$API/events?after=$CURSOR&wait=5" \
-H "Authorization: Bearer $SPREADU_KEY" | jqSave your cursor only after you've safely processed the events. Follow changes explains the feed in full.
Run a small receiver on your computer and expose it with a public HTTPS tunnel,
as described in Try it on your computer.
In Test mode, add the tunnel URL in the portal's webhook settings, subscribe to
* and save the one-time whsec_... secret in your receiver.
Send a test ping to check your signature code, then create another test export to receive real export events. A ping has no feed cursor and doesn't replace handling a real event.
Open the delivery in the portal's delivery inspector. The request body is exactly what was signed. The response shows your receiver's status, a short preview of its body and the duration. Resend keeps the event's identity and body, with a fresh timestamp and signature. Test endpoints keep the captures of their last 20 deliveries; live endpoints keep status details only.
That's a complete round trip. From here, the reference integrations show the whole cycle in working TypeScript and PHP, and the simulator lets you throw corrections, withdrawals and expiry at your code.
Every scenario uses labelled test patterns instead of photographs. Each file names its spread or page, revision and part, with production guides and colour bars. The frozen pixel dimensions in the export are authoritative. The manifest, ZIP and order summary follow the normal production format.
| Scenario | What you get | What to try |
|---|---|---|
spreads-jpg | Ten light JPG spreads, sRGB, 300 DPI. The default. | Download every file, verify checksums and record a receipt. |
pages-pdf | PDF output with a combined PDF and individual page files. | Handle COMBINED_PDF packages and page files without assuming JPGs. |
cover-and-inner | A cover with a spine, plus inner spreads. | Route COVER and INNER parts separately and look at the spine guide. |
with-order | An order number, an external ID and two printed copies. | Read the current order and each revision's frozen order. Copies are not album length. |
print-size | Full-size files for throughput checks. | Measure download time and practise resuming. Read sizeBytes; compressed sizes vary. |
correction | Revision 1 becomes available, then revision 2 replaces it automatically a few seconds later. | Stop producing the withdrawn revision and download revision 2. |
expiring-soon | A downloadable revision with a one-hour window. | Inspect downloadableUntil, then send a warning or expire it. |
Each scenario sends export.requested, then export.available. The
correction scenario continues with withdrawn, requested and available for
revision 2. If your integration confirms revision 1 before the correction
runs, the scenario ends there: no revision 2 follows, also after an unlock. For
a correction you control yourself, use the
simulator.
409 SANDBOX_EXPORT_LIMIT. Reset when you
want a fresh start.rateLimit that GET /me reports./sandbox/ also count against a separate allowance
of 60 per minute, which /me doesn't report.X-RateLimit-* headers on each
response describe whichever of these has the fewest requests left.The readiness checklist in the portal fills itself in from what your integration actually did with a test key:
GET /events with
after. Following the export list's nextCursor doesn't count.When every item is ticked, Request live access emails [email protected] with your lab and your checklist. The Spreadu team reviews the request. Once live access is on, create a live key and swap it into your application. The base URL and your production handling stay the same; the simulator endpoints are only for your test harness.
Start the live feed fresh
Test and live keys read separate event streams. When you switch, throw away
the test cursor and start the live feed without after.
Something not working? Troubleshooting covers the usual suspects.
Allow analytics to help us improve these docs? We measure page visits and outgoing links. No session recordings. Privacy policy