OpenAPI Specification

Subscriby publishes a full OpenAPI 3.1 description of every /v1/* endpoint and every outbound webhook event. The document is generated from the PHP code — request validation rules, API resources, return types and the webhook catalogue are all inspected — and its prose is maintained beside that code, so there is no hand-written YAML to rot.

The same document builds this site's API Reference, one page per resource carrying every operation with its playground, and the webhooks' Event Reference, one page per event family. What you read there is exactly what a client generated from the spec sees.

Where it livesCopy Anchor Link

Both JSON files are regenerated on every Subscriby deploy, so they never drift from the code.

What the document carriesCopy Anchor Link

• paths — every operation with a summary, a description covering tenancy, behaviour and refusals, every parameter and body field described with its type and constraints, the error envelope on each failure status, and request and response examples.
• webhooks — every outbound event, keyed by its name, described as the POST your endpoint receives: the signed envelope, the data object field by field, named payload examples, and the SB-* headers.
• components.securitySchemes.bearerToken — the personal access token, so a generated client or a playground knows to send Authorization: Bearer.
• servers — https://api.subscriby.net, the only host the document describes.

Vendor extensionsCopy Anchor Link

Every operation carries three x- extensions, and every webhook entry carries the first of them:

{
  "paths": {
    "/v1/projects/{project}/plans": {
      "post": {
        "summary": "Create a plan",
        "x-required-scopes": ["project-subscription-plan:create"],
        "x-webhook-events": ["plan.created"],
        "x-mcp-tools": ["create_plan"],
        "requestBody": { "...": "..." }
      }
    }
  }
}

Tooling reads them to generate permission-aware UIs (Postman collections, auto-generated SDK comments, LangChain toolkits) without inspecting the server, and the reference pages on this site render them as the badge row above each operation.

Typical consumersCopy Anchor Link

• Postman / Insomnia — import the JSON URL as a collection. Every endpoint lands under the correct tag with example request and response shapes.
• openapi-generator / Stainless / Speakeasy / Fern — produce a typed client in any language. x-required-scopes ends up as comments in the generated source.
• LangChain / LangGraph — use OpenAPIToolkit to expose every Subscriby endpoint as an LLM tool.
• Custom agents — feed the spec to your LLM alongside a personal access token and let it compose requests.
• Webhook consumers — generate the payload types for your handlers from the webhooks object, so a renamed field is a compile error rather than a silent undefined.

RelatedCopy Anchor Link

• API Reference — the document rendered as pages, with a playground on each.
• Event Reference — every webhook event's envelope and payload, from the same document.
• Ability catalog — the strings that appear in x-required-scopes.
• Errors — the envelope every operation can return on failure.