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:

AI gateway

The single seam through which your product reaches Claude. You never hold an Anthropic key: authenticate as your product's service identity — the same credential you use for quota consume (your pod's ServiceAccount token in Authorization: Bearer, or your bbas_ as X-Internal-Key). The platform meters ai_calls against the org, pins the model, and proxies to Anthropic with the platform's key.

This section is maintained by hand (the AI gateway is not yet in the generated schema above). The request fields below are the authoritative contract.

POST /v1/ai/messages — request body:

Do not send model — the platform pins it centrally, so provider/model changes never touch your product.

curl -X POST https://api.bizbasics.ai/v1/ai/messages \
  -H "Authorization: Bearer <pod-SA token>" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id":     "{org_id}",                 // REQUIRED — metered to this org; omit -> 422
    "system":     "You are a concise assistant.",
    "max_tokens": 512,
    "messages": [
      { "role": "user", "content": "Summarise this deal in one line." }
    ]
  }'
# 200 -> Anthropic-style response:
{ "id": "msg_...", "role": "assistant", "model": "<platform-pinned>",
  "content": [ { "type": "text", "text": "..." } ],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 42, "output_tokens": 18 } }

Over the org's ai_calls limit returns 429 with the used/limit/reset in the detail. 503 means the gateway is unconfigured; 502 means the AI provider was unreachable; other upstream errors are passed through with their original status.

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.