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: canvas, poster, photo print, framed print and metal print, all 8×10 inches. Product images are previews; ordering is not open yet, and nothing can be bought or charged through the connector.

== API calls ==
All calls use the connector's Bearer token. Full 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); header Idempotency-Key (new UUID per order). Returns total and a Stripe checkout_url)
- 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.
- 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. Never crop away part of the subject.
- Be proactive: whenever the customer mentions Tangibl, printing, framing, a canvas, a poster, a wall, or a gift, create new images directly at a print ratio (8×10: 4:5 portrait or 5:4 landscape; canvas: 11:13 full-wrap) at high resolution, instead of a default square or wide image. If unsure of the product, ask which one before generating, or default to 4:5 portrait.
- Keep important details (faces, text, signs) away from the outer edges: frames cover a few millimetres, and canvas edges wrap around the sides.
- 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 always uploaded as its full-wrap file (3300×3900, 11:13) with product_id=canvas-print; there is no front-only canvas.
- Delete a creation (deleteDraft) only when the customer clearly asks, after confirming which one by name; deletion is permanent and not possible once it has an order.
- 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: Compose as an 8×10 print: 4:5 portrait (2400×3000) or 5:4 landscape (3000×2400), full-bleed scene reaching every edge, no borders, no text near edges.
- poster: Compose as an 8×10 matte poster: 4:5 portrait (2400×3000) or 5:4 landscape (3000×2400), full-bleed scene reaching every edge, no borders, keep text and faces a little in from the edges.
- framed-print: Compose for an 8×10 frame: 4:5 portrait (2400×3000) or 5:4 landscape (3000×2400), full-bleed scene reaching every edge, keep key details at least 5% in from each edge, no borders.
- metal-print: Compose as an 8×10 metal print: 4:5 portrait (2400×3000) or 5:4 landscape (3000×2400), full-bleed scene reaching every edge, vivid colour, no borders.
- canvas-print: Compose as an 8×10 gallery-wrap canvas: 11:13 portrait at 3300×3900. Keep the whole subject inside the central 2400×3000 front; the outer 450 px on every side is continuing background only (it wraps around the edges). No borders.

== 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. 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 free US shipping. When the customer wants to buy, confirm the item, quantity and total, call startCheckout, then complete payment on checkout_url, a Stripe checkout page with a standard card form, 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. 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 15 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 (POST https://gettangibl.com/api/v1/drafts/{id}/checkout, new UUID Idempotency-Key, optional quantity 1–5) 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.

== Canvas (8×10 in, gallery wrap) — supplier product preview ==
1. The canvas file is one portrait image, exactly 3300×3900 pixels (11:13), JPEG, under 4 MB.
2. The canvas wraps around a wooden frame:
   - The front is the central 2400×3000 area (x 450–2850, y 450–3450).
   - The whole subject (heads, ears, paws, legs, tails, faces, any text) belongs inside the front, with breathing room (ideally inside x 600–2700, y 600–3300).
   - The outer 450-pixel band on every side wraps around the edges and back, so it should contain only continuing background (sky, grass, foliage, wall, texture), with no borders or frames.
   - When starting from an existing image, extending its background outward to 3300×3900 works better than cropping; if the subject would reach the wrap band, a new version is better.
3. Upload with uploadCanvasPrintFile or uploadDraft (product_id=canvas-print, a new UUID as Idempotency-Key, reused only to retry the same file).
4. The canvas preview is ready immediately (getDraftProof status preview_ready): getDraftProofImage shows the canvas at a slight angle, drawn from the exact file, with the image wrapping around the 1.25 in sides. Show it to the customer right away.
5. A photo from the print partner may follow (supplier_mockup.status ready, image at supplier_mockup.image_url); it is optional. requestSupplierMockup retries it if it failed.
6. A rejected upload (wrong size or ratio) means the file needs adjusting before trying again.

== Poster, photo print, framed print, metal print (8×10 in) ==
1. Artwork is 4:5 portrait (2400×3000) or 5:4 landscape (3000×2400), JPEG/PNG under 4 MB, printed edge to edge (the frame covers about 0.1 in of each edge). Other shapes need recreating or outpainting at the right ratio (see Print-ready artwork), not padding or cropping.
2. Upload with uploadDraft (product_id, new UUID Idempotency-Key).
3. The product preview is ready immediately (getDraftProof status preview_ready): getDraftProofImage shows the artwork on the actual product, drawn from the exact file. Show it right away. If status is blocked, the artwork does not fit; recreate it at the right ratio.
4. Posters may also get an optional photo from the print partner (supplier_mockup), as for canvas.

== Changes ==
- Same artwork, different product among photo/poster/framed/metal: reviseDraftProduct with the earlier draft as parent_id.
- Switching to or from canvas: the canvas needs its own wrap-ready image, uploaded as above.
- Edited artwork: upload the new file with ?parent_id=<earlier draft> so versions stay linked.

== Feedback for the Tangibl team ==
Customers' ideas, requests and problems are welcome through sendFeedback (POST https://gettangibl.com/api/feedback): 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. There is no support email yet; this is the channel.

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