openapi: 3.1.0
info:
  title: Surfboard Payments, public site API
  version: 1.0.0
  summary: "Everything www.surfboardpayments.com serves to machines: content, brand assets, discovery documents and an MCP endpoint."
  description: |-
    This is the public, unauthenticated surface of www.surfboardpayments.com. No key, no signup, no rate limit on the GET endpoints. CORS is open, so a browser agent can call it directly.

    It is not the payments API. Taking a payment means the Carbon API, which is credentialed per account and described separately at /openapi/carbon.json. If you are here to build an integration, start with /agent-instructions.md.

    Two rules worth knowing before you call anything:

    - Paths are case-sensitive and JSON endpoints keep their `.json` suffix.
    - Every failure, including a 404 on a path that does not exist, returns the Error schema with a `code` you can branch on.
  termsOfService: https://www.surfboardpayments.com/terms-and-conditions
  contact:
    name: Surfboard Payments
    url: https://www.surfboardpayments.com/contact
  license:
    name: Terms of use
    url: https://www.surfboardpayments.com/terms-and-conditions
servers:
  - url: https://www.surfboardpayments.com
    description: Production. The apex domain 301s here, path preserved.
security: []
externalDocs:
  description: Developer portal and API reference
  url: https://developers.surfboardpayments.com/
tags:
  - name: Discovery
    description: "Start here: what exists on this domain and where."
  - name: Content
    description: "The site as data: company, products, capabilities, solutions, methods, articles."
  - name: Developer
    description: The API reference, the integration guides, and search over both.
  - name: Brand
    description: Brand guidelines and the asset kits cleared for outside use.
  - name: Agents
    description: Instructions, skills and the MCP endpoint.
