API reference

Platform endpoints live under https://api.bizbasics.ai (api.bizbasics.app for staging). Authenticate with an API key:

Authorization: Bearer bbk_...

Create keys at Settings → API keys (org admin). Keys carry read/write scopes and can be bound to a single product. The full key is shown once on creation. Browser sessions (the platform cookie) also work for user-facing calls.

A second credential, your SSO secret bbas_…, authenticates the platform's internal endpoints (quota consume, webhook registration) as X-Internal-Key. On those, your product is derived from the credential — you cannot self-declare it with a header. You are never issued the platform's shared internal key or signing secret; see the SSO contract.

The endpoint signatures, request-body fields and query parameters below are generated from the platform's live API schema — they always match what the API actually accepts.

Workspace records

Publish a summary of a user-visible object so it appears in the cross-product workspace view (search, recents) at app.bizbasics.ai.

curl -X POST https://api.bizbasics.ai/v1/workspace-records \
  -H "Authorization: Bearer bbk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "org_id":         "{org_id}",
    "source_product": "my-product",
    "record_type":    "deal",
    "source_ref":     "deal_abc123",
    "title":          "Acme Inc — $42k",
    "subtitle":       "Closing 2026-03-15",
    "summary_text":   "Renewal negotiation; awaiting legal review.",
    "app_href":       "https://my-product.example.com/deals/abc123",
    "meta":           { "stage": "negotiation" }
  }'
# 201 -> { "workspace_record_id": "...", "status": "active" }

Upserts by (org_id, source_product, record_type, source_ref) — idempotent. A product-scoped key may only publish as its own product and for its own org. The list endpoint is scoped to the caller's org and paginates with limit/offset.

Quotas

Your bb_at token carries role, plan, apps and a quotas snapshot (see the SSO contract) — bounded by the token TTL. For live usage/limits, query the platform:

curl https://api.bizbasics.ai/v1/quota/status \
  -H "Authorization: Bearer bbk_..."
# -> { "org_id": "...", "quotas": {
#        "seats": { "used": 12, "limit": 25, "remaining": 13,
#                   "period": "month", "reset_at": "..." } } }

GET /v1/quota/breakdown returns the same split by product. Consume quota atomically before a metered operation with POST /v1/quota/consume, authenticating with your bbas_ as X-Internal-Key:

curl -X POST https://api.bizbasics.ai/v1/quota/consume \
  -H "X-Internal-Key: bbas_..." -H "Content-Type: application/json" \
  -d '{
    "org_id":          "{org_id}",                 // from bb_at
    "resource":        "ai_calls",                 // ai_calls | api_calls | storage_bytes | seats
    "amount":          1,                           // default 1
    "product_id":      "your-product",              // optional — per-product usage breakdown
    "idempotency_key": "op_abc123"                  // optional — prevents double-counts on retry
  }'
# 200 ->
{ "allowed": true, "used": 12, "limit": 25, "remaining": 13,   // limit/remaining = -1 means unlimited
  "resource": "ai_calls", "period": "month", "reset_at": "<ISO8601, start of next month UTC>" }

Over limit returns 200 with "allowed": false (never a 429) — you decide how to respond. Fails open (allowed: true, limit: -1) if the platform's quota store is unreachable.

Catalog

The products visible to the current org, each with an entitled flag. Useful for building your own launcher or cross-links.

Search across the org

Full-text search over the org's workspace records (optionally filtered by record_type or product). This is how monk pulls cross-product context.

Webhooks

Subscribe to org/member/entitlement lifecycle events as signed POSTs. Register server-to-server with your bbas_ as X-Internal-Key — the webhook is bound to your product (derived from the credential). See Webhooks for the event list, signature verification, and retry behaviour.

Debugging

Recent activity made with your credentials, for troubleshooting:

OpenAPI spec

Generated from the platform-api codebase: api.bizbasics.ai/openapi.json. The endpoint tables on this page are derived from that same schema.