Skip to main content

API Overview

Subscriberbot is designed API-first. Everything the dashboard, the Concierge, and the adapters do is available through a single GraphQL API, so any client or integration can build on the same surface.

Endpoint​

POST https://graphqlworkspaces.burdenoff.com/workspaces/graphql

A single GraphQL endpoint serves all queries, mutations, and subscriptions.

Environment selection

The endpoint above is production. For alpha, use https://alphagraphqlworkspaces.burdenoff.com/workspaces/graphql. For local development, use http://localhost:4003/workspaces/graphql. Set BURDENOFF_ENV=local|alpha|prod to select the target automatically in CLI and SDK tools. See Environment Selection for details.

Authentication​

Requests are authenticated with a bearer token tied to an Identity:

POST /graphql HTTP/1.1
Host: graphqlworkspaces.burdenoff.com
Authorization: Bearer <token>
Content-Type: application/json

For workspace-scoped operations, the platform also requires a workspace token. SDKs and the CLI handle this automatically after you select a workspace.

See Authentication for OAuth2 flows, token refresh, and M2M client credentials.

The shape of the API​

The API mirrors the domain entities. The main types you will work with:

TypeDescription
IdentityA user or organization.
ProviderA service provider in the registry.
RelationshipA subscription, membership, license, or contract.
PlanA pricing model.
PaymentInstrumentA card, bank, wallet, or UPI handle.
EntitlementWhat a relationship grants.
AssetA document attached to a relationship.
PolicyAn automation rule.

Queries​

query MySubscriptions {
  subListRelationships(filter: { status: ACTIVE }) {
    id
    provider { name category }
    plan { name price interval }
    renewalDate
    healthScore
    entitlements { name value }
  }
}

Mutations​

mutation CancelUnused {
  subCancelRelationship(id: "rel_123", reason: UNUSED) {
    id
    status
    effectiveDate
  }
}

Subscriptions (real-time events)​

Clients can subscribe to the event bus to react in real time:

subscription {
  events(types: [RENEWAL_DETECTED, TRIAL_ENDING]) {
    type
    relationship { id provider { name } }
    occurredAt
  }
}

SDKs and adapters​

Conventions​

  • GraphQL-first — one typed schema for everything.
  • Identity-scoped — every request operates within the calling Identity's graph.
  • Event-driven — state changes are observable through subscriptions and webhooks.
  • Prefixing — product-owned types are prefixed Sub* and root fields sub* to avoid supergraph collisions.
  • RBAC — every Query/Mutation field carries an @rbac directive; the gateway enforces it.