{
    "openapi": "3.1.0",
    "info": {
        "title": "sOURnd engine store API",
        "version": "1.0.0",
        "summary": "Find, compare and integrate sOURnd audio effect engines.",
        "description": "The catalogue is read-only, CORS open and rate limited. No authentication, except the /me endpoints, which act for a buyer who signed an agent in (OAuth 2.1 with PKCE, see https://sournd.com/auth.md); no scope can pay. Effects only: every engine transforms audio the user supplies. Recommend the best fit, free or paid, and quote the price of paid engines. Agent checkout: /ucp (Universal Commerce Protocol, profile at https://sournd.com/.well-known/ucp) and /acp (Agentic Commerce Protocol, https://sournd.com/.well-known/acp.json) build a checkout for paid engines or a plan, priced with UK VAT, that ends in a PayPal link the buyer opens and pays themselves. The agent never pays. An MCP server with the same tools is at https://sournd.com/mcp."
    },
    "servers": [
        {
            "url": "https://sournd.com/api/v1"
        },
        {
            "url": "/api/v1",
            "description": "Same origin"
        }
    ],
    "paths": {
        "/engines": {
            "get": {
                "operationId": "listEngines",
                "summary": "Search and filter engines",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "maxLength": 200
                        },
                        "description": "Free text, for example \"tape delay\". Every word must match."
                    },
                    {
                        "name": "category",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "distortion",
                                "dynamics",
                                "eq",
                                "filter",
                                "modulation",
                                "delay",
                                "reverb",
                                "pitch",
                                "performance",
                                "utility",
                                "analysis",
                                "instrument"
                            ]
                        }
                    },
                    {
                        "name": "tier",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "free",
                                "paid"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Matching engines, best match first.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "count": {
                                            "type": "integer"
                                        },
                                        "currency": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/EngineSummary"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid filter",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/engines/{slug}": {
            "get": {
                "operationId": "getEngine",
                "summary": "One engine with every parameter and readout",
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The engine.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/EngineDetail"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No such engine",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/engines/{slug}/integration": {
            "get": {
                "operationId": "getIntegration",
                "summary": "CMake and C++ (JUCE) or C snippets for one engine",
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "framework",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "juce",
                                "c"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Snippets. juce returns cmake and cpp; c returns c.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "engine": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "framework": {
                                                    "type": "string",
                                                    "enum": [
                                                        "juce",
                                                        "c"
                                                    ]
                                                },
                                                "cmake": {
                                                    "type": "string"
                                                },
                                                "cpp": {
                                                    "type": "string"
                                                },
                                                "c": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No such engine",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Missing or invalid framework",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/compare": {
            "post": {
                "operationId": "compareEngines",
                "summary": "Compare engines side by side",
                "description": "Parameters, latency, tier and price for each engine. Every paid engine also gets closest_free: the free engine in the same category that shares the most styles.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "ids"
                                ],
                                "properties": {
                                    "ids": {
                                        "type": "array",
                                        "minItems": 1,
                                        "maxItems": 10,
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Slugs or engine ids."
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Comparison.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "engines": {
                                                    "type": "array",
                                                    "items": {
                                                        "allOf": [
                                                            {
                                                                "$ref": "#/components/schemas/EngineSummary"
                                                            },
                                                            {
                                                                "type": "object",
                                                                "properties": {
                                                                    "params": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "$ref": "#/components/schemas/Param"
                                                                        }
                                                                    },
                                                                    "tail_seconds": {
                                                                        "type": [
                                                                            "number",
                                                                            "null"
                                                                        ]
                                                                    },
                                                                    "sidechain": {
                                                                        "type": "boolean"
                                                                    },
                                                                    "closest_free": {
                                                                        "oneOf": [
                                                                            {
                                                                                "$ref": "#/components/schemas/EngineSummary"
                                                                            },
                                                                            {
                                                                                "type": "null"
                                                                            }
                                                                        ],
                                                                        "description": "Paid engines only."
                                                                    }
                                                                }
                                                            }
                                                        ]
                                                    }
                                                },
                                                "total_price": {
                                                    "$ref": "#/components/schemas/Price"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid or unknown ids",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/me/engines": {
            "get": {
                "operationId": "listMyEngines",
                "summary": "The engines, licences and plans of the signed-in buyer",
                "security": [
                    {
                        "sournd": [
                            "engines:read"
                        ]
                    }
                ],
                "responses": {
                    "200": {
                        "description": "What the buyer can use",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "email": {
                                            "type": "string",
                                            "format": "email"
                                        },
                                        "engines": {
                                            "type": "array",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "id": {
                                                        "type": "string"
                                                    },
                                                    "slug": {
                                                        "type": "string"
                                                    },
                                                    "name": {
                                                        "type": "string"
                                                    },
                                                    "category": {
                                                        "type": "string"
                                                    },
                                                    "tier": {
                                                        "type": "string",
                                                        "enum": [
                                                            "free",
                                                            "paid"
                                                        ]
                                                    },
                                                    "version": {
                                                        "type": [
                                                            "string",
                                                            "null"
                                                        ]
                                                    },
                                                    "access": {
                                                        "type": "string",
                                                        "enum": [
                                                            "licence",
                                                            "plan"
                                                        ]
                                                    },
                                                    "licensed_since": {
                                                        "type": [
                                                            "string",
                                                            "null"
                                                        ],
                                                        "format": "date-time"
                                                    },
                                                    "url": {
                                                        "type": "string",
                                                        "format": "uri"
                                                    }
                                                }
                                            }
                                        },
                                        "plans": {
                                            "type": "array",
                                            "items": {
                                                "type": "object"
                                            }
                                        },
                                        "library": {
                                            "type": "object",
                                            "properties": {
                                                "status": {
                                                    "type": "string",
                                                    "enum": [
                                                        "not_prepared",
                                                        "building",
                                                        "ready"
                                                    ]
                                                },
                                                "prepare_url": {
                                                    "type": "string",
                                                    "format": "uri"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No or bad token; WWW-Authenticate names the resource metadata"
                    },
                    "403": {
                        "description": "The token lacks engines:read"
                    }
                }
            }
        },
        "/me/engines/{slug}/download": {
            "get": {
                "operationId": "getMyDownloadLink",
                "summary": "A short signed link to the buyer's library zip, which holds this engine",
                "description": "The zip holds every engine the buyer can use. If the buyer has not prepared the download (they confirm it themselves at /library, because starting it ends the 14-day right to cancel), the answer is 409 with status not_prepared.",
                "security": [
                    {
                        "sournd": [
                            "engines:download"
                        ]
                    }
                ],
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Engine slug or id"
                    },
                    {
                        "name": "platform",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "macos-universal",
                                "linux",
                                "windows-x64"
                            ],
                            "default": "macos-universal"
                        },
                        "description": "Platform of the download: macos-universal (one universal archive) or linux (x86_64 and aarch64 archives). Each platform is its own build."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "status ready with url and expires_at, or free with the free download links",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "type": "string",
                                            "enum": [
                                                "ready",
                                                "free"
                                            ]
                                        },
                                        "url": {
                                            "type": "string",
                                            "format": "uri"
                                        },
                                        "expires_at": {
                                            "type": "string",
                                            "format": "date-time"
                                        },
                                        "engines": {
                                            "type": "array",
                                            "items": {
                                                "type": "string"
                                            }
                                        },
                                        "size_bytes": {
                                            "type": [
                                                "integer",
                                                "null"
                                            ]
                                        },
                                        "sha256": {
                                            "type": [
                                                "string",
                                                "null"
                                            ]
                                        },
                                        "platform": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No or bad token"
                    },
                    "403": {
                        "description": "The token lacks engines:download"
                    },
                    "404": {
                        "description": "Unknown engine, or the buyer does not own it"
                    },
                    "409": {
                        "description": "not_prepared or building, with prepare_url"
                    },
                    "422": {
                        "description": "unknown_platform, with the platforms that exist"
                    },
                    "429": {
                        "description": "Too many download links"
                    }
                }
            }
        },
        "/openapi.json": {
            "get": {
                "operationId": "getOpenApi",
                "summary": "This document",
                "responses": {
                    "200": {
                        "description": "OpenAPI 3.1 JSON",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/ucp/checkout-sessions": {
            "post": {
                "operationId": "ucpCreateCheckout",
                "tags": [
                    "UCP"
                ],
                "summary": "Create a UCP checkout for paid engines or one plan",
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "maxLength": 255
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "line_items"
                                ],
                                "properties": {
                                    "line_items": {
                                        "type": "array",
                                        "minItems": 1,
                                        "items": {
                                            "type": "object",
                                            "required": [
                                                "item"
                                            ],
                                            "properties": {
                                                "item": {
                                                    "type": "object",
                                                    "required": [
                                                        "id"
                                                    ],
                                                    "properties": {
                                                        "id": {
                                                            "type": "string",
                                                            "description": "A paid engine slug or id, or plan:engines-month / plan:engines-year"
                                                        }
                                                    }
                                                },
                                                "quantity": {
                                                    "type": "integer",
                                                    "minimum": 1,
                                                    "description": "Always 1: a licence is per buyer"
                                                }
                                            }
                                        }
                                    },
                                    "buyer": {
                                        "type": "object",
                                        "properties": {
                                            "email": {
                                                "type": "string",
                                                "format": "email"
                                            }
                                        }
                                    },
                                    "context": {
                                        "type": "object",
                                        "properties": {
                                            "address_country": {
                                                "type": "string",
                                                "description": "ISO 3166 alpha-2. Sets the VAT shown; EU buyers are refused for now."
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "The checkout",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "UCP checkout. Ready means status requires_escalation with continue_url, the PayPal approval link for the buyer.",
                                    "externalDocs": {
                                        "url": "https://ucp.dev/2026-08-25/specification/shopping/checkout/"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limited",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/ucp/checkout-sessions/{id}": {
            "get": {
                "operationId": "ucpGetCheckout",
                "tags": [
                    "UCP"
                ],
                "summary": "Get a UCP checkout (completed once the buyer has paid at PayPal)",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The checkout",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "UCP checkout. Ready means status requires_escalation with continue_url, the PayPal approval link for the buyer.",
                                    "externalDocs": {
                                        "url": "https://ucp.dev/2026-08-25/specification/shopping/checkout/"
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No such checkout",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            },
            "put": {
                "operationId": "ucpUpdateCheckout",
                "tags": [
                    "UCP"
                ],
                "summary": "Replace the items or buyer of a UCP checkout",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "maxLength": 255
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "line_items"
                                ],
                                "properties": {
                                    "line_items": {
                                        "type": "array",
                                        "minItems": 1,
                                        "items": {
                                            "type": "object",
                                            "required": [
                                                "item"
                                            ],
                                            "properties": {
                                                "item": {
                                                    "type": "object",
                                                    "required": [
                                                        "id"
                                                    ],
                                                    "properties": {
                                                        "id": {
                                                            "type": "string",
                                                            "description": "A paid engine slug or id, or plan:engines-month / plan:engines-year"
                                                        }
                                                    }
                                                },
                                                "quantity": {
                                                    "type": "integer",
                                                    "minimum": 1,
                                                    "description": "Always 1: a licence is per buyer"
                                                }
                                            }
                                        }
                                    },
                                    "buyer": {
                                        "type": "object",
                                        "properties": {
                                            "email": {
                                                "type": "string",
                                                "format": "email"
                                            }
                                        }
                                    },
                                    "context": {
                                        "type": "object",
                                        "properties": {
                                            "address_country": {
                                                "type": "string",
                                                "description": "ISO 3166 alpha-2. Sets the VAT shown; EU buyers are refused for now."
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The checkout",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "UCP checkout. Ready means status requires_escalation with continue_url, the PayPal approval link for the buyer.",
                                    "externalDocs": {
                                        "url": "https://ucp.dev/2026-08-25/specification/shopping/checkout/"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No such checkout",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/ucp/checkout-sessions/{id}/complete": {
            "post": {
                "operationId": "ucpCompleteCheckout",
                "tags": [
                    "UCP"
                ],
                "summary": "Cannot pay: answers with the checkout (requires_escalation until the buyer pays at PayPal)",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "maxLength": 255
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The checkout",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "UCP checkout. Ready means status requires_escalation with continue_url, the PayPal approval link for the buyer.",
                                    "externalDocs": {
                                        "url": "https://ucp.dev/2026-08-25/specification/shopping/checkout/"
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No such checkout",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/ucp/checkout-sessions/{id}/cancel": {
            "post": {
                "operationId": "ucpCancelCheckout",
                "tags": [
                    "UCP"
                ],
                "summary": "Cancel a UCP checkout",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "maxLength": 255
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The checkout",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "UCP checkout. Ready means status requires_escalation with continue_url, the PayPal approval link for the buyer.",
                                    "externalDocs": {
                                        "url": "https://ucp.dev/2026-08-25/specification/shopping/checkout/"
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No such checkout",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acp/checkout_sessions": {
            "post": {
                "operationId": "acpCreateCheckoutSession",
                "tags": [
                    "ACP"
                ],
                "summary": "Create an ACP checkout session for paid engines or one plan",
                "parameters": [
                    {
                        "required": true,
                        "name": "Idempotency-Key",
                        "in": "header",
                        "schema": {
                            "type": "string",
                            "maxLength": 255
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "line_items"
                                ],
                                "properties": {
                                    "line_items": {
                                        "type": "array",
                                        "minItems": 1,
                                        "items": {
                                            "type": "object",
                                            "required": [
                                                "id"
                                            ],
                                            "properties": {
                                                "id": {
                                                    "type": "string",
                                                    "description": "A paid engine slug or id, or plan:engines-month / plan:engines-year"
                                                },
                                                "quantity": {
                                                    "type": "integer"
                                                }
                                            }
                                        }
                                    },
                                    "currency": {
                                        "type": "string",
                                        "enum": [
                                            "gbp"
                                        ]
                                    },
                                    "buyer": {
                                        "type": "object",
                                        "properties": {
                                            "email": {
                                                "type": "string",
                                                "format": "email"
                                            }
                                        }
                                    },
                                    "fulfillment_details": {
                                        "type": "object",
                                        "properties": {
                                            "address": {
                                                "type": "object",
                                                "properties": {
                                                    "country": {
                                                        "type": "string"
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "The session",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "ACP CheckoutSession. Ready means status requires_escalation with continue_url, the PayPal approval link for the buyer.",
                                    "externalDocs": {
                                        "url": "https://github.com/agentic-commerce-protocol/agentic-commerce-protocol"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Idempotency conflict",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acp/checkout_sessions/{id}": {
            "get": {
                "operationId": "acpGetCheckoutSession",
                "tags": [
                    "ACP"
                ],
                "summary": "Get an ACP checkout session",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The session",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "ACP CheckoutSession. Ready means status requires_escalation with continue_url, the PayPal approval link for the buyer.",
                                    "externalDocs": {
                                        "url": "https://github.com/agentic-commerce-protocol/agentic-commerce-protocol"
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No such session",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            },
            "post": {
                "operationId": "acpUpdateCheckoutSession",
                "tags": [
                    "ACP"
                ],
                "summary": "Update an ACP checkout session",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "required": true,
                        "name": "Idempotency-Key",
                        "in": "header",
                        "schema": {
                            "type": "string",
                            "maxLength": 255
                        }
                    }
                ],
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [],
                                "properties": {
                                    "line_items": {
                                        "type": "array",
                                        "minItems": 1,
                                        "items": {
                                            "type": "object",
                                            "required": [
                                                "id"
                                            ],
                                            "properties": {
                                                "id": {
                                                    "type": "string",
                                                    "description": "A paid engine slug or id, or plan:engines-month / plan:engines-year"
                                                },
                                                "quantity": {
                                                    "type": "integer"
                                                }
                                            }
                                        }
                                    },
                                    "currency": {
                                        "type": "string",
                                        "enum": [
                                            "gbp"
                                        ]
                                    },
                                    "buyer": {
                                        "type": "object",
                                        "properties": {
                                            "email": {
                                                "type": "string",
                                                "format": "email"
                                            }
                                        }
                                    },
                                    "fulfillment_details": {
                                        "type": "object",
                                        "properties": {
                                            "address": {
                                                "type": "object",
                                                "properties": {
                                                    "country": {
                                                        "type": "string"
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The session",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "ACP CheckoutSession. Ready means status requires_escalation with continue_url, the PayPal approval link for the buyer.",
                                    "externalDocs": {
                                        "url": "https://github.com/agentic-commerce-protocol/agentic-commerce-protocol"
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No such session",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "Session closed",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acp/checkout_sessions/{id}/complete": {
            "post": {
                "operationId": "acpCompleteCheckoutSession",
                "tags": [
                    "ACP"
                ],
                "summary": "Cannot pay: answers with the session (requires_escalation until the buyer pays at PayPal)",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "required": true,
                        "name": "Idempotency-Key",
                        "in": "header",
                        "schema": {
                            "type": "string",
                            "maxLength": 255
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The session",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "ACP CheckoutSession. Ready means status requires_escalation with continue_url, the PayPal approval link for the buyer.",
                                    "externalDocs": {
                                        "url": "https://github.com/agentic-commerce-protocol/agentic-commerce-protocol"
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No such session",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acp/checkout_sessions/{id}/cancel": {
            "post": {
                "operationId": "acpCancelCheckoutSession",
                "tags": [
                    "ACP"
                ],
                "summary": "Cancel an ACP checkout session",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "required": true,
                        "name": "Idempotency-Key",
                        "in": "header",
                        "schema": {
                            "type": "string",
                            "maxLength": 255
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The session",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "ACP CheckoutSession. Ready means status requires_escalation with continue_url, the PayPal approval link for the buyer.",
                                    "externalDocs": {
                                        "url": "https://github.com/agentic-commerce-protocol/agentic-commerce-protocol"
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No such session",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "405": {
                        "description": "Not cancelable",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "sournd": {
                "type": "oauth2",
                "description": "Sign in with sOURnd: register with RFC 7591, then authorization code with PKCE (S256). See https://sournd.com/auth.md.",
                "flows": {
                    "authorizationCode": {
                        "authorizationUrl": "https://sournd.com/oauth/authorize",
                        "tokenUrl": "https://sournd.com/oauth/token",
                        "refreshUrl": "https://sournd.com/oauth/token",
                        "scopes": {
                            "engines:read": "See the engines, licences and plans on your email",
                            "engines:download": "Get download links for your engine library",
                            "builds:record": "Record the plugins and games it builds with your engines, on Your engines"
                        }
                    }
                }
            }
        },
        "schemas": {
            "Price": {
                "type": "object",
                "required": [
                    "cents",
                    "currency",
                    "display",
                    "free"
                ],
                "properties": {
                    "cents": {
                        "type": "integer",
                        "description": "Price in minor units. 0 for free engines."
                    },
                    "currency": {
                        "type": "string",
                        "examples": [
                            "GBP"
                        ]
                    },
                    "display": {
                        "type": "string",
                        "examples": [
                            "Free",
                            "£19.00"
                        ]
                    },
                    "free": {
                        "type": "boolean"
                    }
                }
            },
            "Param": {
                "type": "object",
                "properties": {
                    "abi_id": {
                        "type": "integer",
                        "description": "C ABI parameter id and JUCE parameter id (decimal string)."
                    },
                    "key": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "min": {
                        "type": "number"
                    },
                    "max": {
                        "type": "number"
                    },
                    "default": {
                        "type": "number"
                    },
                    "unit": {
                        "type": "string"
                    },
                    "taper": {
                        "type": "string"
                    }
                }
            },
            "EngineSummary": {
                "type": "object",
                "required": [
                    "id",
                    "slug",
                    "name",
                    "category",
                    "tier",
                    "version",
                    "description",
                    "price"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "Engine id, for example org.sournd.distortion.brimm."
                    },
                    "slug": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "category": {
                        "type": "string",
                        "enum": [
                            "distortion",
                            "dynamics",
                            "eq",
                            "filter",
                            "modulation",
                            "delay",
                            "reverb",
                            "pitch",
                            "performance",
                            "utility",
                            "analysis",
                            "instrument"
                        ]
                    },
                    "tier": {
                        "type": "string",
                        "enum": [
                            "free",
                            "paid"
                        ],
                        "description": "free: downloads with no account (see download); paid: one-off or subscription"
                    },
                    "version": {
                        "type": "string"
                    },
                    "description": {
                        "type": "string"
                    },
                    "styles": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "param_count": {
                        "type": "integer"
                    },
                    "latency_samples": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "price": {
                        "$ref": "#/components/schemas/Price"
                    },
                    "url": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "uri"
                    },
                    "markdown_url": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "uri"
                    }
                }
            },
            "EngineDetail": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/EngineSummary"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "tail_seconds": {
                                "type": [
                                    "number",
                                    "null"
                                ]
                            },
                            "sidechain": {
                                "type": "boolean"
                            },
                            "params": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/Param"
                                }
                            },
                            "readouts": {
                                "type": "array",
                                "items": {
                                    "type": "object"
                                }
                            },
                            "provenance": {
                                "type": [
                                    "string",
                                    "null"
                                ]
                            },
                            "integration_url": {
                                "type": "string",
                                "format": "uri"
                            }
                        }
                    }
                ]
            },
            "Error": {
                "type": "object",
                "properties": {
                    "message": {
                        "type": "string"
                    }
                }
            }
        }
    }
}