Tangibl connector — usage guide for AI assistants

This page covers using Tangibl after the connector is set up (setup: https://gettangibl.com/connect). Tangibl turns images made in a conversation into physical keepsakes: wall art (canvas, poster, photo print, framed print and metal print, sizes up to 24×36 inches; posters start at 18×24) and merch (T-shirt, hoodie, mug, stickers, sherpa blanket, playing cards). Product images are previews. Ordering depends on the customer (listProducts ordering_available); nothing is charged without the customer approving a checkout.

== Tools ==
The connector is the MCP server at https://gettangibl.com/api/mcp. Its tools are the operations below, called by name; the server handles idempotency, so tool calls carry no Idempotency-Key.
To save a new image: uploadDraftImage when the app can pass the image from the conversation as a file, uploadDraftFromUrl for a public https link, or createUploadLink for a single-use Tangibl page where the customer picks the image (getUploadLink then returns the saved creation).
Custom REST integrations use the same operations at the paths below, with the Bearer token and a new UUID Idempotency-Key on writes; there, uploadDraft and uploadCanvasPrintFile are multipart uploads. Full REST description: https://gettangibl.com/api/v1/openapi
- listProducts: GET https://gettangibl.com/api/v1/products (Products, artwork rules and generation hints)
- uploadDraft: POST https://gettangibl.com/api/v1/uploads (multipart/form-data: file (JPEG/PNG), product_id, name, optional occasion and note; header Idempotency-Key (new UUID); optional ?parent_id=)
- uploadCanvasPrintFile: POST https://gettangibl.com/api/v1/canvas/uploads (multipart/form-data: file (3300×3900), product_id=canvas-print, name, optional occasion and note; header Idempotency-Key)
- listMyDrafts: GET https://gettangibl.com/api/v1/drafts (Recent drafts with their names, occasions and notes)
- reviseDraftProduct: POST https://gettangibl.com/api/v1/drafts (application/json: {"parent_id", "product_id", optional "name", "occasion", "note"}; header Idempotency-Key. Same artwork, another product; not for new images)
- getDraft: GET https://gettangibl.com/api/v1/drafts/{id} (One draft)
- deleteDraft: DELETE https://gettangibl.com/api/v1/drafts/{id} (Permanently delete a creation (not possible once it has an order). Only when the customer clearly asks, after confirming which one)
- updateDraftDetails: PATCH https://gettangibl.com/api/v1/drafts/{id} (application/json: any of {"name", "occasion", "note"}; empty string clears)
- getDraftPreview: GET https://gettangibl.com/api/v1/drafts/{id}/preview (Artwork image (JPEG))
- getDraftProof: GET https://gettangibl.com/api/v1/drafts/{id}/proof (Preview status)
- getDraftProofImage: GET https://gettangibl.com/api/v1/drafts/{id}/proof/image (Product preview image (JPEG))
- requestSupplierMockup: POST https://gettangibl.com/api/v1/drafts/{id}/supplier-mockup (Retry a failed canvas or poster preview)
- startCheckout: POST https://gettangibl.com/api/v1/drafts/{id}/checkout (application/json: optional {"quantity"} (1–5), {"size"} (required for T-shirt and hoodie: ask the customer) and {"address_id"} (where it ships, from listAddresses; required once the customer has saved addresses); header Idempotency-Key (new UUID per order). Returns total, ship_to and a Stripe checkout_url)
- getCart: GET https://gettangibl.com/api/v1/cart (The saved cart: items, prices, one shipping line, total)
- addToCart: POST https://gettangibl.com/api/v1/cart/items (application/json: {"draft_id", optional "size" (required for T-shirt and hoodie), optional "quantity" 1–5}; same creation and size again sets its quantity. Returns the cart)
- updateCartItem: PATCH https://gettangibl.com/api/v1/cart/items/{cart_item_id} (application/json: {"quantity"} 1–5. Returns the cart)
- removeCartItem: DELETE https://gettangibl.com/api/v1/cart/items/{cart_item_id} (Remove one line (POST …/delete also works). Returns the cart)
- checkoutCart: POST https://gettangibl.com/api/v1/cart/checkout (application/json: {"address_id"} (where it ships; required once the customer has saved addresses); header Idempotency-Key (new UUID per order). One order and one Stripe checkout_url for the whole cart; the cart empties once paid)
- listAddresses: GET https://gettangibl.com/api/v1/addresses (The address book: labelled US and Colombian addresses ("Me", "Mom") with address_id and the default)
- createAddressLink: POST https://gettangibl.com/api/v1/addresses/links (application/json: {"label"}. A single-use page (address_url, 30 minutes) where the customer enters the address; same label replaces a saved one)
- getAddressLink: GET https://gettangibl.com/api/v1/addresses/links/{address_link_id} (waiting, saved (with the address and address_id) or expired)
- updateAddress: PATCH https://gettangibl.com/api/v1/addresses/{address_id} (application/json: {"label"} and/or {"is_default": true})
- deleteAddress: DELETE https://gettangibl.com/api/v1/addresses/{address_id} (Remove an address (POST …/delete also works). Only when the customer clearly asks)
- listMyOrders: GET https://gettangibl.com/api/v1/orders (Recent orders and their status)
- getOrder: GET https://gettangibl.com/api/v1/orders/{id} (One order: payment status, total, tracking; report_problem_url (paid orders) is where the customer reports a misprint with photos)
- sendFeedback: POST https://gettangibl.com/api/feedback (application/json: {"message", "topic", "agent_name", "context"})

== Print-ready artwork ==
- Print-ready artwork is composed for the product shape from the start. Before any upload, check the image against the product ratio.
- Create and send the flat artwork itself, never a picture of the product: no mug, frame, wall, room, mockup or person wearing it. Tangibl makes the product preview from the artwork.
- If the image does not match, recreate it natively at the product ratio: regenerate the same scene, subject and style with the correct aspect ratio, or outpaint it with real, coherent scene content. Then show the recomposed image and say in one short sentence that you adapted it to fit the product.
- Never pad, letterbox or fill to fit: no blurred, smeared, mirrored, stretched or solid-colour bars or borders (canvas wrap edges are added by Tangibl, not by you). Never crop away part of the subject.
- Be proactive: whenever the customer mentions Tangibl, printing, framing, a canvas, a poster, a wall, a T-shirt, a hoodie, a mug, stickers, a blanket, playing cards or a gift, create new images directly in the shape that product needs (each product generation_hint: wall art uses the chosen size_options artwork requirements; canvas uses the selected size accepted_ratios, e.g. 2:3 or 3:4 for 24x36; stickers a cut-out on a transparent background; blanket landscape; playing cards 5:7) at high resolution, instead of a default square or wide image. If unsure of the product, ask which one before generating. When the customer names a wall-art product (canvas, poster, photo, framed or metal print) before the image exists, your first reply is the size question; generate only after they answer, directly at the ratio for that size.
- Keep important details (faces, text, signs) away from the outer edges: frames cover a few millimetres, canvas edges wrap around the sides, playing cards are trimmed and blanket edges wrap into the hem.
- Give every creation a short name the customer would recognize (for example "Fox in the snow") when saving it, and add the occasion and a note when the customer mentions them. The occasion is the event or reason (for example "Mom's birthday", "Christmas", "housewarming"); the note is anything else worth remembering (for example "for the reading nook", "use warmer colors next time"). Customers come back to creations by name: listMyDrafts shows names, and updateDraftDetails renames or adds details when asked.
- After every save, show the product preview in the conversation without being asked: poll getDraftProof until image_url is set (usually under a minute), then show getDraftProofImage inline. A canvas is uploaded as flat artwork at the selected size ratio with product_id=canvas-print and size; Tangibl adds the wrapped edges.
- For deletion, ask the customer to identify the creation by name; never infer it from age or recency. requestDraftDeletion shows the exact name, artwork and product preview in a chat widget. Nothing is deleted until the customer reviews the exact name and preview and clicks Confirm deletion in that widget. Direct API deletion is disabled; never confirm for them.
- Customers are usually not technical: plain language works best, and operation names, IDs and technical sizes are rarely useful to them unless they ask.
Example: the customer has a wide 3:2 landscape and wants a framed print. Recomposing it for an 8×10 frame (regenerating the same scene at 5:4, or outpainting sky and foreground with real scene content) gives a much better result than adding blurred bars above and below the original.
Generation hints per product:
- photo-print: Choose 8x10, 16x20, 18x24 or 24x36 with the customer before generating. Use that size_options image_requirements (portrait or landscape); full-bleed, no borders. Pass size on upload.
- poster: Large matte posters only: 18x24 (3:4 portrait or 4:3 landscape) or 24x36 (2:3 or 3:2). Ask the size before generating; use its size_options recommended pixels, full-bleed, with faces and text inside the edges. Pass size on upload.
- framed-print: Choose 8x10, 16x20, 18x24 or 24x36 before generating. Use its size_options image_requirements; no borders, keep key details 5% inside edges. Pass size on upload.
- metal-print: Choose 8x10, 16x20, 20x30 or 24x36 before generating. Use its size_options image_requirements; full-bleed, vivid color, no borders. Pass size on upload.
- canvas-print: Ask the size (8x10, 16x20, 18x24 or 24x36) before generating. Generate flat portrait artwork in a shape that size accepts (size_options full_wrap_artwork.accepted_ratios): 8x10 takes 4:5, 3:4 or square; 16x20 takes 4:5 or 3:4; 18x24 takes 3:4, 4:5 or 2:3; 24x36 takes 2:3 or 3:4. A standard tall 2:3 image works for 18x24 and 24x36. Tangibl wraps and mirrors the edges itself: no wrap band, border or padding. Keep faces and text a little in from the edges. Upload it right away with product_id=canvas-print and size, then show getDraftProofImage.
- t-shirt: Compose for the front of a white T-shirt: 4:5 portrait (2400×3000), printed 12 in wide across the chest. A bold subject reads best; a subject on a transparent background (PNG) prints without a box around it, a full scene prints as a rectangle. No borders.
- hoodie: Compose for the front of a white hoodie: 4:5 portrait (2400×3000) or square, printed up to 12 × 12 in on the chest above the pocket. A subject on a transparent background (PNG) prints without a box around it. No borders.
- mug: Compose for an 11 oz mug: 4:5 portrait or square (2400×2400 or larger). The same image is printed on both sides at full mug height, so keep the subject centered with a little space around it. No borders.
- stickers: Create sticker art as a cut-out: the subject alone on a fully transparent background (PNG with alpha), no background scene, no border or drop shadow (the white kiss-cut border is added by the cut), bold shapes, square canvas (2400×2400 or larger), subject filling most of it. Only use a full rectangular image if the customer asks for one.
- blanket: Compose as a 50×60 in sherpa blanket laid landscape: 6:5 (for example 3000×2500), full-bleed to every edge. The edges wrap into the hem, so keep faces and text at least 8% in from each side. Portrait artwork loses most of its top and bottom.
- playing-cards: Compose as a playing card back: 5:7 portrait (at least 1550×2250), full-bleed to every edge. About 1/8 in is trimmed off each side and the corners are rounded, so keep faces, text and key details well inside (at least 8% from each edge).

== Talking with customers ==
- Most customers are not technical. Plain language works best; operation names, endpoints, IDs, pixel sizes and file formats are rarely useful to them unless they ask.
- Creations are easiest to refer to by name ("your Fox in the snow poster"). Each upload carries a short name, plus occasion and note when the customer mentions them; new versions keep their parent's details unless changed. listMyDrafts shows names, so "the one for Mom's birthday" can be found without IDs, and updateDraftDetails renames or updates details.
- Customers expect the assistant to handle sizing, composition, file preparation, uploads and retries, rather than being asked to crop, resize or export.
- Product images are previews. Nothing is ordered or charged unless the customer checks out and approves the payment.

== Ordering ==
Ordering: only when listProducts says ordering_available is true for this customer. For wall art, choose the size before uploading and pass size to uploadDraft or uploadCanvasPrintFile. Checkout uses the saved draft size; to change it, create and review a new draft using reviseDraftProduct with size (canvas requires a new upload). For a T-shirt or hoodie, ask the customer's size (sizes in listProducts) and pass it as size to startCheckout; stickers default to 4×4 in unless the customer picks 3×3 or 5.5×5.5. That flag and ordering_notice are specific to the signed-in customer and take precedence over general statements on the Tangibl website (which describe the public launch). Prices in listProducts include standard US shipping: say "shipping included", never "free shipping". The Stripe checkout page shows shipping as its own line, and promotion codes discount the product, not shipping. Before confirming a larger wall-art order, call listProducts with product_id and size to quote that exact size; the unfiltered catalog only prices the default. Where it ships: the address book (listAddresses) holds labelled addresses such as "Me" and "Mom", in the US or Colombia. Colombian orders need a saved Colombian address (createAddressLink) before checkout; their shipping costs more and is quoted at checkout (the listProducts prices are for the US), and canvas, metal prints and playing cards don't ship there. When the customer names someone ("send it to me", "to my mom"), pass that address_id to startCheckout or checkoutCart; if more than one could match, ask. If they name nobody, confirm the default address with them before checkout ("Ship to Me: 12 Oak St, Brooklyn, NY?"), or ask which one when there is no default. Never make an address the default unless the customer asks. For someone not in the address book, call createAddressLink, give the customer address_url, then getAddressLink and read the address back. Never collect or type an address in the chat. While the address book is empty, a US customer's own first order needs no address_id: the checkout page asks for the address and saves it as "Me". One order ships to one address: items for different people need separate checkouts. When the customer wants to buy, confirm the item, quantity, total and recipient, call startCheckout, then complete payment on checkout_url, a Stripe checkout page with a standard card form (it offers to save the card, and shows saved cards next time), with the customer approving the payment (or give them the link to pay themselves). Never pay without the customer's explicit approval of the total. Describe order progress in Tangibl's own words (made to order by Tangibl, production and shipping times, tracking by email); never name or mention a print partner, supplier or manufacturer. Several creations in one order (cheaper: one shipment, and each extra item adds little shipping): use the cart. addToCart each creation (draft_id, size where needed, quantity), show getCart (items, shipping, total) to the customer, then checkoutCart for one checkout_url covering everything. The cart is saved and emptied once that order is paid; removeCartItem or updateCartItem change it. When the customer asks to put creations together or to add one more, use the cart instead of separate checkouts. startCheckout remains the shortcut for a single creation. A customer with a promo code enters it on the checkout page (Add promotion code); the discounted total shows there before paying. getOrder shows whether payment went through. When ordering_available is false, the creation stays saved for when ordering opens. Returns and reprints: every item is personalized and made to order, so there are no returns or refunds for change of mind. Tangibl reprints only proven misprints (a production error, shown in a photo) reported within 30 days of delivery. Mention this in one short sentence before checkout. To report a misprint, give the customer report_problem_url from getOrder; they add the photos there. Full policy: /returns
Steps: startCheckout (draft_id, optional quantity 1–5, size for T-shirt and hoodie; wall art uses its saved draft size) returns the total and checkout_url, valid about 30 minutes. The page asks for a US shipping address, email and card. After payment, getOrder shows status paid. Shipping is US-only.
Several creations together: addToCart (draft_id, size, quantity) for each, getCart to show the items, shipping and total, then checkoutCart for one checkout_url. updateCartItem (cart_item_id, quantity) and removeCartItem (cart_item_id) change it. getOrder lists every item in items.

== Wall-art sizes ==
Ask the customer to choose a size before generating. listProducts size_options describes the exact geometry for each size. Pass size when saving the image and in reviseDraftProduct. Photo print, framed print and canvas: 8x10, 16x20, 18x24, 24x36. Metal: 8x10, 16x20, 20x30, 24x36. Matte poster: only 18x24 and 24x36.
Resolution: Tangibl prints wall art at 150 PPI or more, measured on the image you provide (size_options minimum_pixels). Minimum short × long side: 8x10 1200 × 1500, 16x20 2400 × 3000, 18x24 2700 × 3600, 20x30 3000 × 4500, 24x36 3600 × 5400. A smaller image is refused for that size (resolution_too_low) and the error names the sizes it is large enough for: offer one of those, or recreate it larger. Most generated images (about 1024–1536 px) are enough for 8x10 only, so check before promising a big size.
A saved preview is bound to its size. To change size, use reviseDraftProduct with parent_id, product_id and size; if the shape changes, upload recomposed artwork instead. Canvas needs artwork at the new size ratio when the ratio changes. Review the new preview before checkout. Older 8x10 poster drafts remain viewable but cannot start a new order.

== Canvas (gallery wrap) ==
1. Ask the size before generating, then generate flat portrait artwork in a shape that size accepts (size_options full_wrap_artwork.accepted_ratios): 8x10 takes 4:5, 3:4 or square; 16x20 takes 4:5 or 3:4; 18x24 takes 3:4, 4:5 or 2:3; 24x36 takes 2:3 or 3:4. JPEG or PNG under 4 MiB, at 150 PPI or more for the size (short side at least 1200 px for 8x10, 2400 for 16x20, 2700 for 18x24, 3600 for 24x36).
2. Tangibl builds the full-wrap print file: it scales the artwork to cover the front at 300 PPI; a little extra width or height wraps around the sides and the rest of the edge is mirrored. Do not add a wrap band, border or padding and do not outpaint. Keep faces and text a little in from the edges.
3. Save it with product_id=canvas-print and size (see Tools for the upload options).
4. Show getDraftProofImage immediately. The preview shows the actual selected size and wrap geometry. An extra product photo may also follow; it is optional.

== Poster, photo print, framed print, metal print ==
1. Use the selected size_options image_requirements. For example, 18x24 uses 3:4 portrait or 4:3 landscape; 24x36 uses 2:3 or 3:2. Target 300 pixels per inch. Prepare the whole composition for the selected shape, never padding or cropping away the subject.
2. Save it with product_id and size. JPEG/PNG under 4 MiB; JPEG recommended for large files.
3. Show getDraftProofImage immediately. If blocked, follow readiness.guidance. Below 150 PPI (readiness.effective_ppi) the size cannot be ordered: offer a smaller size or recreate the image larger.
4. Posters may also get an optional extra product photo.

== T-shirt, hoodie, mug, stickers, blanket, playing cards ==
1. Artwork is any JPEG/PNG of at least 1000 px on the short side (2400 px or more recommended); Tangibl composes it into the product's print file. Follow each product's generation_hint for the best shape:
   - T-shirt and hoodie: 4:5 portrait, printed across the chest; a subject on a transparent background prints without a box around it.
   - Mug: 4:5 or square; the same image goes on both sides.
   - Stickers: a cut-out subject on a fully transparent background (PNG), square canvas; the cut follows its outline with a thin white border. Only use a full rectangular image if the customer asks.
   - Blanket: landscape (6:5 or 5:4); the print fills the whole 50 × 60 in blanket.
   - Playing cards: 5:7 portrait for the card back; about 1/8 in is trimmed from each edge.
2. Save it with product_id (see Tools for the upload options). The preview is ready immediately (getDraftProof status preview_ready): the exact print file on the product. Show it right away.
3. Sizes are chosen at checkout: T-shirt S–5XL and hoodie S–3XL (ask the customer), stickers 3×3, 4×4 (default) or 5.5×5.5 in; mug (11 oz), blanket (50 × 60 in) and playing cards have one size.

== Changes ==
- Same artwork, different product among photo/poster/framed/metal and the merch products: reviseDraftProduct with the earlier draft as parent_id (stickers usually look best from a transparent cut-out instead).
- Switching to or from canvas: upload the artwork for the canvas size ratio, as above.
- Edited artwork: save the new file as a new creation with the same name (over REST, ?parent_id=<earlier draft> links the versions).

== Feedback for the Tangibl team ==
Customers' ideas, requests and problems are welcome through sendFeedback: a short message, a topic, agent_name, and brief context, sent with the customer's agreement. An email address is only needed if they want a reply. Keys, payment details and other people's personal data don't belong in feedback. The main support contact is support@gettangibl.com; the feedback API remains available.

== Errors ==
- 401: the connection is missing, expired or revoked; reconnecting the Tangibl connector fixes it.
- 429: rate limited; retrying after a minute usually works.
- Other errors: one retry is reasonable; the customer's saved creations are not affected.