paths:
  /api/ai/site-overview.json:
    get:
      operationId: getSiteOverview
      summary: Site overview, sitemap and company facts
      description: "The single best first call. Returns the company record, every public page grouped by section, the supported payment methods, and the URL of every other machine-readable resource on this domain. Call this before crawling: it replaces walking the sitemap."
      tags:
        - Content
      responses:
        "200":
          description: The site overview.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SiteOverview"
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/ai/company.json:
    get:
      operationId: getCompany
      summary: Company record
      description: Legal entity, founding year, offices with addresses, leadership and board, licensing authority and licence type, certifications, infrastructure, partnerships and contact routes. Use this to answer "who are Surfboard Payments" without scraping the about page.
      tags:
        - Content
      responses:
        "200":
          description: The company record.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Company"
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/ai/products.json:
    get:
      operationId: listProducts
      summary: Product catalogue
      description: "Every product, grouped by category: payment terminals, Tap to Pay on iPhone and Android, online checkout, and accessories. Each product carries its features, hardware specs and market availability. Use this to answer which device or product fits a described situation."
      tags:
        - Content
      responses:
        "200":
          description: The product catalogue.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductCatalogue"
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/ai/platform.json:
    get:
      operationId: listPlatformCapabilities
      summary: Platform capabilities
      description: Every capability the platform exposes, from tokenization and offline payments to tipping, receipts and webhooks, each with the page that documents it. Use this to check whether something is supported before promising it.
      tags:
        - Content
      responses:
        "200":
          description: The capability list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatformCapabilities"
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/ai/solutions.json:
    get:
      operationId: listSolutions
      summary: Solutions by industry and by audience
      description: The industry solutions (retail, hospitality, healthcare, and the rest) and the audience solutions (ISVs, POS providers, marketplaces). Use this to map a described business onto the closest documented fit.
      tags:
        - Content
      responses:
        "200":
          description: The solution list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Solutions"
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/ai/payment-methods.json:
    get:
      operationId: listPaymentMethods
      summary: Supported payment methods
      description: Every supported payment method with the countries and channels it covers, when to use it, and the three paths to switching it on (Partner Portal, Merchant Portal, Payment Methods API). Use this to answer "can I take X in country Y".
      tags:
        - Content
      responses:
        "200":
          description: The payment method list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentMethods"
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/ai/docs.json:
    get:
      operationId: getApiReference
      summary: Carbon API reference, every endpoint
      description: "The full API reference as data: every documented endpoint with its method, path, description and complete reference page in markdown. For a typed contract instead of prose, read the OpenAPI document at /openapi/carbon.json."
      tags:
        - Developer
      responses:
        "200":
          description: The API reference.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiReference"
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/ai/guides.json:
    get:
      operationId: listDeveloperGuides
      summary: Integration guides
      description: "Every integration guide with its full markdown body: creating orders, taking payments, refunds, webhooks, SDKs, onboarding, terminal management. This is the corpus to ground an integration on. Large: fetch one guide instead when you know which you need."
      tags:
        - Developer
      responses:
        "200":
          description: Every guide, with bodies.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeveloperGuides"
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/ai/guides/{slug}.md:
    get:
      operationId: getDeveloperGuideMarkdown
      summary: One integration guide as markdown
      description: The markdown source of a single guide, which is the cheap way to read one without pulling the whole collection. Slugs come from listDeveloperGuides. The same bytes are served at /developers/guides/{slug}.md.
      tags:
        - Developer
      parameters:
        - name: slug
          in: path
          required: true
          description: Guide slug, from listDeveloperGuides.
          schema:
            type: string
            pattern: ^[a-z0-9][a-z0-9-]*$
          example: create-an-order
      responses:
        "200":
          description: The guide as markdown.
          content:
            text/markdown:
              schema:
                type: string
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/ai/changelog.json:
    get:
      operationId: getChangelog
      summary: Product changelog
      description: Release notes for every product, newest first, with version, build and full body. Use this to check whether a feature has shipped and in which version.
      tags:
        - Developer
      responses:
        "200":
          description: The changelog.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Changelog"
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/ai/knowledge-hub.json:
    get:
      operationId: listKnowledgeHubArticles
      summary: Knowledge hub articles
      description: "Every published article with its full body: payments explainers, market and regulation pieces, product launches and company news. Use this for background and for citable company statements."
      tags:
        - Content
      responses:
        "200":
          description: Every article, with bodies.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KnowledgeHub"
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/ai/partner-portal.json:
    get:
      operationId: listPartnerPortalGuides
      summary: Partner Portal guides
      description: "How-to guides for the Partner Portal: onboarding merchants, applications, billing plans, branding, terminals, shipments, reporting. Use this for questions about operating a partner account rather than about the API."
      tags:
        - Content
      responses:
        "200":
          description: Every Partner Portal guide, with bodies.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PartnerPortalGuides"
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/ai/merchant-portal.json:
    get:
      operationId: listMerchantPortalGuides
      summary: Merchant Portal guides
      description: "How-to guides for the Merchant Portal: dashboard, sales and reports, payment links, gift cards, products, stores, terminals, user levels. Use this for questions a merchant would ask."
      tags:
        - Content
      responses:
        "200":
          description: Every Merchant Portal guide, with bodies.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MerchantPortalGuides"
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/ai/brand.json:
    get:
      operationId: getBrandGuidelines
      summary: Brand guidelines
      description: "Logo files and placement rules, the colour palette with its approved contrast pairings, typography, product naming, tone of voice, imagery rules and press boilerplate. Read this before generating anything that represents Surfboard Payments: a deck, a landing page, a badge, a press line."
      tags:
        - Brand
      responses:
        "200":
          description: The brand guidelines.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BrandGuidelines"
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /brand.md:
    get:
      operationId: getBrandGuidelinesMarkdown
      summary: Brand guidelines as markdown
      description: The same guidelines as getBrandGuidelines, as one markdown document, for pasting into a prompt.
      tags:
        - Brand
      responses:
        "200":
          description: The brand guidelines as markdown.
          content:
            text/markdown:
              schema:
                type: string
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/kit/index.json:
    get:
      operationId: listDownloadKits
      summary: Download kits
      description: Logo and product image kits cleared for partner and press use, with the URL templates for each kit manifest, zip and file.
      tags:
        - Brand
      responses:
        "200":
          description: Every kit.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KitIndex"
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/kit/{slug}.json:
    get:
      operationId: getDownloadKit
      summary: One kit manifest
      description: "Every file in one kit, each with a caption saying what it is and when to use it. Slugs come from listDownloadKits: a product slug, or \"brand\" for the logo kit."
      tags:
        - Brand
      parameters:
        - name: slug
          in: path
          required: true
          description: Kit slug, from listDownloadKits.
          schema:
            type: string
            pattern: ^[a-z0-9][a-z0-9-]*$
          example: brand
      responses:
        "200":
          description: The kit manifest.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KitManifest"
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/kit/{slug}.zip:
    get:
      operationId: downloadKitArchive
      summary: One kit as a zip
      description: The whole kit as a zip, including a README carrying the usage terms.
      tags:
        - Brand
      parameters:
        - name: slug
          in: path
          required: true
          description: Kit slug, from listDownloadKits.
          schema:
            type: string
            pattern: ^[a-z0-9][a-z0-9-]*$
          example: brand
      responses:
        "200":
          description: The zip archive.
          content:
            application/zip:
              schema:
                type: string
                format: binary
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/kit/{slug}/{filename}:
    get:
      operationId: downloadKitFile
      summary: One file from a kit
      description: A single asset, served as an attachment. Filenames come from getDownloadKit.
      tags:
        - Brand
      parameters:
        - name: slug
          in: path
          required: true
          description: Kit slug, from listDownloadKits.
          schema:
            type: string
            pattern: ^[a-z0-9][a-z0-9-]*$
          example: brand
        - name: filename
          in: path
          required: true
          description: File name exactly as listed in the kit manifest, extension included.
          schema:
            type: string
            pattern: ^[A-Za-z0-9._-]+$
          example: surfboard-payments-primary.svg
      responses:
        "200":
          description: The file.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/index.json:
    get:
      operationId: getApiIndex
      summary: Index of every endpoint on this domain
      description: A flat listing of the endpoints in this spec, grouped by purpose. Human-first; prefer this spec for tooling.
      tags:
        - Discovery
      responses:
        "200":
          description: The endpoint index.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiIndex"
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /llms.txt:
    get:
      operationId: getLlmsTxt
      summary: Site map for language models
      description: "The llms.txt document: the whole site as one markdown file, with a link and a one-line description for every page, plus when to use Surfboard Payments and how an agent should call it. Start here if you would otherwise crawl."
      tags:
        - Discovery
      responses:
        "200":
          description: The llms.txt document.
          content:
            text/plain:
              schema:
                type: string
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /llms-full.txt:
    get:
      operationId: getLlmsFullTxt
      summary: Full content dump for language models
      description: Every page, guide and article as one markdown file. Large. Use getLlmsTxt first and fetch what you need.
      tags:
        - Discovery
      responses:
        "200":
          description: The full content dump.
          content:
            text/plain:
              schema:
                type: string
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /agent-instructions.md:
    get:
      operationId: getAgentInstructions
      summary: When to use Surfboard Payments, and how to call it
      description: "The agent instruction file: the jobs Surfboard Payments is the right answer for, the ones it is not, the order to do an integration in, the safety rules that apply to payments work, and which endpoint or tool to reach for at each step."
      tags:
        - Agents
      responses:
        "200":
          description: The agent instructions as markdown.
          content:
            text/markdown:
              schema:
                type: string
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /openapi.json:
    get:
      operationId: getOpenApiSpec
      summary: This document
      description: The OpenAPI 3.1 description of this domain. Served as YAML at /openapi.yaml.
      tags:
        - Discovery
      responses:
        "200":
          description: This OpenAPI document.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpenApiDocument"
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /openapi/carbon.json:
    get:
      operationId: getCarbonOpenApiSpec
      summary: OpenAPI spec for the Carbon payments API
      description: The OpenAPI 3.1 description of the Carbon API, the credentialed payments API behind terminals, orders, payments, merchants and webhooks. Generated from the published reference. Served as YAML at /openapi/carbon.yaml.
      tags:
        - Discovery
      responses:
        "200":
          description: The Carbon API OpenAPI document.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpenApiDocument"
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /.well-known/api-catalog:
    get:
      operationId: getApiCatalog
      summary: RFC 9727 API catalog
      description: A linkset naming the service documentation and every machine-readable resource on this domain.
      tags:
        - Discovery
      responses:
        "200":
          description: The linkset.
          content:
            application/linkset+json:
              schema:
                $ref: "#/components/schemas/ApiCatalog"
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /.well-known/agent-skills/index.json:
    get:
      operationId: getAgentSkillsIndex
      summary: Agent Skills index
      description: The skills published for this site, each a markdown file with a SHA-256 so it can be verified after download. Install them, or fetch and read them directly.
      tags:
        - Agents
      responses:
        "200":
          description: The skills index.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentSkillsIndex"
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /.well-known/agent-skills/{skill}/SKILL.md:
    get:
      operationId: getAgentSkill
      summary: One agent skill
      description: The markdown body of one skill. Names come from getAgentSkillsIndex.
      tags:
        - Agents
      parameters:
        - name: skill
          in: path
          required: true
          description: Skill name, from getAgentSkillsIndex.
          schema:
            type: string
            pattern: ^[a-z0-9][a-z0-9-]*$
          example: surfboard-overview
      responses:
        "200":
          description: The skill as markdown.
          content:
            text/markdown:
              schema:
                type: string
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /.well-known/mcp/server-card.json:
    get:
      operationId: getMcpServerCard
      summary: MCP server card
      description: "How to reach the documentation MCP server: the hosted Streamable HTTP endpoint, the npm package for a stdio client, and the tools it exposes."
      tags:
        - Agents
      responses:
        "200":
          description: The server card.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/McpServerCard"
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /.well-known/mcp:
    get:
      operationId: describeMcpEndpoint
      summary: Describe the MCP endpoint
      description: "A GET on the MCP endpoint returns the same server card, so a client that has only the URL can learn what it is talking to before opening a session. A GET asking for text/event-stream returns 405: this server answers over JSON, not a server-initiated stream."
      tags:
        - Agents
      responses:
        "200":
          description: The server card.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/McpServerCard"
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "405":
          description: Sent for a GET that asks for text/event-stream. Use POST.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      operationId: callMcpEndpoint
      summary: Call the MCP server (Streamable HTTP)
      description: "The Model Context Protocol endpoint, Streamable HTTP transport. POST a JSON-RPC 2.0 message: initialize to open a session, tools/list to enumerate tools, tools/call to run one. Responses come back as a single JSON object rather than an SSE stream. Tools cover the API reference, the webhook catalog and the integration guides."
      tags:
        - Agents
      requestBody:
        required: true
        description: A JSON-RPC 2.0 request or notification.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/JsonRpcRequest"
      responses:
        "200":
          description: The JSON-RPC response. Notifications get 202 with an empty body.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonRpcResponse"
        "202":
          description: The message was a notification, so there is nothing to return.
        "400":
          description: The body was not valid JSON.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/developer-search:
    post:
      operationId: searchDeveloperDocs
      summary: Ask a question about the developer docs
      description: "Natural-language search across the integration guides and the API reference. Returns a Server-Sent Events stream of answer tokens, terminated by \"data: [DONE]\". Rate limited per IP. An agent that can run MCP should prefer callMcpEndpoint, which returns whole documents rather than a prose answer."
      tags:
        - Developer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - question
              properties:
                question:
                  type: string
                  minLength: 1
                  description: The question, in plain language.
                messages:
                  type: array
                  description: Prior turns, oldest first, for a follow-up question.
                  items:
                    type: object
                    required:
                      - role
                      - content
                    properties:
                      role:
                        type: string
                        enum:
                          - user
                          - assistant
                      content:
                        type: string
      responses:
        "200":
          description: An SSE stream of answer tokens.
          content:
            text/event-stream:
              schema:
                type: string
        "400":
          description: The body was not valid JSON, or question was missing.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: No resource at this path. The body names where to look instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Too many requests from this address. Retry-After says when to come back.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "503":
          description: Search is not configured on this deployment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  schemas:
    Error:
      type: object
      description: Every failed request on this domain returns this shape. Branch on error.code, which is stable; error.message and error.hint are written for a human or an agent to read.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - status
            - message
            - hint
          properties:
            code:
              type: string
              description: Stable machine-readable code. Does not change for a given condition.
              enum:
                - not_found
                - method_not_allowed
                - invalid_request
                - invalid_json
                - unsupported_media_type
                - rate_limited
                - upstream_error
                - internal_error
                - not_configured
            status:
              type: integer
              description: The HTTP status, repeated in the body.
            message:
              type: string
              description: What went wrong.
            hint:
              type: string
              description: What to do about it.
            documentation_url:
              type: string
              format: uri
            details:
              description: Field-level detail, present on validation failures.
    SiteOverview:
      type: object
      description: Company facts, the full sitemap, and pointers to every other machine-readable resource.
      required:
        - name
        - description
        - url
        - sitemap
        - aiEndpoints
        - lastUpdated
      properties:
        name:
          type: string
        tagline:
          type: string
        description:
          type: string
        url:
          type: string
          format: uri
        founded:
          type: integer
        headquarters:
          type: string
        industry:
          type: string
        regulation:
          type: string
          description: Licensing authority and licence type.
        certifications:
          type: array
          items:
            type: string
        infrastructure:
          type: string
        uptime:
          type: string
        setupRecord:
          type: string
        employees:
          type: string
        marketsServed:
          type: array
          items:
            type: string
          description: Countries where merchants can be boarded.
        offices:
          type: array
          items:
            type: object
            properties:
              city:
                type: string
              country:
                type: string
              address:
                type: string
        keyPeople:
          type: object
          additionalProperties:
            type: string
        pricing:
          type: object
          additionalProperties: true
        sitemap:
          type: object
          description: Every public page, grouped by section.
          additionalProperties: true
        externalLinks:
          type: object
          additionalProperties:
            type: string
        aiEndpoints:
          type: object
          description: The other JSON endpoints in this spec, keyed by name.
          additionalProperties: true
        paymentMethodActivation:
          type: object
          additionalProperties: true
        supportedPaymentMethods:
          type: array
          items:
            type: string
        lastUpdated:
          type: string
          format: date
    Company:
      type: object
      description: "Structured company record: legal entity, offices, leadership, licensing, certifications, partnerships."
      required:
        - name
        - legalName
        - founded
        - regulation
        - lastUpdated
      properties:
        name:
          type: string
        legalName:
          type: string
        founded:
          type: integer
        type:
          type: string
        industry:
          type: string
        description:
          type: string
        mission:
          type: string
        headquarters:
          type: object
          additionalProperties: true
        offices:
          type: array
          items:
            type: object
            additionalProperties: true
        employees:
          type: string
        leadership:
          type: object
          additionalProperties: true
        boardMembers:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              role:
                type: string
        regulation:
          type: object
          additionalProperties: true
        certifications:
          type: array
          items:
            type: string
        infrastructure:
          type: object
          additionalProperties: true
        financials:
          type: object
          additionalProperties: true
        partnerships:
          type: array
          items:
            type: object
            additionalProperties: true
        targetMarket:
          type: object
          additionalProperties: true
        socialResponsibility:
          type: object
          additionalProperties: true
        contact:
          type: object
          additionalProperties: true
        lastUpdated:
          type: string
          format: date
    ProductCatalogue:
      type: object
      description: Terminals, Tap to Pay products, online products and accessories, grouped by category.
      required:
        - categories
        - lastUpdated
      properties:
        lastUpdated:
          type: string
          format: date
        pricing:
          type: object
          additionalProperties: true
        categories:
          type: array
          items:
            type: object
            required:
              - name
              - products
            properties:
              name:
                type: string
              description:
                type: string
              products:
                type: array
                items:
                  type: object
                  required:
                    - name
                  properties:
                    name:
                      type: string
                    slug:
                      type: string
                    url:
                      type: string
                      format: uri-reference
                    description:
                      type: string
                    features:
                      type: array
                      items:
                        type: string
                    specs:
                      type: object
                      additionalProperties:
                        type: string
                    availability:
                      type: array
                      items:
                        type: string
    PlatformCapabilities:
      type: object
      description: Every platform capability with the page that documents it.
      required:
        - capabilities
        - totalCapabilities
      properties:
        overviewUrl:
          type: string
          format: uri-reference
        totalCapabilities:
          type: integer
          minimum: 0
        lastUpdated:
          type: string
          format: date
        capabilities:
          type: array
          items:
            type: object
            required:
              - name
              - slug
              - url
              - description
            properties:
              name:
                type: string
              slug:
                type: string
              url:
                type: string
                format: uri-reference
              description:
                type: string
    Solutions:
      type: object
      description: Solution pages, split by industry and by audience.
      required:
        - byIndustry
        - byAudience
      properties:
        overviewUrl:
          type: string
          format: uri-reference
        totalSolutions:
          type: integer
          minimum: 0
        lastUpdated:
          type: string
          format: date
        byIndustry:
          type: array
          items:
            $ref: "#/components/schemas/NamedPage"
        byAudience:
          type: array
          items:
            $ref: "#/components/schemas/NamedPage"
    NamedPage:
      type: object
      required:
        - name
        - slug
        - url
        - description
      properties:
        name:
          type: string
        slug:
          type: string
        url:
          type: string
          format: uri-reference
        description:
          type: string
    PaymentMethods:
      type: object
      description: Supported payment methods, the countries and channels each covers, and how a merchant enables it.
      required:
        - methods
        - categories
      properties:
        activation:
          type: object
          description: The three ways a method gets switched on.
          additionalProperties: true
        categories:
          type: array
          items:
            type: object
            required:
              - id
              - label
            properties:
              id:
                type: string
              label:
                type: string
              description:
                type: string
        methods:
          type: array
          items:
            type: object
            required:
              - slug
              - name
              - category
            properties:
              slug:
                type: string
              name:
                type: string
              url:
                type: string
                format: uri-reference
              category:
                type: string
                description: Matches a categories[].id.
              tagline:
                type: string
              oneLiner:
                type: string
              description:
                type: string
              countries:
                type: array
                items:
                  type: string
                description: ISO 3166-1 alpha-2, uppercase.
              channels:
                type: array
                items:
                  type: string
                  enum:
                    - in-store
                    - online
                    - unattended
              whenToUse:
                type: string
              customerBase:
                type: string
              useCases:
                type: array
                items:
                  type: string
              related:
                type: array
                items:
                  type: string
              externalUrl:
                type: string
                format: uri
        indexUrl:
          type: string
          format: uri-reference
        lastUpdated:
          type: string
          format: date
    ApiReference:
      type: object
      description: Every documented Carbon API endpoint with its full reference page as markdown.
      required:
        - totalEndpoints
        - apis
        - endpoints
      properties:
        totalEndpoints:
          type: integer
          minimum: 0
        lastUpdated:
          type: string
          format: date
        apis:
          type: array
          items:
            type: string
          description: API section names, e.g. "Payments API".
        endpoints:
          type: array
          items:
            type: object
            required:
              - title
              - slug
              - api
              - method
              - path
            properties:
              title:
                type: string
              slug:
                type: string
              description:
                type: string
              api:
                type: string
              method:
                type: string
                enum:
                  - GET
                  - POST
                  - PUT
                  - PATCH
                  - DELETE
              path:
                type: string
                description: Path relative to the account base URL, with :params.
              content:
                type: string
                description: The reference page as markdown.
    DeveloperGuides:
      type: object
      description: Integration guides, in-store and online.
      required:
        - totalGuides
        - lastUpdated
        - guides
      properties:
        totalGuides:
          type: integer
          minimum: 0
        lastUpdated:
          type: string
          format: date
          description: ISO 8601 date the collection was generated.
        categories:
          type: array
          items:
            type: string
        guides:
          type: array
          description: One guide per entry.
          items:
            type: object
            description: "One document: its metadata plus the full markdown body."
            required:
              - title
              - slug
              - url
              - content
            properties:
              title:
                type: string
              slug:
                type: string
                description: URL segment, unique within the collection.
              url:
                type: string
                format: uri-reference
                description: Path to the rendered page.
              description:
                type: string
              category:
                type: string
              tags:
                type: array
                items:
                  type: string
              content:
                type: string
                description: The full document body as markdown.
    PartnerPortalGuides:
      type: object
      description: Partner Portal how-to guides.
      required:
        - totalGuides
        - lastUpdated
        - guides
      properties:
        totalGuides:
          type: integer
          minimum: 0
        lastUpdated:
          type: string
          format: date
          description: ISO 8601 date the collection was generated.
        categories:
          type: array
          items:
            type: string
        guides:
          type: array
          description: One guide per entry.
          items:
            type: object
            description: "One document: its metadata plus the full markdown body."
            required:
              - title
              - slug
              - url
              - content
            properties:
              title:
                type: string
              slug:
                type: string
                description: URL segment, unique within the collection.
              url:
                type: string
                format: uri-reference
                description: Path to the rendered page.
              description:
                type: string
              category:
                type: string
              tags:
                type: array
                items:
                  type: string
              content:
                type: string
                description: The full document body as markdown.
    MerchantPortalGuides:
      type: object
      description: Merchant Portal how-to guides.
      required:
        - totalGuides
        - lastUpdated
        - guides
      properties:
        totalGuides:
          type: integer
          minimum: 0
        lastUpdated:
          type: string
          format: date
          description: ISO 8601 date the collection was generated.
        categories:
          type: array
          items:
            type: string
        guides:
          type: array
          description: One guide per entry.
          items:
            type: object
            description: "One document: its metadata plus the full markdown body."
            required:
              - title
              - slug
              - url
              - content
            properties:
              title:
                type: string
              slug:
                type: string
                description: URL segment, unique within the collection.
              url:
                type: string
                format: uri-reference
                description: Path to the rendered page.
              description:
                type: string
              category:
                type: string
              tags:
                type: array
                items:
                  type: string
              content:
                type: string
                description: The full document body as markdown.
    Changelog:
      type: object
      description: Release notes for every product, newest first.
      required:
        - totalEntries
        - entries
      properties:
        totalEntries:
          type: integer
          minimum: 0
        lastUpdated:
          type: string
          format: date
        products:
          type: array
          items:
            type: string
        entries:
          type: array
          items:
            type: object
            required:
              - title
              - slug
              - product
              - version
              - date
            properties:
              title:
                type: string
              slug:
                type: string
              url:
                type: string
                format: uri-reference
              product:
                type: string
              version:
                type: string
              build:
                type:
                  - string
                  - "null"
              date:
                type: string
                format: date
              summary:
                type: string
              content:
                type: string
                description: The release note as markdown.
    KnowledgeHub:
      type: object
      description: Published articles on payments, technology and company news, with full bodies.
      required:
        - totalArticles
        - articles
      properties:
        totalArticles:
          type: integer
          minimum: 0
        lastUpdated:
          type: string
          format: date
        categories:
          type: array
          items:
            type: string
        articles:
          type: array
          items:
            type: object
            required:
              - title
              - slug
              - url
              - date
            properties:
              title:
                type: string
              slug:
                type: string
              url:
                type: string
                format: uri-reference
              date:
                type: string
                format: date
              dateModified:
                type:
                  - string
                  - "null"
                format: date
              blurb:
                type: string
              author:
                type: string
              tags:
                type: array
                items:
                  type: string
              coverImage:
                type: string
                format: uri
              content:
                type: string
                description: The article as markdown.
    BrandGuidelines:
      type: object
      description: "The rules for representing Surfboard Payments: logo files and placement, colour palette with contrast pairings, typography, product naming, voice, imagery, and press boilerplate."
      required:
        - name
        - instructions
        - logo
        - color
        - typography
      properties:
        $schema:
          type: string
          format: uri
        name:
          type: string
        description:
          type: string
        instructions:
          type: array
          items:
            type: string
          description: Read these first. They are the rules an agent generating brand material must follow.
        naming:
          type: object
          additionalProperties: true
        logo:
          type: object
          additionalProperties: true
        color:
          type: object
          additionalProperties: true
        typography:
          type: object
          additionalProperties: true
        voice:
          type: object
          additionalProperties: true
        imagery:
          type: object
          additionalProperties: true
        boilerplate:
          type: object
          additionalProperties: true
        usage:
          type: object
          additionalProperties: true
        contact:
          type: object
          additionalProperties: true
        lastUpdated:
          type: string
          format: date
    KitIndex:
      type: object
      description: Every download kit, with the URL templates for its manifest, zip and individual files.
      required:
        - kits
        - routes
      properties:
        name:
          type: string
        description:
          type: string
        routes:
          type: object
          properties:
            manifest:
              type: string
              description: URL template, {slug} substituted.
            zip:
              type: string
            file:
              type: string
        brand:
          type: string
          format: uri
        kits:
          type: array
          items:
            type: object
            required:
              - slug
              - name
              - assetCount
              - manifest
            properties:
              slug:
                type: string
              name:
                type: string
              title:
                type: string
              description:
                type: string
              assetCount:
                type: integer
                minimum: 0
              page:
                type: string
                format: uri
              manifest:
                type: string
                format: uri
    KitManifest:
      type: object
      description: "One kit: every file in it, with a caption saying what the file is for."
      required:
        - slug
        - assets
        - downloadAll
      properties:
        slug:
          type: string
        name:
          type: string
        title:
          type: string
        description:
          type: string
        page:
          type: string
          format: uri
        downloadAll:
          type: string
          format: uri
          description: The whole kit as a zip.
        assetCount:
          type: integer
          minimum: 0
        assets:
          type: array
          items:
            type: object
            required:
              - file
              - download
              - format
            properties:
              file:
                type: string
              caption:
                type: string
                description: What this file is, and when to reach for it.
              kind:
                type: string
              format:
                type: string
                enum:
                  - svg
                  - png
                  - jpg
                  - webp
                  - pdf
              download:
                type: string
                format: uri
              source:
                type: string
                format: uri
    ApiIndexGroup:
      type: object
      description: One group of endpoints in the plain index.
      properties:
        description:
          type: string
        endpoints:
          type: array
          items:
            type: object
            required:
              - path
              - method
            properties:
              path:
                type: string
              method:
                type: string
                enum:
                  - GET
                  - POST
              description:
                type: string
    ApiIndex:
      type: object
      description: A plain listing of every endpoint on this domain, grouped by purpose.
      required:
        - name
        - ai
      properties:
        name:
          type: string
        description:
          type: string
        ai:
          $ref: "#/components/schemas/ApiIndexGroup"
        kits:
          $ref: "#/components/schemas/ApiIndexGroup"
        llm:
          $ref: "#/components/schemas/ApiIndexGroup"
        developer:
          $ref: "#/components/schemas/ApiIndexGroup"
        internal:
          $ref: "#/components/schemas/ApiIndexGroup"
      additionalProperties:
        type: object
        properties:
          description:
            type: string
          endpoints:
            type: array
            items:
              type: object
              properties:
                path:
                  type: string
                method:
                  type: string
                description:
                  type: string
    JsonRpcRequest:
      type: object
      description: A JSON-RPC 2.0 request as defined by the Model Context Protocol.
      required:
        - jsonrpc
        - method
      properties:
        jsonrpc:
          type: string
          const: "2.0"
        id:
          description: Omit for notifications. Present for requests that expect a response.
          oneOf:
            - type: string
            - type: integer
        method:
          type: string
          description: One of initialize, tools/list, tools/call, ping, or notifications/initialized.
          examples:
            - initialize
            - tools/list
            - tools/call
            - ping
        params:
          type: object
          additionalProperties: true
    JsonRpcResponse:
      type: object
      description: A JSON-RPC 2.0 response. Either result or error is present, never both.
      required:
        - jsonrpc
      properties:
        jsonrpc:
          type: string
          const: "2.0"
        id:
          oneOf:
            - type: string
            - type: integer
            - type: "null"
        result:
          type: object
          additionalProperties: true
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: integer
              description: JSON-RPC error code, e.g. -32601 for an unknown method.
            message:
              type: string
            data: {}
    McpServerCard:
      type: object
      description: "Describes the MCP server: how to install it, how to reach it over HTTP, and which tools it exposes."
      required:
        - serverInfo
        - capabilities
      properties:
        $schema:
          type: string
          format: uri
        serverInfo:
          type: object
          required:
            - name
            - version
          properties:
            name:
              type: string
            title:
              type: string
            version:
              type: string
            description:
              type: string
        transport:
          type: object
          additionalProperties: true
        transports:
          type: array
          items:
            type: object
            additionalProperties: true
        endpoint:
          type:
            - string
            - "null"
          format: uri
          description: The Streamable HTTP endpoint, or null for a stdio-only server.
        capabilities:
          type: object
          additionalProperties: true
        documentation:
          type: string
          format: uri
        repository:
          type: string
          format: uri
        homepage:
          type: string
          format: uri
    ApiCatalog:
      type: object
      description: RFC 9727 linkset naming the service docs and the machine-readable resources on this domain.
      required:
        - linkset
      properties:
        linkset:
          type: array
          items:
            type: object
            required:
              - anchor
            properties:
              anchor:
                type: string
                format: uri
                description: The resource the links below belong to.
            additionalProperties: true
    AgentSkillsIndex:
      type: object
      description: "Agent Skills index: each skill is a markdown file with a SHA-256 so it can be verified after download."
      required:
        - version
        - skills
      properties:
        $schema:
          type: string
          format: uri
        version:
          type: string
        skills:
          type: array
          items:
            type: object
            required:
              - name
              - url
              - sha256
            properties:
              name:
                type: string
              type:
                type: string
                enum:
                  - prompt
              description:
                type: string
              url:
                type: string
                format: uri
              sha256:
                type: string
                pattern: ^[0-9a-f]{64}$
    OpenApiDocument:
      type: object
      description: An OpenAPI 3.1 document.
      required:
        - openapi
        - info
        - paths
      properties:
        openapi:
          type: string
        info:
          type: object
          additionalProperties: true
        servers:
          type: array
          items:
            type: object
            additionalProperties: true
        paths:
          type: object
          additionalProperties: true
        components:
          type: object
          additionalProperties: true
x-mcp:
  endpoint: https://www.surfboardpayments.com/.well-known/mcp
  transport: streamable-http
  serverCard: https://www.surfboardpayments.com/.well-known/mcp/server-card.json
x-agent-instructions: https://www.surfboardpayments.com/agent-instructions.md
