{
  "openapi": "3.1.0",
  "info": {
    "title": "surfpay.ai, the Surfboard Payments agent surface",
    "version": "1.0.0",
    "summary": "Everything surfpay.ai serves to machines: the integration brief, the agent skills pack, the developer guides it bundles, search over both, and an MCP endpoint.",
    "description": "This is the public, unauthenticated surface of surfpay.ai. No key, no signup,\nno rate limit. CORS is open, so a browser-based agent can call it directly.\n\nIt is **not** the payments API. Taking a payment means the Carbon API, which is\ncredentialed per account and described separately at https://www.surfboardpayments.com/openapi/carbon.json.\nIf you are here to build an integration, start with https://surfpay.ai/agent-instructions.md.\n\nThree things worth knowing before you call anything:\n\n- Paths are case-sensitive, and JSON endpoints keep their `.json` suffix.\n- Every failure, including a 404 on a path that does not exist, returns the\n  `Error` schema with a `code` you can branch on.\n- `GET /` content-negotiates: ask for `text/markdown` and you get the brief\n  rather than HTML.",
    "termsOfService": "https://www.surfboardpayments.com/terms-and-conditions",
    "contact": {
      "name": "Surfboard Payments",
      "url": "https://surfpay.ai/contact",
      "email": "support@surfboardpayments.com"
    },
    "license": {
      "name": "Terms of use",
      "url": "https://www.surfboardpayments.com/terms-and-conditions"
    }
  },
  "servers": [
    {
      "url": "https://surfpay.ai",
      "description": "Production. The only host; there is no sandbox to point at."
    }
  ],
  "security": [],
  "externalDocs": {
    "description": "Developer portal and API reference for the payments API",
    "url": "https://developers.surfboardpayments.com"
  },
  "tags": [
    {
      "name": "Agents",
      "description": "Start here: the brief, when to use it, and the MCP endpoint."
    },
    {
      "name": "Discovery",
      "description": "What exists on this domain and where."
    },
    {
      "name": "Skills",
      "description": "The agent skills pack, and the guides each skill bundles."
    },
    {
      "name": "Search",
      "description": "Keyword search over the skills and the bundled guides."
    },
    {
      "name": "Operations",
      "description": "Liveness, and what version of the brief is deployed."
    }
  ],
  "x-mcp": {
    "endpoint": "https://surfpay.ai/.well-known/mcp",
    "transport": "streamable-http",
    "serverCard": "https://surfpay.ai/.well-known/mcp/server-card.json",
    "protocolVersion": "2025-06-18",
    "version": "1.0.0",
    "tools": [
      "get_integration_brief",
      "list_skills",
      "get_skill",
      "search_docs",
      "get_guide"
    ]
  },
  "x-agent-instructions": "https://surfpay.ai/agent-instructions.md",
  "paths": {
    "/": {
      "get": {
        "operationId": "getHomepage",
        "tags": [
          "Agents"
        ],
        "summary": "The integration brief, or the human page",
        "description": "Content-negotiated. Send `Accept: text/markdown` or `Accept: text/plain`, or add `?format=md`, and you get the integration brief as markdown. Anything else gets the HTML page, which carries the same brief in a `<pre id=\"agent-payload\">` block as the first element in the body.",
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "Force markdown without setting an Accept header.",
            "schema": {
              "type": "string",
              "enum": [
                "md",
                "markdown",
                "txt"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The brief as markdown, or the page as HTML.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "getLlmsTxt",
        "tags": [
          "Agents"
        ],
        "summary": "The integration brief, llms.txt convention",
        "description": "The whole brief as one plain-text file: when to use Surfboard Payments, the six steps of an integration, the safety rules, the conventions that break first integrations, and a table of every machine-readable resource.",
        "responses": {
          "200": {
            "description": "The integration brief, llms.txt convention",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-instructions.md": {
      "get": {
        "operationId": "getAgentInstructions",
        "tags": [
          "Agents"
        ],
        "summary": "When to use Surfboard Payments, and how to call it",
        "description": "The same brief, framed as a routing decision: what this company is the right answer for, what it is not, and who publishes it. Read this before deciding whether to integrate at all.",
        "responses": {
          "200": {
            "description": "When to use Surfboard Payments, and how to call it",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/payload.md": {
      "get": {
        "operationId": "getPayloadMarkdown",
        "tags": [
          "Agents"
        ],
        "summary": "The integration brief as markdown",
        "description": "Identical content to /llms.txt without the llms.txt header and resource table. `/AGENTS.md`, `/CLAUDE.md` and `/skill.md` are aliases of this response, so an agent guessing a well-known filename always lands somewhere.",
        "responses": {
          "200": {
            "description": "The integration brief as markdown",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "getOpenApiSpec",
        "tags": [
          "Discovery"
        ],
        "summary": "This specification",
        "description": "The document you are reading, as OpenAPI 3.1 JSON.",
        "responses": {
          "200": {
            "description": "This specification",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenApiDocument"
                }
              }
            }
          }
        }
      }
    },
    "/openapi.yaml": {
      "get": {
        "operationId": "getOpenApiSpecYaml",
        "tags": [
          "Discovery"
        ],
        "summary": "This specification, as YAML",
        "description": "The same document, served as `application/yaml`. The bytes are the JSON form: YAML 1.2 is a superset of JSON, so this parses with any YAML reader and cannot drift from /openapi.json.",
        "responses": {
          "200": {
            "description": "The specification.",
            "content": {
              "application/yaml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/api-catalog": {
      "get": {
        "operationId": "getApiCatalog",
        "tags": [
          "Discovery"
        ],
        "summary": "API catalog, RFC 9727",
        "description": "A linkset naming the service descriptions and agent surfaces published for this domain and for the payments API.",
        "responses": {
          "200": {
            "description": "API catalog, RFC 9727",
            "content": {
              "application/linkset+json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiCatalog"
                }
              }
            }
          }
        }
      }
    },
    "/api/index.json": {
      "get": {
        "operationId": "getApiIndex",
        "tags": [
          "Discovery"
        ],
        "summary": "Every endpoint on this domain, grouped",
        "description": "The same endpoints as this specification, flattened to a list an agent can read without an OpenAPI parser.",
        "responses": {
          "200": {
            "description": "Every endpoint on this domain, grouped",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiIndex"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/agent-skills/index.json": {
      "get": {
        "operationId": "getAgentSkillsIndex",
        "tags": [
          "Skills"
        ],
        "summary": "Agent skills index, agentskills.io v0.2.0",
        "description": "The skills pack in the format `npx skills` and compatible clients read, with a SHA-256 per skill so a cautious agent can detect a tampered response.",
        "responses": {
          "200": {
            "description": "Agent skills index, agentskills.io v0.2.0",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentSkillsIndex"
                }
              }
            }
          }
        }
      }
    },
    "/skills.json": {
      "get": {
        "operationId": "getSkillsPack",
        "tags": [
          "Skills"
        ],
        "summary": "The skills pack, with the guides each skill bundles",
        "description": "Pack-level listing: the install command, the index URL, and for each skill its description, hash, and the guide slugs it carries.",
        "responses": {
          "200": {
            "description": "The skills pack, with the guides each skill bundles",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SkillsPack"
                }
              }
            }
          }
        }
      }
    },
    "/api/skills.json": {
      "get": {
        "operationId": "listSkills",
        "tags": [
          "Skills"
        ],
        "summary": "List the skills",
        "description": "Every skill with its description, guide slugs, hash, and the URLs for its markdown and its JSON representation.",
        "responses": {
          "200": {
            "description": "List the skills",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SkillList"
                }
              }
            }
          }
        }
      }
    },
    "/api/skills/{skill}.json": {
      "get": {
        "operationId": "getSkill",
        "tags": [
          "Skills"
        ],
        "summary": "Read one skill",
        "description": "The complete SKILL.md for one skill, as JSON, alongside its description and the guides it bundles. This is the procedure: what to do in what order, what goes wrong, and what \"done\" looks like.",
        "parameters": [
          {
            "name": "skill",
            "in": "path",
            "required": true,
            "description": "Skill name. The router, `surfboard-payments`, is the one to read first.",
            "schema": {
              "type": "string",
              "enum": [
                "surfboard-auth",
                "surfboard-go-live",
                "surfboard-in-store",
                "surfboard-onboarding",
                "surfboard-online-checkout",
                "surfboard-payments",
                "surfboard-server-to-server",
                "surfboard-terminals",
                "surfboard-testing",
                "surfboard-webhooks"
              ]
            },
            "example": "surfboard-auth"
          }
        ],
        "responses": {
          "200": {
            "description": "The skill.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Skill"
                }
              }
            }
          },
          "404": {
            "description": "No skill by that name.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/skills/{skill}/SKILL.md": {
      "get": {
        "operationId": "getSkillMarkdown",
        "tags": [
          "Skills"
        ],
        "summary": "Read one skill, as markdown",
        "description": "The same file as `getSkill`, served as `text/markdown` with its frontmatter intact, which is the form `npx skills add` and MCP clients expect.",
        "parameters": [
          {
            "name": "skill",
            "in": "path",
            "required": true,
            "description": "Skill name. The router, `surfboard-payments`, is the one to read first.",
            "schema": {
              "type": "string",
              "enum": [
                "surfboard-auth",
                "surfboard-go-live",
                "surfboard-in-store",
                "surfboard-onboarding",
                "surfboard-online-checkout",
                "surfboard-payments",
                "surfboard-server-to-server",
                "surfboard-terminals",
                "surfboard-testing",
                "surfboard-webhooks"
              ]
            },
            "example": "surfboard-auth"
          }
        ],
        "responses": {
          "200": {
            "description": "The skill.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "No skill by that name. The body is the markdown 404, listing where to look instead.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/guides.json": {
      "get": {
        "operationId": "listGuides",
        "tags": [
          "Skills"
        ],
        "summary": "List the bundled developer guides",
        "description": "The 41 guides bundled with the skills pack, each with its title, one-line summary, category, tags, the skills that carry it, and the canonical URL of the guide upstream.",
        "responses": {
          "200": {
            "description": "List the bundled developer guides",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GuideList"
                }
              }
            }
          }
        }
      }
    },
    "/api/guides/{guide}.json": {
      "get": {
        "operationId": "getGuide",
        "tags": [
          "Skills"
        ],
        "summary": "Read one guide",
        "description": "The full markdown of one developer guide, as JSON. Guides are generated from the same corpus that powers the developer site, so they cannot drift from the documentation.",
        "parameters": [
          {
            "name": "guide",
            "in": "path",
            "required": true,
            "description": "Guide slug, without the extension.",
            "schema": {
              "type": "string",
              "enum": [
                "account-management",
                "android-softpos-sdk",
                "api-conventions",
                "b2b-invoices",
                "cancel-a-payment",
                "capture-a-payment",
                "checkoutx-softpos",
                "client-auth-tokens",
                "create-an-order",
                "create-order-error-codes",
                "customer-identification",
                "device-registration",
                "emv-terminal-integration",
                "interapp-integration",
                "merchant-onboarding",
                "multi-merchant-terminals",
                "nfc-tag-reading",
                "notification-subscriptions",
                "online-payment-link",
                "partial-payments",
                "partial-refund",
                "partner-branding",
                "payment-lifecycle",
                "payment-methods",
                "payment-page",
                "pos-templates",
                "receipts",
                "recurring-payments",
                "refund-an-order",
                "self-hosted-checkout",
                "server-to-server-api",
                "settlements-reporting",
                "store-management",
                "tap-to-pay-iphone",
                "terminal-device-management",
                "terminal-logistics",
                "tips-configuration",
                "tokens",
                "transactions-and-reports",
                "void-a-payment",
                "webhooks-notifications"
              ]
            },
            "example": "account-management"
          }
        ],
        "responses": {
          "200": {
            "description": "The guide.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Guide"
                }
              }
            }
          },
          "404": {
            "description": "No guide with that slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/guides/{guide}.md": {
      "get": {
        "operationId": "getGuideMarkdown",
        "tags": [
          "Skills"
        ],
        "summary": "Read one guide, as markdown",
        "description": "The same guide as `getGuide`, served as `text/markdown`.",
        "parameters": [
          {
            "name": "guide",
            "in": "path",
            "required": true,
            "description": "Guide slug, without the extension.",
            "schema": {
              "type": "string",
              "enum": [
                "account-management",
                "android-softpos-sdk",
                "api-conventions",
                "b2b-invoices",
                "cancel-a-payment",
                "capture-a-payment",
                "checkoutx-softpos",
                "client-auth-tokens",
                "create-an-order",
                "create-order-error-codes",
                "customer-identification",
                "device-registration",
                "emv-terminal-integration",
                "interapp-integration",
                "merchant-onboarding",
                "multi-merchant-terminals",
                "nfc-tag-reading",
                "notification-subscriptions",
                "online-payment-link",
                "partial-payments",
                "partial-refund",
                "partner-branding",
                "payment-lifecycle",
                "payment-methods",
                "payment-page",
                "pos-templates",
                "receipts",
                "recurring-payments",
                "refund-an-order",
                "self-hosted-checkout",
                "server-to-server-api",
                "settlements-reporting",
                "store-management",
                "tap-to-pay-iphone",
                "terminal-device-management",
                "terminal-logistics",
                "tips-configuration",
                "tokens",
                "transactions-and-reports",
                "void-a-payment",
                "webhooks-notifications"
              ]
            },
            "example": "account-management"
          }
        ],
        "responses": {
          "200": {
            "description": "The guide.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "No guide with that slug. The body is the markdown 404, listing where to look instead.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/search": {
      "get": {
        "operationId": "searchDocs",
        "tags": [
          "Search"
        ],
        "summary": "Search the skills and the bundled guides",
        "description": "Keyword search across the skills pack and the guides it bundles. Every term is scored, and a result matching all of them ranks far above one matching a single term. For a specific API endpoint or webhook event, search the documentation corpus instead: https://www.surfboardpayments.com/.well-known/mcp.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Keywords, e.g. \"webhook retry\" or \"tap to pay iphone\".",
            "schema": {
              "type": "string",
              "minLength": 2
            },
            "example": "refund a payment"
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Restrict results to skills or to guides.",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "skill",
                "guide"
              ],
              "default": "all"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum results. Clamped to this range rather than rejected.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 25,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked results, best first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResults"
                }
              }
            }
          },
          "400": {
            "description": "`q` is missing or shorter than two characters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/payload.json": {
      "get": {
        "operationId": "getBrief",
        "tags": [
          "Agents"
        ],
        "summary": "The integration brief, as JSON",
        "description": "The brief and the when-to-use guidance as structured fields rather than one markdown blob, for a caller that wants to render or diff the parts separately.",
        "responses": {
          "200": {
            "description": "The integration brief, as JSON",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Brief"
                }
              }
            }
          }
        }
      }
    },
    "/api/health.json": {
      "get": {
        "operationId": "getHealth",
        "tags": [
          "Operations"
        ],
        "summary": "Liveness, and what is deployed",
        "description": "Confirms the site is answering and reports the payload version, the spec version, and how many skills and guides are being served. Uncached.",
        "responses": {
          "200": {
            "description": "Liveness, and what is deployed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/mcp": {
      "get": {
        "operationId": "getMcpServerCard",
        "tags": [
          "Agents"
        ],
        "summary": "MCP server card",
        "description": "How to connect to the MCP server on this domain: transports, tools, and the protocol version. A GET describes the endpoint; a POST speaks to it.",
        "responses": {
          "200": {
            "description": "The server card.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpServerCard"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "callMcpEndpoint",
        "tags": [
          "Agents"
        ],
        "summary": "MCP endpoint, Streamable HTTP",
        "description": "Post a single JSON-RPC 2.0 message. The server is stateless: it issues no\n`Mcp-Session-Id`, so no session header is needed on later requests, and it\nanswers with one `application/json` body rather than an SSE stream.\n\nTools: `get_integration_brief`, `list_skills`, `get_skill`, `search_docs`, `get_guide`.\n\nA notification (a message with no `id`) is acknowledged with 202 and no body.",
        "parameters": [
          {
            "name": "MCP-Protocol-Version",
            "in": "header",
            "required": false,
            "description": "Negotiated during initialize. Defaults to 2025-06-18.",
            "schema": {
              "type": "string",
              "example": "2025-06-18"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              },
              "example": {
                "jsonrpc": "2.0",
                "id": 1,
                "method": "tools/call",
                "params": {
                  "name": "search_docs",
                  "arguments": {
                    "query": "refund a payment"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The JSON-RPC response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              }
            }
          },
          "202": {
            "description": "A notification was accepted. No body."
          },
          "400": {
            "description": "The body was not a JSON-RPC message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Content-Type was not application/json.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/mcp/server-card.json": {
      "get": {
        "operationId": "getMcpServerCardFile",
        "tags": [
          "Agents"
        ],
        "summary": "MCP server card, at the file path",
        "description": "Identical to `GET /.well-known/mcp`. Both paths are published because the discovery proposals disagree about which one to probe.",
        "responses": {
          "200": {
            "description": "MCP server card, at the file path",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpServerCard"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "description": "Returned by every failure on this domain, including a 404 on a path that does not exist. Branch on `error.code`; `error.hint` says what to do next.",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "not_found",
                  "invalid_request",
                  "method_not_allowed",
                  "unsupported_media_type",
                  "internal_error"
                ],
                "description": "A closed set. Safe to branch on."
              },
              "message": {
                "type": "string",
                "description": "What went wrong, in one sentence."
              },
              "hint": {
                "type": "string",
                "description": "What to do instead."
              },
              "documentation": {
                "type": "string",
                "format": "uri"
              },
              "index": {
                "type": "string",
                "format": "uri",
                "description": "Every endpoint on this domain."
              },
              "instructions": {
                "type": "string",
                "format": "uri"
              }
            },
            "required": [
              "code",
              "message",
              "hint",
              "documentation"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "Skill": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "enum": [
              "surfboard-auth",
              "surfboard-go-live",
              "surfboard-in-store",
              "surfboard-onboarding",
              "surfboard-online-checkout",
              "surfboard-payments",
              "surfboard-server-to-server",
              "surfboard-terminals",
              "surfboard-testing",
              "surfboard-webhooks"
            ]
          },
          "description": {
            "type": "string"
          },
          "markdown": {
            "type": "string",
            "description": "The complete SKILL.md, frontmatter included."
          },
          "guides": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "account-management",
                "android-softpos-sdk",
                "api-conventions",
                "b2b-invoices",
                "cancel-a-payment",
                "capture-a-payment",
                "checkoutx-softpos",
                "client-auth-tokens",
                "create-an-order",
                "create-order-error-codes",
                "customer-identification",
                "device-registration",
                "emv-terminal-integration",
                "interapp-integration",
                "merchant-onboarding",
                "multi-merchant-terminals",
                "nfc-tag-reading",
                "notification-subscriptions",
                "online-payment-link",
                "partial-payments",
                "partial-refund",
                "partner-branding",
                "payment-lifecycle",
                "payment-methods",
                "payment-page",
                "pos-templates",
                "receipts",
                "recurring-payments",
                "refund-an-order",
                "self-hosted-checkout",
                "server-to-server-api",
                "settlements-reporting",
                "store-management",
                "tap-to-pay-iphone",
                "terminal-device-management",
                "terminal-logistics",
                "tips-configuration",
                "tokens",
                "transactions-and-reports",
                "void-a-payment",
                "webhooks-notifications"
              ]
            },
            "description": "Slugs of the guides this skill bundles."
          },
          "sha256": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "markdownUrl": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "name",
          "description",
          "markdown",
          "guides",
          "sha256",
          "url"
        ]
      },
      "SkillSummary": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "enum": [
              "surfboard-auth",
              "surfboard-go-live",
              "surfboard-in-store",
              "surfboard-onboarding",
              "surfboard-online-checkout",
              "surfboard-payments",
              "surfboard-server-to-server",
              "surfboard-terminals",
              "surfboard-testing",
              "surfboard-webhooks"
            ]
          },
          "description": {
            "type": "string"
          },
          "guides": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "account-management",
                "android-softpos-sdk",
                "api-conventions",
                "b2b-invoices",
                "cancel-a-payment",
                "capture-a-payment",
                "checkoutx-softpos",
                "client-auth-tokens",
                "create-an-order",
                "create-order-error-codes",
                "customer-identification",
                "device-registration",
                "emv-terminal-integration",
                "interapp-integration",
                "merchant-onboarding",
                "multi-merchant-terminals",
                "nfc-tag-reading",
                "notification-subscriptions",
                "online-payment-link",
                "partial-payments",
                "partial-refund",
                "partner-branding",
                "payment-lifecycle",
                "payment-methods",
                "payment-page",
                "pos-templates",
                "receipts",
                "recurring-payments",
                "refund-an-order",
                "self-hosted-checkout",
                "server-to-server-api",
                "settlements-reporting",
                "store-management",
                "tap-to-pay-iphone",
                "terminal-device-management",
                "terminal-logistics",
                "tips-configuration",
                "tokens",
                "transactions-and-reports",
                "void-a-payment",
                "webhooks-notifications"
              ]
            }
          },
          "sha256": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "markdownUrl": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "name",
          "description",
          "guides",
          "sha256",
          "url"
        ]
      },
      "SkillList": {
        "type": "object",
        "properties": {
          "count": {
            "type": "integer"
          },
          "install": {
            "type": "string",
            "description": "The command that installs the whole pack."
          },
          "index": {
            "type": "string",
            "format": "uri"
          },
          "skills": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SkillSummary"
            }
          }
        },
        "required": [
          "count",
          "skills"
        ]
      },
      "SkillsPack": {
        "type": "object",
        "properties": {
          "pack": {
            "type": "string"
          },
          "install": {
            "type": "string"
          },
          "index": {
            "type": "string",
            "format": "uri"
          },
          "guidesSource": {
            "type": "string",
            "format": "uri"
          },
          "skills": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        },
        "required": [
          "pack",
          "install",
          "skills"
        ]
      },
      "Guide": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string",
            "enum": [
              "account-management",
              "android-softpos-sdk",
              "api-conventions",
              "b2b-invoices",
              "cancel-a-payment",
              "capture-a-payment",
              "checkoutx-softpos",
              "client-auth-tokens",
              "create-an-order",
              "create-order-error-codes",
              "customer-identification",
              "device-registration",
              "emv-terminal-integration",
              "interapp-integration",
              "merchant-onboarding",
              "multi-merchant-terminals",
              "nfc-tag-reading",
              "notification-subscriptions",
              "online-payment-link",
              "partial-payments",
              "partial-refund",
              "partner-branding",
              "payment-lifecycle",
              "payment-methods",
              "payment-page",
              "pos-templates",
              "receipts",
              "recurring-payments",
              "refund-an-order",
              "self-hosted-checkout",
              "server-to-server-api",
              "settlements-reporting",
              "store-management",
              "tap-to-pay-iphone",
              "terminal-device-management",
              "terminal-logistics",
              "tips-configuration",
              "tokens",
              "transactions-and-reports",
              "void-a-payment",
              "webhooks-notifications"
            ]
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "category": {
            "type": "string",
            "description": "in-store or online, as classified upstream."
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "markdown": {
            "type": "string"
          },
          "source": {
            "type": "string",
            "format": "uri",
            "description": "The guide upstream."
          },
          "skills": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "surfboard-auth",
                "surfboard-go-live",
                "surfboard-in-store",
                "surfboard-onboarding",
                "surfboard-online-checkout",
                "surfboard-payments",
                "surfboard-server-to-server",
                "surfboard-terminals",
                "surfboard-testing",
                "surfboard-webhooks"
              ]
            }
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "markdownUrl": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "slug",
          "title",
          "markdown",
          "url"
        ]
      },
      "GuideSummary": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string",
            "enum": [
              "account-management",
              "android-softpos-sdk",
              "api-conventions",
              "b2b-invoices",
              "cancel-a-payment",
              "capture-a-payment",
              "checkoutx-softpos",
              "client-auth-tokens",
              "create-an-order",
              "create-order-error-codes",
              "customer-identification",
              "device-registration",
              "emv-terminal-integration",
              "interapp-integration",
              "merchant-onboarding",
              "multi-merchant-terminals",
              "nfc-tag-reading",
              "notification-subscriptions",
              "online-payment-link",
              "partial-payments",
              "partial-refund",
              "partner-branding",
              "payment-lifecycle",
              "payment-methods",
              "payment-page",
              "pos-templates",
              "receipts",
              "recurring-payments",
              "refund-an-order",
              "self-hosted-checkout",
              "server-to-server-api",
              "settlements-reporting",
              "store-management",
              "tap-to-pay-iphone",
              "terminal-device-management",
              "terminal-logistics",
              "tips-configuration",
              "tokens",
              "transactions-and-reports",
              "void-a-payment",
              "webhooks-notifications"
            ]
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "source": {
            "type": "string",
            "format": "uri"
          },
          "skills": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "surfboard-auth",
                "surfboard-go-live",
                "surfboard-in-store",
                "surfboard-onboarding",
                "surfboard-online-checkout",
                "surfboard-payments",
                "surfboard-server-to-server",
                "surfboard-terminals",
                "surfboard-testing",
                "surfboard-webhooks"
              ]
            }
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "markdownUrl": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "slug",
          "title",
          "url"
        ]
      },
      "GuideList": {
        "type": "object",
        "properties": {
          "count": {
            "type": "integer"
          },
          "source": {
            "type": "string",
            "format": "uri",
            "description": "The corpus these are generated from."
          },
          "guides": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GuideSummary"
            }
          }
        },
        "required": [
          "count",
          "guides"
        ]
      },
      "SearchResult": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "skill",
              "guide"
            ]
          },
          "id": {
            "type": "string",
            "description": "Skill name or guide slug."
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "score": {
            "type": "number",
            "description": "Relative. Comparable within one response only."
          }
        },
        "required": [
          "type",
          "id",
          "title",
          "url",
          "score"
        ]
      },
      "SearchResults": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "all",
              "skill",
              "guide"
            ]
          },
          "count": {
            "type": "integer"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchResult"
            }
          }
        },
        "required": [
          "query",
          "count",
          "results"
        ]
      },
      "Brief": {
        "type": "object",
        "properties": {
          "version": {
            "type": "string"
          },
          "whenToUse": {
            "type": "string",
            "description": "Routing guidance, as markdown."
          },
          "instructions": {
            "type": "string",
            "description": "The six-step brief, as markdown."
          },
          "llmsTxt": {
            "type": "string",
            "format": "uri"
          },
          "resources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "what": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                }
              },
              "required": [
                "what",
                "url"
              ]
            }
          }
        },
        "required": [
          "version",
          "whenToUse",
          "instructions"
        ]
      },
      "Health": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok"
            ]
          },
          "payloadVersion": {
            "type": "string"
          },
          "specVersion": {
            "type": "string"
          },
          "mcpVersion": {
            "type": "string"
          },
          "skills": {
            "type": "integer"
          },
          "guides": {
            "type": "integer"
          }
        },
        "required": [
          "status",
          "payloadVersion",
          "skills",
          "guides"
        ]
      },
      "AgentSkillsIndex": {
        "type": "object",
        "properties": {
          "$schema": {
            "type": "string",
            "format": "uri"
          },
          "version": {
            "type": "string"
          },
          "skills": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "sha256": {
                  "type": "string",
                  "pattern": "^[0-9a-f]{64}$"
                }
              },
              "required": [
                "name",
                "description",
                "url",
                "sha256"
              ]
            }
          }
        },
        "required": [
          "version",
          "skills"
        ]
      },
      "McpServerCard": {
        "type": "object",
        "properties": {
          "$schema": {
            "type": "string",
            "format": "uri"
          },
          "serverInfo": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "version": {
                "type": "string"
              },
              "description": {
                "type": "string"
              }
            },
            "required": [
              "name",
              "version"
            ]
          },
          "endpoint": {
            "type": "string",
            "format": "uri"
          },
          "transports": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "capabilities": {
            "type": "object"
          },
          "documentation": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "serverInfo",
          "endpoint",
          "transports"
        ]
      },
      "JsonRpcRequest": {
        "type": "object",
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0"
          },
          "id": {
            "description": "Omit for a notification, which is answered with 202 and no body.",
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              }
            ]
          },
          "method": {
            "type": "string",
            "enum": [
              "initialize",
              "ping",
              "tools/list",
              "tools/call"
            ]
          },
          "params": {
            "type": "object"
          }
        },
        "required": [
          "jsonrpc",
          "method"
        ]
      },
      "JsonRpcResponse": {
        "type": "object",
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0"
          },
          "id": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "result": {
            "type": "object"
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "integer",
                "description": "JSON-RPC 2.0 reserved codes."
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        },
        "required": [
          "jsonrpc",
          "id"
        ]
      },
      "ApiCatalog": {
        "type": "object",
        "description": "RFC 9727 linkset.",
        "properties": {
          "linkset": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        },
        "required": [
          "linkset"
        ]
      },
      "ApiIndex": {
        "type": "object",
        "properties": {
          "site": {
            "type": "string",
            "format": "uri"
          },
          "openapi": {
            "type": "string",
            "format": "uri"
          },
          "count": {
            "type": "integer"
          },
          "groups": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "endpoints": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "operationId": {
                        "type": "string"
                      },
                      "method": {
                        "type": "string"
                      },
                      "path": {
                        "type": "string"
                      },
                      "summary": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "operationId",
                      "method",
                      "path"
                    ]
                  }
                }
              },
              "required": [
                "name",
                "endpoints"
              ]
            }
          }
        },
        "required": [
          "site",
          "count",
          "groups"
        ]
      },
      "OpenApiDocument": {
        "type": "object",
        "description": "An OpenAPI 3.1 document.",
        "properties": {
          "openapi": {
            "type": "string"
          },
          "info": {
            "type": "object"
          },
          "paths": {
            "type": "object"
          }
        },
        "required": [
          "openapi",
          "info",
          "paths"
        ]
      }
    },
    "responses": {
      "NotFound": {
        "description": "Nothing at that path.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}