REST API

Build on FORG. Automate Everything.

Every FORG capability is exposed via a clean REST API. Build custom dashboards, automate rule management, and integrate AI usage data directly into your workflows.

REST endpoints

Webhook events

Bearer

token auth

TS + Py

SDK (Q3 2025)

API Reference Get your API key

Quick start

Up in 30 seconds

Authenticate with your license key as a Bearer token and start querying immediately — no SDK required.

Request

curl https://forg.pro/api/v1/sessions \
  -H "Authorization: Bearer lic_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Response

json

{
  "sessions": [
    {
      "id": "sess_01j9xkp2mv",
      "user_ref": "user_8f31…",
      "workspace_type": "AI coding workspace",
      "model_class": "Advanced Balanced",
      "started_at": "2025-05-29T13:00:00Z",
      "ended_at": "2025-05-29T14:22:01Z",
      "tokens_in": 48210,
      "tokens_out": 12048,
      "cost_usd": 0.38,
      "rule_actions": []
    }
  ],
  "total": 1,
  "cursor": null
}

Endpoints reference

All endpoints are relative to https://forg.pro

Method	Path	Description
GET	/api/v1/sessions	List sessions with filters (user, time, model)
GET	/api/v1/sessions/:id	Get full metadata for a specific session
DELETE	/api/v1/sessions/:id	Delete a session and its associated signals
GET	/api/v1/usage	Aggregate token/cost metrics across your account
GET	/api/v1/usage/teams	Usage breakdown by team or user group
GET	/api/v1/usage/models	Usage breakdown by model
GET	/api/v1/rules	List all rules and their current status
POST	/api/v1/rules	Create a new rule
PUT	/api/v1/rules/:id	Update an existing rule by ID
DELETE	/api/v1/rules/:id	Delete a rule by ID
GET	/api/v1/webhooks	List configured webhook endpoints
POST	/api/v1/webhooks	Register a new webhook endpoint

Authentication

API authentication

All API requests are authenticated using your FORG license key as a Bearer token. License keys follow the format lic_<20hex>.

Keys are tied to your license — not per-project

Rotate your key at any time from the dashboard

Revoked keys return HTTP 401 immediately

Keys inherit your plan's rate limits

Authorization header

Authorization: Bearer lic_xxxxxxxxxxxxxxxxxxxx

Full example

curl https://forg.pro/api/v1/usage \
  -H "Authorization: Bearer lic_a1b2c3d4e5f6g7h8i9j0"

Never commit your license key to source control. Use environment variables: FORG_API_KEY.

Webhooks

Subscribe to what matters

Event	Description
session.started	Fired when a new Claude Code session begins
session.ended	Fired when a session ends; includes token/cost totals
budget.alert	Usage crossed 80% of a configured budget threshold
budget.exceeded	Usage crossed 100% of a configured budget threshold
rule.triggered	A rule fired and an action was taken (block, alert, etc.)
anomaly.detected	The ML classifier flagged an anomalous usage pattern

session.ended

json

{
  "event": "session.ended",
  "id": "evt_01j9abc",
  "ts": "2025-05-29T14:22:01Z",
  "data": {
    "session_id": "sess_xyz1234",
    "user_id": "alice@co.com",
    "workspace_type": "AI coding workspace",
    "model_class": "Advanced Balanced",
    "tokens_in": 48210,
    "tokens_out": 12048,
    "cost_usd": 0.38,
    "duration_ms": 142300
  }
}

budget.exceeded

json

{
  "event": "budget.exceeded",
  "id": "evt_01j9def",
  "ts": "2025-05-29T16:05:44Z",
  "data": {
    "budget_id": "bgt_monthly_alice",
    "user_id": "alice@co.com",
    "limit_usd": 50.00,
    "used_usd": 50.14,
    "period": "monthly"
  }
}

Coming Q3 2025

Official SDKs

Type-safe clients for TypeScript and Python — built on top of the same REST API.

TS

TypeScript

@forg-pro/sdk

npm install @forg-pro/sdk

typescript

import { ForgClient } from "@forg-pro/sdk";

const forg = new ForgClient({
  apiKey: process.env.FORG_API_KEY,
});

const sessions = await forg.sessions.list({
  userId: "alice@co.com",
  limit: 20,
});

console.log(sessions.data);

Py

Python

forg-sdk

pip install forg-sdk

python

import forg

client = forg.Client(
    api_key=os.environ["FORG_API_KEY"]
)

sessions = client.sessions.list(
    user_id="alice@co.com",
    limit=20,
)

for s in sessions.data:
    print(s.cost_usd)

Rate limits

Limits apply per license key. Exceeding the limit returns 429 rate_limited with a Retry-After header.

Plan	Requests / min
Solo	100
Professional	500
Team	1,000
Business	5,000
Enterprise	Custom

Error reference

All errors return a JSON body with { "error": "code", "message": "..." }

Status	Error code	Description
400	invalid_request	Malformed JSON or missing required field
401	unauthorized	Missing or invalid Bearer token
403	forbidden	Token lacks permission for this resource
404	not_found	Resource does not exist
422	insufficient_data	k-anonymity threshold not met; result suppressed
429	rate_limited	Too many requests; see Retry-After header
500	internal_error	Unexpected server error

Start building with the FORG API

API access is included on all paid plans. Your license key is your API key — no extra setup required.

API Reference Get your API key