DEVELOPER DOCS

Integration surface

The application integrates through a stable, versioned API. The frozen contract — schemas, error codes, retry and idempotency rules — lives inreports/integration-contract.md. This page is the orientation layer.

API v1 — endpoints

POST/api/v1/auth/tokenpassword grant (login + installation registration) or refresh_token rotation

POST/api/v1/auth/logoutrevoke calling installation + all its tokens

GET/api/v1/meaccount, installation, and organization context

GET/api/v1/entitlementsplan, features, limits, allowance, spend state

GET/api/v1/usage/summarylightweight usage snapshot

POST/api/v1/usageingest one usage record — or { records: [...] } batch (≤500)

GET/api/v1/installationslist registered installations

DELETE/api/v1/installations/{id}revoke an installation

Token lifecycle

password grant ──► access_token (15m)
                 └─► refresh_token (90d, rotating)

access expired ──► POST /auth/token
                   grant_type=refresh_token
                 ──► new pair; old refresh revoked

logout/revoke ──► installation status=REVOKED
                 ──► all tokens refuse

Usage record (essential fields)

requestId    unique, 8-128 chars (idempotency)
occurredAt   ISO-8601, ±7d skew bound
provider     e.g. "anthropic" | "local"
model        model identifier
mode         CLOUD (billable) | LOCAL
status       SUCCESS | ERROR | REJECTED | CANCELED
inputTokens / outputTokens / cachedTokens
toolCalls / computeMs

Never trust the client

Prices, allowances and entitlements are resolved server-side. The app reports measurements; the platform decides cost.

Idempotent by design

Retry any usage submission safely — requestId deduplicates. Refresh tokens rotate on use.

Local is local

mode=LOCAL records meter for analytics but are never billed. Cloud inference is metered and priced.