API Reference

API Overview

The FORG REST API gives you programmatic access to all data and configuration in your account: sessions, events, rules, budgets, reports, webhooks, users, teams, and orgs. All responses are JSON.

Base URL

https://forg.pro/api/v1/

All API requests must use HTTPS. HTTP requests are redirected to HTTPS. The v1 prefix is stable; breaking changes will be released under a new version prefix with a deprecation window of at least 12 months.

Authentication

Authenticate using an API key in the Authorization header:

Authorization: Bearer forg_live_a3f9e2c1b84d7f6e0a2c1d8e9f0b3c4d

API keys are scoped to your organization and have the format forg_live_{32hex} (production) or forg_test_{32hex} (test environment). Create keys in the dashboard under Settings → API Keys. Test keys are available on all plans; live keys require Team plan or higher.

See the Authentication page for full details on key scopes, rotation, and test vs. live behavior.

Rate limits

Plan	Primary limit	Requests / day
Lite / Developer / Professional	Not available	Not available
Team	600	100,000
Business	10,000/hour	Custom
Enterprise	Custom	Custom

Rate limit headers are included on every response:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 598
X-RateLimit-Reset: 1717200060

When a limit is exceeded, the API returns 429 Too Many Requests with aRetry-After header indicating seconds to wait.

Pagination

List endpoints use cursor-based pagination. Pass cursor from a previous response to fetch the next page:

GET /api/v1/sessions?limit=50&cursor=sess_abc123
{
  "data": [...],
  "cursor": "sess_xyz789",
  "has_more": true
}

The default page size is 20; maximum is 100. Results are ordered newest-first unlessorder=asc is specified.

Error format

All errors return a consistent JSON body:

{
  "error": "Budget limit exceeded for user user_abc",
  "code":  "budget_exceeded",
  "status": 402,
  "request_id": "req_9f3e2a1b"
}

HTTP status	Meaning
400	Bad request — invalid parameters
401	Unauthorized — missing or invalid API key
403	Forbidden — insufficient scope
404	Not found
402	Payment required — budget exceeded or plan limit
422	Unprocessable entity — validation error
429	Rate limit exceeded
500	Internal server error

Versioning

v1 is the current stable version. The API version is in the URL path, not a header. When a new version is released:

The old version remains available for 12 months
Deprecation warnings appear as Deprecation response headers
A migration guide is published in the changelog

SDKs

Official SDKs wrap the REST API with typed interfaces:

npm install @forg-pro/sdk       # TypeScript / Node.js
pip install forg-sdk             # Python (coming soon)

OpenAPI spec

The full OpenAPI 3.1 spec is available at https://forg.pro/api/v1/openapi.json. Import it into Postman, Insomnia, or any compatible client.

Authentication →Sessions →Events →Rules →Reports →Webhooks →