{"openapi":"3.1.0","info":{"title":"Printvine API","version":"2026-07-13","description":"Universal printing infrastructure. Upload artwork, run product-aware preflight, quote, order, and track — every live vendor submission requires recorded human approval of the exact production file."},"servers":[{"url":"https://printvine-hqy9d6el1-bouncinsoul17s-projects.vercel.app/api"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"pv_test_sk_... or pv_live_sk_..."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Same key + same payload replays the original response; same key + different payload returns IDEMPOTENCY_CONFLICT."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"request_id":{"type":"string"},"doc_url":{"type":"string"}}}}},"Address":{"type":"object","required":["name","line1","city","state","postal_code","country"],"properties":{"name":{"type":"string"},"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2}}}}},"paths":{"/v1/products":{"get":{"summary":"List products","responses":{"200":{"description":"Product list"}}}},"/v1/products/{id}":{"get":{"summary":"Get a product with its variants","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Product"},"404":{"description":"Not found"}}}},"/v1/variants":{"get":{"summary":"List product variants","parameters":[{"name":"product","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Variant list"}}}},"/v1/files":{"post":{"summary":"Upload artwork (multipart `file` part, or JSON {filename, content_base64})","responses":{"201":{"description":"File created"},"400":{"description":"Unsupported or invalid file"}}}},"/v1/files/{id}":{"get":{"summary":"Get file metadata","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"File"}}}},"/v1/preflight_jobs":{"post":{"summary":"Run product-aware preflight; returns report + production_file_id","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["file_id","variant_id"],"properties":{"file_id":{"type":"string"},"variant_id":{"type":"string"}}}}}},"responses":{"201":{"description":"Completed preflight job"}}}},"/v1/preflight_jobs/{id}":{"get":{"summary":"Get a preflight job","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Preflight job"}}}},"/v1/quotes":{"post":{"summary":"Create a quote (requires production candidates from preflight)","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["line_items","ship_to"],"properties":{"line_items":{"type":"array","items":{"type":"object","required":["variant_id","quantity","files"],"properties":{"variant_id":{"type":"string"},"quantity":{"type":"integer"},"files":{"type":"object","required":["front"],"properties":{"front":{"type":"string"},"back":{"type":"string"}}}}}},"ship_to":{"$ref":"#/components/schemas/Address"},"routing_preference":{"type":"string","enum":["lowest_cost","fastest_delivery","highest_reliability","balanced","preferred_vendor","manual_review"]}}}}}},"responses":{"201":{"description":"Quote with shipping options"},"422":{"description":"PREFLIGHT_REQUIRED / NO_ELIGIBLE_VENDOR"}}}},"/v1/quotes/{id}":{"get":{"summary":"Get a quote","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Quote"}}}},"/v1/quotes/{id}/select_shipping":{"post":{"summary":"Select a shipping option (finalizes the total)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated quote"}}}},"/v1/orders":{"post":{"summary":"Create an order from a quote; returns checkout URL","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"201":{"description":"Order + checkout"},"422":{"description":"Quote unusable"}}},"get":{"summary":"List orders (cursor pagination: limit, starting_after)","responses":{"200":{"description":"Order list"}}}},"/v1/orders/{id}":{"get":{"summary":"Get an order with print jobs","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order"}}}},"/v1/orders/{id}/cancel":{"post":{"summary":"Cancel before vendor submission (auto-refunds paid orders)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cancelled order"},"409":{"description":"Not cancellable"}}}},"/v1/orders/{id}/shipments":{"get":{"summary":"List shipments for an order","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Shipments"}}}},"/v1/orders/{id}/timeline":{"get":{"summary":"Order event timeline","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Events"}}}},"/v1/webhook_endpoints":{"post":{"summary":"Register a signed webhook endpoint (secret returned once)","responses":{"201":{"description":"Endpoint with secret"}}},"get":{"summary":"List webhook endpoints","responses":{"200":{"description":"Endpoints"}}}},"/v1/webhook_endpoints/{id}":{"delete":{"summary":"Delete a webhook endpoint","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"}}}},"/v1/events":{"get":{"summary":"Poll the event feed (webhook alternative)","responses":{"200":{"description":"Events"}}}}}}