briven · docs

http api

every dashboard surface is built on these endpoints; you can build your own client on top of them too. base url https://api.briven.tech. all responses are JSON unless otherwise noted. auth is either a dashboard session cookie (Better Auth) or a project API key in Authorization: Bearer brk_…; each section calls out which.

admin-only routes under /v1/admin/*aren't listed here — they need platform-admin and are documented in the operator runbook.

invoke

Call a deployed function. Auth: project API key (brk_…) in Authorization: Bearer header.

  • POST/v1/projects/:id/invoke

    Body: { function: string, args?: unknown }. Returns { result, durationMs } or { error }. Counts against your project's monthly invocation cap.

realtime

Subscribe to reactive queries over WebSocket. SDK clients (@briven/react / svelte / vue) wrap this.

  • GET/v1/projects/:id/realtime

    WSS upgrade. Send { type: "subscribe", function, args }, receive frames as the underlying rows change. Auth: project API key.

projects

Project CRUD. Auth: dashboard session cookie.

  • GET/v1/projects

    List every project the caller can see.

  • POST/v1/projects

    Body: { name, slug?, region?, orgId? }. Creates a fresh schema + runtime under the named org (defaults to your personal org).

  • GET/v1/projects/:id

    Project details.

  • PATCH/v1/projects/:id

    Body: { name?, slug? }. Rename a project.

  • POST/v1/projects/:id/move

    Body: { orgId }. Re-parent to a different org (you must be a member of both).

  • DELETE/v1/projects/:id

    Soft-delete. The schema and data are retained for 30 days before hard deletion.

deployments

Bundle uploads + history. Auth: project API key (POST) or session (GET).

  • POST/v1/projects/:id/deployments

    Upload a schema + functions bundle. Body: multipart form with bundle.tar.gz. Server diffs against the live schema, generates a migration, applies transactionally.

  • GET/v1/projects/:id/deployments

    List recent deployments with their status + schema diff summary.

  • GET/v1/projects/:id/deployments/:deploymentId

    Deployment detail including error code/message if it failed.

  • POST/v1/projects/:id/deployments/:deploymentId/cancel

    Cancel a pending or running deployment.

studio

Dashboard data browser + DDL surface. Auth: dashboard session, admin role on the project.

  • GET/v1/projects/:id/studio/tables

    List user tables.

  • POST/v1/projects/:id/studio/tables

    Body: { tableName, columns: [{ name, type, notNull?, primaryKey?, defaultExpr?, references? }] }. CREATE TABLE.

  • PATCH/v1/projects/:id/studio/tables/:table

    Body: { newName }. Rename a table.

  • POST/v1/projects/:id/studio/tables/:table/truncate

    Body: { cascade? }. TRUNCATE TABLE … RESTART IDENTITY.

  • DELETE/v1/projects/:id/studio/tables/:table

    DROP TABLE.

  • GET/v1/projects/:id/studio/tables/:table/columns

    Per-column metadata with PK + FK target.

  • POST/v1/projects/:id/studio/tables/:table/columns

    Body: { column: { name, type, notNull?, defaultExpr?, references? } }. ADD COLUMN.

  • PATCH/v1/projects/:id/studio/tables/:table/columns/:column

    Two-mode: { newName } to rename, or { notNull?, defaultExpr? } to alter nullability / default.

  • DELETE/v1/projects/:id/studio/tables/:table/columns/:column

    DROP COLUMN.

  • GET/v1/projects/:id/studio/tables/:table/indexes

    List indexes on a table.

  • POST/v1/projects/:id/studio/tables/:table/indexes

    Body: { columns: string[], unique?, name? }. CREATE INDEX.

  • DELETE/v1/projects/:id/studio/tables/:table/indexes/:name

    DROP INDEX (refuses the primary-key index).

  • GET/v1/projects/:id/studio/tables/:table/rows

    Paginated rows. Query: limit, offset, orderBy + dir, and per-column <col>__eq=value filters.

  • POST/v1/projects/:id/studio/tables/:table/rows

    Body: { values: { col: value, … } }. Insert a row.

  • PATCH/v1/projects/:id/studio/tables/:table/rows

    Body: { primaryKeyColumn, primaryKeyValue, column, value }. Update a single cell.

  • DELETE/v1/projects/:id/studio/tables/:table/rows

    Body: { primaryKeyColumn, primaryKeyValue }. Delete a row.

  • POST/v1/projects/:id/studio/query

    Body: { sql }. Run arbitrary SQL scoped to the project owner role. 5s statement_timeout. Audit-logged.

  • GET/v1/projects/:id/studio/schema

    One-shot read of every table + columns + FK edges.

  • GET/v1/projects/:id/studio/schema.ts

    Generates the equivalent briven/schema.ts so a dashboard-built database can graduate to git + CLI.

  • GET/v1/projects/:id/studio/relationships

    Every FK edge in the schema (used by the studio overview).

logs + stats

Function invocation history. Auth: dashboard session.

  • GET/v1/projects/:id/function-logs

    Query: function, status (ok|err), before (cursor), limit.

  • GET/v1/projects/:id/function-names

    Distinct function names actually called in this project.

  • GET/v1/projects/:id/function-stats

    Query: function (required), hours (default 24). Returns count + errCount + p50Ms + p99Ms.

  • GET/v1/projects/:id/hourly-invocations

    24-hour series of invocation counts per hour (used by the project sparkline).

  • GET/v1/projects/:id/logs/stream

    SSE stream of new invocations as they arrive.

usage

Metering. Auth: project API key or session.

  • GET/v1/projects/:id/usage

    Current period: invocations.count + totalDurationMs, storage.bytes, limits.

api keys

Per-project deploy / invoke keys.

  • GET/v1/projects/:id/api-keys

    List keys (hashes only).

  • POST/v1/projects/:id/api-keys

    Body: { name, scope }. Returns the plaintext key once — record it then; never retrievable again.

  • PATCH/v1/projects/:id/api-keys/:keyId

    Rename a key.

  • DELETE/v1/projects/:id/api-keys/:keyId

    Revoke a key.

project members + invitations

Per-project access control (separate from org membership).

  • GET/v1/projects/:id/members

    List members + roles.

  • POST/v1/projects/:id/invitations

    Body: { email, role, callbackURL }. Sends an email with a one-time accept link.

  • GET/v1/me/invitations

    Pending project invitations for the signed-in user.

  • POST/v1/me/invitations/accept

    Body: { token }. Accept by token from the email link.

orgs (teams)

Multi-org workspace. Personal org is auto-created on signup.

  • GET/v1/me/orgs

    Every org the caller belongs to.

  • POST/v1/orgs

    Body: { name, slug? }. Create a team org (paid tiers only — free tier caps at the personal org).

  • PATCH/v1/orgs/:id

    Body: { name }. Rename a team org.

  • DELETE/v1/orgs/:id

    Soft-delete a team org. Refuses while live projects still belong to it; move or delete them first.

  • GET/v1/orgs/:id/members

    List org members with roles.

  • PATCH/v1/orgs/:id/members/:userId

    Body: { role }. Change role. Refuses to demote the last owner.

  • DELETE/v1/orgs/:id/members/:userId

    Remove a member.

  • GET/v1/orgs/:id/invitations

    Pending org invitations.

  • POST/v1/orgs/:id/invitations

    Body: { email, role, callbackURL }. Invite a collaborator.

  • POST/v1/org-invitations/accept

    Body: { token }.

billing

Polar.sh-backed subscription management.

  • GET/v1/billing/subscription

    Current tier, status, period end, polar customer id.

  • GET/v1/billing/plans

    Public plan + price list (matches docs.briven.tech/pricing).

  • POST/v1/billing/checkout

    Body: { tier, successURL }. Returns { url } — hosted Polar checkout URL.

  • POST/v1/billing/portal

    Returns { url } for the Polar customer portal (manage payment / cancel).

  • POST/v1/billing/webhook

    Polar.sh webhook receiver. HMAC-validated. Server-side only — your app doesn't call this.