Skip to content
Basalt

API Reference

The full OpenAPI 3.1 document is auto-generated by scripts/generate-openapi.ts on every API change and published to api.basalted.com/openapi.json.

Endpoint summary

Auth

  • POST /v1/auth/oauth/start — body { provider: "github" | "google", redirect: string }. Returns { url } to redirect the user to.
  • GET /v1/auth/oauth/callback — provider-driven; sets basalt_session cookie.
  • POST /v1/auth/logout — clears session.

Identity

  • GET /v1/me → { id, email, tier: "free" | "pro" | "founder", created_at }.

Vaults

  • GET /v1/vaults → Vault[]
  • POST /v1/vaults — body { name, source: "upload" | "sync" }. Returns Vault.
  • DELETE /v1/vaults/:id — soft-deletes.

Briefs

  • POST /v1/briefs/generate — body { vault_id, window_days?, verbs?: string[] }. p95 < 8 s.
  • GET /v1/briefs?vault_id=...&cursor=... — paginated.
  • GET /v1/briefs/:id → Brief with full content.

Findings

  • GET /v1/findings?vault_id=...&verb=... — finding timeline across briefs.

Billing

  • POST /v1/billing/checkout — body { plan: "pro" | "founder", success_url, cancel_url } → { url }.
  • POST /v1/billing/webhook — Stripe webhook endpoint; HMAC-verified.

Error envelope

All non-2xx responses look like:

{
  "error": "rate_limited",
  "scope": "briefs",
  "retry_after": 60
}

Standard codes: unauthorized, forbidden, not_found, rate_limited, invalid_request, internal_error.