{"openapi":"3.1.0","info":{"title":"Merilane","description":"Merilane is a decision underwriter: paste a ticket → recommend one of N named outcomes with evidence (recommend-only — never refunds / never moves money). Flagship default is billing wrong-charge (Credit / Escalate / Deny via billing_v1). Live templates also include claims_v1, trust_safety_v1, lead_routing_v1, guardrails_v1 stubs. Bearer settle_live_… keys + optional webhook HMAC for Zapier/Zendesk. Paste/demo mode (SETTLE_AUTH_DISABLED=1) rate-limits unauthenticated POST /v1/decide by IP.","version":"0.8.41"},"paths":{"/zendesk-card":{"get":{"tags":["demo"],"summary":"Demo Zendesk decision card (alias)","description":"Alias of /demo/zendesk-card.","operationId":"zendesk_card_demo_zendesk_card_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/demo/zendesk-card":{"get":{"tags":["demo"],"summary":"Demo Zendesk decision card","description":"Standalone HTML fixture mirroring the Zendesk sidebar decision card (Credit / Escalate / Deny). Demo-safe dogfood surface — Merilane never auto-refunds.","operationId":"zendesk_card_demo_demo_zendesk_card_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/health":{"get":{"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/v1":{"get":{"tags":["meta"],"summary":"API discovery","description":"Service name, version, and well-known endpoint map for clients and the paste UI. Includes decide, audit (truncated previews), webhooks, and the demo Zendesk card.","operationId":"discovery_v1_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Discovery V1 Get"}}}}}}},"/v1/audit":{"get":{"tags":["audit"],"summary":"Recent audit rows (truncated previews)","description":"Newest-first decision cards from the SQLite audit for the paste-page drawer. ticket_preview and invoice_preview are truncated (~100 chars); full ticket text is never returned via this endpoint. Merilane never auto-refunds.","operationId":"audit_recent_v1_audit_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Audit Recent V1 Audit Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/kit/session":{"post":{"tags":["kit"],"summary":"Kit session mint (disabled — paid / dogfood only)","description":"Public open mint is disabled (conversion gate). Sessions are minted server-side only on GET /kit?checkout=success&session_id=… after Stripe payment_status=paid, or GET /kit?dogfood=1 (internal). Optional ops escape: header X-Merilane-Kit-Dogfood: 1 when SETTLE_KIT_DOGFOOD_OPEN=1. Merilane never refunds.","operationId":"create_kit_session_route_v1_kit_session_post","parameters":[{"name":"X-Merilane-Kit-Dogfood","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Merilane-Kit-Dogfood"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Create Kit Session Route V1 Kit Session Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/keys":{"post":{"tags":["admin"],"summary":"Mint API key (ops-only)","description":"Create a settle_accounts + settle_api_keys row (Supabase or local SQLite). Protected by env SETTLE_ADMIN_TOKEN via header X-Settle-Admin-Token. Returns plaintext api_key once.","operationId":"mint_key_v1_keys_post","parameters":[{"name":"X-Settle-Admin-Token","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Settle-Admin-Token"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MintKeyRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MintKeyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/decide":{"post":{"tags":["decide"],"summary":"Underwrite a billing dispute","description":"Paste ticket + invoice → recommend-only decision with confidence, rationale, and optional $ false-credit avoided. Merilane never auto-refunds — money movement stays in your stack. Optional template_id (body) or X-Merilane-Template header selects a locked registry template; omit both (or pass billing_v1) for today's billing path (auto_credit | human | deny). Live P1 stubs: claims_v1, trust_safety_v1, lead_routing_v1, guardrails_v1 (thin recommend-only heuristics). If body and header are both set they must match; unknown ids return 400 with the live list. Auth: Authorization Bearer settle_live_… (metered) and/or X-Merilane-Kit-Session (paid Kit unlock). Public unauthenticated paste (SETTLE_AUTH_DISABLED=1) is IP rate-limited → 429; not a cash path. Bearer/Kit decides are not subject to that public limit.","operationId":"decide_route_v1_decide_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional. Bearer settle_live_… metered API key. Required when auth is enabled and no Kit session is present.","title":"Authorization"},"description":"Optional. Bearer settle_live_… metered API key. Required when auth is enabled and no Kit session is present."},{"name":"X-Merilane-Kit-Session","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional paid Kit unlock session token (also accepted via cookie after /kit checkout). Not a cash path by itself — cash is https://merilane.io/kit ($29).","title":"X-Merilane-Kit-Session"},"description":"Optional paid Kit unlock session token (also accepted via cookie after /kit checkout). Not a cash path by itself — cash is https://merilane.io/kit ($29)."},{"name":"X-Merilane-Template","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional underwrite template id (same as body template_id). Must match body if both are set. Omit with body omit → billing_v1. Live: billing_v1, claims_v1, trust_safety_v1, lead_routing_v1, guardrails_v1.","title":"X-Merilane-Template"},"description":"Optional underwrite template id (same as body template_id). Must match body if both are set. Omit with body omit → billing_v1. Live: billing_v1, claims_v1, trust_safety_v1, lead_routing_v1, guardrails_v1."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecideRequest"},"examples":{"billing_default":{"summary":"Billing default (omit template_id)","description":"Homepage curl shape — omit template_id → billing_v1.","value":{"ticket_text":"Customer says they were charged twice for March.","invoice_text":"Invoice #1842 — single March seat line, $49.","amount_cents":4900}},"billing_explicit":{"summary":"Billing explicit template_id","description":"Same as omit; template_id billing_v1.","value":{"ticket_text":"Customer says they were charged twice for March.","invoice_text":"Invoice #1842 — single March seat line, $49.","amount_cents":4900,"template_id":"billing_v1"}},"claims_stub":{"summary":"Claims FNOL stub","description":"claims_v1 + FNOL-shaped ticket/invoice fields.","value":{"ticket_text":"FNOL: rear-end collision on I-95, policy #PL-44219, no injuries reported, photos attached.","invoice_text":"Estimate shop quote #EST-901 — bumper + sensor, $2,500. Date of loss 2026-09-12.","amount_cents":250000,"template_id":"claims_v1"}},"unknown_template":{"summary":"Unknown template → 400","description":"recruiting_v1 is not in the live registry; API returns 400 with live list in detail.","value":{"ticket_text":"Screen this candidate resume for role fit.","invoice_text":"Requisition REQ-100 — backend engineer.","amount_cents":0,"template_id":"recruiting_v1"}}}}}},"responses":{"200":{"description":"Recommend-only underwrite result (never moves money).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecideResponse"},"examples":{"billing_human":{"summary":"billing_v1 → human","value":{"decision":"human","confidence":0.62,"rationale":"Mixed signals; escalate for human review.","findings":{"complexity":0.55},"amount_cents":4900,"model":"jev-latest","tokens":{"input_tokens":12,"output_tokens":8},"pack":"billing_dispute","template_id":"billing_v1","audit_id":42}},"billing_deny":{"summary":"billing_v1 → deny","value":{"decision":"deny","confidence":0.91,"rationale":"Abuse/fraud signal with valid charge evidence.","findings":{"abuse_or_fraud_signal":0.95},"false_credit_dollars_avoided":120.0,"amount_cents":12000,"model":"jev-latest","tokens":{},"pack":"billing_dispute","template_id":"billing_v1","audit_id":7}},"billing_auto_credit":{"summary":"billing_v1 → auto_credit","value":{"decision":"auto_credit","confidence":0.88,"rationale":"Invoice contradicts charge; policy favors credit.","findings":{"invoice_contradicts_charge":0.88},"false_credit_dollars_avoided":0.0,"amount_cents":4900,"model":"jev-latest","tokens":{},"pack":"billing_dispute","template_id":"billing_v1","audit_id":11}},"claims_specialist":{"summary":"claims_v1 stub → specialist","value":{"decision":"specialist","confidence":0.7,"rationale":"FNOL stub: route to specialist review.","findings":{"stub":true},"amount_cents":250000,"model":"claims_v1_stub","tokens":{},"pack":"insurance_claims","template_id":"claims_v1","audit_id":99}}}}}},"400":{"description":"Unknown/not-enabled template_id, or body vs X-Merilane-Template mismatch. detail is a string (do not invent shapes).","content":{"application/json":{"examples":{"unknown_template":{"summary":"Unknown template_id","value":{"detail":"Unknown or not-enabled template_id: 'recruiting_v1'. Live templates: billing_v1, claims_v1, guardrails_v1, lead_routing_v1, trust_safety_v1"}},"template_mismatch":{"summary":"Body vs header mismatch","value":{"detail":"template_id mismatch: body 'billing_v1' vs header X-Merilane-Template 'claims_v1'"}}}}}},"401":{"description":"Missing/malformed Bearer or invalid API key (when auth enabled).","content":{"application/json":{"examples":{"missing_bearer":{"summary":"Missing or malformed Authorization","value":{"detail":"Missing or malformed Authorization header; use Bearer <settle_live_…>"}},"invalid_key":{"summary":"Bad API key","value":{"detail":"Invalid API key"}}}}}},"422":{"description":"Pydantic validation error (standard FastAPI body)."},"429":{"description":"Public IP rate limit or Kit/account quota gate. detail is an object as already returned (message/plan/used/limit) — do not reinvent.","content":{"application/json":{"examples":{"public_ip":{"summary":"Public paste IP rate limit","value":{"detail":{"message":"Public paste rate limit exceeded. Try again in 60s, or use Authorization: Bearer settle_live_…","limit":30,"window_sec":60,"retry_after_sec":60}}},"kit_quota":{"summary":"Kit session quota","value":{"detail":{"message":"Kit decide quota exceeded","plan":"kit","used":25,"limit":25}}}}}}},"503":{"description":"Upstream/engine or auth backend unavailable (string or structured as today).","content":{"application/json":{"examples":{"missing_upstream_key":{"summary":"Engine upstream key missing","value":{"detail":"TYPESAFE_API_KEY not found in env, box-secrets, or jev-cli credentials"}},"auth_backend":{"summary":"Auth/metering backend unavailable","value":{"detail":{"message":"Auth/metering backend unavailable","upstream_status":503}}}}}}}},"security":[{"BearerAuth":[]},{}]}},"/v1/webhook/decide":{"post":{"tags":["webhooks"],"summary":"Webhook decide ingress","description":"Same decision engine as POST /v1/decide. If SETTLE_WEBHOOK_SECRET is set, require HMAC-SHA256 in X-Settle-Signature (sha256=<hex>). Otherwise require Bearer settle_live_… (unless auth disabled). Not subject to the public paste IP rate limit. Merilane never auto-refunds.","operationId":"webhook_decide_v1_webhook_decide_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"X-Settle-Signature","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Settle-Signature"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecideResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/hooks/zendesk":{"post":{"tags":["webhooks"],"summary":"Zendesk / Make / Zapier hook alias","description":"Alias of /v1/webhook/decide for tagged-ticket automations. Not subject to the public paste IP rate limit. Merilane never auto-refunds.","operationId":"hooks_zendesk_v1_hooks_zendesk_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"X-Settle-Signature","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Settle-Signature"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecideResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"DecideRequest":{"properties":{"ticket_text":{"type":"string","minLength":1,"title":"Ticket Text","description":"Support ticket / dispute text"},"invoice_text":{"type":"string","minLength":1,"title":"Invoice Text","description":"Invoice or billing context"},"amount_cents":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Amount Cents","description":"Disputed amount in cents (for dollars-avoided estimate)"},"template_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Template Id","description":"Optional underwrite template from the locked server registry. Omit (or billing_v1) → billing outcomes auto_credit|human|deny. Live stubs: claims_v1 (stp|specialist|escalate), trust_safety_v1 (allow|warn|review|block), lead_routing_v1 (hot_ae|nurture|disqualify|escalate), guardrails_v1 (allow|block|escalate). Also via X-Merilane-Template; if both set they must match. Unknown ids → 400."}},"type":"object","required":["ticket_text","invoice_text"],"title":"DecideRequest"},"DecideResponse":{"properties":{"decision":{"type":"string","enum":["auto_credit","human","deny","stp","specialist","escalate","allow","warn","review","block","hot_ae","nurture","disqualify"],"title":"Decision"},"confidence":{"type":"number","title":"Confidence"},"rationale":{"type":"string","title":"Rationale"},"findings":{"additionalProperties":true,"type":"object","title":"Findings"},"false_credit_dollars_avoided":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"False Credit Dollars Avoided"},"amount_cents":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Amount Cents"},"model":{"type":"string","title":"Model","default":"unknown"},"tokens":{"additionalProperties":true,"type":"object","title":"Tokens"},"pack":{"type":"string","title":"Pack","default":"billing_dispute"},"template_id":{"type":"string","title":"Template Id","description":"Resolved underwrite template (billing_v1 when omitted; claims_v1 when requested).","default":"billing_v1"},"audit_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Audit Id"},"usage":{"anyOf":[{"$ref":"#/components/schemas/MeteringUsage"},{"type":"null"}]}},"type":"object","required":["decision","confidence","rationale"],"title":"DecideResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthResponse":{"properties":{"ok":{"type":"boolean","title":"Ok","default":true},"service":{"type":"string","title":"Service","default":"merilane"}},"type":"object","title":"HealthResponse"},"MeteringUsage":{"properties":{"used":{"type":"integer","title":"Used"},"limit":{"type":"integer","title":"Limit"}},"type":"object","required":["used","limit"],"title":"MeteringUsage"},"MintKeyRequest":{"properties":{"name":{"type":"string","maxLength":120,"minLength":1,"title":"Name","default":"dogfood"},"plan":{"type":"string","maxLength":40,"minLength":1,"title":"Plan","default":"free"},"limit":{"type":"integer","maximum":10000000.0,"minimum":1.0,"title":"Limit","default":10000}},"type":"object","title":"MintKeyRequest"},"MintKeyResponse":{"properties":{"api_key":{"type":"string","title":"Api Key"},"key_prefix":{"type":"string","title":"Key Prefix"},"account_id":{"type":"string","title":"Account Id"},"plan":{"type":"string","title":"Plan"},"monthly_decide_limit":{"type":"integer","title":"Monthly Decide Limit"}},"type":"object","required":["api_key","key_prefix","account_id","plan","monthly_decide_limit"],"title":"MintKeyResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"settle_live_…","description":"Metered Merilane API key: Authorization: Bearer settle_live_… Kit practice uses X-Merilane-Kit-Session (or cookie) after paid /kit unlock. Public unauthenticated paste (when SETTLE_AUTH_DISABLED=1) is IP rate-limited → 429; not a cash path."}}}}