{"openapi":"3.1.0","info":{"title":"parseaddr","description":"Hosted libpostal. Turn messy free-text addresses into clean structured fields — one API call, no 2–4GB self-host.","version":"1.0.0"},"paths":{"/health":{"get":{"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/parse":{"post":{"summary":"Parse","operationId":"parse_v1_parse_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-parseaddr-client","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Parseaddr-Client"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParseIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/expand":{"post":{"summary":"Expand","operationId":"expand_v1_expand_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-parseaddr-client","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Parseaddr-Client"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpandIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/signup":{"post":{"summary":"Signup","description":"Free-tier self-serve: email -> a rate-capped API key. No card required. Paid plans are\nan upgrade away via Stripe Checkout. A per-IP throttle stops one host minting unlimited\nfree keys (each key carries its own monthly cap).","operationId":"signup_v1_signup_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/usage":{"get":{"summary":"Usage","description":"Machine-readable usage for the caller's own key — powers the dashboard and lets an\nagent self-check its remaining quota (and prepaid credit balance) before hitting the cap.","operationId":"usage_v1_usage_get","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/checkout":{"post":{"summary":"Create Checkout","description":"Create a Stripe Checkout Session for a paid plan and return its URL. The matching\nwebhook issues or upgrades the key once the session completes.","operationId":"create_checkout_v1_checkout_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/credits/topup":{"post":{"summary":"Credits Topup","description":"Agent-callable prepaid-credit purchase: exchange a pack for a one-time Stripe\nCheckout URL. An agent (no human form) calls this with its Bearer key, gets a\ncheckout_url, and the webhook credits the balance on payment — the buy path that\nkeeps a pipeline running past its monthly cap without a human in the loop.","operationId":"credits_topup_v1_credits_topup_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopupIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/checkout/key":{"get":{"summary":"Checkout Key","description":"Reveal the API key issued for a completed Checkout session, so a brand-new buyer — who paid\nwithout ever holding a free key to paste — can retrieve it on the success page. Guards:\n  - the session must be a real, PAID, completed session on our own Stripe account, and\n  - we only ever return that session's own linked customer's key.\nReturns {\"status\": \"pending\"} (not an error) when the async webhook hasn't issued the key yet:\nStripe's success redirect can beat its own webhook by a few seconds, so the page polls.","operationId":"checkout_key_v1_checkout_key_get","parameters":[{"name":"session_id","in":"query","required":true,"schema":{"type":"string","title":"Session Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"CheckoutIn":{"properties":{"plan":{"type":"string","maxLength":32,"title":"Plan","examples":["pro"]},"email":{"anyOf":[{"type":"string","maxLength":254},{"type":"null"}],"title":"Email","description":"Prefill the Checkout email."}},"type":"object","required":["plan"],"title":"CheckoutIn"},"ExpandIn":{"properties":{"address":{"type":"string","maxLength":2000,"title":"Address","examples":["100 main st"]}},"type":"object","required":["address"],"title":"ExpandIn"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ParseIn":{"properties":{"address":{"type":"string","maxLength":2000,"title":"Address","examples":["flat 2, 10 downing st, london sw1a 2aa"]},"language":{"anyOf":[{"type":"string","maxLength":16},{"type":"null"}],"title":"Language","description":"Optional ISO language hint, e.g. 'en'."}},"type":"object","required":["address"],"title":"ParseIn"},"SignupIn":{"properties":{"email":{"type":"string","maxLength":254,"title":"Email","examples":["dev@example.com"]},"source":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Source","description":"First-touch channel (mcp/pkg-npm/ad/…)."}},"type":"object","required":["email"],"title":"SignupIn"},"TopupIn":{"properties":{"pack":{"type":"string","maxLength":16,"title":"Pack","examples":["small"]}},"type":"object","required":["pack"],"title":"TopupIn"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"ApiKeyBearer":{"type":"http","scheme":"bearer","description":"Your parseaddr API key as a Bearer token (Authorization: Bearer pa_live_…)."}}},"security":[{"ApiKeyBearer":[]}]}