{ "openapi": "3.1.0", "info": { "title": "EstateTrace API", "description": "High-Alpha Pre-Probate & Inheritance Property Signal Engine", "version": "1.0.0" }, "paths": { "/": { "get": { "summary": "Read Root", "operationId": "read_root__get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/chat_ui": { "get": { "summary": "Read Chat", "operationId": "read_chat_chat_ui_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/app": { "get": { "summary": "Read Chat", "operationId": "read_chat_app_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/faq": { "get": { "summary": "Read Guide", "operationId": "read_guide_faq_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/guide": { "get": { "summary": "Read Guide", "operationId": "read_guide_guide_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/a2a-guide": { "get": { "summary": "Read Developers", "operationId": "read_developers_a2a_guide_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/docs/a2a": { "get": { "summary": "Read Developers", "operationId": "read_developers_docs_a2a_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/developers": { "get": { "summary": "Read Developers", "operationId": "read_developers_developers_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/llms.txt": { "get": { "summary": "Read Llms Txt", "operationId": "read_llms_txt_llms_txt_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/config": { "get": { "tags": [ "System & Config" ], "summary": "Get System Config", "description": "Returns the unified application operating mode, pricing scale, and active environment metadata.", "operationId": "get_system_config_config_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/config": { "get": { "tags": [ "System & Config" ], "summary": "Get System Config", "description": "Returns the unified application operating mode, pricing scale, and active environment metadata.", "operationId": "get_system_config_api_v1_config_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/health": { "get": { "tags": [ "System & Config" ], "summary": "Get Health", "description": "Service health check endpoint.", "operationId": "get_health_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/terms": { "get": { "tags": [ "System & Config" ], "summary": "Get Terms", "description": "Returns the canonical EstateTrace Terms of Service & Usage Agreement payload.", "operationId": "get_terms_terms_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/a2a/checkout": { "post": { "tags": [ "A2A Commerce" ], "summary": "A2A Checkout", "description": "Machine-native checkout endpoint for autonomous AI agents (Phase 1 A2A Commerce).\nReturns an HTTP 402 payment specification payload with Base L2 USDC payment instructions.\nAdapts automatically during PRE_LAUNCH_MODE / SIMULATED_PAYMENTS.\nLogs telemetry on inbound agent activity.", "operationId": "a2a_checkout_api_v1_a2a_checkout_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2ACheckoutRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/a2a/settle/{charge_id}": { "post": { "tags": [ "A2A Commerce" ], "summary": "A2A Settle", "description": "Verification & delivery endpoint for A2A transactions.\nVerifies on-chain payment tx_hash on Base L2, transitions charge to sold, and delivers full lead data instantly.", "operationId": "a2a_settle_api_v1_a2a_settle__charge_id__post", "parameters": [ { "name": "charge_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Charge Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2ASettleRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/a2a/status/{charge_id}": { "get": { "tags": [ "A2A Commerce" ], "summary": "A2A Status", "description": "Polling/status check endpoint for A2A reservations and settlements.\nReturns the current state: pending, settled, expired, or not_found.", "operationId": "a2a_status_api_v1_a2a_status__charge_id__get", "parameters": [ { "name": "charge_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Charge Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/charge/create": { "post": { "tags": [ "Checkout & Charges" ], "summary": "Create Charge", "operationId": "create_charge_charge_create_post", "parameters": [ { "name": "x-service-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Service-Token" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeCreateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/charge/{charge_id}/status": { "get": { "tags": [ "Checkout & Charges" ], "summary": "Get Charge Status", "operationId": "get_charge_status_charge__charge_id__status_get", "parameters": [ { "name": "charge_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Charge Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/charge/{charge_id}/confirm_claim": { "post": { "tags": [ "Checkout & Charges" ], "summary": "Confirm Charge Claim", "operationId": "confirm_charge_claim_charge__charge_id__confirm_claim_post", "parameters": [ { "name": "charge_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Charge Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/charge/{charge_id}/download_csv": { "get": { "tags": [ "Checkout & Charges" ], "summary": "Download Charge Csv", "operationId": "download_charge_csv_charge__charge_id__download_csv_get", "parameters": [ { "name": "charge_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Charge Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/charge/{charge_id}/poll": { "get": { "tags": [ "Checkout & Charges" ], "summary": "Poll Payment Onchain", "description": "Auto-poll Base L2 for incoming USDC payment. No tx hash needed \u2014 scans recent blocks.", "operationId": "poll_payment_onchain_charge__charge_id__poll_get", "parameters": [ { "name": "charge_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Charge Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/charge/{charge_id}/settle": { "post": { "tags": [ "Checkout & Charges" ], "summary": "Settle Charge Onchain", "description": "Verify on-chain Base L2 USDC payment and transition leads to sold.", "operationId": "settle_charge_onchain_charge__charge_id__settle_post", "parameters": [ { "name": "charge_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Charge Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettleRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/dev/mock_pay": { "post": { "tags": [ "Checkout & Charges" ], "summary": "Mock Pay", "operationId": "mock_pay_dev_mock_pay_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MockPayRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/dev/reset_leads": { "post": { "tags": [ "Checkout & Charges" ], "summary": "Reset Leads", "operationId": "reset_leads_dev_reset_leads_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/inventory/freshness": { "get": { "tags": [ "Checkout & Charges" ], "summary": "Get Inventory Freshness", "operationId": "get_inventory_freshness_api_v1_inventory_freshness_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/stripe/checkout": { "post": { "tags": [ "Stripe Checkout" ], "summary": "Stripe Checkout", "description": "Create a Stripe Checkout Session for human buyers who prefer card payment.\nReserves leads with a 15-minute lock (same as Base L2 USDC path).\nReturns a Stripe Checkout URL for redirect.", "operationId": "stripe_checkout_api_v1_stripe_checkout_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeCheckoutRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/stripe/webhook": { "post": { "tags": [ "Stripe Checkout" ], "summary": "Stripe Webhook", "description": "Stripe webhook handler. Verifies signature, processes payment events,\ntransitions leads to SOLD, triggers JIT enrichment.", "operationId": "stripe_webhook_api_v1_stripe_webhook_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/stripe/status/{charge_id}": { "get": { "tags": [ "Stripe Checkout" ], "summary": "Stripe Status", "description": "Frontend polling endpoint to check Stripe payment status.\nUsed as a fallback when the webhook hasn't fired yet or redirect timing is slow.", "operationId": "stripe_status_api_v1_stripe_status__charge_id__get", "parameters": [ { "name": "charge_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Charge Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/admin/promo_voucher": { "post": { "tags": [ "Admin" ], "summary": "Create Voucher", "description": "Create a new promo voucher. Works for both Stripe and USDC checkout paths.", "operationId": "create_voucher_api_v1_admin_promo_voucher_post", "parameters": [ { "name": "X-Admin-Token", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Admin-Token" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoucherCreate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/admin/promo_vouchers": { "get": { "tags": [ "Admin" ], "summary": "List Vouchers", "description": "List all promo vouchers.", "operationId": "list_vouchers_api_v1_admin_promo_vouchers_get", "parameters": [ { "name": "X-Admin-Token", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Admin-Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/admin/promo_voucher/{code}": { "get": { "tags": [ "Admin" ], "summary": "Get Voucher", "description": "Get details for a specific voucher.", "operationId": "get_voucher_api_v1_admin_promo_voucher__code__get", "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "title": "Code" } }, { "name": "X-Admin-Token", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Admin-Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Admin" ], "summary": "Delete Voucher", "description": "Delete a voucher (hard delete).", "operationId": "delete_voucher_api_v1_admin_promo_voucher__code__delete", "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "title": "Code" } }, { "name": "X-Admin-Token", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Admin-Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/chat": { "post": { "tags": [ "Chatbot" ], "summary": "Chat Endpoint", "operationId": "chat_endpoint_chat_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/tts": { "post": { "tags": [ "Chatbot" ], "summary": "Generate Tts", "description": "Synthesize text into MP3 audio via OpenAI TTS API.", "operationId": "generate_tts_api_v1_tts_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TTSRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/webhooks/coinbase": { "post": { "tags": [ "Webhooks" ], "summary": "Coinbase Webhook", "operationId": "coinbase_webhook_api_v1_webhooks_coinbase_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/webhook/coinbase": { "post": { "tags": [ "Webhooks" ], "summary": "Coinbase Webhook", "operationId": "coinbase_webhook_webhook_coinbase_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/webhook/jeeves-email": { "post": { "tags": [ "Webhooks" ], "summary": "Jeeves Email Webhook", "description": "Webhook for the Cloudflare Email Routing Worker (Phase 1 Inbound Strategy)", "operationId": "jeeves_email_webhook_webhook_jeeves_email_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } } }, "components": { "schemas": { "A2ACheckoutRequest": { "properties": { "lead_ids": { "items": { "type": "string" }, "type": "array", "title": "Lead Ids" }, "promo_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Promo Code" } }, "type": "object", "required": [ "lead_ids" ], "title": "A2ACheckoutRequest" }, "A2ASettleRequest": { "properties": { "tx_hash": { "type": "string", "title": "Tx Hash" } }, "type": "object", "required": [ "tx_hash" ], "title": "A2ASettleRequest" }, "ChargeCreateRequest": { "properties": { "lead_ids": { "items": { "type": "string" }, "type": "array", "title": "Lead Ids" } }, "type": "object", "required": [ "lead_ids" ], "title": "ChargeCreateRequest" }, "ChatRequest": { "properties": { "message": { "type": "string", "title": "Message" }, "history": { "items": {}, "type": "array", "title": "History", "default": [] }, "client_state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client State" } }, "type": "object", "required": [ "message" ], "title": "ChatRequest" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "MockPayRequest": { "properties": { "charge_id": { "type": "string", "title": "Charge Id" } }, "type": "object", "required": [ "charge_id" ], "title": "MockPayRequest" }, "SettleRequest": { "properties": { "tx_hash": { "type": "string", "title": "Tx Hash" } }, "type": "object", "required": [ "tx_hash" ], "title": "SettleRequest" }, "StripeCheckoutRequest": { "properties": { "lead_ids": { "items": { "type": "string" }, "type": "array", "title": "Lead Ids" }, "promo_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Promo Code" } }, "type": "object", "required": [ "lead_ids" ], "title": "StripeCheckoutRequest" }, "TTSRequest": { "properties": { "text": { "type": "string", "title": "Text" } }, "type": "object", "required": [ "text" ], "title": "TTSRequest" }, "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" }, "VoucherCreate": { "properties": { "code": { "type": "string", "title": "Code" }, "discount_type": { "type": "string", "title": "Discount Type" }, "discount_value": { "type": "number", "title": "Discount Value" }, "max_uses": { "type": "integer", "title": "Max Uses", "default": 1 }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expires At" } }, "type": "object", "required": [ "code", "discount_type", "discount_value" ], "title": "VoucherCreate" } } } }