Skip to main content
The Forge Platform API is a REST API that exposes 42+ endpoints under an OpenAPI 3.1 specification. It covers the full surface of the platform: agents, workflows, runs, events, cost, governance, and operational health. The individual endpoint references are auto-generated from the OpenAPI spec and listed below this page in the sidebar. This page covers the cross-cutting concerns that apply to every endpoint.

​
🌐 Base URL

All API requests are made to your Forge deployment: 
https://forge.gloo.ai
Endpoints are versioned under /api/v1/ and /api/v2/. Both versions are active. V2 endpoints expose the definition-layer shape for agents and add support for skills, models, workflows, budgets, and evals.

​
🔑 Authentication

Every request must include a bearer token in the Authorization header. 
curl https://forge.gloo.ai/api/v1/health \
  -H "Authorization: Bearer forge_sk_abc123..."

import { ForgeClient } from "@tangogroup/forge-sdk";

const forge = new ForgeClient({
  baseUrl: "https://forge.gloo.ai",
  apiKey: "forge_sk_abc123...",
});

const health = await forge.getHealth();

​
API Keys

API keys are created and managed through the Keys endpoints. Each key is scoped to a specific set of permissions and optionally has an expiration time. 
# Create a key with specific scopes
curl -X POST https://forge.gloo.ai/api/v1/keys \
  -H "Authorization: Bearer forge_sk_admin..." \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": ["agents:read", "runs:read", "events:read"],
    "label": "CI/CD pipeline read-only"
  }'
API keys grant access to your organization’s data. Never commit keys to source control. Use environment variables or a secrets manager.

​
Scopes

Every API key is granted a set of scopes that determine which endpoints it can access. A key can only create child keys with a subset of its own scopes.
ScopeGrants Access To
agents:readList and get agents (v1 and v2), agent cards, deployments, lifecycle history
agents:writeTransition lifecycle stages, deploy, undeploy
runs:readList and get workflow runs and their steps
events:readQuery events, get event summaries, SSE event stream
cost:readQuery cost aggregates
keys:manageCreate, list, and revoke API keys
skills:readList and get skill definitions
models:readList and get model catalog entries
workflows:readList and get workflow definitions
budgets:readGet budget status
evals:readList evaluation sets and their runs

​
📋 Response Format

All responses follow a consistent envelope structure.

​
Success Responses

{
  "data": { ... },
  "meta": {
    "requestId": "req_abc123",
    "hasMore": false,
    "nextCursor": null
  }
}
​
data
T | T[]
required
The response payload. A single object for detail endpoints, an array for list endpoints.
​
meta
object
required
Request metadata. Always includes requestId. List endpoints also include hasMore and nextCursor for pagination.

​
Error Responses

{
  "error": {
    "code": "not_found",
    "message": "Agent with ID 'abc123' does not exist."
  },
  "meta": {
    "requestId": "req_def456"
  }
}
​
error.code
string
required
A machine-readable error code. See the error codes table below.
​
error.message
string
required
A human-readable description of what went wrong.

​
❌ Error Codes

CodeHTTP StatusDescription
unauthorized401Missing or invalid API key. The Authorization header is absent or the key has been revoked.
forbidden403The API key is valid but lacks the required scope for this endpoint.
not_found404The requested resource does not exist.
bad_request400The request body or query parameters are malformed or fail validation.
internal_error500An unexpected server-side error. Include the requestId from meta when reporting issues.

​
📄 Pagination

List endpoints support cursor-based pagination. When more results are available, the response includes hasMore: true and a nextCursor value. 
# First page
curl "https://forge.gloo.ai/api/v1/events?since=2026-04-01T00:00:00Z&limit=50" \
  -H "Authorization: Bearer forge_sk_abc123..."

# Next page (use nextCursor from previous response)
curl "https://forge.gloo.ai/api/v1/events?since=2026-04-01T00:00:00Z&limit=50&cursor=eyJsYXN0..." \
  -H "Authorization: Bearer forge_sk_abc123..."
Pass the nextCursor value from the previous response as the cursor query parameter to fetch the next page. Continue until hasMore is false or nextCursor is null.

​
Pagination Parameters

ParameterTypeDefaultDescription
limitinteger25-50 (varies by endpoint)Maximum number of results per page. Range: 1-100.
cursorstring(none)Opaque cursor from a previous response’s nextCursor.

​
⏱️ Rate Limiting

The Platform API enforces rate limits per API key. When you exceed the limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating when you can retry.
Rate limits are applied per API key, not per IP address. Contact the Forge team if you need higher limits for production workloads.

​
📦 Endpoint Groups

The API is organized into the following groups. Each endpoint is documented individually in the sidebar below.
GroupVersionEndpointsDescription
Healthv11Platform and gateway health status
Agentsv14Agent listing, detail, lifecycle transitions, lifecycle history
Agentsv26Definition-layer agents, agent cards, deployments, deploy, undeploy
Runsv12Workflow run listing and detail with steps
Eventsv13Event query, summary statistics, SSE stream
Costv11Cost aggregates with filters
Keysv13API key creation, listing, and revocation
Skillsv22Skill definition listing and detail
Modelsv22Model catalog listing and detail
Evalsv23Evaluation sets, detail, and evaluation runs

​
📺 SSE Event Stream

The /api/v1/events/stream endpoint provides a Server-Sent Events stream for real-time event monitoring. Any operator interface or external consumer can subscribe to this stream for live platform events. 
curl -N "https://forge.gloo.ai/api/v1/events/stream" \
  -H "Authorization: Bearer forge_sk_abc123..." \
  -H "Accept: text/event-stream"
The SSE stream requires events:read scope. The connection stays open indefinitely — use it for monitoring dashboards, alerting systems, or agent-side event consumption.

​
🚀 Next Steps

TypeScript SDK

Typed client library wrapping all API operations.

MCP Server

Model Context Protocol server for agent-to-Forge integration.

SDK Overview

Compare all three integration methods.