{ "openapi": "3.1.0", "info": { "title": "EternalEngine Public API", "description": "Read-only surface of the EternalEngine platform, covering every service whose data a tenant's own API key can authenticate. Generated from services/ee-postframe/openapi.yaml and services/ee-paygate/openapi.yaml by scripts/growth/gen-public-openapi.mjs — do not hand-edit this file, edit the source specs and regenerate.\n\n## ⚠ Known issue — not yet live\nservices/ee-gateway's blanket JWT-only authMiddleware sits in front of every operation in this spec and rejects any non-JWT Bearer token (pf_*/pg_* API keys included) with 401 before it is ever proxied to the service that would validate it. The service-level apiKeyAuth middlewares that validate these keys are real, tested, and tenant-scoped — they are simply unreachable from the public internet today.\n\nFull evidence: docs/growth/PUBLIC-API-AND-MCP.md §Precondition.\n\n## Authentication\nEvery operation below requires a Bearer API key from the service that owns it: PostFrame keys are `pf_live_*`/`pf_test_*`, PayGate keys are `pg_live_*`/`pg_test_*`. Mint one from the EternalEngine app under Developers → API Keys for the relevant app.\n\n## This is a READ-ONLY surface\nOnly GET operations are published here. Every write operation (POST/PUT/PATCH/DELETE) on the underlying service is deliberately excluded — this spec and the MCP server generated from it can only ever read your data.", "version": "1.0.0", "x-generated-at": "2026-09-15T12:08:46.573Z", "x-known-issue": { "status": "BLOCKED — not yet reachable through the public gateway", "measured": "2026-09-15", "summary": "services/ee-gateway's blanket JWT-only authMiddleware sits in front of every operation in this spec and rejects any non-JWT Bearer token (pf_*/pg_* API keys included) with 401 before it is ever proxied to the service that would validate it. The service-level apiKeyAuth middlewares that validate these keys are real, tested, and tenant-scoped — they are simply unreachable from the public internet today.", "evidence": [ "services/ee-gateway/src/middleware/auth.middleware.ts:61-99 (authMiddleware: jose jwtVerify, RS256 JWT only, hard 401 on failure — no fallback path)", "services/ee-gateway/src/app.ts:444-458 (the /api/v1/{*path} protected catch-all every non-allowlisted path falls through to)", "services/ee-gateway/src/app.ts:266-436 (the FULL enumerated allowlist of routes exempt from authMiddleware — none of it is a customer-API-key path)", "services/ee-postframe/src/middleware/api-key-auth.ts (the real, working, unreachable-from-outside apiKeyAuth)", "services/ee-paygate/src/middleware/api-key-auth.ts (same)" ], "fixSketch": "A minimal, scoped gateway change would add explicit pre-catch-all mounts for the two services (mirroring the existing pattern used for /api/v1/estimates/public, /api/v1/invoices/public, etc. at services/ee-gateway/src/app.ts) that skip authMiddleware and rely on each service's own apiKeyAuth + tenantContext + RLS to authenticate — no new key format, no new scopes, no new backend endpoint. This is a decision for the gateway's owner, not something this generator or its mission implements." }, "contact": { "name": "EternalEngine Support", "email": "support@eternalengineos.io" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://app.eternalengineos.io/api/v1", "description": "EternalEngine public API" } ], "tags": [ { "name": "Emails", "description": "Send, list, and manage transactional emails" }, { "name": "Templates", "description": "Email template CRUD and rendering" }, { "name": "Contacts", "description": "Contact management and custom fields" }, { "name": "Audiences", "description": "Audience lists for broadcast sends" }, { "name": "Broadcasts", "description": "Bulk email campaigns to audiences" }, { "name": "Domains", "description": "Sending domain management and DNS verification" }, { "name": "Providers", "description": "Email provider configuration (SES, SMTP, etc.)" }, { "name": "API Keys", "description": "API key management" }, { "name": "Webhooks", "description": "Webhook endpoint management" }, { "name": "Suppressions", "description": "Suppression list management (bounces, complaints, manual)" }, { "name": "Analytics", "description": "Delivery metrics and statistics" }, { "name": "Usage", "description": "Email quota and usage tracking" }, { "name": "Settings", "description": "Tenant settings and onboarding" }, { "name": "Billing", "description": "Subscription management and Stripe integration" }, { "name": "Status", "description": "Public service health" }, { "name": "Transactions", "description": "Charge, list, and inspect payment transactions" }, { "name": "Disputes", "description": "Chargeback / dispute management" }, { "name": "Routing", "description": "Transaction routing rules across providers" }, { "name": "Connect", "description": "Stripe Connect account, catalog, balance, and payouts" }, { "name": "Customers", "description": "Customer directory derived from transaction history" }, { "name": "Me", "description": "The authenticated tenant's own platform subscription" } ], "paths": { "/paygate/api-keys": { "get": { "tags": [ "API Keys" ], "summary": "List API keys for the tenant", "operationId": "listApiKeys", "responses": { "200": { "description": "API keys (no secret material)", "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKeys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "mode": { "type": "string", "enum": [ "test", "live" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } } }, "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-paygate" } }, "/paygate/connect/account": { "get": { "tags": [ "Connect" ], "summary": "Get the tenant's Stripe Connect account status", "operationId": "getConnectAccount", "responses": { "200": { "description": "Connect account status", "content": { "application/json": { "schema": { "type": "object", "properties": { "connected": { "type": "boolean" }, "account": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "charges_enabled": { "type": "boolean" }, "payouts_enabled": { "type": "boolean" }, "details_submitted": { "type": "boolean" }, "business_name": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "default_currency": { "type": "string", "nullable": true }, "platform_fee_percent": { "type": "number", "nullable": true }, "platform_fee_fixed_cents": { "type": "integer", "nullable": true }, "onboarding_completed_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } }, "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-paygate" } }, "/paygate/connect/balance": { "get": { "tags": [ "Connect" ], "summary": "Get the connected account's Stripe balance", "operationId": "getConnectBalance", "responses": { "200": { "description": "Balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "type": "array", "items": { "type": "object" } }, "pending": { "type": "array", "items": { "type": "object" } }, "connect_reserved": { "type": "array", "items": { "type": "object" } } } } } } }, "503": { "description": "Payment processing not configured" } }, "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-paygate" } }, "/paygate/connect/checkout/sessions": { "get": { "tags": [ "Connect" ], "summary": "List recent Checkout sessions", "operationId": "listCheckoutSessions", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Sessions + conversion stats", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "type": "object" } }, "stats": { "type": "object", "properties": { "total": { "type": "integer" }, "completed": { "type": "integer" }, "expired": { "type": "integer" }, "conversion_rate": { "type": "number" } } } } } } } } }, "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-paygate" } }, "/paygate/connect/coupons": { "get": { "tags": [ "Connect" ], "summary": "List Stripe coupons on the connected account", "operationId": "listCoupons", "responses": { "200": { "description": "Coupons", "content": { "application/json": { "schema": { "type": "object", "properties": { "coupons": { "type": "array", "items": { "type": "object" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-paygate" } }, "/paygate/connect/payouts": { "get": { "tags": [ "Connect" ], "summary": "List Stripe Connect payouts", "operationId": "listPayouts", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Payouts", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-paygate" } }, "/paygate/connect/products": { "get": { "tags": [ "Connect" ], "summary": "List Stripe products/plans on the connected account", "operationId": "listProducts", "responses": { "200": { "description": "Products", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-paygate" } }, "/paygate/connect/subscriptions": { "get": { "tags": [ "Connect" ], "summary": "List Stripe subscriptions on the connected account", "operationId": "listSubscriptions", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Subscriptions", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptions": { "type": "array", "items": { "type": "object" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-paygate" } }, "/paygate/customers": { "get": { "tags": [ "Customers" ], "summary": "List customers (aggregated from transaction history)", "operationId": "listCustomers", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "enum": [ "total_spent", "name", "count", "last_activity" ] } }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Customers", "content": { "application/json": { "schema": { "type": "object", "properties": { "customers": { "type": "array", "items": { "type": "object", "properties": { "customer_email": { "type": "string", "format": "email" }, "customer_name": { "type": "string", "nullable": true }, "transaction_count": { "type": "integer" }, "total_spent_cents": { "type": "integer" }, "total_refunded_cents": { "type": "integer" }, "dispute_count": { "type": "integer" }, "last_transaction_at": { "type": "string", "format": "date-time", "nullable": true }, "first_transaction_at": { "type": "string", "format": "date-time", "nullable": true }, "avg_transaction_cents": { "type": "integer", "nullable": true } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } } }, "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-paygate" } }, "/paygate/customers/{email}": { "get": { "tags": [ "Customers" ], "summary": "Get a customer's transaction history", "operationId": "getCustomerByEmail", "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string", "format": "email" } } ], "responses": { "200": { "description": "Customer detail" } }, "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-paygate" } }, "/paygate/me/invoices/{invoiceId}/pdf": { "get": { "tags": [ "Me" ], "summary": "Download a branded PDF of the tenant's own platform subscription invoice", "operationId": "getSubscriptionInvoicePdf", "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^in_[A-Za-z0-9]+$" } } ], "responses": { "200": { "description": "PDF document", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid invoice id" }, "403": { "description": "Invoice does not belong to this tenant" }, "503": { "description": "Stripe not configured" } }, "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-paygate" } }, "/paygate/me/volume": { "get": { "tags": [ "Me" ], "summary": "Get the tenant's month-to-date processing volume", "operationId": "getMonthToDateVolume", "responses": { "200": { "description": "{ tenant_id, processed_cents, transaction_count, active_tier, period_start, period_end }", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } }, "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-paygate" } }, "/paygate/settings": { "get": { "tags": [ "Settings" ], "summary": "Get merchant settings and fraud rules", "operationId": "getMerchantSettings", "responses": { "200": { "description": "{settings, fraud_rules} — never a 500, missing row returns defaults", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-paygate" } }, "/paygate/status": { "get": { "tags": [ "Status" ], "summary": "Service health (public, no auth)", "operationId": "getStatus", "security": [], "responses": { "200": { "description": "Status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "stripe_connect": { "type": "boolean" } } } } } } }, "x-source-service": "ee-paygate" } }, "/paygate/transactions": { "get": { "tags": [ "Transactions" ], "summary": "List transactions", "operationId": "listTransactions", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "succeeded", "failed", "refunded", "disputed" ] } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "charge", "refund", "payout" ] } }, { "name": "provider", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 200 } }, { "name": "from_date", "in": "query", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to_date", "in": "query", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Paginated transaction list", "content": { "application/json": { "schema": { "type": "object", "properties": { "transactions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "charge", "refund", "payout" ] }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed", "refunded", "disputed" ] }, "amount_cents": { "type": "integer" }, "currency": { "type": "string" }, "provider": { "type": "string" }, "customer_email": { "type": "string", "nullable": true }, "customer_name": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-paygate" } }, "/paygate/transactions/disputes": { "get": { "tags": [ "Disputes" ], "summary": "List disputes", "operationId": "listDisputes", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Disputes", "content": { "application/json": { "schema": { "type": "object", "properties": { "disputes": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } } }, "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-paygate" } }, "/paygate/transactions/disputes/{id}": { "get": { "tags": [ "Disputes" ], "summary": "Get a dispute by ID", "operationId": "getDisputeById", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Dispute" }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-paygate" } }, "/paygate/transactions/providers": { "get": { "tags": [ "Providers" ], "summary": "List configured payment providers", "operationId": "listProviders", "responses": { "200": { "description": "Providers", "content": { "application/json": { "schema": { "type": "object", "properties": { "providers": { "type": "array", "items": { "type": "object" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-paygate" } }, "/paygate/transactions/routing": { "get": { "tags": [ "Routing" ], "summary": "List routing rules", "operationId": "listRoutingRules", "responses": { "200": { "description": "Rules", "content": { "application/json": { "schema": { "type": "object", "properties": { "rules": { "type": "array", "items": { "type": "object" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-paygate" } }, "/paygate/transactions/stats": { "get": { "tags": [ "Transactions" ], "summary": "Payment stats", "description": "Aggregate transaction stats for the tenant (volume, count, avg).", "operationId": "getPaymentStats", "responses": { "200": { "description": "Stats object", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-paygate" } }, "/paygate/transactions/{id}": { "get": { "tags": [ "Transactions" ], "summary": "Get transaction by ID", "operationId": "getTransactionById", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Transaction", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "charge", "refund", "payout" ] }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed", "refunded", "disputed" ] }, "amount_cents": { "type": "integer" }, "currency": { "type": "string" }, "provider": { "type": "string" }, "customer_email": { "type": "string", "nullable": true }, "customer_name": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-paygate" } }, "/paygate/webhooks/events": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook delivery events", "operationId": "listWebhookEvents", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "event_type", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook events", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-paygate" } }, "/postframe/analytics/overview": { "get": { "tags": [ "Analytics" ], "summary": "Get delivery overview", "description": "Get aggregate delivery metrics for a date range.", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Delivery summary metrics" } }, "operationId": "getAnalyticsOverview", "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-postframe" } }, "/postframe/analytics/timeseries": { "get": { "tags": [ "Analytics" ], "summary": "Get time series metrics", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "interval", "in": "query", "schema": { "type": "string", "enum": [ "hour", "day", "week" ] } } ], "responses": { "200": { "description": "Time series data points" } }, "operationId": "getAnalyticsTimeseries", "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-postframe" } }, "/postframe/api-keys": { "get": { "tags": [ "API Keys" ], "summary": "List API keys", "responses": { "200": { "description": "List of API keys (secrets masked)" } }, "operationId": "getApiKeys", "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-postframe" } }, "/postframe/audiences": { "get": { "tags": [ "Audiences" ], "summary": "List audiences", "responses": { "200": { "description": "List of audiences" } }, "operationId": "getAudiences", "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-postframe" } }, "/postframe/audiences/{audienceId}/broadcasts": { "get": { "tags": [ "Broadcasts" ], "summary": "List broadcasts for an audience", "parameters": [ { "name": "audienceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of broadcasts" } }, "operationId": "getAudiencesByAudienceIdBroadcasts", "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-postframe" } }, "/postframe/audiences/{id}": { "get": { "tags": [ "Audiences" ], "summary": "Get audience details", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Audience details" } }, "operationId": "getAudiencesById", "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-postframe" } }, "/postframe/billing/subscription": { "get": { "tags": [ "Billing" ], "summary": "Get subscription status", "responses": { "200": { "description": "Current billing subscription" } }, "operationId": "getBillingSubscription", "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-postframe" } }, "/postframe/contacts": { "get": { "tags": [ "Contacts" ], "summary": "List contacts", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of contacts" } }, "operationId": "getContacts", "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-postframe" } }, "/postframe/contacts/{id}": { "get": { "tags": [ "Contacts" ], "summary": "Get a contact", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Contact details" } }, "operationId": "getContactsById", "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-postframe" } }, "/postframe/domains": { "get": { "tags": [ "Domains" ], "summary": "List domains", "responses": { "200": { "description": "List of sending domains" } }, "operationId": "getDomains", "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-postframe" } }, "/postframe/domains/{id}": { "get": { "tags": [ "Domains" ], "summary": "Get domain details", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Domain details including DNS records and verification status" } }, "operationId": "getDomainsById", "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-postframe" } }, "/postframe/emails": { "get": { "tags": [ "Emails" ], "summary": "List emails", "description": "List sent emails with pagination, filtering by status, recipient, and date range.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "queued", "sending", "delivered", "bounced", "failed", "complained" ] } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "email" } }, { "name": "from_date", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to_date", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "List of emails", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "from": { "type": "string", "format": "email" }, "to": { "type": "string", "format": "email" }, "subject": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "sending", "delivered", "bounced", "failed", "complained" ] }, "provider": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "delivered_at": { "type": "string", "format": "date-time", "nullable": true }, "opened_at": { "type": "string", "format": "date-time", "nullable": true }, "clicked_at": { "type": "string", "format": "date-time", "nullable": true } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } } }, "operationId": "getEmails", "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-postframe" } }, "/postframe/emails/{id}": { "get": { "tags": [ "Emails" ], "summary": "Get email details", "description": "Get full details of a sent email including delivery status and events.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Email details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "from": { "type": "string", "format": "email" }, "to": { "type": "string", "format": "email" }, "subject": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "sending", "delivered", "bounced", "failed", "complained" ] }, "provider": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "delivered_at": { "type": "string", "format": "date-time", "nullable": true }, "opened_at": { "type": "string", "format": "date-time", "nullable": true }, "clicked_at": { "type": "string", "format": "date-time", "nullable": true } } } } } } }, "operationId": "getEmailsById", "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-postframe" } }, "/postframe/providers": { "get": { "tags": [ "Providers" ], "summary": "List providers", "responses": { "200": { "description": "List of configured email providers" } }, "operationId": "getProviders", "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-postframe" } }, "/postframe/settings": { "get": { "tags": [ "Settings" ], "summary": "Get tenant settings", "responses": { "200": { "description": "Current tenant settings" } }, "operationId": "getSettings", "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-postframe" } }, "/postframe/settings/onboarding": { "get": { "tags": [ "Settings" ], "summary": "Get onboarding status", "description": "Returns setup progress for new tenants.", "responses": { "200": { "description": "Onboarding status", "content": { "application/json": { "schema": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "completed": { "type": "boolean" } } } }, "steps_completed": { "type": "integer" }, "total_steps": { "type": "integer" }, "next_step": { "type": "string" }, "complete": { "type": "boolean" } } } } } } }, "operationId": "getSettingsOnboarding", "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-postframe" } }, "/postframe/suppressions": { "get": { "tags": [ "Suppressions" ], "summary": "List suppressions", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "bounce", "complaint", "manual" ] } } ], "responses": { "200": { "description": "List of suppressed addresses" } }, "operationId": "getSuppressions", "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-postframe" } }, "/postframe/templates": { "get": { "tags": [ "Templates" ], "summary": "List templates", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of templates" } }, "operationId": "getTemplates", "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-postframe" } }, "/postframe/templates/{id}": { "get": { "tags": [ "Templates" ], "summary": "Get a template", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Template details" } }, "operationId": "getTemplatesById", "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-postframe" } }, "/postframe/usage/quota": { "get": { "tags": [ "Usage" ], "summary": "Get usage quota", "description": "Returns current email usage against plan limits.", "responses": { "200": { "description": "Current usage and limits", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "string" }, "emails_sent_this_month": { "type": "integer" }, "monthly_limit": { "type": "integer" }, "emails_sent_today": { "type": "integer" }, "daily_limit": { "type": "integer" } } } } } } }, "operationId": "getUsageQuota", "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-postframe" } }, "/postframe/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhooks", "responses": { "200": { "description": "List of webhook endpoints" } }, "operationId": "getWebhooks", "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "limit": 100, "window": "1m", "per": "authenticated caller", "source": "services/ee-gateway/src/middleware/rate-limit.middleware.ts:150-153 (standardLimiter), applied via the protected catch-all at services/ee-gateway/src/app.ts:444-458" }, "x-source-service": "ee-postframe" } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key" } } }, "security": [ { "bearerAuth": [] } ] }