{ "openapi": "3.0.3", "info": { "title": "TradeExecutor.ai Public Commerce API", "version": "1.0.0", "description": "Agent-facing API for discovering, pricing, and purchasing TradeExecutor.ai licenses.\n\nTwo products. One-time purchase. No subscription. Digital delivery within 60 seconds\nof payment confirmation.\n\nAll responses include an `X-Request-Id` header and, on errors, a `request_id` field in the body.\n\n**Idempotency:** POST /checkout supports the `Idempotency-Key` header (preferred) and\n`client_reference_id` body field (fallback). Duplicate requests with the same key return\nthe original session — no new charge is created.\n", "contact": { "email": "support@tradeexecutor.ai" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://tradeexecutor.ai/api/public/v1", "description": "Production" } ], "tags": [ { "name": "health", "description": "Service status" }, { "name": "catalog", "description": "Product discovery" }, { "name": "checkout", "description": "Purchase flow" }, { "name": "license", "description": "License verification" } ], "paths": { "/health": { "get": { "tags": [ "health" ], "summary": "Service health check", "description": "Returns API health and current Stripe mode. Agents should verify `stripe_mode` is `test` before running automated test flows.", "operationId": "getHealth", "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" }, "example": { "status": "ok", "stripe_mode": "live", "version": "1.0.0", "timestamp": "2026-04-24T12:00:00Z", "request_id": "req_abc123" } } } } } } }, "/catalog": { "get": { "tags": [ "catalog" ], "summary": "Full product catalog", "description": "Returns all available products with pricing, delivery details, and current inventory.", "operationId": "getCatalog", "responses": { "200": { "description": "Catalog returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogResponse" } } } } } } }, "/products/{code}": { "get": { "tags": [ "catalog" ], "summary": "Single product details", "operationId": "getProduct", "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "robot_basic", "robot_complete" ] }, "description": "Product code" } ], "responses": { "200": { "description": "Product found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "404": { "description": "Product not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/inventory": { "get": { "tags": [ "catalog" ], "summary": "Current license inventory", "description": "Lightweight inventory check. Cached up to 60 seconds.", "operationId": "getInventory", "responses": { "200": { "description": "Inventory count", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "public, max-age=60" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryResponse" } } } } } } }, "/checkout": { "post": { "tags": [ "checkout" ], "summary": "Create a Stripe Checkout session", "description": "Creates a hosted Stripe Checkout session. Returns a `checkout_url` for the agent to\npresent to the buyer (or redirect to).\n\n**Idempotency:** Send the same `Idempotency-Key` header on retries to avoid duplicate\nsessions. Falls back to `client_reference_id` if no header is provided.\n\nIf a license has already been issued for the idempotency key, returns `409 Conflict`.\n", "operationId": "createCheckout", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Unique key to deduplicate requests. Valid for 24 hours." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutRequest" }, "examples": { "basic": { "summary": "Standard tier purchase", "value": { "product_code": "robot_basic", "customer_email": "buyer@example.com", "agent_id": "my-agent-v1", "agent_platform": "openai-gpts", "client_reference_id": "order-abc-123" } }, "complete": { "summary": "Complete tier purchase", "value": { "product_code": "robot_complete", "customer_email": "buyer@example.com", "agent_id": "my-agent-v1", "agent_platform": "openai-gpts" } } } } } }, "responses": { "200": { "description": "Checkout session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutResponse" }, "example": { "session_id": "cs_live_xxx", "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_xxx", "expires_at": "2026-04-24T12:30:00Z", "product_code": "robot_basic", "amount": 199700, "currency": "USD", "promo_applied": false, "promo_reason": null, "idempotency_key": "my-idem-key", "was_cached": false, "request_id": "req_abc123" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "License already issued for this idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlreadyPurchasedError" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Stripe or server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/checkout/{session_id}": { "get": { "tags": [ "checkout" ], "summary": "Checkout session status", "description": "Poll this endpoint after checkout to verify payment and license delivery.", "operationId": "getCheckoutStatus", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stripe Checkout session ID (starts with cs_)" } ], "responses": { "200": { "description": "Session status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutStatusResponse" }, "example": { "session_id": "cs_live_xxx", "status": "complete", "payment_status": "paid", "license_issued": true, "license_key_redacted": "TSAI-****-****-7K9M", "license_delivered_to_email": "b***@example.com", "completed_at": "2026-04-24T12:05:22Z", "request_id": "req_abc123" } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/license/verify": { "get": { "tags": [ "license" ], "summary": "Verify a license key", "description": "Verifies that a license key is valid for the given email address.\nReturns generic `not_found` on mismatch to prevent email enumeration.\n", "operationId": "verifyLicense", "parameters": [ { "name": "license_key", "in": "query", "required": true, "schema": { "type": "string" }, "example": "TSAI-ABCD-EFGH-JKMN-PQRS" }, { "name": "email", "in": "query", "required": true, "schema": { "type": "string", "format": "email" }, "example": "buyer@example.com" } ], "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LicenseValidResponse" }, { "$ref": "#/components/schemas/LicenseInvalidResponse" } ] }, "examples": { "valid": { "value": { "valid": true, "product_code": "robot_complete", "status": "active", "issued_at": "2026-04-24T12:05:22Z", "request_id": "req_abc123" } }, "invalid": { "value": { "valid": false, "reason": "not_found", "request_id": "req_abc123" } } } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } } } } }, "components": { "schemas": { "HealthResponse": { "type": "object", "required": [ "status", "stripe_mode", "version", "timestamp" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "stripe_mode": { "type": "string", "enum": [ "test", "live" ], "description": "Current Stripe key mode — never cached" }, "version": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "request_id": { "type": "string" } } }, "Price": { "type": "object", "required": [ "amount", "currency", "display" ], "properties": { "amount": { "type": "integer", "description": "Amount in cents" }, "currency": { "type": "string" }, "display": { "type": "string" } } }, "Product": { "type": "object", "required": [ "code", "name", "description", "price", "license_model", "delivery" ], "properties": { "code": { "type": "string", "enum": [ "robot_basic", "robot_complete" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "price": { "$ref": "#/components/schemas/Price" }, "license_model": { "type": "string" }, "delivery": { "type": "string" }, "delivery_items": { "type": "array", "items": { "type": "string" } }, "system_requirements": { "type": "array", "items": { "type": "string" } }, "fulfillment_time_seconds": { "type": "integer" }, "refund_policy_url": { "type": "string", "format": "uri" }, "terms_url": { "type": "string", "format": "uri" }, "checkout_url_template": { "type": "string", "format": "uri" }, "request_id": { "type": "string" } } }, "Merchant": { "type": "object", "properties": { "name": { "type": "string" }, "legal_name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "contact": { "type": "string" }, "currency": { "type": "string" }, "jurisdiction": { "type": "string" } } }, "InventoryBlock": { "type": "object", "required": [ "total_cap", "remaining", "source", "updated_at" ], "properties": { "total_cap": { "type": "integer" }, "remaining": { "type": "integer" }, "source": { "type": "string", "enum": [ "authoritative" ] }, "updated_at": { "type": "string", "format": "date-time" } } }, "CatalogResponse": { "type": "object", "required": [ "merchant", "products", "inventory", "schema_version" ], "properties": { "merchant": { "$ref": "#/components/schemas/Merchant" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "inventory": { "$ref": "#/components/schemas/InventoryBlock" }, "schema_version": { "type": "string" }, "request_id": { "type": "string" } } }, "InventoryResponse": { "allOf": [ { "$ref": "#/components/schemas/InventoryBlock" }, { "type": "object", "properties": { "request_id": { "type": "string" } } } ] }, "CheckoutRequest": { "type": "object", "required": [ "product_code" ], "properties": { "product_code": { "type": "string", "enum": [ "robot_basic", "robot_complete" ] }, "customer_email": { "type": "string", "format": "email", "description": "Optional. Stripe Checkout will collect it if omitted." }, "agent_id": { "type": "string", "maxLength": 128, "description": "Identifier for the calling agent — used for attribution." }, "agent_platform": { "type": "string", "maxLength": 128, "description": "Platform the agent is running on." }, "client_reference_id": { "type": "string", "maxLength": 200, "description": "Agent-generated correlation ID. Used as idempotency fallback." }, "promo_code": { "type": "string", "description": "Stripe promotion code to apply. Fails soft if invalid." }, "metadata": { "type": "object", "maxProperties": 10, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Passthrough metadata merged into the Stripe session." } } }, "CheckoutResponse": { "type": "object", "required": [ "session_id", "checkout_url", "product_code", "amount", "currency", "was_cached" ], "properties": { "session_id": { "type": "string" }, "checkout_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" }, "product_code": { "type": "string" }, "amount": { "type": "integer" }, "currency": { "type": "string" }, "promo_applied": { "type": "boolean" }, "promo_reason": { "type": "string", "nullable": true }, "idempotency_key": { "type": "string", "nullable": true }, "was_cached": { "type": "boolean", "description": "True when returning a deduplicated cached response" }, "request_id": { "type": "string" } } }, "CheckoutStatusResponse": { "type": "object", "required": [ "session_id", "status", "payment_status", "license_issued" ], "properties": { "session_id": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "complete", "expired" ] }, "payment_status": { "type": "string", "enum": [ "paid", "unpaid", "no_payment_required" ] }, "license_issued": { "type": "boolean" }, "license_key_redacted": { "type": "string", "nullable": true, "description": "Last 4 characters visible — full key delivered by email only" }, "license_delivered_to_email": { "type": "string", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "request_id": { "type": "string" } } }, "LicenseValidResponse": { "type": "object", "required": [ "valid", "product_code", "status", "issued_at" ], "properties": { "valid": { "type": "boolean", "enum": [ true ] }, "product_code": { "type": "string" }, "status": { "type": "string", "enum": [ "active" ] }, "issued_at": { "type": "string", "format": "date-time" }, "request_id": { "type": "string" } } }, "LicenseInvalidResponse": { "type": "object", "required": [ "valid", "reason" ], "properties": { "valid": { "type": "boolean", "enum": [ false ] }, "reason": { "type": "string", "enum": [ "not_found" ] }, "request_id": { "type": "string" } } }, "ErrorResponse": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "invalid_product_code", "invalid_email", "inventory_exhausted", "stripe_error", "rate_limited", "not_found", "validation_failed", "internal_error" ] }, "message": { "type": "string" }, "request_id": { "type": "string" } } }, "AlreadyPurchasedError": { "type": "object", "required": [ "error", "message", "license_key_redacted" ], "properties": { "error": { "type": "string", "enum": [ "already_purchased" ] }, "message": { "type": "string" }, "license_key_redacted": { "type": "string" }, "request_id": { "type": "string" } } }, "RateLimitError": { "type": "object", "required": [ "error", "retry_after_seconds" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "retry_after_seconds": { "type": "integer" } } } } } }