{"openapi":"3.1.0","info":{"title":"massprint API","version":"1.0.0","description":"Print-on-demand for AI agents: upload a PDF, pay a Razorpay link, get a printed storybook delivered in India. MCP server (no key needed) at /mcp. Docs at /docs; index at /llms.txt.","contact":{"email":"work@msomu.com"}},"servers":[{"url":"https://themassprint.com"}],"security":[{"apiKey":[]},{}],"paths":{"/v1/catalog":{"get":{"summary":"SKUs, formats, prices, limits","responses":{"200":{"description":"Catalog"}}}},"/v1/uploads":{"post":{"summary":"Start a PDF upload","description":"Requires an API key or a web session. Returns a signed put_url. PUT the raw PDF bytes to it; the PUT response includes the validation report.","security":[{"apiKey":[]}],"responses":{"201":{"description":"Upload created","content":{"application/json":{"schema":{"type":"object","properties":{"upload_id":{"type":"string"},"put_url":{"type":"string"},"expires_at":{"type":"string"},"max_bytes":{"type":"integer"}}}}}},"401":{"description":"No API key or session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/uploads/{id}/content":{"put":{"summary":"Upload the PDF bytes (signed URL from POST /v1/uploads)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"exp","in":"query","required":true,"schema":{"type":"string"}},{"name":"sig","in":"query","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"Stored and printable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadValidation"}}}},"403":{"description":"Bad/expired signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Not a PDF — rejected before storage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Stored but has blocking validation errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadValidation"}}}}},"security":[]}},"/v1/uploads/{id}/validation":{"get":{"summary":"Validation report for an upload","description":"Requires an API key or a web session, and returns 404 for uploads the caller does not own.","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadValidation"}}}},"401":{"description":"No API key or session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/orders":{"post":{"summary":"Create a print order","description":"Validates PDF + address BEFORE minting any payment link. payment_link keys/anonymous: response carries payment_url. invoiced keys: order auto-confirms. Save order_token — shown once.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"upload_id":{"type":"string"},"sku":{"type":"string","default":"storybook","description":"Optional; inferred from format (sticker-a3 → sticker-a3, else storybook)."},"format":{"type":"string","enum":["paperback","hardcover","sticker-a3"],"description":"paperback/hardcover: bound storybook. sticker-a3: single-sheet A3 portrait sticker / wall chart (exactly 1 page, 842×1191 pt)."},"copies":{"type":"integer","minimum":1,"maximum":20,"default":1},"email":{"type":"string","format":"email"},"address":{"$ref":"#/components/schemas/Address"}},"required":["upload_id","format","email","address"]}}}},"responses":{"201":{"description":"Order created","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/Order"},"order_token":{"type":"string"}}}}}},"422":{"description":"Invalid fields or unprintable PDF","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/orders/{id}":{"get":{"summary":"Order status + tracking","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"token","in":"query","required":false,"schema":{"type":"string"},"description":"order_token (alternative to API-key/session auth)"},{"name":"X-Order-Token","in":"header","required":false,"schema":{"type":"string"},"description":"order_token as a header — preferred over ?token so it stays out of URLs/logs."}],"responses":{"200":{"description":"Order","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/Order"}}}}}},"403":{"description":"Not the owner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/orders/{id}/cancel":{"post":{"summary":"Cancel an unpaid order","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"token","in":"query","required":false,"schema":{"type":"string"}},{"name":"X-Order-Token","in":"header","required":false,"schema":{"type":"string"},"description":"order_token as a header (alternative to ?token)."}],"responses":{"200":{"description":"Canceled"},"409":{"description":"Not awaiting_payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook-endpoints":{"post":{"summary":"Register a status-callback URL (API key required)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"}},"required":["url"]}}}},"responses":{"201":{"description":"Registered; save the returned secret (shown once)"}}},"get":{"summary":"List webhook endpoints","responses":{"200":{"description":"List"}}}},"/v1/webhook-endpoints/{id}":{"delete":{"summary":"Deactivate a webhook endpoint (API key required)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deactivated","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}}}}}},"404":{"description":"No such endpoint on this key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/enterprise/apply":{"post":{"summary":"Apply for an enterprise (invoiced) account","description":"Self-serve enterprise application. GSTIN required for tax invoicing. Reviewed before issue; the API key is emailed to contact_email once approved. Agents can use the apply_enterprise MCP tool instead.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company_name":{"type":"string"},"contact_email":{"type":"string","format":"email"},"gstin":{"type":"string","description":"15-char India GSTIN, e.g. 29ABCDE1234F1Z5","pattern":"^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z][1-9A-Z]Z[0-9A-Z]$"},"expected_monthly_volume":{"type":"integer","minimum":0},"notes":{"type":"string"}},"required":["company_name","contact_email","gstin"]}}}},"responses":{"201":{"description":"Application received (pending review)"},"422":{"description":"Invalid fields (e.g. bad GSTIN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[]}},"/v1/health":{"get":{"summary":"Liveness","responses":{"200":{"description":"ok"}},"security":[]}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Platform API key (mp_live_...). Optional for one-off agent use."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"resolution":{"type":"string","description":"How the caller can recover."},"details":{}},"required":["code","message"]}}},"Address":{"type":"object","properties":{"name":{"type":"string"},"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"pincode":{"type":"string","pattern":"^[1-9][0-9]{5}$","description":"6-digit India PIN"},"phone":{"type":"string","description":"India mobile, optional +91"}},"required":["name","line1","city","state","pincode","phone"]},"Order":{"type":"object","properties":{"order_id":{"type":"string"},"status":{"type":"string","enum":["awaiting_payment","confirmed","printing","shipped","delivered","expired","canceled","refunded"]},"sku":{"type":"string"},"format":{"type":"string","enum":["paperback","hardcover","sticker-a3"]},"copies":{"type":"integer"},"page_count":{"type":"integer"},"amount":{"type":"object","properties":{"total_paise":{"type":"integer"},"display":{"type":"string"},"currency":{"type":"string"}}},"email":{"type":"string","format":"email"},"payment_mode":{"type":"string","enum":["payment_link","invoiced"]},"payment_url":{"type":"string","description":"Present while awaiting_payment: the Razorpay link to pay."},"payment_expires_at":{"type":"string"},"paid_at":{"type":"string"},"tracking":{"type":"object","properties":{"carrier":{"type":"string"},"awb":{"type":"string"},"url":{"type":"string","description":"Clickable tracking link, when the shipper provided one."}}},"created_at":{"type":"string"},"updated_at":{"type":"string"}}},"Issue":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"resolution":{"type":"string"}}},"Validation":{"type":"object","properties":{"printable":{"type":"boolean"},"page_count":{"type":"integer"},"trim":{"type":"object","properties":{"width_mm":{"type":"number"},"height_mm":{"type":"number"},"name":{"type":"string"}}},"size_bytes":{"type":"integer"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Issue"}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/Issue"}},"sku":{"type":"string","description":"SKU whose rules the file best matches; top-level errors/warnings are for this SKU."},"by_sku":{"type":"object","description":"Per-SKU verdict (the format is not declared at upload time, so the file is checked against every SKU).","additionalProperties":{"type":"object","properties":{"printable":{"type":"boolean"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Issue"}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/Issue"}}}}}}},"UploadValidation":{"type":"object","properties":{"upload_id":{"type":"string"},"validation":{"$ref":"#/components/schemas/Validation"}}}}}}