Tapebloom Partner API
Quote, upload, finalize and order in test mode, end to end.
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, and every page here is also available as one plain-text file 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.
Copies a prompt for your AI coding tool. It has no key in it: the tool reads TAPEBLOOM_API_KEY from your environment.
See the prompt
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 <key>` 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: { <surface>: 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=<unix seconds>,v1=<hex>`: 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.
Before you start
- A
tb_test_key from the partner portal (API keys tab), exported asTAPEBLOOM_API_KEY. Keep it on your server. - A card on file for test mode (Billing tab in the portal, or POST /billing/setup). Test mode takes Stripe's test cards.
- An audio file and, if you have one, artwork. The examples use
side-a.wavandcover.png.
export TAPEBLOOM_API_KEY=tb_test_… # from the partner portal; never commit it
export TB=https://api.tapebloom.com/v11. 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.
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"
}
}'{
"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.
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": "<upload id>", "object": "upload", "kind": "audio", "state": "created",
# "upload": { "method": "PUT", "url": "<signed URL>", "expires_in": … } }
curl -sS -X PUT "<signed URL>" -H "Content-Type: audio/wav" --data-binary @"$FILE"3. Finalize
curl -sS -X POST "$TB/uploads/<upload id>/finalize" \
-H "Authorization: Bearer $TAPEBLOOM_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: finalize-side-a-v1" \
-d '{}'
# → 202 { "id": "<upload 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/<upload id>" -H "Authorization: Bearer $TAPEBLOOM_API_KEY"
# → { "id": "<upload 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); a surface you leave out prints Tapebloom's default design. rights_warranty: true records that you accept the rights warranty in your partner agreement.
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": "<a service from shipping_options>",
"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"
}'{
"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 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.
curl -sS "$TB/orders/c3e8a1f4-2b6d-4f7a-9e05-8d1b3c7a2e96" -H "Authorization: Bearer $TAPEBLOOM_API_KEY"