API reference

4RGE is served by several backend services. The two that expose application APIs are the agents API (agent runs and automations) and the platform / control-plane API (desktop, mobile, model control, prompt control, and provisioning).

Base URLs

Authentication

API requests are authenticated with your 4RGE session (the same Supabase-backed auth used by the apps) and are scoped to an organization. Pass the session access token as a Bearer token:

curl "https://agents-api.4rged.ai/api/health" \
  -H "Authorization: Bearer <session-access-token>"

Requests resolve the caller's effective access and the target organization before doing any work — there is no separate unauthenticated or global token surface for application APIs.

Agents API

Handles agent runs, automations, GitHub integration, and operational summaries.

Agent runs

Create a run

curl -X POST "https://agents-api.4rged.ai/api/agent-runs" \
  -H "Authorization: Bearer <session-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_abc123",
    "repositoryId": "42",
    "prompt": "Add unit tests for the auth middleware",
    "agentKind": "cloud",
    "source": "cloud_ui"
  }'

Success returns 201 with the run record, job enqueue info, and usage reservation. A 402 response indicates the run was denied by budget or contract policy.

Run sources and denial responses

The source field on create accepts cloud_ui, github_app, bitbucket_app, or api — the agents-api handler defaults UI creates to cloud_ui. Budget or contract blocks return HTTP 402 with a usageReservation object from reserveAgentRunUsage before any job is enqueued; fix org budget policy or ask an operator to adjust contract capacity rather than retrying identical requests.

Fetch a run

curl "https://agents-api.4rged.ai/api/agent-runs/run_xyz?organizationId=org_abc123" \
  -H "Authorization: Bearer <session-access-token>"

Git operations

curl "https://agents-api.4rged.ai/api/agent-runs/run_xyz/git/diff?organizationId=org_abc123" \
  -H "Authorization: Bearer <session-access-token>"

Terminal and desktop

Automations

See Automations for trigger payload examples.

GitHub integration

Operations

Run-related endpoints enforce usage reservations against your budget and contract.

Platform / control-plane API

Backs the desktop and mobile surfaces and admin/provisioning flows.

Desktop and runtime

Fetch effective policy

curl "https://api.4rged.ai/api/desktop/effective-policy?organizationId=org_abc123" \
  -H "Authorization: Bearer <session-access-token>"

Mobile

Model and prompt control

Provisioning (platform operators)

curl "https://api.4rged.ai/api/provisioning/contracts" \
  -H "Authorization: Bearer <platform-operator-session>"

Organization admin

Health