Finalize the sample spread
Exists for ss_test_ keys only: finalizes the sandbox loan’s sample spread through the same operation the workspace’s Finalize runs, so the snapshot, the lock and the spread.finalized event are what a live finalize produces, with livemode: false the only difference. Needs spreads:write. The optional external_user_id lands in the snapshot’s finalized_by_external_user_id. Answers 404 when the loan is not in the sandbox, 409 spread_already_finalized until a reopen, and 409 spread_not_ready when no sample document has completed on the loan; the sample spread is built from the tax-1065-2024 sample. A live key gets 403 mode_mismatch. Honors Idempotency-Key: a replay returns the same snapshot_id and event_id and queues nothing.
Requires the spreads:write scope. Rate limit: 10 requests per minute per key (the strict lane).
Authentication
Bearer token. Use ss_live_… for live data or ss_test_… for the sandbox (test mode). See Authentication.
Path parameters
Headers
Idempotency token. Retries that reuse the key within 24h replay the original response. Up to 255 characters; a UUID is typical. See Idempotency.
Pin the API version, e.g. 2026-10-07. Omit to get the latest. See Versioning.
Request
Opaque id of your own end user, 1 to 256 characters once trimmed. Lands in the snapshot’s
finalized_by_external_user_id, exactly as an embed session’s finalize would stamp it. Omit it and the
field reads null.
Response headers
Set to true when the response is replayed from the idempotency cache for a request that re-presented an Idempotency-Key it had already used. Absent on the original (winner) response. A replay repeats the original status and body. When the original could not be stored (an unhandled server fault, or a body over the 1 MiB replay cap) the replay is an error envelope that says so; the operation is never re-run under the same key.
The API surface version the server resolved for this request. Always present, regardless of whether the client supplied the request-side SpreadSpace-Version header. Default: 2026-10-07.
Request budget of the endpoint’s rate-limit policy per 60-second sliding window. See Rate limits.
Requests left in the current window. Suppressed on 429 responses produced outside the rate limiter (for example a usage throttle), where a remaining budget would be misleading.
Seconds until a guaranteed-fresh window.
The active policy in limit;w=window-seconds form.
Response
The final snapshot this finalize minted.
The documents-only machine snapshot minted beside it.
The id of the spread.finalized event this finalize queued; the delivery’s id and
SpreadSpace-Event-Id equal it.