{
    "openapi": "3.1.0",
    "info": {
        "title": "Archergate API",
        "version": "0.3.0",
        "description": "Licensing and distribution platform for indie software. Machine-bound license keys, marketplace, agent-native checkout, portable signed receipts, W3C DID identity, and passkey authentication.",
        "contact": {
            "name": "Archergate",
            "email": "hello@archergate.io",
            "url": "https://archergate.io"
        },
        "license": {
            "name": "MIT",
            "url": "https://opensource.org/licenses/MIT"
        }
    },
    "servers": [
        {
            "url": "https://archergate.io",
            "description": "Archergate Cloud"
        },
        {
            "url": "https://your-server.example.com",
            "description": "Self-hosted instance (replace with your deployment URL)"
        }
    ],
    "paths": {
        "/api/terms": {
            "get": {
                "operationId": "getTerms",
                "summary": "Machine-readable pricing, capabilities, and competitor comparison",
                "description": "Returns structured JSON with pricing model, platform capabilities, API endpoints, and a comparison table against Keygen, Cryptlex, iLok, and Gumroad. Designed for agents to evaluate licensing solutions programmatically.",
                "responses": {
                    "200": {
                        "description": "Terms and pricing data",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "provider": { "type": "string" },
                                        "pricing": {
                                            "type": "object",
                                            "properties": {
                                                "model": { "type": "string" },
                                                "transaction_fee_percent": { "type": "number" },
                                                "monthly_fee_cents": { "type": "integer" },
                                                "sdk_cost": { "type": "string" },
                                                "self_host_cost": { "type": "string" }
                                            }
                                        },
                                        "capabilities": { "type": "object" },
                                        "endpoints": { "type": "object" },
                                        "comparison": {
                                            "type": "array",
                                            "items": { "type": "object" }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/receipt": {
            "get": {
                "operationId": "getReceipt",
                "summary": "Issue a signed license receipt",
                "description": "Returns an HMAC-SHA256 signed portable receipt for a license key. The receipt can be verified by any agent without contacting Archergate, enabling cross-agent license verification.",
                "parameters": [
                    {
                        "name": "key",
                        "in": "query",
                        "required": true,
                        "schema": { "type": "string" },
                        "description": "License key (XXXX-XXXX-XXXX-XXXX)"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Signed receipt",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "receipt": {
                                            "type": "object",
                                            "properties": {
                                                "version": { "type": "integer" },
                                                "issuer": { "type": "string" },
                                                "license_key": { "type": "string" },
                                                "product_id": { "type": "string" },
                                                "product_name": { "type": "string" },
                                                "buyer_email": { "type": "string" },
                                                "max_machines": { "type": "integer" },
                                                "is_active": { "type": "boolean" },
                                                "issued_at": { "type": "string", "format": "date-time" },
                                                "expires_at": { "type": "string", "format": "date-time" },
                                                "checked_at": { "type": "string", "format": "date-time" }
                                            }
                                        },
                                        "signature": { "type": "string" },
                                        "verify_url": { "type": "string" },
                                        "verify_method": { "type": "string" }
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "post": {
                "operationId": "verifyReceipt",
                "summary": "Verify a signed license receipt",
                "description": "Verifies an HMAC-SHA256 signed receipt and checks if the license is still active. Any agent can call this to confirm license validity without needing API keys.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": ["receipt", "signature"],
                                "properties": {
                                    "receipt": { "type": "object", "description": "The receipt payload from getReceipt" },
                                    "signature": { "type": "string", "description": "HMAC-SHA256 signature" }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Verification result",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "valid": { "type": "boolean" },
                                        "still_active": { "type": "boolean" },
                                        "receipt_age_seconds": { "type": "integer" }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/checkout/create": {
            "post": {
                "operationId": "createCheckout",
                "summary": "Create a Stripe checkout session",
                "description": "Creates a payment link for a product. Returns a URL the buyer (or agent) must open to complete purchase. On success, a license key is generated and emailed automatically.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": ["product_id", "buyer_email"],
                                "properties": {
                                    "product_id": { "type": "string", "description": "Product ID from marketplace" },
                                    "buyer_email": { "type": "string", "description": "Email to receive the license key" },
                                    "agent_id": { "type": "string", "description": "Agent identifier for attribution" }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Checkout session",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "url": { "type": "string", "format": "uri" },
                                        "session_id": { "type": "string" }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/marketplace/listings": {
            "get": {
                "operationId": "browseMarketplace",
                "summary": "Browse marketplace listings",
                "description": "Search and filter indie software products. Supports category filtering, text search, sorting, and pagination.",
                "parameters": [
                    { "name": "category", "in": "query", "schema": { "type": "string" } },
                    { "name": "search", "in": "query", "schema": { "type": "string" } },
                    { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["newest", "price_asc", "price_desc", "popular"] } },
                    { "name": "page", "in": "query", "schema": { "type": "integer" } },
                    { "name": "limit", "in": "query", "schema": { "type": "integer" } }
                ],
                "responses": {
                    "200": {
                        "description": "Product listings",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "products": { "type": "array", "items": { "type": "object" } },
                                        "total": { "type": "integer" },
                                        "page": { "type": "integer" }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/marketplace/product/{id}": {
            "get": {
                "operationId": "getProductDetails",
                "summary": "Get product details",
                "description": "Returns full details for a single marketplace product including developer info, images, and pricing.",
                "parameters": [
                    { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
                ],
                "responses": {
                    "200": {
                        "description": "Product details",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "product": { "type": "object" }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/marketplace/categories": {
            "get": {
                "operationId": "getCategories",
                "summary": "Get marketplace categories with counts",
                "description": "Returns all product categories and how many active listings each contains.",
                "responses": {
                    "200": {
                        "description": "Category list",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "categories": {
                                            "type": "array",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "category": { "type": "string" },
                                                    "count": { "type": "integer" }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/.well-known/did.json": {
            "get": {
                "operationId": "getDIDDocument",
                "summary": "W3C DID Document",
                "description": "Returns the W3C Decentralized Identifier document for did:web:archergate.io. Establishes Archergate as a verifiable issuer of software license credentials using Ed25519 keys.",
                "responses": {
                    "200": {
                        "description": "DID Document",
                        "content": {
                            "application/did+json": {
                                "schema": { "type": "object" }
                            }
                        }
                    }
                }
            }
        },
        "/validate": {
            "post": {
                "operationId": "validateLicense",
                "summary": "Validate a license key",
                "description": "Checks if a license key is valid for a given machine fingerprint and application. Returns validation status, expiry, and whether the key is bound to this machine.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": ["license_key", "machine_fingerprint", "plugin_id"],
                                "properties": {
                                    "license_key": { "type": "string" },
                                    "machine_fingerprint": { "type": "string" },
                                    "plugin_id": { "type": "string" }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Validation result",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "valid": { "type": "boolean" },
                                        "expires_at": { "type": "string", "format": "date-time" },
                                        "machine_bound": { "type": "boolean" },
                                        "trial": { "type": "boolean" },
                                        "trial_days_remaining": { "type": "integer" }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/activate": {
            "post": {
                "operationId": "activateLicense",
                "summary": "Activate a license on a machine",
                "description": "Binds a license key to a specific machine via SHA-256 fingerprint.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": ["license_key", "machine_fingerprint", "plugin_id"],
                                "properties": {
                                    "license_key": { "type": "string" },
                                    "machine_fingerprint": { "type": "string" },
                                    "plugin_id": { "type": "string" }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Activation successful",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "activated": { "type": "boolean" },
                                        "machine_fingerprint": { "type": "string" },
                                        "activated_at": { "type": "string", "format": "date-time" }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/deactivate": {
            "post": {
                "operationId": "deactivateLicense",
                "summary": "Release a license from a machine",
                "description": "Unbinds a license key from its current machine, freeing a seat.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": ["license_key", "machine_fingerprint"],
                                "properties": {
                                    "license_key": { "type": "string" },
                                    "machine_fingerprint": { "type": "string" }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Deactivation successful",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "deactivated": { "type": "boolean" }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/discover": {
            "get": {
                "operationId": "discover",
                "summary": "One-stop agent discovery endpoint",
                "description": "Returns everything an AI agent needs to connect to Archergate: identity, protocols (MCP, OpenAPI, A2A, OpenAI plugin, DID), all 14 tools across 5 capability layers, quickstart examples, pricing, and self-describing links. No registry needed.",
                "responses": {
                    "200": {
                        "description": "Full discovery payload",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": { "type": "string" },
                                        "summary": { "type": "string" },
                                        "protocols": { "type": "object" },
                                        "capabilities": { "type": "object" },
                                        "quickstart": { "type": "object" },
                                        "pricing": { "type": "object" },
                                        "_links": { "type": "object" }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/catalog": {
            "get": {
                "operationId": "getCatalog",
                "summary": "Machine-readable product catalog with structured capability metadata for AI agent discovery",
                "description": "Returns all listed products with prices, checkout URLs, structured software capability metadata (OACS), and inline instructions for purchasing via MCP or REST. Each product includes compatibility, inputs, outputs, seat model, trial availability, and platform fields for agent filtering. Supports category, search, sort, and pagination parameters. See /oacs for the capability spec.",
                "externalDocs": {
                    "description": "Open Agent Capability Spec (OACS)",
                    "url": "https://archergate.io/oacs"
                },
                "parameters": [
                    { "name": "category", "in": "query", "schema": { "type": "string" } },
                    { "name": "search", "in": "query", "schema": { "type": "string" } },
                    { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["newest", "price_asc", "price_desc", "name"] } },
                    { "name": "page", "in": "query", "schema": { "type": "integer" } }
                ],
                "responses": {
                    "200": {
                        "description": "Product catalog with agent instructions and OACS metadata",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "catalog_version": { "type": "string" },
                                        "issuer": { "type": "string" },
                                        "generated_at": { "type": "string", "format": "date-time" },
                                        "total": { "type": "integer" },
                                        "_oacs": {
                                            "type": "object",
                                            "description": "Open Agent Capability Spec discovery block",
                                            "properties": {
                                                "version": { "type": "string" },
                                                "spec": { "type": "string", "format": "uri" },
                                                "discovery": { "type": "string", "format": "uri" },
                                                "catalog": { "type": "string", "format": "uri" }
                                            }
                                        },
                                        "products": {
                                            "type": "array",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "id": { "type": "string" },
                                                    "name": { "type": "string" },
                                                    "plugin_id": { "type": "string" },
                                                    "description": { "type": "string" },
                                                    "price_cents": { "type": "integer" },
                                                    "price_display": { "type": "string" },
                                                    "currency": { "type": "string" },
                                                    "category": { "type": "string" },
                                                    "developer": { "type": "string" },
                                                    "max_machines": { "type": "integer" },
                                                    "download_url": { "type": "string", "format": "uri" },
                                                    "icon_url": { "type": "string", "format": "uri" },
                                                    "created_at": { "type": "string", "format": "date-time" },
                                                    "compatibility": {
                                                        "type": "array",
                                                        "items": { "type": "string" },
                                                        "description": "Platform/framework compatibility tags (e.g. vst3, au, clap, unity, blender)"
                                                    },
                                                    "inputs": {
                                                        "type": "array",
                                                        "items": { "type": "string" },
                                                        "description": "What the software accepts (e.g. audio, midi, sidechain, source-code)"
                                                    },
                                                    "outputs": {
                                                        "type": "array",
                                                        "items": { "type": "string" },
                                                        "description": "What the software produces (e.g. audio, parameter-automation, renders)"
                                                    },
                                                    "seat_model": {
                                                        "type": "string",
                                                        "enum": ["per-machine", "per-user", "per-seat", "floating"],
                                                        "description": "License seat model"
                                                    },
                                                    "trial_available": {
                                                        "type": "boolean",
                                                        "description": "Whether a free trial is available"
                                                    },
                                                    "platforms": {
                                                        "type": "array",
                                                        "items": { "type": "string", "enum": ["windows", "macos", "linux"] },
                                                        "description": "Supported operating systems"
                                                    },
                                                    "min_version": {
                                                        "type": "string",
                                                        "description": "Minimum host version if applicable"
                                                    },
                                                    "checkout_url": { "type": "string", "format": "uri" },
                                                    "product_page": { "type": "string", "format": "uri" }
                                                }
                                            }
                                        },
                                        "_agent_howto": { "type": "object" },
                                        "filters": { "type": "object" },
                                        "_links": { "type": "object" }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/tools": {
            "get": {
                "operationId": "getTools",
                "summary": "OpenAI-format tool manifest",
                "description": "Returns all 14 tools in OpenAI function-calling format. Compatible with ChatGPT, GPTs, Langchain, CrewAI, AutoGen, and any OpenAI SDK consumer.",
                "responses": {
                    "200": {
                        "description": "Tool manifest with MCP config",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "schema_version": { "type": "string" },
                                        "tools": { "type": "array", "items": { "type": "object" } },
                                        "mcp": { "type": "object" },
                                        "_links": { "type": "object" }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/health": {
            "get": {
                "operationId": "healthCheck",
                "summary": "Server health check",
                "responses": {
                    "200": {
                        "description": "Server is running",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": { "type": "string", "enum": ["ok"] },
                                        "version": { "type": "string" }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}