REST API

Subscriby exposes a versioned REST API at https://api.subscriby.net/v1. Every mutation the creator dashboard can perform is also reachable through the API, scoped by personal access tokens.

Shape at a glanceCopy Anchor Link

• Base URL — https://api.subscriby.net/v1
• Authentication — Authorization: Bearer sbt_live_... (a personal access token, minted under Settings → API Tokens or with POST /v1/tokens)
• Tenant scoping — every token carries a mandatory scope:team:<uuid> ability and optional scope:project:<uuid> entries; the server resolves the team from the token, never from the request body
• Mutations — POST / PATCH / PUT / DELETE all require an Idempotency-Key header; successful 2xx responses are replayed for 24h under the same key
• Errors — uniform envelope { "error": { "code", "message", "docs_url", "remediation", "request_id", "fields"?, "context"? } }
• Rate limiting — 300 requests/min and 10,000 requests/hour per token, plus endpoint-specific buckets
• Pagination — list endpoints return a data array; most accept a limit query parameter (documented per endpoint). See Pagination.
• Identifiers — every resource id is a bare UUID string. See below.

IdentifiersCopy Anchor Link

Resource ids are UUIDs: 36 characters, lowercase, hyphenated, with no type prefix.

"id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13"

There is no prj_-style prefix to parse, and nothing in an id tells you what kind of thing it points at — the field name does that. Store ids as opaque strings; do not parse, sort or infer from them.

Two identifiers in the platform are deliberately not UUIDs, and both are documented where they appear:

The envelope id is a ULID rather than a UUID on purpose: it sorts by creation time, so a consumer replaying a backlog can order events without reading created_at.

Who this is forCopy Anchor Link

Core conceptsCopy Anchor Link

• Authentication — minting tokens, the bearer header, and scope tuples.
• Abilities — the ability strings that gate every endpoint.
• Tenancy and scopes — how scope:team and optional scope:project tuples combine.
• Idempotency — structuring retries so you never duplicate a mutation.
• Rate limiting — per-token and per-endpoint buckets + Retry-After semantics.
• Pagination — how list endpoints return data today.
• Errors — every error code with HTTP status, remediation, and recovery hints.
• Versioning and deprecation — the v1 contract and how breaking changes are announced.
• OpenAPI specification — the auto-generated machine-readable spec.
• Agent Readiness — the well-known documents that lead an agent here: the RFC 9727 API catalog, the A2A agent card, the MCP server card and the agent-skills index.
• API Reference — every operation, grouped by resource: fields, types, refusals, the events it fires, the MCP tools that wrap it, and a playground that calls the live API.

Agents firstCopy Anchor Link

The API contract is designed for LLM-driven clients. Every error carries a docs_url and a remediation string so agents can self-correct without a round-trip to documentation. The same ability catalog backs both the REST API and the MCP server — an ability you grant a token once works across both transports.

VersioningCopy Anchor Link

Breaking changes are never introduced within a major version. Additive changes (new fields, new endpoints, new error codes) can appear at any time. See the versioning and deprecation policy for the full contract.