{"openapi":"3.1.0","info":{"title":"Premier Letters API","version":"1.0.0","description":"Create, quote, preview and track real, pen-written letters, cards and postcards mailed via USPS. See also the remote MCP server at https://www.premierletters.com/api/mcp for AI agents.","contact":{"url":"https://www.premierletters.com/developers"}},"servers":[{"url":"https://www.premierletters.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"pl_live_...","description":"API key from Settings → API keys. Sent as `Authorization: Bearer pl_live_...`."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"suggestion":{"type":"string"},"details":{}},"required":["error","message"]},"Recipient":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address_line1":{"type":"string"},"address_line2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string","description":"Two-letter US state code"},"zip":{"type":"string"},"custom_fields":{"type":"object","additionalProperties":{"type":"string"}}}},"OrderOptions":{"type":"object","properties":{"handwriting_style":{"type":"string","description":"Font UUID from GET /api/v1/styles"},"paper_type":{"type":"string","enum":["standard","premium"]},"product_type":{"type":"string","description":"e.g. letter, card, postcard"},"authenticity_preset":{"type":"string"},"mailing_option":{"type":"string","enum":["we_mail","you_mail_stamped","you_mail_no_stamp"]},"include_letter":{"type":"boolean"},"include_envelope":{"type":"boolean"},"copies":{"type":"integer","minimum":1,"maximum":500}}},"OrderCreate":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Letter body. Supports {{first_name}}/{{last_name}}/{{greeting}} merge fields."},"recipients":{"type":"array","items":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address_line1":{"type":"string"},"address_line2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string","description":"Two-letter US state code"},"zip":{"type":"string"},"custom_fields":{"type":"object","additionalProperties":{"type":"string"}}}}},"options":{"type":"object","properties":{"handwriting_style":{"type":"string","description":"Font UUID from GET /api/v1/styles"},"paper_type":{"type":"string","enum":["standard","premium"]},"product_type":{"type":"string","description":"e.g. letter, card, postcard"},"authenticity_preset":{"type":"string"},"mailing_option":{"type":"string","enum":["we_mail","you_mail_stamped","you_mail_no_stamp"]},"include_letter":{"type":"boolean"},"include_envelope":{"type":"boolean"},"copies":{"type":"integer","minimum":1,"maximum":500}}},"payment":{"type":"object","properties":{"method":{"type":"string","enum":["card_on_file","checkout_session"]},"return_url":{"type":"string","format":"uri"}}},"skip_invalid":{"type":"boolean"}}},"Order":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"letter_count":{"type":"integer"},"total_cents":{"type":"integer"},"tracking_url":{"type":"string","format":"uri"},"checkout_url":{"type":"string","format":"uri"}}},"PricingBreakdown":{"type":"object","properties":{"basePrice":{"type":"integer","description":"Cents"},"paperSurchargeCents":{"type":"integer"},"printedPageSurchargeCents":{"type":"integer"},"printedEnvelopeSurchargeCents":{"type":"integer"},"signatureSurchargeCents":{"type":"integer"},"meterSurchargeCents":{"type":"integer"},"postageCents":{"type":"integer","description":"Postage passed through at face value; 0 when the customer stamps it themselves"},"pieceCentsPerLetter":{"type":"integer","description":"Pen work per piece, excluding postage"},"totalCents":{"type":"integer"},"perLetterCents":{"type":"integer"},"pieceCount":{"type":"integer"}}}}},"paths":{"/api/v1/config":{"get":{"summary":"Public pricing + agent-discovery config","security":[],"responses":{"200":{"description":"Live pricing tiers, character meter, and service levels"}}}},"/api/v1/auth/verify":{"get":{"summary":"Verify an API key","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Key is valid; returns account + payment method summary"},"401":{"description":"Missing or invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/styles":{"get":{"summary":"List handwriting styles","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Array of available fonts"}}}},"/api/v1/validate":{"post":{"summary":"Dry-run validation + pricing for an order","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderCreate"}}}},"responses":{"200":{"description":"Order is valid; includes total_cents and a full PricingBreakdown","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"total_cents":{"type":"integer"},"breakdown":{"$ref":"#/components/schemas/PricingBreakdown"}}}}}},"422":{"description":"One or more recipients/fields failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/preview":{"post":{"summary":"Render a letter to SVG and get its price, without creating an order","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string"},"handwriting_style":{"type":"string"},"product_type":{"type":"string"},"paper_type":{"type":"string"}}}}}},"responses":{"200":{"description":"SVG data URL, char count, and price"}}},"get":{"summary":"Same as POST, via query params (message, handwriting_style, product_type, paper_type)","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"SVG data URL, char count, and price"}}}},"/api/v1/orders":{"get":{"summary":"List the caller's orders","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer"}},{"name":"status","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated order list"}}},"post":{"summary":"Create (and pay for) a new order","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderCreate"}}}},"responses":{"201":{"description":"Order created and paid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"202":{"description":"Order created, payment pending (checkout_url returned)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"402":{"description":"Payment required or failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/orders/{id}":{"get":{"summary":"Get order detail with recipients","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Order + recipients + summary"},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/orders/{id}/tracking":{"get":{"summary":"Lightweight per-recipient tracking","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Tracking summary + per-recipient status"},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/webhooks/stripe":{"post":{"summary":"Stripe webhook receiver (inbound, not called by API clients)","security":[],"responses":{"200":{"description":"Acknowledged"}}}}}}