REST API / Account

Usage & tokens

The meter is always visible — including to your scripts. Token management endpoints are admin-only, and tokens themselves can't mint tokens.

GET /api/v1/usage #

This month's usage against the plan: contracts started, weighted AI credits consumed, archive capacity, a per-user breakdown, admin-set per-user limits, and the 30 most recent metered events. `enforced` tells you whether allowances block (false in development deployments).

Auth · Bearer token · any member

Request

curl https://app.version90.com/api/v1/usage \
  -H "Authorization: Bearer $V90_TOKEN"

200

{
  "contracts_used": 6,   "contracts_included": 10,
  "ai_credits_used": 84, "ai_credits_included": 300,
  "archive_used": 41,    "archive_capacity": 100,
  "enforced": true,
  "by_user": [{
    "user_id": "b3c1d5e7-…",
    "display_name": "Priya Nair",
    "email": "priya@yourco.com",
    "credits": 62,
    "contracts": 4,
    "actions": { "ai_review": 5, "ai_explain": 6, "contract_created": 4 }
  }],
  "user_ai_limits": { "9e8d7c6b-…": 50 },   // 0 = AI blocked; absent = unlimited
  "recent": [{
    "kind": "ai_review",           // contract_created | ai_review | ai_explain |
                                   // ai_identify | archive_stored | archive_reextract
    "credits": 10,                 // 0 for included/free actions
    "label": "AI review: MSA — Meridian Robotics",
    "user": "Priya Nair",
    "workspace_title": "MSA — Meridian Robotics",
    "created_at": "2026-07-11T18:20:01+00:00",
    "voided": false                // true = failed run, charge reversed
  }]
}

POST /api/v1/api-tokens #

Mint a long-lived token. The plaintext secret is in THIS response and never again — store it immediately. Admin-only, and interactive-only: existing tokens get 403 (credential creation stays a human act).

Auth · Interactive session · admin/owner role

Parameter	In	Type	Required	Description
name	body	string	yes	Label, e.g. 'warehouse-sync' (1–200 chars)
expires_in_days	body	int	no	1–3650; omit for non-expiring

Request

curl -X POST https://app.version90.com/api/v1/api-tokens \
  -H "Authorization: Bearer $CLERK_SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "warehouse-sync", "expires_in_days": 365}'

201 — the only time you see `secret`

{
  "id": "2a3b4c5d-…",
  "name": "warehouse-sync",
  "prefix": "v90_hK92mQx1",
  "secret": "v90_hK92mQx1TrfW…",     // shown once, stored only as a hash
  "created_at": "2026-07-11T18:30:00+00:00",
  "last_used_at": null,
  "expires_at": "2027-07-11T18:30:00+00:00",
  "revoked": false
}

Errors

403 insufficient_permissionsnot an admin/owner
403 api_token_forbiddena token tried to mint a token

GET /api/v1/api-tokens #

List the organization's tokens: prefix, last use, expiry, revocation. Secrets are never returned after creation.

Auth · Bearer token or session · admin/owner role

Request

curl https://app.version90.com/api/v1/api-tokens \
  -H "Authorization: Bearer $V90_TOKEN"

200

[{
  "id": "2a3b4c5d-…",
  "name": "warehouse-sync",
  "prefix": "v90_hK92mQx1",
  "created_at": "2026-07-11T18:30:00+00:00",
  "last_used_at": "2026-07-12T02:11:48+00:00",
  "expires_at": "2027-07-11T18:30:00+00:00",
  "revoked": false
}]

DELETE /api/v1/api-tokens/{id} #

Revoke a token, effective immediately (the next request with it gets 401). Idempotent; the action is audited.

Auth · Bearer token or session · admin/owner role

Parameter	In	Type	Required	Description
id	path	uuid	yes	Token id

Request

curl -X DELETE "https://app.version90.com/api/v1/api-tokens/$TOKEN_ID" \
  -H "Authorization: Bearer $V90_TOKEN"

200

{
  "id": "2a3b4c5d-…",
  "name": "warehouse-sync",
  "prefix": "v90_hK92mQx1",
  "created_at": "2026-07-11T18:30:00+00:00",
  "last_used_at": "2026-07-12T02:11:48+00:00",
  "expires_at": "2027-07-11T18:30:00+00:00",
  "revoked": true
}

Errors

404no such token in your organization