# Tapebloom Partner API documentation > Plain-text copy of https://docs.tapebloom.com. OpenAPI spec: https://docs.tapebloom.com/openapi.json. Contract version 1.0.0-pilot. ## Tapebloom Partner API URL: https://docs.tapebloom.com > Early access. Tapebloom is building its production and fulfillment operations and is opening the API to select partners. Keys come by invitation through the partner portal, and only test mode is open: test orders are never made or shipped. This documentation describes the service being built. The Partner API is a server-to-server JSON API. Every path below is relative to `https://api.tapebloom.com/v1`. The full contract is the OpenAPI 3.1 spec (https://docs.tapebloom.com/openapi.json), and every page here is also available as one plain-text file (https://docs.tapebloom.com/llms-full.txt) for tools. ### Set up with AI Using an AI coding tool? Copy this prompt into it. It points the tool at these docs and the spec, walks it through the flow below, and tells it to read your key from the `TAPEBLOOM_API_KEY` environment variable. The prompt never contains a key. "Set up with AI" prompt (copy it into your AI coding tool): ```text Help me integrate the Tapebloom Partner API into this codebase. Read these first, and treat the OpenAPI spec as the source of truth for paths, fields, states and error codes. Do not guess fields that are not in it. - Docs: https://docs.tapebloom.com - Full docs as plain text: https://docs.tapebloom.com/llms-full.txt - OpenAPI 3.1 spec: https://docs.tapebloom.com/openapi.json Setup - Base URL: https://api.tapebloom.com/v1 - Read the API key from the TAPEBLOOM_API_KEY environment variable. Never hard-code, log or commit it, and never send it to a browser or mobile app: call the API from server code only. If the variable is not set, stop and ask me to set it; do not ask me to paste the key into this chat. - Start in test mode with a tb_test_ key. Tapebloom is in early access and refuses live keys (403 live_mode_unavailable); test orders are never made or shipped. - Send `Authorization: Bearer ` and `Content-Type: application/json`. Paths have no trailing slash. Build the flow end to end 1. Quote: POST /quotes with items (format, quantity, runtime_seconds) and ship_to. Keep the quote id and pick a service from shipping_options. A quote expires after 24 hours and is used by one order. 2. Upload each audio file and the artwork (sized to each surface's canvas from GET /artwork_templates): POST /uploads with kind, size_bytes, sha256 (hex) and content_type; PUT the exact bytes to upload.url; then POST /uploads/{id}/finalize, which answers 202 with state processing while the bytes are checked; GET /uploads/{id} until state is finalized (wait 2s, then double the wait up to 30s between checks) and use its asset_version_id (a rejected upload has rejected_reason: start a new upload). 3. Card on file: GET /billing. If payment_method is null, POST /billing/setup and have a person complete the Stripe page it returns (Stripe test cards in test mode). Orders need a card first (409 payment_method_required). 4. Order: POST /orders with quote_id, shipping_service, items that match the quote's formats and quantities in order (tracks[].asset_version_id, plus tracks[].side, A or B, on every cassette track, optional tracks[].title and artist, and optional surfaces: { : artwork asset_version_id } using the surfaces from GET /artwork_templates), and rights_warranty: true only once the account holder has accepted the rights warranty in the partner agreement. 5. Follow the order: webhooks, GET /orders/{id}, and GET /events?order_id=…&after_sequence=… to fill gaps. Fix an order in needs_attention with POST /orders/{id}/revisions; cancel with POST /orders/{id}/cancel. Idempotency - Send an Idempotency-Key header on every write that takes one (quotes accept one; uploads, finalize, orders, revisions, cancel, webhook endpoint creation, secret rotation and delivery replays require one). - Generate one key per logical operation, store it with your own record, and reuse it when retrying after a timeout, a network error or a 5xx. Use a new key for a different request; 422 idempotency_mismatch means a key was reused for a different request. - On 429 rate_limited (300 requests a minute per key), wait the seconds in the Retry-After header, then retry with the same Idempotency-Key. Webhooks - Create an endpoint with POST /webhook_endpoints and store the returned signing secret (whsec_…) in an environment variable such as TAPEBLOOM_WEBHOOK_SECRET. It is shown once. - Verify every delivery before trusting it. The Tapebloom-Signature header is `t=,v1=`: v1 is HMAC-SHA256 of `${t}.${rawBody}` with the secret. Use the raw body before parsing, compare in constant time, accept a match on any v1 (there is one per active secret during a rotation), and reject timestamps more than 5 minutes from now. - The same event can arrive more than once. Record the event id in the same database transaction as its effects and answer a repeat with 2xx. Order events per order with `sequence`, not by arrival. Errors - Every error is `{ "error": { "code", "message", "field"?, "request_id" } }`. Branch on `code`, and log `request_id`. Write tests that run against test mode only. When you finish, tell me what you built and what I still need to configure (environment variables, the webhook URL, the card on file). MCP server - The Tapebloom MCP server at https://mcp.tapebloom.com/mcp offers the same API as tools (quotes, uploads, orders, events, billing), with test keys only. It is handy for trying the flow while you build. Before placing, revising or cancelling an order through it, show me what will happen and the total, and wait for my OK. To connect it, add the snippet for your tool; it reads the key from TAPEBLOOM_API_KEY when the tool starts. - Claude Code (.mcp.json): { "mcpServers": { "tapebloom": { "type": "http", "url": "https://mcp.tapebloom.com/mcp", "headers": { "Authorization": "Bearer ${TAPEBLOOM_API_KEY}" } } } } - Cursor (.cursor/mcp.json): { "mcpServers": { "tapebloom": { "url": "https://mcp.tapebloom.com/mcp", "headers": { "Authorization": "Bearer ${env:TAPEBLOOM_API_KEY}" } } } } ``` Want your AI tool to call the API itself, as tools? Connect it to the MCP server (https://docs.tapebloom.com/mcp). ### Before you start - A `tb_test_` key from the partner portal (API keys tab), exported as `TAPEBLOOM_API_KEY`. Keep it on your server. - A card on file for test mode (Billing tab in the portal, or POST /billing/setup (https://docs.tapebloom.com/billing)). Test mode takes Stripe's test cards. - An audio file and, if you have one, artwork. The examples use `side-a.wav` and `cover.png`. ```bash export TAPEBLOOM_API_KEY=tb_test_… # from the partner portal; never commit it export TB=https://api.tapebloom.com/v1 ``` ### 1. Get a quote A quote prices items for a shipping address and lists the shipping services you can choose. Formats are `vinyl_12`, `vinyl_7`, `cassette`, `cd_jewel`, `cd_jacket`; `runtime_seconds` is the item's total programme length. A quote expires after 24 hours and is used by one order. ```bash curl -sS "$TB/quotes" \ -H "Authorization: Bearer $TAPEBLOOM_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: quote-$(uuidgen)" \ -d '{ "items": [{ "format": "cassette", "quantity": 1, "runtime_seconds": 1800 }], "ship_to": { "name": "Sam Rivera", "line1": "1 Example Street", "city": "Portland", "region": "OR", "postal_code": "97201", "country": "US" } }' ``` 201 Created (prices come from your mode's price list): ```json { "id": "6f1c2a8e-5b7d-4e2f-9a31-0c4d8b2e7f15", "object": "quote", "environment": "test", "currency": "usd", "items": [{ "position": 1, "format": "cassette", "quantity": 1, "runtime_seconds": 1800, "unit_price_minor": …, "setup_fee_minor": …, "amount_minor": … }], "subtotal_minor": …, "shipping_options": [{ "service": "…", "amount_minor": …, "min_days": …, "max_days": … }], "ship_to": { … }, "expires_at": "…", "created_at": "…" } ``` ### 2. Upload the audio Declare the file with its size and SHA-256, `PUT` the exact bytes to the signed URL you get back, then finalize. The bytes are checked in the background, and the finalized upload has an immutable `asset_version_id`. See Uploads (https://docs.tapebloom.com/uploads). ```bash FILE=side-a.wav SIZE=$(wc -c < "$FILE" | tr -d ' ') SHA=$(shasum -a 256 "$FILE" | cut -d' ' -f1) curl -sS "$TB/uploads" \ -H "Authorization: Bearer $TAPEBLOOM_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: upload-side-a-v1" \ -d "{\"kind\":\"audio\",\"size_bytes\":$SIZE,\"sha256\":\"$SHA\",\"content_type\":\"audio/wav\",\"filename\":\"$FILE\"}" # → { "id": "", "object": "upload", "kind": "audio", "state": "created", # "upload": { "method": "PUT", "url": "", "expires_in": … } } curl -sS -X PUT "" -H "Content-Type: audio/wav" --data-binary @"$FILE" ``` ### 3. Finalize ```bash curl -sS -X POST "$TB/uploads//finalize" \ -H "Authorization: Bearer $TAPEBLOOM_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: finalize-side-a-v1" \ -d '{}' # → 202 { "id": "", "object": "upload", "state": "processing" } # Check until it is finalized (usually within a minute), waiting 2s, then 4s, 8s… up to 30s: curl -sS "$TB/uploads/" -H "Authorization: Bearer $TAPEBLOOM_API_KEY" # → { "id": "", "object": "upload", "kind": "audio", "state": "finalized", # "asset_version_id": "9b2e4c71-3a5f-4d8e-b6c0-2f7a1e9d4c38", "created_at": "…" } ``` Repeat steps 2 and 3 for artwork with `"kind": "artwork"` and its own content type, such as `image/png`. ### 4. Create the order Reference the quote, one of its shipping services, and your finalized versions. Items must match the quote's formats and quantities, in order. Every cassette track needs a `side` (`A` or `B`); `title` and `artist` are optional and print in tracklists. Artwork goes on named surfaces (see artwork templates (https://docs.tapebloom.com/validation#artwork-templates)); a surface you leave out prints Tapebloom's default design. `rights_warranty: true` records that you accept the rights warranty in your partner agreement. ```bash curl -sS "$TB/orders" \ -H "Authorization: Bearer $TAPEBLOOM_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: order-1042" \ -d '{ "quote_id": "6f1c2a8e-5b7d-4e2f-9a31-0c4d8b2e7f15", "shipping_service": "", "items": [{ "format": "cassette", "quantity": 1, "surfaces": { "jcard_outside": "4d7a0f2c-8e1b-4b9a-a5d3-6c2e9f0b1a47" }, "tracks": [{ "asset_version_id": "9b2e4c71-3a5f-4d8e-b6c0-2f7a1e9d4c38", "side": "A", "title": "Opening", "artist": "Example Artist" }] }], "rights_warranty": true, "external_ref": "shop-order-1042" }' ``` 201 Created: ```json { "id": "c3e8a1f4-2b6d-4f7a-9e05-8d1b3c7a2e96", "object": "order", "environment": "test", "state": "received", "revision": 1, "items": [ … ], "created_at": "…", "updated_at": "…" } ``` ### 5. Follow it Add a webhook endpoint (https://docs.tapebloom.com/webhooks) to hear about every state change, or read the order with `GET /orders/{id}`. To reconcile, `GET /events?order_id=…&after_sequence=…` returns the order's history in sequence with no gaps. The states are described in Orders (https://docs.tapebloom.com/orders). ```bash curl -sS "$TB/orders/c3e8a1f4-2b6d-4f7a-9e05-8d1b3c7a2e96" -H "Authorization: Bearer $TAPEBLOOM_API_KEY" ``` ## Authentication and environments URL: https://docs.tapebloom.com/authentication Send your key as a Bearer token on every request to `https://api.tapebloom.com/v1`: ```bash curl -sS "https://api.tapebloom.com/v1/billing" -H "Authorization: Bearer $TAPEBLOOM_API_KEY" ``` Keep keys on your server. Cross-origin browser requests receive no CORS allowance, so a key in a web page or app would not work anyway, and would be exposed. ### Test and live The key, not the host, selects the mode. Every object carries `environment`, and test and live data never mix: a test order can only use test uploads, test quotes and the test card on file. Key prefix | Mode | Status `tb_test_` | test | Open to invited partners. Orders are never made or shipped; cards are Stripe test cards. `tb_live_` | live | Refused with 403 `live_mode_unavailable` until live payments and production are ready. ### Getting a key Keys come by invitation. Invited partners create and revoke them in the partner portal. A key is shown once when it is created; Tapebloom stores only a fingerprint, so a lost key is revoked and replaced, not recovered. ### Scopes Each operation needs one scope, listed in the API reference (https://docs.tapebloom.com/reference). A key without it gets 403 `insufficient_scope`. Scope | Allows `orders:read` | List and read orders. `orders:write` | Quotes, orders, revisions and cancellations. `uploads:write` | Start, finalize and check uploads. `events:read` | Read event history. `webhooks:manage` | Webhook endpoints and deliveries. `billing:read` | Read the card on file. `billing:write` | Start a card setup. ### Errors - 401 `missing_api_key`: no `Authorization: Bearer` header. - 401 `invalid_api_key`: the key is unknown or revoked. - 403 `insufficient_scope`: the key lacks the operation's scope. - 403 `live_mode_unavailable`: a live key, during early access. ## Uploads URL: https://docs.tapebloom.com/uploads Files never pass through the API. You declare a file, `PUT` its bytes to a signed URL, then finalize it. An order refers to files by `asset_version_id`. 1. `POST /uploads` with `kind` (`audio` or `artwork`), `size_bytes`, `sha256` (64 hex characters) and `content_type`. Optional: `filename`, `recording_title`, and `asset_id` to add a new version to an existing asset. Needs an `Idempotency-Key`; a repeat with the same key returns the same upload with a fresh URL. 2. `PUT` the exact bytes to `upload.url` before `upload.expires_in` seconds pass. The URL is single-use. 3. `POST /uploads/{id}/finalize` with `{}`. It checks the stored size, moves the file out of reach of the upload URL (it can no longer be replaced) and answers 202 with `state: processing` while the bytes are checked against the declared SHA-256 in the background. 4. `GET /uploads/{id}` until `state` is `finalized`, usually within a minute (longer for very large files). Wait 2 seconds before the first check, then double the wait after each check, up to 30 seconds between checks; stop at `finalized` or `rejected`. A finalized upload has the `asset_version_id` to use in orders. ### Upload states State | Meaning `created` | Waiting for the bytes and for finalize. An upload left here for a day is rejected as `upload_expired`. `processing` | Finalize was called; the bytes are being checked. `finalized` | The bytes matched. `asset_version_id` is set, and the version never changes. `rejected` | `rejected_reason` says why: `size_mismatch`, `checksum_mismatch`, `file_missing`, `verification_failed` (the file could not be checked after several tries; uploading it again usually works) or `upload_expired`. Start a new upload. ### Retrying finalize Finalize is safe to retry with the same `Idempotency-Key`, including after a timeout: a retry resumes the work and returns the current state (202 while processing), and once the upload is finalized it returns the same version marked `Idempotent-Replayed: true`. A file that did not match is a 422 with the reason. Its key is bound to this upload and this exact request before any work starts, so a different request needs a new key, even if the first one failed. Finalizing before the bytes are stored returns 409 `upload_incomplete`. ### Quality checks Finalizing only checks that the bytes are the ones you declared. Decoding, runtime and artwork checks run later, at order validation; a problem moves the order to `needs_attention`. See Validation and artwork (https://docs.tapebloom.com/validation). Computing the declaration (Node): ```ts import { createHash } from "node:crypto"; import { readFile } from "node:fs/promises"; const bytes = await readFile("side-a.wav"); const declared = { kind: "audio", size_bytes: bytes.byteLength, sha256: createHash("sha256").update(bytes).digest("hex"), content_type: "audio/wav", filename: "side-a.wav", }; ``` ## Orders and lifecycle URL: https://docs.tapebloom.com/orders An order is created from a quote and finalized uploads (see the quickstart (https://docs.tapebloom.com/#order)). The quote's price, address and shipping are committed for 72 hours; validation confirms against that commitment. Request limits: at most 100 items per order and 200 tracks per item. Each format's manufacturing limits, such as runtime, are checked by validation. Formats: `vinyl_12`, `vinyl_7`, `cassette`, `cd_jewel`, `cd_jacket`. Each track is `{ "asset_version_id": …, "side": "A" }`, in play order. On a cassette every track needs a `side`, `A` or `B`; validation moves an order with a cassette track missing one to `needs_attention` with `track_side_missing`. ### States State | Meaning `received` | The order is accepted and stored. Next: validation. `validating` | Files, runtime and artwork are checked against the format, and the quote's commitment is confirmed. `needs_attention` | Something must be fixed; `attention_reason` says what, as a code. Fix it with a revision, or cancel. `materials_hold` | Valid, but materials could not be reserved yet. It moves on to `awaiting_payment` once they can be. `awaiting_payment` | The card on file is charged once for the committed total. A decline leaves the order here until you save a new card. `released` | Paid and released to production. From here a cancel request opens an exception instead of cancelling. `cancelled` | Cancelled before release. Reserved materials are returned and any payment is refunded. `complete` | The carrier has accepted shipments holding every unit the order needs. ### Transitions - `received` → `validating` - `validating` → `needs_attention` - `needs_attention` → `validating` - `validating` → `materials_hold` - `validating` → `awaiting_payment` - `materials_hold` → `awaiting_payment` - `awaiting_payment` → `materials_hold` - `awaiting_payment` → `released` - `released` → `complete` - `received`, `validating`, `needs_attention`, `materials_hold`, `awaiting_payment` → `cancelled` Every transition is an event (`order.received`, `order.needs_attention`, …) delivered to your webhooks (https://docs.tapebloom.com/webhooks) and kept in `GET /events`. Test orders are never made or shipped. ### Fixing an order Only an order in `needs_attention` can be revised. `POST /orders/{id}/revisions` replaces its items (earlier revisions stay as history) and returns it to validation. Each revision needs `rights_warranty: true` and an `Idempotency-Key`. Different formats or quantities, a different shipping service, or an expired price commitment need a new `quote_id`. Revising an order in any other state returns 409 `order_not_revisable`. ### Cancelling `POST /orders/{id}/cancel`, optionally with a `reason` code such as `changed_mind`. Before release the order is cancelled, reserved materials are returned and any payment is refunded. After release the order does not change: the response is 409 `order_released` with the `exception_id` opened for your request. ### Listing and history - `GET /orders` lists orders newest first; filter with `state` and page with `limit` and `starting_after`. - `GET /orders/{id}` returns the order with its current items, amount, latest payment, units and shipments. - `GET /events?order_id=…&after_sequence=…` returns one order's events in sequence with no gaps. Use it to reconcile or to recover missed webhooks. - `GET /events` without `order_id` is the account-wide list, for browsing. An event committed late can land behind a cursor you have already passed, so do not rely on advancing it to see every event. ### Units and shipments Once released, `units` lists the physical units made for the order and `shipments` the parcels holding them, with carrier, tracking number and tracking URL when known. The order is `complete` once the carrier has accepted shipments holding every unit it needs. ## Billing URL: https://docs.tapebloom.com/billing Each mode has its own card on file. Orders need one first: without it, `POST /orders` returns 409 `payment_method_required`. - `GET /billing` returns the card (brand, last four digits, expiry) or `payment_method: null`. - `POST /billing/setup` with a `return_url` (https) returns a Stripe-hosted page, valid until `expires_at`, where someone on your team saves a card. Card details go to Stripe only. Test mode takes Stripe's test cards. You can also save a card in the partner portal's Billing tab. ### When an order is charged Each order is charged once, off-session, for its committed total (product plus quoted shipping) when validation passes and the order reaches `awaiting_payment`. The order's `payment` object and `payment.*` events follow the charge. Payment states: `pending`, `requires_action`, `succeeded`, `failed`, `canceled`, `unknown`. - A declined card is not charged again until you save a new one. The order waits in `awaiting_payment` and you receive `payment.failed`. - Saving a new card charges the orders that were waiting after a decline. - Cancelling before release refunds any payment (`refund.succeeded` or `refund.failed`). If billing is not available in a mode yet, `POST /billing/setup` returns 503 `billing_unavailable`. ## Webhooks URL: https://docs.tapebloom.com/webhooks Tapebloom sends each event as a signed JSON `POST` to your enabled endpoints in the event's mode. Create one with `POST /webhook_endpoints`: ```bash curl -sS "https://api.tapebloom.com/v1/webhook_endpoints" \ -H "Authorization: Bearer $TAPEBLOOM_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: endpoint-main-v1" \ -d '{ "url": "https://example.com/tapebloom/webhooks", "event_types": ["order.needs_attention", "order.complete"] }' ``` The response includes the signing `secret` (`whsec_…`). Store it, for example as `TAPEBLOOM_WEBHOOK_SECRET`; it is not shown again except in a replay of the same request. Omit `event_types` to receive every type. The URL must be `https` (in test mode, `http://localhost` and `http://127.0.0.1` also work). At most 10 endpoints can be enabled per mode. ### Event types `order.awaiting_payment`, `order.cancelled`, `order.complete`, `order.exception_opened`, `order.materials_hold`, `order.needs_attention`, `order.received`, `order.released`, `order.validating`, `payment.canceled`, `payment.failed`, `payment.requires_action`, `payment.succeeded`, `refund.failed`, `refund.succeeded`, `shipment.delivered`, `shipment.returned`, `shipment.shipped` ### The delivery ```json { "id": "1a7e3c90-4f2b-4d6a-8c15-9e0b7d2f3a64", "type": "order.needs_attention", "occurred_at": "…", "environment": "test", "order_id": "c3e8a1f4-2b6d-4f7a-9e05-8d1b3c7a2e96", "sequence": 3, "data": { "order_id": "…", "object": "order", "object_id": "…", "state": "needs_attention", "reason": "…" } } ``` The headers carry `Tapebloom-Signature` and `Tapebloom-Event-Id`. The body is the same bytes on every attempt for one event. ### Verifying the signature `Tapebloom-Signature: t=,v1=`. Each `v1` is an HMAC-SHA256 of `${t}.${rawBody}` with your endpoint's signing secret. During a secret rotation there is one `v1` per active secret. Every attempt is freshly signed with a new `t`. - Verify against the raw body, before parsing it. - Compare in constant time, and accept a match on any `v1`. - Reject timestamps more than 5 minutes from now, either way. Verifying a delivery (TypeScript, Node): ```ts import { createHmac, timingSafeEqual } from "node:crypto"; const TOLERANCE_SECONDS = 300; export function verifyTapebloomSignature(rawBody: string, header: string | null, secrets: string[]): boolean { if (!header) return false; let t: number | undefined; const candidates: Buffer[] = []; for (const part of header.split(",")) { const [key, value] = part.trim().split("=", 2); if (key === "t" && /^\d{1,12}$/.test(value ?? "")) t = Number(value); else if (key === "v1" && /^[0-9a-f]{64}$/.test(value ?? "")) candidates.push(Buffer.from(value, "hex")); } if (t === undefined || candidates.length === 0) return false; if (Math.abs(Math.floor(Date.now() / 1000) - t) > TOLERANCE_SECONDS) return false; return secrets.some((secret) => { const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest(); return candidates.some((c) => c.length === expected.length && timingSafeEqual(c, expected)); }); } // A Next.js route handler (any Fetch API runtime works the same way). export async function POST(request: Request) { const rawBody = await request.text(); const ok = verifyTapebloomSignature(rawBody, request.headers.get("tapebloom-signature"), [ process.env.TAPEBLOOM_WEBHOOK_SECRET!, ]); if (!ok) return Response.json({ error: "bad_signature" }, { status: 401 }); const event = JSON.parse(rawBody); // Record event.id and apply its effects in ONE database transaction; // if the id is already recorded, it is a repeat: do nothing. return Response.json({ received: true }); } ``` ### Duplicates and ordering - The same event may arrive more than once, each time freshly signed. Record its `id` in the same database transaction as its effects, and acknowledge a repeat with 2xx without repeating them. - There is no global ordering. Use `sequence` per `order_id`, and `GET /events?order_id=…&after_sequence=…` to fill gaps. - For effects outside your database (an email, another API), pass the event `id` as that service's idempotency key. ### Retries Answer with a 2xx within 10 seconds. Redirects are not followed. A failed delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 5 hours, then every 10 hours, for up to 3 days; then it is `abandoned`. Delivery states: `pending`, `delivered`, `abandoned`. - `GET /webhook_endpoints/{id}/deliveries` lists an endpoint's deliveries; `GET /webhook_deliveries/{id}` shows every attempt with its status code or error. - `POST /webhook_deliveries/{id}/replay` sends a delivery again now, with a new 3-day retry window. The event's id, sequence and body are unchanged. - `POST /webhook_endpoints/{id}/disable` and `/enable` set the endpoint's state; both are safe to repeat and take no `Idempotency-Key`. ### Rotating the secret `POST /webhook_endpoints/{id}/rotate_secret` returns a new `secret`. The old one keeps signing alongside it for `overlap_hours` (default 24, 0 to 168), so each delivery carries both signatures and you can switch without a gap. Verify against both secrets until you have deployed the new one. ## Errors, idempotency and pagination URL: https://docs.tapebloom.com/errors ### Errors Every failure, including 404 and 405, returns the same shape, and every response carries a `Request-Id` header. Codes are stable strings: branch on `code`, show `message` to developers, and quote `request_id` when you contact us. ```json { "error": { "code": "invalid_sha256", "message": "…", "field": "sha256", "request_id": "req_4f0c8e2a9b7d4c1e8a3f6b2d0e9c7a15" } } ``` Status | Meaning and codes 400 | The body is not JSON, or the Idempotency-Key is missing or malformed. 401 | The API key is missing or not valid (`missing_api_key`, `invalid_api_key`). 403 | The key lacks a scope (`insufficient_scope`), or is a live key (`live_mode_unavailable`). 404 | No such resource for this key, or no such path. 409 | The resource's state does not allow this (`order_not_revisable`, `quote_already_used`, `upload_incomplete`, `too_many_endpoints`, `endpoint_disabled`, `delivery_in_flight`, `payment_method_required`, `partner_terms_required`). 413 | The body is over 2 MiB (`body_too_large`). It may be refused only after more of it was sent. 415 | The body is not application/json. 422 | The request is invalid; `field` names the problem, `code` says what it is. 429 | Too many requests for this API key (`rate_limited`): 300 a minute across all endpoints. Wait the number of seconds in `Retry-After`, then retry with the same Idempotency-Key. 500 | Our error. Retrying is safe with the same Idempotency-Key. Other codes in the contract: `format_unavailable` (no price for a format in your mode), `idempotency_mismatch`, `order_released` (409, with `exception_id`), `invalid_url` and `billing_unavailable` (503). A 422 names the problem in `field`. ### Idempotency - Writes that change things require an `Idempotency-Key` header (1–255 printable ASCII characters); `POST /quotes` accepts one. Enabling, disabling and billing setup take none. - Keys are scoped to your account, mode and operation, and kept for 30 days. - Repeating a request with the same key returns the original response, marked `Idempotent-Replayed: true`. - Reusing a key for a different request returns 422 `idempotency_mismatch`. - A request that failed is not stored, so you can correct it and retry with the same key. Finalize is the exception: see Uploads (https://docs.tapebloom.com/uploads#finalize-retries). - A 500 is our error. Retrying is safe with the same key. Generate one key per logical operation (a UUID saved with your own record works well) and reuse it for every retry of that operation. ### Pagination List endpoints return `{ "object": "list", "data": […], "has_more": … }`. Pass `limit` (1–100) and, for the next page, `starting_after` with the last id of the page you have. `GET /events` for one order pages by `after_sequence` instead. ### Other limits - Each API key can make 300 requests a minute across all endpoints. Past that you get 429 `rate_limited` with a `Retry-After` header in seconds: wait that long, then retry (with the same `Idempotency-Key` for writes). - Request bodies are limited to 2 MiB (413 `body_too_large`). Upload files go to the signed URL, not through the API. - Bodies must be `application/json` (415 otherwise). - Paths have no trailing slash: `/orders/` is a 404, not a redirect. - Amounts are integers in the currency's minor unit (cents for `usd`), with an explicit lowercase currency. ## Validation and artwork URL: https://docs.tapebloom.com/validation A new or revised order moves to `validating`. Every file is fully decoded, then checked against its format and, for artwork, its surface's template. The order then moves to `awaiting_payment` (and is charged), or to `needs_attention` with `findings` to fix with a revision (https://docs.tapebloom.com/orders#revisions). Some findings are reviewed by Tapebloom staff instead: the order waits in `validating`, uncharged, until they are decided. In test mode reviews are approved at once. ### Validation reason codes Each finding has a stable `code`, the item, track or `surface` it concerns, and what was `measured` and `expected`. `attention_reason` and the `order.needs_attention` event carry the first one you need to fix. Treat a code you do not recognize as needing a person to look. Code | Means | Who acts `audio_unreadable`, `audio_empty`, `audio_truncated` | The file does not decode fully, has no audio, or stops early | You `audio_sample_rate_low`, `audio_bit_depth_low`, `audio_bit_depth_unknown` | Below 44.1 kHz or 16-bit, or the depth cannot be read | You `audio_channels_unsupported` | Not mono or stereo | You `runtime_changed` | The item runs longer than quoted: quote again | You `track_side_missing`, `side_runtime_exceeded` | A cassette track has no side, or a side is too long for the tape | You `artwork_unreadable`, `artwork_format_unsupported`, `artwork_too_many_pixels` | The image does not decode, is not PNG, JPEG, TIFF or WebP, or exceeds 200 megapixels | You `artwork_dimensions_mismatch` | Proportions differ from the template's canvas by more than a pixel | You `artwork_color_cmyk` | CMYK artwork: send RGB, ideally sRGB | You `artwork_resolution_too_low` | Below the template's `min_ppi` at its printed size | You `artwork_surface_missing` | A required surface has no artwork and no default design | You `artwork_resolution_low` | Between `min_ppi` and `target_ppi` (300) at its printed size | Staff review `artwork_template_unapproved` | The surface's template awaits a print-and-fit proof | Staff review `content_mismatch`, `file_missing` | Tapebloom's stored copy is wrong or missing; staff may ask you to upload again | Staff `quote_required`, `price_commitment_expired` | The order has no quote, or its price commitment has passed: revise with a new quote | You ### Artwork templates Every printed surface has a versioned template. `GET /artwork_templates` (optionally `?format=cassette`) returns each surface's trim size, bleed, safe area and folds in millimetres, its printable mask, the zone kept for each unit's QR code, and the pixels needed to reach 300 ppi. Send artwork that covers the whole `canvas` (trim plus bleed) at the same proportions; a larger file is fine. Resolution is measured at the printed size from the decoded pixels; the file's DPI setting is ignored. Format | Surfaces (keys for `surfaces`) `cassette` | `jcard_outside`, `label_side_a`, `label_side_b` `cd_jewel` | `front_insert`, `tray_card`, `disc_face` `cd_jacket` | `jacket`, `disc_face` Templates are `provisional` until a print-and-fit proof on the production stock approves them. While provisional, the geometry may change in a new version; an order keeps the version it was submitted with, and its artwork is reviewed by staff. Disc faces print on a Primera Bravo 4202; paper on an Epson EcoTank. ## MCP server URL: https://docs.tapebloom.com/mcp > Test mode only. The MCP server accepts `tb_test_` keys and refuses live keys, even once the API opens live mode. Test orders are never made, charged for real or shipped. The Tapebloom MCP server offers the Partner API as tools to AI agents and coding tools that speak the Model Context Protocol (https://modelcontextprotocol.io). It is at `https://mcp.tapebloom.com/mcp` (Streamable HTTP, stateless) and authenticates with your API key as a Bearer token, exactly like the API. ### Connect Export your test key as `TAPEBLOOM_API_KEY`, then add the server to your tool's config. Each snippet reads the key from the environment when the tool starts; never paste the key into the file. Claude Code: .mcp.json: ```json { "mcpServers": { "tapebloom": { "type": "http", "url": "https://mcp.tapebloom.com/mcp", "headers": { "Authorization": "Bearer ${TAPEBLOOM_API_KEY}" } } } } ``` Cursor: .cursor/mcp.json: ```json { "mcpServers": { "tapebloom": { "url": "https://mcp.tapebloom.com/mcp", "headers": { "Authorization": "Bearer ${env:TAPEBLOOM_API_KEY}" } } } } ``` Other clients: use the URL above with an `Authorization: Bearer ` header. ### Tools Each tool is one API operation and returns that operation's response body, so the reference (https://docs.tapebloom.com/reference) describes its fields. A tool is listed only when your key has its scope. Tool | Operation | Scope `list_artwork_templates` | `GET /artwork_templates` | `orders:read` `create_quote` | `POST /quotes` | `orders:write` `create_upload` | `POST /uploads` | `uploads:write` `finalize_upload` | `POST /uploads/{id}/finalize` | `uploads:write` `get_upload` | `GET /uploads/{id}` | `uploads:write` `get_billing` | `GET /billing` | `billing:read` `start_billing_setup` | `POST /billing/setup` | `billing:write` `create_order` | `POST /orders` | `orders:write` `list_orders` | `GET /orders` | `orders:read` `get_order` | `GET /orders/{id}` | `orders:read` `revise_order` | `POST /orders/{id}/revisions` | `orders:write` `cancel_order` | `POST /orders/{id}/cancel` | `orders:write` `list_events` | `GET /events` | `events:read` Upload bytes do not go through MCP: `create_upload` returns a signed URL, the agent PUTs the file there (with `curl`, say), then calls `finalize_upload` and checks `get_upload` until the upload is finalized. Webhook endpoints are managed through the API only. ### Safeguards - Every write takes a required `idempotency_key`, sent as the `Idempotency-Key` header, so an agent can retry safely; reusing one for a different call is `idempotency_mismatch`. - `create_order`, `revise_order` and `cancel_order` are marked destructive. That is a hint to the client: many ask before running such a tool, but MCP does not require it, and how (or whether) a client asks is up to the client and its settings. - `create_order` (and `revise_order` onto a new quote) needs `confirm_total_minor`: the quote's `subtotal_minor` plus the chosen shipping option's `amount_minor`. A call is refused if the total cannot be worked out (`quote_not_found`, `invalid_shipping_service`) or does not match (`total_mismatch`), before the order is sent. - That check proves the agent used the right number, not that a person agreed to it. The server tells agents to show the person the total and wait for their OK, but it cannot see whether they did. In test mode nothing is charged; review your client's tool-approval settings before relying on an agent to order. - `rights_warranty: true` states that the account holder holds the rights to every recording and artwork and accepts the rights warranty. Agents are told to set it only when the person says so. - Every MCP message counts once against the key's API rate limit (300 a minute), refused calls included. A failed call returns the API's error, with its `code` and `request_id`, as a tool error. - Browsers cannot call the server: a request with an `Origin` header is refused. ## API reference URL: https://docs.tapebloom.com/reference Server-to-server API for Tapebloom's partner pilot. Tapebloom is building its production and fulfillment operations and is opening access to select partners; this contract describes the service being built. **Test mode only.** The pilot accepts `tb_test_` keys. Live keys are refused with `live_mode_unavailable` until live payments and production are ready. **Authentication.** Send `Authorization: Bearer `. Keep keys on your server: cross-origin browser requests receive no CORS allowance. **Paths** have no trailing slash: `/orders/` is a 404, not a redirect. Send paths exactly as listed. A path with repeated slashes, such as `/v1//orders`, is normalized by the hosting platform with a 308 redirect that carries no `Request-Id`, before the API sees it. **Errors.** Every failure, including 404 and 405, returns `{ "error": { "code", "message", "field"?, "request_id" } }`. Codes are stable strings. Each response carries a `Request-Id` header. **Amounts** are integers in the currency's minor unit, with an explicit lowercase currency. **Idempotency.** Writes that change things require an `Idempotency-Key` header (1–255 printable ASCII characters); quotes accept one. Keys are scoped to your account, mode and operation, and kept for 30 days. Repeating a request with the same key returns the original response (marked `Idempotent-Replayed: true`); reusing a key for a different request returns 422 `idempotency_mismatch`. A request that failed is not stored, so you can correct it and retry with the same key. The exception is finalize: its key is bound to the upload and the exact request before any work starts, so retry the same request to resume, and use a new key for a different one. Enabling or disabling a webhook endpoint sets a state, is safe to repeat, and takes no key. **Body size.** Request bodies are limited to 2 MiB and answered with 413 `body_too_large` beyond that. The API stops reading at the limit, but the hosting platform may accept more of the body before the API sees it, so the 413 can arrive after you have sent more than 2 MiB. Upload files go to the signed upload URL, not through the API. **Request limits.** An order has at most 100 items and an item at most 200 tracks. These are request limits; each format's manufacturing limits, such as runtime, are checked by validation. **Validation.** A new or revised order moves to `validating` (event `order.validating`). Every file is fully decoded first, so allow a few minutes for large uploads. Audio must be at least 44.1 kHz and 16-bit, mono or stereo; each item must run no longer than quoted; cassette tracks need a `side`, and each side must fit the tape. Then the order either moves to `awaiting_payment` and is charged at once, or to `needs_attention` with `findings` to fix by posting a revision. Artwork is checked against each surface's template (see `GET /artwork_templates`): it must cover the canvas at matching proportions, in RGB, at 300 ppi at its printed size (from 200 ppi staff review it; below, it is refused). Some checks (artwork resolution between 200 and 300 ppi, and artwork on templates not yet approved by a print proof) are reviewed by staff, holding the order in `validating` without charging it; in test mode these reviews are approved at once. Time in review does not count against your 72-hour price commitment. **Events.** `GET /events` with `order_id` and `after_sequence` returns an order's history in sequence with no gaps: use it to reconcile an order or recover missed webhooks. Without `order_id`, the account-wide list is for browsing; an event committed late can land behind a cursor you have already passed, so do not rely on advancing it to see every event. ### Quotes #### POST /quotes (Price items and list shipping options) Scope: orders:write A quote expires 24 hours after it is created and can be used by one order (or one revision). Prices come from the price list configured for your mode; a format without a price returns `format_unavailable`. Parameters: - Idempotency-Key (header): string (pattern ^[\x21-\x7e]{1,255}$) Body: - items (required): array of object (1–100 items) - format (required): "vinyl_12" | "vinyl_7" | "cassette" | "cd_jewel" | "cd_jacket" - quantity (required): integer (1–10000) - runtime_seconds (required): integer (1–86400). Total programme length of the item. - ship_to (required): AddressInput Responses: - 201: The quote. (Quote) - 400: The body is not JSON, or the Idempotency-Key is missing or malformed. (Error) - 401: The API key is missing or not valid (`missing_api_key`, `invalid_api_key`). (Error) - 403: The key lacks a scope (`insufficient_scope`), or is a live key (`live_mode_unavailable`). (Error) - 413: The body is over 2 MiB (`body_too_large`). It may be refused only after more of it was sent. (Error) - 415: The body is not application/json. (Error) - 422: The request is invalid; `field` names the problem, `code` says what it is. (Error) - 429: Too many requests for this API key (`rate_limited`): 300 a minute across all endpoints. Wait the number of seconds in `Retry-After`, then retry with the same Idempotency-Key. (Error) - 500: Our error. Retrying is safe with the same Idempotency-Key. (Error) ### Uploads #### POST /uploads (Start an upload) Scope: uploads:write Declares the file and returns a single-use signed URL: `PUT` the exact bytes to it, then call finalize. A repeat with the same Idempotency-Key returns the same upload with a fresh URL. Parameters: - Idempotency-Key (header, required): string (pattern ^[\x21-\x7e]{1,255}$) Body: - kind (required): "audio" | "artwork" - size_bytes (required): integer (≥ 1) - sha256 (required): string (pattern ^[0-9a-fA-F]{64}$) - content_type (required): string. Example: `audio/wav`, `image/png`. - filename: string (1–255 chars) - asset_id: string (uuid). Add a new version to this existing asset. - recording_title: string (1–300 chars) Responses: - 201: The upload and where to send the bytes. (UploadCreated) - 400: The body is not JSON, or the Idempotency-Key is missing or malformed. (Error) - 401: The API key is missing or not valid (`missing_api_key`, `invalid_api_key`). (Error) - 403: The key lacks a scope (`insufficient_scope`), or is a live key (`live_mode_unavailable`). (Error) - 413: The body is over 2 MiB (`body_too_large`). It may be refused only after more of it was sent. (Error) - 415: The body is not application/json. (Error) - 422: The request is invalid; `field` names the problem, `code` says what it is. (Error) - 429: Too many requests for this API key (`rate_limited`): 300 a minute across all endpoints. Wait the number of seconds in `Retry-After`, then retry with the same Idempotency-Key. (Error) - 500: Our error. Retrying is safe with the same Idempotency-Key. (Error) #### GET /uploads/{id} (Get an upload) Scope: uploads:write The upload's state: `created` (waiting for the bytes), `processing` (finalize was called and the bytes are being verified), `finalized` (with the `asset_version_id` to use in orders) or `rejected` (with `rejected_reason`: `size_mismatch`, `checksum_mismatch`, `file_missing`, `verification_failed` (the file could not be checked after several tries; uploading it again usually works) or `upload_expired`; start a new upload). An upload that never receives its bytes is rejected as `upload_expired` after a day. While polling, wait 2 seconds before the first check, then double the wait after each check, up to 30 seconds between checks; stop at `finalized` or `rejected`. Parameters: - id (path, required): string (uuid). The upload. Responses: - 200: The upload. (Upload) - 401: The API key is missing or not valid (`missing_api_key`, `invalid_api_key`). (Error) - 403: The key lacks a scope (`insufficient_scope`), or is a live key (`live_mode_unavailable`). (Error) - 404: No such resource for this key, or no such path. (Error) - 429: Too many requests for this API key (`rate_limited`): 300 a minute across all endpoints. Wait the number of seconds in `Retry-After`, then retry with the same Idempotency-Key. (Error) - 500: Our error. Retrying is safe with the same Idempotency-Key. (Error) #### POST /uploads/{id}/finalize (Verify and finalize an upload) Scope: uploads:write Call once the bytes are PUT. Checks the stored size against the declaration and moves the file out of reach of the upload URL, so it can no longer be replaced. The bytes are then checked against the declared SHA-256 in the background, whatever their size: the response is 202 with `state: processing`, and `GET /uploads/{id}` shows the result, usually within a minute (longer for very large files). Poll it with backoff: 2 seconds, doubling to at most 30. A finalized upload has an immutable asset version (`asset_version_id`). Calling finalize again with the same Idempotency-Key is safe at any time, including after a timeout: it resumes the work and returns the current state, and once the upload is finalized it returns the version marked `Idempotent-Replayed: true`. The key is bound to this upload and this exact request before any work starts, so the same key with a different request is refused with `idempotency_mismatch` even if the first one failed. A file that does not match its declaration is rejected (422 `size_mismatch` or `checksum_mismatch`, or `rejected` in `GET /uploads/{id}`). File-quality checks run as soon as the file is finalized (each file is fully decoded) and are applied at order validation; see Validation. Parameters: - id (path, required): string (uuid). The upload. - Idempotency-Key (header, required): string (pattern ^[\x21-\x7e]{1,255}$) Responses: - 200: The finalized asset version. (UploadFinalized) - 202: The bytes are being verified; see `GET /uploads/{id}`. (UploadProcessing) - 400: The body is not JSON, or the Idempotency-Key is missing or malformed. (Error) - 401: The API key is missing or not valid (`missing_api_key`, `invalid_api_key`). (Error) - 403: The key lacks a scope (`insufficient_scope`), or is a live key (`live_mode_unavailable`). (Error) - 404: No such resource for this key, or no such path. (Error) - 409: The resource's state does not allow this (`order_not_revisable`, `quote_already_used`, `upload_incomplete`, `too_many_endpoints`, `endpoint_disabled`, `delivery_in_flight`, `payment_method_required`, `partner_terms_required`). (Error) - 413: The body is over 2 MiB (`body_too_large`). It may be refused only after more of it was sent. (Error) - 415: The body is not application/json. (Error) - 422: The request is invalid; `field` names the problem, `code` says what it is. (Error) - 429: Too many requests for this API key (`rate_limited`): 300 a minute across all endpoints. Wait the number of seconds in `Retry-After`, then retry with the same Idempotency-Key. (Error) - 500: Our error. Retrying is safe with the same Idempotency-Key. (Error) ### Orders #### POST /orders (Create an order from a quote) Scope: orders:write The items must match the quote's formats and quantities, in order, and reference finalized asset versions of your account and mode. `rights_warranty: true` records that you accept the rights warranty in your partner agreement. The quote's price, address and shipping are committed for 72 hours; validation confirms against that commitment. Your account needs a card on file in this mode first (409 `payment_method_required`; see `POST /billing/setup`). In live mode an account owner must also have accepted the partner terms in the partner portal (409 `partner_terms_required`). Parameters: - Idempotency-Key (header, required): string (pattern ^[\x21-\x7e]{1,255}$) Body: - quote_id (required): string (uuid) - shipping_service (required): string. One of the quote's shipping_options. - items (required): array of object (1–100 items) - format (required): "vinyl_12" | "vinyl_7" | "cassette" | "cd_jewel" | "cd_jacket" - quantity (required): integer (1–10000) - surfaces: object. Artwork per printed surface, e.g. `{ "front_insert": "" }`. The surfaces of each format are listed by `GET /artwork_templates`; a surface you leave out prints Tapebloom's default design. Artwork covers the template's whole canvas (trim plus bleed). Replaces the earlier `artwork_version_id`, which is now refused with `field_removed`. - tracks (required): array of object (1–200 items) - asset_version_id (required): string (uuid). A finalized audio asset version. - side: "A" | "B". Cassettes: the side the track plays on. Required for cassettes. - title: string (1–200 chars). Printed in tracklists. - artist: string (1–200 chars). Printed in tracklists. - rights_warranty (required): true - title: string (1–300 chars) - external_ref: string (1–200 chars). Your own reference. Responses: - 201: The order, in `received`. (Order) - 400: The body is not JSON, or the Idempotency-Key is missing or malformed. (Error) - 401: The API key is missing or not valid (`missing_api_key`, `invalid_api_key`). (Error) - 403: The key lacks a scope (`insufficient_scope`), or is a live key (`live_mode_unavailable`). (Error) - 409: The resource's state does not allow this (`order_not_revisable`, `quote_already_used`, `upload_incomplete`, `too_many_endpoints`, `endpoint_disabled`, `delivery_in_flight`, `payment_method_required`, `partner_terms_required`). (Error) - 413: The body is over 2 MiB (`body_too_large`). It may be refused only after more of it was sent. (Error) - 415: The body is not application/json. (Error) - 422: The request is invalid; `field` names the problem, `code` says what it is. (Error) - 429: Too many requests for this API key (`rate_limited`): 300 a minute across all endpoints. Wait the number of seconds in `Retry-After`, then retry with the same Idempotency-Key. (Error) - 500: Our error. Retrying is safe with the same Idempotency-Key. (Error) #### GET /orders (List orders, newest first) Scope: orders:read Parameters: - state (query): "received" | "validating" | "needs_attention" | "materials_hold" | "awaiting_payment" | "released" | "cancelled" | "complete". Only orders in this state. - limit (query): integer (1–100). Page size. Default 20. - starting_after (query): string (uuid). The last order id of the previous page. Responses: - 200: A page of orders. (list of OrderSummary) - 401: The API key is missing or not valid (`missing_api_key`, `invalid_api_key`). (Error) - 403: The key lacks a scope (`insufficient_scope`), or is a live key (`live_mode_unavailable`). (Error) - 422: The request is invalid; `field` names the problem, `code` says what it is. (Error) - 429: Too many requests for this API key (`rate_limited`): 300 a minute across all endpoints. Wait the number of seconds in `Retry-After`, then retry with the same Idempotency-Key. (Error) - 500: Our error. Retrying is safe with the same Idempotency-Key. (Error) #### GET /orders/{id} (Get an order) Scope: orders:read The order with its current items, amounts and latest payment as separate objects. Parameters: - id (path, required): string (uuid). The order. Responses: - 200: The order. (Order) - 401: The API key is missing or not valid (`missing_api_key`, `invalid_api_key`). (Error) - 403: The key lacks a scope (`insufficient_scope`), or is a live key (`live_mode_unavailable`). (Error) - 404: No such resource for this key, or no such path. (Error) - 429: Too many requests for this API key (`rate_limited`): 300 a minute across all endpoints. Wait the number of seconds in `Retry-After`, then retry with the same Idempotency-Key. (Error) - 500: Our error. Retrying is safe with the same Idempotency-Key. (Error) #### POST /orders/{id}/revisions (Fix an order that needs attention) Scope: orders:write Only from `needs_attention`. New items replace the current ones (earlier revisions stay as history) and the order returns to validation. Different formats or quantities, a different shipping service, or an expired price commitment need a new `quote_id`. Every revision replaces the order's content, so each needs `rights_warranty: true`: an explicit acceptance, recorded with the API key, time and warranty version, for that revision. Parameters: - id (path, required): string (uuid). The order. - Idempotency-Key (header, required): string (pattern ^[\x21-\x7e]{1,255}$) Body: - items (required): array of object (1–100 items) - format (required): "vinyl_12" | "vinyl_7" | "cassette" | "cd_jewel" | "cd_jacket" - quantity (required): integer (1–10000) - surfaces: object. Artwork per printed surface, e.g. `{ "front_insert": "" }`. The surfaces of each format are listed by `GET /artwork_templates`; a surface you leave out prints Tapebloom's default design. Artwork covers the template's whole canvas (trim plus bleed). Replaces the earlier `artwork_version_id`, which is now refused with `field_removed`. - tracks (required): array of object (1–200 items) - asset_version_id (required): string (uuid). A finalized audio asset version. - side: "A" | "B". Cassettes: the side the track plays on. Required for cassettes. - title: string (1–200 chars). Printed in tracklists. - artist: string (1–200 chars). Printed in tracklists. - reason: string (1–500 chars) - quote_id: string (uuid) - shipping_service: string - rights_warranty (required): true Responses: - 201: The revised order, back in `validating`. (Order) - 400: The body is not JSON, or the Idempotency-Key is missing or malformed. (Error) - 401: The API key is missing or not valid (`missing_api_key`, `invalid_api_key`). (Error) - 403: The key lacks a scope (`insufficient_scope`), or is a live key (`live_mode_unavailable`). (Error) - 404: No such resource for this key, or no such path. (Error) - 409: The resource's state does not allow this (`order_not_revisable`, `quote_already_used`, `upload_incomplete`, `too_many_endpoints`, `endpoint_disabled`, `delivery_in_flight`, `payment_method_required`, `partner_terms_required`). (Error) - 413: The body is over 2 MiB (`body_too_large`). It may be refused only after more of it was sent. (Error) - 415: The body is not application/json. (Error) - 422: The request is invalid; `field` names the problem, `code` says what it is. (Error) - 429: Too many requests for this API key (`rate_limited`): 300 a minute across all endpoints. Wait the number of seconds in `Retry-After`, then retry with the same Idempotency-Key. (Error) - 500: Our error. Retrying is safe with the same Idempotency-Key. (Error) #### POST /orders/{id}/cancel (Cancel an order) Scope: orders:write Before release the order is cancelled, reserved materials are returned and any payment is refunded. After release the order does not change: the response is 409 `order_released` with the `exception_id` opened for your request. Parameters: - id (path, required): string (uuid). The order. - Idempotency-Key (header, required): string (pattern ^[\x21-\x7e]{1,255}$) Body: - reason: string (pattern ^[a-z][a-z0-9_]{0,63}$). Example: `changed_mind`. Responses: - 200: The cancelled order. (Order) - 400: The body is not JSON, or the Idempotency-Key is missing or malformed. (Error) - 401: The API key is missing or not valid (`missing_api_key`, `invalid_api_key`). (Error) - 403: The key lacks a scope (`insufficient_scope`), or is a live key (`live_mode_unavailable`). (Error) - 404: No such resource for this key, or no such path. (Error) - 409: The order was already released (`order_released`, with `exception_id`), or another conflict. (Error) - 413: The body is over 2 MiB (`body_too_large`). It may be refused only after more of it was sent. (Error) - 415: The body is not application/json. (Error) - 422: The request is invalid; `field` names the problem, `code` says what it is. (Error) - 429: Too many requests for this API key (`rate_limited`): 300 a minute across all endpoints. Wait the number of seconds in `Retry-After`, then retry with the same Idempotency-Key. (Error) - 500: Our error. Retrying is safe with the same Idempotency-Key. (Error) ### Artwork templates #### GET /artwork_templates (Artwork templates) Scope: orders:read The print template of every surface of every format, in the version new orders pin: physical size in millimetres, bleed, safe area, folds, the printable mask, the zone kept for each unit's QR code, and the resolution artwork needs. A template is `provisional` until a print-and-fit proof approves it; its geometry may then change in a new version, which only later orders pin. Parameters: - format (query): "vinyl_12" | "vinyl_7" | "cassette" | "cd_jewel" | "cd_jacket". Only this format's surfaces. Responses: - 200: The current templates. (list of ArtworkTemplate) - 401: The API key is missing or not valid (`missing_api_key`, `invalid_api_key`). (Error) - 403: The key lacks a scope (`insufficient_scope`), or is a live key (`live_mode_unavailable`). (Error) - 422: The request is invalid; `field` names the problem, `code` says what it is. (Error) - 429: Too many requests for this API key (`rate_limited`): 300 a minute across all endpoints. Wait the number of seconds in `Retry-After`, then retry with the same Idempotency-Key. (Error) - 500: Our error. Retrying is safe with the same Idempotency-Key. (Error) ### Events #### GET /events (Event history) Scope: events:read With `order_id`: that order's events after `after_sequence`, in sequence, with no gaps. Without: your account's events after `starting_after`, oldest first, for browsing (see Events above). Parameters: - order_id (query): string (uuid). One order's events. - after_sequence (query): integer (≥ 0). With order_id: events after this sequence number. - starting_after (query): string (uuid). Without order_id: events after this event. - type (query): string (pattern ^[a-z_]+\.[a-z_]+$). Only events of this type. - limit (query): integer (1–100). Page size. Default 50. Responses: - 200: A page of events. (list of Event) - 401: The API key is missing or not valid (`missing_api_key`, `invalid_api_key`). (Error) - 403: The key lacks a scope (`insufficient_scope`), or is a live key (`live_mode_unavailable`). (Error) - 404: No such resource for this key, or no such path. (Error) - 422: The request is invalid; `field` names the problem, `code` says what it is. (Error) - 429: Too many requests for this API key (`rate_limited`): 300 a minute across all endpoints. Wait the number of seconds in `Retry-After`, then retry with the same Idempotency-Key. (Error) - 500: Our error. Retrying is safe with the same Idempotency-Key. (Error) ### Billing #### GET /billing (Card on file) Scope: billing:read The card orders in this mode are charged to, or `payment_method: null` when none is saved. Each order is charged once, off-session, for its committed total (product plus quoted shipping) when it reaches `awaiting_payment`. A declined card is not charged again until you save a new one; the order then waits in `awaiting_payment` and you receive `payment.failed`. Responses: - 200: Billing for this key's account and mode. (Billing) - 401: The API key is missing or not valid (`missing_api_key`, `invalid_api_key`). (Error) - 403: The key lacks a scope (`insufficient_scope`), or is a live key (`live_mode_unavailable`). (Error) - 429: Too many requests for this API key (`rate_limited`): 300 a minute across all endpoints. Wait the number of seconds in `Retry-After`, then retry with the same Idempotency-Key. (Error) - 500: Our error. Retrying is safe with the same Idempotency-Key. (Error) #### POST /billing/setup (Save a card) Scope: billing:write Returns a Stripe-hosted page where you save a card for this mode (test mode accepts Stripe's test cards). Card details go to Stripe only; Tapebloom keeps the brand, last four digits and expiry. Completing the page replaces the card on file, and orders waiting after a declined charge are charged again with the new card. The page expires at `expires_at`. Body: - return_url (required): string (uri, ≤ 2000 chars). Where Stripe sends you after the card is saved. - cancel_url: string (uri, ≤ 2000 chars). Where Stripe sends you if you leave without saving. Defaults to return_url. Responses: - 201: The setup page. (BillingSetup) - 400: The body is not JSON, or the Idempotency-Key is missing or malformed. (Error) - 401: The API key is missing or not valid (`missing_api_key`, `invalid_api_key`). (Error) - 403: The key lacks a scope (`insufficient_scope`), or is a live key (`live_mode_unavailable`). (Error) - 413: The body is over 2 MiB (`body_too_large`). It may be refused only after more of it was sent. (Error) - 415: The body is not application/json. (Error) - 422: The request is invalid; `field` names the problem, `code` says what it is. (Error) - 429: Too many requests for this API key (`rate_limited`): 300 a minute across all endpoints. Wait the number of seconds in `Retry-After`, then retry with the same Idempotency-Key. (Error) - 500: Our error. Retrying is safe with the same Idempotency-Key. (Error) - 503: Billing is not available in this mode yet (`billing_unavailable`). (Error) ### Webhook endpoints #### POST /webhook_endpoints (Add a webhook endpoint) Scope: webhooks:manage The response includes the endpoint's signing `secret`; store it, as it is not shown again except in a replay of this request. A replay returns the endpoint's current settings (for example `enabled: false` if it was disabled since) with the originally issued secret while that secret still signs, and without `secret` after it has been rotated out. At most 10 endpoints can be enabled per mode (`too_many_endpoints`). The URL must be `https` with a valid port (in test mode also `http://localhost` or `http://127.0.0.1`); one that cannot receive deliveries is refused with `invalid_url`. Omit `event_types` to receive every type. Parameters: - Idempotency-Key (header, required): string (pattern ^[\x21-\x7e]{1,255}$) Body: - url (required): string (uri, ≤ 2048 chars) - event_types: array of "order.awaiting_payment" | "order.cancelled" | "order.complete" | "order.exception_opened" | "order.materials_hold" | "order.needs_attention" | "order.received" | "order.released" | "order.validating" | "payment.canceled" | "payment.failed" | "payment.requires_action" | "payment.succeeded" | "refund.failed" | "refund.succeeded" | "shipment.delivered" | "shipment.returned" | "shipment.shipped" (1–50 items) - description: string (1–200 chars) Responses: - 201: The endpoint and its signing secret. (WebhookEndpointWithSecret) - 400: The body is not JSON, or the Idempotency-Key is missing or malformed. (Error) - 401: The API key is missing or not valid (`missing_api_key`, `invalid_api_key`). (Error) - 403: The key lacks a scope (`insufficient_scope`), or is a live key (`live_mode_unavailable`). (Error) - 409: The resource's state does not allow this (`order_not_revisable`, `quote_already_used`, `upload_incomplete`, `too_many_endpoints`, `endpoint_disabled`, `delivery_in_flight`, `payment_method_required`, `partner_terms_required`). (Error) - 413: The body is over 2 MiB (`body_too_large`). It may be refused only after more of it was sent. (Error) - 415: The body is not application/json. (Error) - 422: The request is invalid; `field` names the problem, `code` says what it is. (Error) - 429: Too many requests for this API key (`rate_limited`): 300 a minute across all endpoints. Wait the number of seconds in `Retry-After`, then retry with the same Idempotency-Key. (Error) - 500: Our error. Retrying is safe with the same Idempotency-Key. (Error) #### GET /webhook_endpoints (List webhook endpoints, newest first) Scope: webhooks:manage Enabled and disabled endpoints, without secrets. Parameters: - limit (query): integer (1–100). Page size. Default 20. - starting_after (query): string (uuid). The last endpoint id of the previous page. Responses: - 200: A page of endpoints. (list of WebhookEndpoint) - 401: The API key is missing or not valid (`missing_api_key`, `invalid_api_key`). (Error) - 403: The key lacks a scope (`insufficient_scope`), or is a live key (`live_mode_unavailable`). (Error) - 422: The request is invalid; `field` names the problem, `code` says what it is. (Error) - 429: Too many requests for this API key (`rate_limited`): 300 a minute across all endpoints. Wait the number of seconds in `Retry-After`, then retry with the same Idempotency-Key. (Error) - 500: Our error. Retrying is safe with the same Idempotency-Key. (Error) #### GET /webhook_endpoints/{id} (Get a webhook endpoint) Scope: webhooks:manage Without its secret. Parameters: - id (path, required): string (uuid). The endpoint. Responses: - 200: The endpoint. (WebhookEndpoint) - 401: The API key is missing or not valid (`missing_api_key`, `invalid_api_key`). (Error) - 403: The key lacks a scope (`insufficient_scope`), or is a live key (`live_mode_unavailable`). (Error) - 404: No such resource for this key, or no such path. (Error) - 429: Too many requests for this API key (`rate_limited`): 300 a minute across all endpoints. Wait the number of seconds in `Retry-After`, then retry with the same Idempotency-Key. (Error) - 500: Our error. Retrying is safe with the same Idempotency-Key. (Error) #### POST /webhook_endpoints/{id}/enable (Enable an endpoint) Scope: webhooks:manage Safe to repeat; takes no Idempotency-Key. Fails with `too_many_endpoints` when 10 are already enabled. Parameters: - id (path, required): string (uuid). The endpoint. Responses: - 200: The endpoint. (WebhookEndpoint) - 400: The body is not JSON, or the Idempotency-Key is missing or malformed. (Error) - 401: The API key is missing or not valid (`missing_api_key`, `invalid_api_key`). (Error) - 403: The key lacks a scope (`insufficient_scope`), or is a live key (`live_mode_unavailable`). (Error) - 404: No such resource for this key, or no such path. (Error) - 409: The resource's state does not allow this (`order_not_revisable`, `quote_already_used`, `upload_incomplete`, `too_many_endpoints`, `endpoint_disabled`, `delivery_in_flight`, `payment_method_required`, `partner_terms_required`). (Error) - 413: The body is over 2 MiB (`body_too_large`). It may be refused only after more of it was sent. (Error) - 415: The body is not application/json. (Error) - 429: Too many requests for this API key (`rate_limited`): 300 a minute across all endpoints. Wait the number of seconds in `Retry-After`, then retry with the same Idempotency-Key. (Error) - 500: Our error. Retrying is safe with the same Idempotency-Key. (Error) #### POST /webhook_endpoints/{id}/disable (Disable an endpoint) Scope: webhooks:manage Safe to repeat; takes no Idempotency-Key. A disabled endpoint receives no new deliveries; pending ones are abandoned once their retry window ends. Parameters: - id (path, required): string (uuid). The endpoint. Responses: - 200: The endpoint. (WebhookEndpoint) - 400: The body is not JSON, or the Idempotency-Key is missing or malformed. (Error) - 401: The API key is missing or not valid (`missing_api_key`, `invalid_api_key`). (Error) - 403: The key lacks a scope (`insufficient_scope`), or is a live key (`live_mode_unavailable`). (Error) - 404: No such resource for this key, or no such path. (Error) - 413: The body is over 2 MiB (`body_too_large`). It may be refused only after more of it was sent. (Error) - 415: The body is not application/json. (Error) - 429: Too many requests for this API key (`rate_limited`): 300 a minute across all endpoints. Wait the number of seconds in `Retry-After`, then retry with the same Idempotency-Key. (Error) - 500: Our error. Retrying is safe with the same Idempotency-Key. (Error) #### POST /webhook_endpoints/{id}/rotate_secret (Issue a new signing secret) Scope: webhooks:manage The old secret keeps signing alongside the new one for `overlap_hours` (default 24, 0 to 168), so each delivery carries one `v1` signature per active secret and you can switch without a gap. The response includes the new `secret`, shown only here and in a replay of this request. Like create, a replay returns the endpoint's current settings with that secret while it still signs, and without `secret` once it has been rotated out. Parameters: - id (path, required): string (uuid). The endpoint. - Idempotency-Key (header, required): string (pattern ^[\x21-\x7e]{1,255}$) Body: - overlap_hours: integer (0–168). Default 24. Responses: - 200: The endpoint and its new secret. (WebhookEndpointWithSecret) - 400: The body is not JSON, or the Idempotency-Key is missing or malformed. (Error) - 401: The API key is missing or not valid (`missing_api_key`, `invalid_api_key`). (Error) - 403: The key lacks a scope (`insufficient_scope`), or is a live key (`live_mode_unavailable`). (Error) - 404: No such resource for this key, or no such path. (Error) - 413: The body is over 2 MiB (`body_too_large`). It may be refused only after more of it was sent. (Error) - 415: The body is not application/json. (Error) - 422: The request is invalid; `field` names the problem, `code` says what it is. (Error) - 429: Too many requests for this API key (`rate_limited`): 300 a minute across all endpoints. Wait the number of seconds in `Retry-After`, then retry with the same Idempotency-Key. (Error) - 500: Our error. Retrying is safe with the same Idempotency-Key. (Error) #### GET /webhook_endpoints/{id}/deliveries (An endpoint's deliveries, newest first) Scope: webhooks:manage Parameters: - id (path, required): string (uuid). The endpoint. - state (query): "pending" | "delivered" | "abandoned". Only deliveries in this state. - limit (query): integer (1–100). Page size. Default 20. - starting_after (query): string (uuid). The last delivery id of the previous page. Responses: - 200: A page of deliveries. (list of WebhookDelivery) - 401: The API key is missing or not valid (`missing_api_key`, `invalid_api_key`). (Error) - 403: The key lacks a scope (`insufficient_scope`), or is a live key (`live_mode_unavailable`). (Error) - 404: No such resource for this key, or no such path. (Error) - 422: The request is invalid; `field` names the problem, `code` says what it is. (Error) - 429: Too many requests for this API key (`rate_limited`): 300 a minute across all endpoints. Wait the number of seconds in `Retry-After`, then retry with the same Idempotency-Key. (Error) - 500: Our error. Retrying is safe with the same Idempotency-Key. (Error) ### Webhook deliveries #### GET /webhook_deliveries/{id} (A delivery with every attempt) Scope: webhooks:manage Parameters: - id (path, required): string (uuid). The delivery. Responses: - 200: The delivery, with `attempts`. (WebhookDelivery) - 401: The API key is missing or not valid (`missing_api_key`, `invalid_api_key`). (Error) - 403: The key lacks a scope (`insufficient_scope`), or is a live key (`live_mode_unavailable`). (Error) - 404: No such resource for this key, or no such path. (Error) - 429: Too many requests for this API key (`rate_limited`): 300 a minute across all endpoints. Wait the number of seconds in `Retry-After`, then retry with the same Idempotency-Key. (Error) - 500: Our error. Retrying is safe with the same Idempotency-Key. (Error) #### POST /webhook_deliveries/{id}/replay (Send a delivery again) Scope: webhooks:manage The delivery becomes due now with a new 3-day retry window. The event's id, sequence and body are unchanged; each attempt is freshly signed. Retrying with the same Idempotency-Key returns the first response and never schedules another send, even if the delivery has succeeded since; send a new key for an intentional resend. Fails with `endpoint_disabled` or, while it is being sent, `delivery_in_flight`. Parameters: - id (path, required): string (uuid). The delivery. - Idempotency-Key (header, required): string (pattern ^[\x21-\x7e]{1,255}$) Responses: - 200: The delivery as requeued, with `attempts`. (WebhookDelivery) - 400: The body is not JSON, or the Idempotency-Key is missing or malformed. (Error) - 401: The API key is missing or not valid (`missing_api_key`, `invalid_api_key`). (Error) - 403: The key lacks a scope (`insufficient_scope`), or is a live key (`live_mode_unavailable`). (Error) - 404: No such resource for this key, or no such path. (Error) - 409: The resource's state does not allow this (`order_not_revisable`, `quote_already_used`, `upload_incomplete`, `too_many_endpoints`, `endpoint_disabled`, `delivery_in_flight`, `payment_method_required`, `partner_terms_required`). (Error) - 413: The body is over 2 MiB (`body_too_large`). It may be refused only after more of it was sent. (Error) - 415: The body is not application/json. (Error) - 422: The request is invalid; `field` names the problem, `code` says what it is. (Error) - 429: Too many requests for this API key (`rate_limited`): 300 a minute across all endpoints. Wait the number of seconds in `Retry-After`, then retry with the same Idempotency-Key. (Error) - 500: Our error. Retrying is safe with the same Idempotency-Key. (Error) ### Schemas #### Billing - object (required): "billing" - payment_method (required): null or object #### BillingSetup - object (required): "billing_setup" - url (required): string (uri) - expires_at (required): string (date-time) #### Error - error (required): object - code (required): string (pattern ^[a-z][a-z0-9_]*$). A stable code, such as invalid_sha256. - message (required): string - field: string - request_id (required): string (pattern ^req_[0-9a-f]{32}$) - exception_id: string (uuid). With order_released: the exception opened for the cancel request. #### AddressInput Unknown fields are ignored. - name (required): string (≤ 200 chars) - line1 (required): string (≤ 200 chars) - line2: string (≤ 200 chars) - city (required): string (≤ 200 chars) - region: string (≤ 200 chars) - postal_code (required): string (≤ 200 chars) - country (required): string (pattern ^[A-Za-z]{2}$) - phone: string (≤ 200 chars) #### Address - name (required): string - line1 (required): string - line2: string - city (required): string - region: string - postal_code (required): string - country (required): string (pattern ^[A-Z]{2}$) - phone: string #### ShippingOption - service (required): string - amount_minor (required): integer (≥ 0). An amount in the currency's minor unit (cents for usd). - min_days: integer (≥ 0) - max_days: integer (≥ 0) #### Quote - id (required): string (uuid) - object (required): "quote" - environment (required): "test" | "live" - currency (required): string (pattern ^[a-z]{3}$). ISO 4217 code, lowercase. - items (required): array of object - position (required): integer (≥ 1) - format (required): "vinyl_12" | "vinyl_7" | "cassette" | "cd_jewel" | "cd_jacket" - quantity (required): integer - runtime_seconds (required): integer - unit_price_minor (required): integer (≥ 0). An amount in the currency's minor unit (cents for usd). - setup_fee_minor (required): integer (≥ 0). An amount in the currency's minor unit (cents for usd). - amount_minor (required): integer (≥ 0). An amount in the currency's minor unit (cents for usd). - subtotal_minor (required): integer (≥ 0). An amount in the currency's minor unit (cents for usd). - shipping_options (required): array of ShippingOption (≥ 1 items) - ship_to (required): Address - expires_at (required): string (date-time) - created_at (required): string (date-time) #### UploadCreated - id (required): string (uuid) - object (required): "upload" - kind (required): "audio" | "artwork" - state (required): "created" - upload (required): object - method (required): "PUT" - url (required): string (uri) - expires_in (required): integer. Seconds the URL stays valid. #### UploadFinalized - id (required): string (uuid) - object (required): "upload" - state (required): "finalized" - asset_version_id (required): string (uuid) #### UploadProcessing - id (required): string (uuid) - object (required): "upload" - state (required): "processing" #### Upload - id (required): string (uuid) - object (required): "upload" - kind (required): "audio" | "artwork" - state (required): "created" | "processing" | "finalized" | "rejected" - asset_version_id: string (uuid). Once finalized. - rejected_reason: string. Once rejected: a stable code. Example: `checksum_mismatch`. - created_at (required): string (date-time) #### Amount - currency (required): string (pattern ^[a-z]{3}$). ISO 4217 code, lowercase. - subtotal_minor (required): integer (≥ 0). An amount in the currency's minor unit (cents for usd). - shipping_minor (required): integer (≥ 0). An amount in the currency's minor unit (cents for usd). - total_minor (required): integer (≥ 0). An amount in the currency's minor unit (cents for usd). #### Refund - id (required): string (uuid) - state (required): "pending" | "succeeded" | "failed" - amount_minor (required): integer (≥ 0). An amount in the currency's minor unit (cents for usd). - currency (required): string (pattern ^[a-z]{3}$). ISO 4217 code, lowercase. - reason (required): string - created_at (required): string (date-time) #### Payment - id (required): string (uuid) - state (required): "pending" | "requires_action" | "succeeded" | "failed" | "canceled" | "unknown" - amount_minor (required): integer (≥ 0). An amount in the currency's minor unit (cents for usd). - currency (required): string (pattern ^[a-z]{3}$). ISO 4217 code, lowercase. - amount_received_minor: integer (≥ 0). An amount in the currency's minor unit (cents for usd). - currency_received: string (pattern ^[a-z]{3}$). ISO 4217 code, lowercase. - failure_code: string - refunds (required): array of Refund - created_at (required): string (date-time) #### Unit - id (required): string (uuid) - object (required): "unit" - item_position (required): integer (≥ 1) - serial (required): integer (≥ 1). The unit's number within its item. - state (required): "made" | "passed" | "scrapped" | "packed" | "shipped" | "returned" | "quarantined" - replaces_unit_id: string (uuid). Set on a remade unit: the scrapped unit it replaces. - created_at (required): string (date-time) #### Shipment - id (required): string (uuid) - object (required): "shipment" - state (required): "packing" | "label_created" | "handed_to_carrier" | "voided" | "in_transit" | "delivered" | "returned" - carrier: string - service: string - tracking_number: string - tracking_url: string - unit_ids (required): array of string (uuid). The units in the shipment now. Empty once a voided label releases them. - created_at (required): string (date-time) - state_changed_at (required): string (date-time) #### ArtworkTemplate - id (required): string (uuid) - object (required): "artwork_template" - format (required): "vinyl_12" | "vinyl_7" | "cassette" | "cd_jewel" | "cd_jacket" - surface (required): string. The key to use in an item's `surfaces`. - version (required): integer (≥ 1) - label (required): string - description (required): string - required (required): boolean. The surface is printed on every unit. - default_design: string. Printed when you send no artwork for the surface. Missing when artwork is needed. - status (required): "provisional" | "approved". `provisional` until a print-and-fit proof approves the geometry. - printer (required): "primera_bravo_4202" | "epson_ecotank" - trim (required): object - width_mm (required): number - height_mm (required): number - bleed_mm (required): number. Extend artwork this far past the trim on every side. - safe_mm (required): number. Keep text and faces this far inside the trim. - canvas (required): object. Trim plus bleed: the area your artwork must cover. - width_mm (required): number - height_mm (required): number - folds (required): array of object. Fold lines from the trim's top-left corner; `x` folds are vertical. - axis (required): "x" | "y" - at_mm (required): number - mask: object. The printable area when it is not the whole trim, such as a disc's hub and edge. Missing until measured on the production stock. - qr_zone: object. Where each unit's QR code prints, from the trim's top-left corner. Keep it plain. - x_mm (required): number - y_mm (required): number - size_mm (required): number - target_ppi (required): integer - min_ppi (required): integer - target_pixels (required): object. The smallest artwork that reaches `target_ppi` over the canvas. Larger files of the same proportions are fine. - width (required): integer - height (required): integer - approved_at: string (date-time) - created_at (required): string (date-time) #### Finding - code (required): string. A stable code. Yours to fix: `audio_unreadable`, `audio_empty`, `audio_truncated`, `audio_sample_rate_low` (below 44.1 kHz), `audio_bit_depth_low` (below 16-bit), `audio_bit_depth_unknown`, `audio_channels_unsupported` (not mono or stereo), `runtime_changed` (longer than quoted), `track_side_missing` and `side_runtime_exceeded` (cassettes), `artwork_unreadable`, `artwork_too_many_pixels`, `artwork_format_unsupported`, `artwork_dimensions_mismatch` (proportions differ from the canvas by more than a pixel), `artwork_color_cmyk` (send RGB, ideally sRGB), `artwork_resolution_too_low` (below the template's `min_ppi` at its printed size), `artwork_surface_missing` (a required surface with no default design). Reviewed by staff: `artwork_resolution_low` (between `min_ppi` and `target_ppi`) and `artwork_template_unapproved` (the template awaits a print proof), which may be approved, and `content_mismatch` or `file_missing`, problems with Tapebloom's stored copy that are never waived: staff check them and, if needed, ask you to upload the file again. - kind (required): "partner" | "review" - item_position: integer (≥ 1) - track_position: integer (≥ 1) - surface: string. The artwork surface (such as `front_insert`) or cassette side (`side_a`, `side_b`) concerned. - measured (required): object. What was measured, e.g. `{ "sample_rate": 22050 }`. - expected (required): object. What is required, e.g. `{ "min_sample_rate": 44100 }`. - review_state: "pending" | "approved" | "rejected". For `review` findings. In test mode reviews are approved at once. #### Order - id (required): string (uuid) - object (required): "order" - environment (required): "test" | "live" - state (required): "received" | "validating" | "needs_attention" | "materials_hold" | "awaiting_payment" | "released" | "cancelled" | "complete" - attention_reason: string. Why the order needs attention, as a code: the first of `findings` you need to fix, or `price_commitment_expired`. - title: string - external_ref: string - quote_id: string (uuid) - revision (required): integer (≥ 1) - findings: array of Finding. What validation found in the current revision. `partner` findings are yours to fix with a revision; `review` findings are checked by Tapebloom staff (the order waits in `validating`, and is not charged, until they are decided). - items (required): array of object - position (required): integer (≥ 1) - format (required): "vinyl_12" | "vinyl_7" | "cassette" | "cd_jewel" | "cd_jacket" - quantity (required): integer - artwork_version_id: string (uuid). Only on items from before surfaces, for formats without artwork templates. - surfaces: array of object - surface (required): string - asset_version_id: string (uuid). Your artwork. Missing when the default design prints. - default_design: string. Tapebloom's design printed when no artwork was sent. - template (required): object. The template version pinned when the item was submitted. - id (required): string (uuid) - version (required): integer (≥ 1) - status (required): "provisional" | "approved" - tracks (required): array of object - position (required): integer (≥ 1) - side: "A" | "B" - asset_version_id (required): string (uuid) - recording_id (required): string (uuid) - title: string - artist: string - ship_to: Address - shipping: object - service (required): string - amount_minor (required): integer (≥ 0). An amount in the currency's minor unit (cents for usd). - amount: Amount - price_commitment_until: string (date-time) - rights_warranty_accepted_at: string (date-time) - payment: Payment - units: array of Unit. Physical units made for the order, once released. - shipments: array of Shipment. The order is complete once the carrier has accepted shipments holding every unit it needs. - created_at (required): string (date-time) - updated_at (required): string (date-time) #### OrderSummary - id (required): string (uuid) - object (required): "order" - environment (required): "test" | "live" - state (required): "received" | "validating" | "needs_attention" | "materials_hold" | "awaiting_payment" | "released" | "cancelled" | "complete" - attention_reason: string - title: string - external_ref: string - revision (required): integer (≥ 1) - amount: Amount - created_at (required): string (date-time) - updated_at (required): string (date-time) #### WebhookEndpoint - id (required): string (uuid) - object (required): "webhook_endpoint" - environment (required): "test" | "live" - url (required): string - description: string - event_types: array of "order.awaiting_payment" | "order.cancelled" | "order.complete" | "order.exception_opened" | "order.materials_hold" | "order.needs_attention" | "order.received" | "order.released" | "order.validating" | "payment.canceled" | "payment.failed" | "payment.requires_action" | "payment.succeeded" | "refund.failed" | "refund.succeeded" | "shipment.delivered" | "shipment.returned" | "shipment.shipped". Missing when the endpoint receives every type. - enabled (required): boolean - previous_secret_expires_at: string (date-time). During a rotation: when the previous secret stops signing. - created_at (required): string (date-time) - updated_at (required): string (date-time) #### WebhookEndpointWithSecret - id (required): string (uuid) - object (required): "webhook_endpoint" - environment (required): "test" | "live" - url (required): string - description: string - event_types: array of "order.awaiting_payment" | "order.cancelled" | "order.complete" | "order.exception_opened" | "order.materials_hold" | "order.needs_attention" | "order.received" | "order.released" | "order.validating" | "payment.canceled" | "payment.failed" | "payment.requires_action" | "payment.succeeded" | "refund.failed" | "refund.succeeded" | "shipment.delivered" | "shipment.returned" | "shipment.shipped". Missing when the endpoint receives every type. - enabled (required): boolean - previous_secret_expires_at: string (date-time). During a rotation: when the previous secret stops signing. - created_at (required): string (date-time) - updated_at (required): string (date-time) - secret: string (pattern ^whsec_). The signing secret. Missing only from a replay made after the secret stopped signing. #### WebhookDelivery - id (required): string (uuid) - object (required): "webhook_delivery" - environment (required): "test" | "live" - endpoint_id (required): string (uuid) - event_id (required): string (uuid) - event_type (required): "order.awaiting_payment" | "order.cancelled" | "order.complete" | "order.exception_opened" | "order.materials_hold" | "order.needs_attention" | "order.received" | "order.released" | "order.validating" | "payment.canceled" | "payment.failed" | "payment.requires_action" | "payment.succeeded" | "refund.failed" | "refund.succeeded" | "shipment.delivered" | "shipment.returned" | "shipment.shipped" - order_id (required): string (uuid) - state (required): "pending" | "delivered" | "abandoned" - attempt_count (required): integer (≥ 0) - next_attempt_at: string (date-time). While pending: when the next attempt is due. - deadline_at (required): string (date-time). Retries stop here. - last_status_code: integer - last_error: string - delivered_at: string (date-time) - replay_count (required): integer (≥ 0) - created_at (required): string (date-time) - attempts: array of object - attempt_number (required): integer (≥ 1) - signed_at (required): string (date-time) - status_code: integer (100–599) - error: "timeout" | "network_error" | "blocked_address" | "redirect" | "invalid_url" | "invalid_response" - duration_ms: integer (≥ 0) - created_at (required): string (date-time) #### Event - id (required): string (uuid) - type (required): string (pattern ^[a-z_]+\.[a-z_]+$) - occurred_at (required): string (date-time) - environment (required): "test" | "live" - order_id (required): string (uuid) - sequence (required): integer (≥ 1) - data (required): object. The fields this event type exposes; always includes order_id, object and object_id.