{"openapi":"3.1.0","info":{"title":"GetPassage public and agent-facing API","version":"2026-08-25","summary":"Documented public API surfaces for Passage agents and partner evaluators.","description":"Passage is an approval-led bereavement administration platform. Public endpoints support lead capture, preview task generation, contact requests and feedback. Authenticated user actions require a Clerk session. This specification documents discoverable public integration surfaces only; private app, admin and webhook routes are intentionally excluded.","contact":{"name":"Passage","email":"hello@getpassage.co.uk","url":"https://getpassage.co.uk/contact"}},"servers":[{"url":"https://getpassage.co.uk","description":"Production"}],"tags":[{"name":"Discovery","description":"Agent-readable discovery surfaces."},{"name":"Leads","description":"Free-plan intake and lead saving."},{"name":"Contact","description":"Family or partner contact requests."},{"name":"Testimonials","description":"Public testimonials and moderated feedback submission."},{"name":"Billing","description":"Authenticated Premium checkout."}],"paths":{"/llms.txt":{"get":{"tags":["Discovery"],"summary":"Agent-readable site summary","operationId":"getLlmsTxt","responses":{"200":{"description":"Plain-text agent guide.","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/openapi.json":{"get":{"tags":["Discovery"],"summary":"OpenAPI specification","operationId":"getOpenApiSpec","responses":{"200":{"description":"OpenAPI 3.1 JSON document.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/leads/preview-tasks":{"post":{"tags":["Leads"],"summary":"Generate a free bereavement task preview","operationId":"previewTasks","description":"Returns task suggestions from user-provided intake answers. This endpoint does not send messages, submit forms or create a user account.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewTasksRequest"}}}},"responses":{"200":{"description":"Preview tasks generated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewTasksResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/api/leads":{"post":{"tags":["Leads"],"summary":"Create or update a lead after explicit user save action","operationId":"createLead","description":"Stores contact and case-intake details only after the user chooses to save their plan. Agents must not call this without current user approval.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLeadRequest"}}}},"responses":{"200":{"description":"Lead created or updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLeadResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/api/contact":{"post":{"tags":["Contact"],"summary":"Submit a contact request","operationId":"submitContactRequest","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactRequest"}}}},"responses":{"200":{"description":"Contact request accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/api/testimonials":{"get":{"tags":["Testimonials"],"summary":"List approved public testimonials","operationId":"listTestimonials","responses":{"200":{"description":"Approved testimonials.","content":{"application/json":{"schema":{"type":"object","properties":{"testimonials":{"type":"array","items":{"$ref":"#/components/schemas/Testimonial"}}},"required":["testimonials"]}}}}}}},"/api/testimonials/submit":{"post":{"tags":["Testimonials"],"summary":"Submit testimonial feedback for moderation","operationId":"submitTestimonial","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestimonialSubmission"}}}},"responses":{"200":{"description":"Submission accepted for moderation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/api/stripe/create-premium-session":{"post":{"tags":["Billing"],"summary":"Create authenticated Premium checkout session","operationId":"createPremiumSession","description":"Requires an authenticated Clerk session. Creates a Stripe Checkout URL for the one-off Premium upgrade. Agents must disclose price and obtain explicit user approval before initiating checkout.","security":[{"ClerkSession":[]}],"responses":{"200":{"description":"Checkout session created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSessionResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}},"components":{"securitySchemes":{"ClerkSession":{"type":"apiKey","in":"cookie","name":"__session","description":"Authenticated Clerk browser session cookie. Passage does not publish third-party OAuth scopes for private case access."}},"responses":{"BadRequest":{"description":"Invalid request payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"Jurisdiction":{"type":"string","enum":["england_wales","scotland","northern_ireland","jersey","guernsey"]},"PreviewTasksRequest":{"type":"object","additionalProperties":true,"properties":{"relationship":{"type":"string","description":"Relationship to the person who died."},"location":{"type":"string","description":"Approximate location or jurisdiction."},"jurisdiction":{"$ref":"#/components/schemas/Jurisdiction"},"hasWill":{"type":"boolean"},"isExecutor":{"type":"boolean"}}},"PreviewTasksResponse":{"type":"object","additionalProperties":true,"properties":{"tasks":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"CreateLeadRequest":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","format":"email"},"firstName":{"type":"string"},"lastName":{"type":"string"},"relationship":{"type":"string"},"jurisdiction":{"$ref":"#/components/schemas/Jurisdiction"}},"required":["email"]},"CreateLeadResponse":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean"},"leadId":{"type":"string"}}},"ContactRequest":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"message":{"type":"string"},"type":{"type":"string","enum":["family","partner","support","other"]}},"required":["email","message"]},"StatusResponse":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean"},"status":{"type":"string"}}},"Testimonial":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string"},"rating":{"type":"number"},"quote":{"type":"string"}}},"TestimonialSubmission":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"rating":{"type":"number","minimum":1,"maximum":5},"testimonial":{"type":"string"}},"required":["email","rating","testimonial"]},"CheckoutSessionResponse":{"type":"object","properties":{"url":{"type":"string","format":"uri"}},"required":["url"]},"ErrorResponse":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}