v1 — stable

Forge Documentation

Forge is an AI agent that reads your product's ERD, API specification and context document, then plans and executes any task against your live APIs — streaming every step in real time.

What Forge does

Seeds realistic demo or test data across any product in minutes
Automates customer onboarding flows from a plain-English description
Generates QA fixtures that match your schema — no seed scripts to maintain
Explores and demonstrates every capability your API spec describes

How it works

Give Forge three things: a data model (ERD JSON or image), an API spec (OpenAPI/Swagger JSON), and a context document (plain text describing your domain). The Planner reads all three, decomposes your task into an ordered list of API calls, shows you the plan, and — once approved — executes it step by step with real HTTP calls to your product.

Playground first. The fastest way to start is the Playground — upload your files, describe a task, and see the plan plus execution without writing any code.

Quick Start

From zero to your first executed task in 5 minutes using the REST API.

Step 1 — Get an API key

Sign up at forgeagent.tech/pricing (free tier included) and copy your API key from the Dashboard. Keys look like agos_xxxxxxxxxxxxxxxx.

Step 2 — Create a session

A session ties your product context (ERD + Swagger + description) to a 24-hour workspace.

curl

curl -X POST https://forgeagent.tech/api/v1/sessions   -H "Authorization: Bearer agos_YOUR_KEY"   -H "Content-Type: application/json"   -d '{
    "product": "MyApp",
    "baseUrl": "https://api.myapp.com",
    "erd": { "entities": [...] },
    "swagger": { "openapi": "3.0.0", ... },
    "frs": "MyApp is a project management tool with users, projects, tasks and comments.",
    "auth": { "type": "bearer", "token": "myapp_token_here" }
  }'

# Response
{
  "sessionId": "sess_abc123",
  "expiresAt": "2024-03-31T00:00:00Z"
}

Step 3 — Generate a plan

Describe what you want done in plain English. Forge returns a step-by-step plan for your review.

curl

curl -X POST https://forgeagent.tech/api/v1/sessions/sess_abc123/plan   -H "Authorization: Bearer agos_YOUR_KEY"   -H "Content-Type: application/json"   -d '{ "task": "Create a project called Launch Demo with 5 tasks and invite 3 users" }'

# Response
{
  "planId": "plan_xyz789",
  "steps": [
    { "n": 1, "method": "POST", "path": "/projects", "description": "Create project Launch Demo" },
    { "n": 2, "method": "POST", "path": "/tasks",    "description": "Create task 1 of 5" },
    ...
  ]
}

Step 4 — Approve and execute

curl

# Approve the plan
curl -X POST https://forgeagent.tech/api/v1/sessions/sess_abc123/plan/plan_xyz789/approve   -H "Authorization: Bearer agos_YOUR_KEY"

# Execute (streams SSE events)
curl -N -X POST https://forgeagent.tech/api/v1/sessions/sess_abc123/execute   -H "Authorization: Bearer agos_YOUR_KEY"   -H "Content-Type: application/json"   -d '{ "planId": "plan_xyz789" }'

# Streamed output (text/event-stream)
data: {"type":"step_start","step":1,"description":"Create project Launch Demo"}
data: {"type":"step_done","step":1,"status":"ok","response":{"id":"proj_001"}}
data: {"type":"complete","stepsRun":6,"errors":0}

Prefer a visual flow? The Playground does all of this through a point-and-click UI — upload files, type a task, watch the plan and execution stream live.

Authentication

All API requests require a Bearer token in the Authorization header.

http

Authorization: Bearer agos_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Header	Value
`Authorization`	`Bearer agos_...`
`Content-Type`	`application/json`

Keep keys secret. Never commit them to source control. Use environment variables: FORGE_API_KEY=agos_...

Sessions

A session is your product context scoped to a 24-hour workspace. It holds your ERD, Swagger spec, base URL, auth config and conversation history. Sessions are stateful — the agent remembers previous steps within a session.

Field	Type	Description
`product`	string	Optional display name
`baseUrl`	string (URI)	Required. Root URL of your product API
`erd`	object	Required. Your data model (ERD JSON)
`swagger`	object	Required. OpenAPI 3.x or Swagger 2.x spec
`frs`	string	Required. Plain-English description of your domain
`auth`	object	Auth config: `{type, token}` or `{type, username, password}`

Plans

A plan is an ordered list of API steps that Forge has decided will accomplish your task. Plans are generated, shown to you, and require explicit approval before execution — you are always in control.

Each step contains: method, path, description, payload, and an optional __discover: true flag indicating the agent will first GET the resource to learn the correct payload structure before posting.

Execute

Execution streams Server-Sent Events (SSE) over a persistent HTTP connection.

SSE Event types

type	Key fields	Description
`step_start`	step, description, method, path	Agent is about to make a call
`step_done`	step, status, response	Call completed — status is `ok` or `error`
`discover`	step, resource, sample	Agent fetched schema via a GET call
`log`	message	Progress message
`complete`	stepsRun, errors	All steps finished
`error`	message, step	Fatal error — execution stopped

ERD + Swagger Format

ERD JSON

json

{
  "entities": [
    {
      "name": "User",
      "fields": [
        { "name": "id",    "type": "uuid",   "pk": true },
        { "name": "email", "type": "string", "unique": true },
        { "name": "name",  "type": "string" }
      ]
    },
    {
      "name": "Project",
      "fields": [
        { "name": "id",      "type": "uuid"   },
        { "name": "name",    "type": "string" },
        { "name": "ownerId", "type": "uuid",   "fk": "User.id" }
      ]
    }
  ]
}

Got a PNG diagram? Upload it in the Playground — Forge has a built-in ERD image reader that converts it to JSON automatically.

Examples

Real-world workflows you can adapt and run today.

🌿

Seed a demo environment

E-commerce SaaS · ~12 API calls

Sales Engineering

Populate a blank tenant with realistic catalogue, inventory, and order data before a sales demo.

1Create 3 product categories (Electronics, Apparel, Books)
2Create 10 products with stock levels and pricing
3Create 5 customer accounts with realistic names and addresses
4Place 3 sample orders in different states (pending, shipped, delivered)
5Add discount code DEMO20 for 20% off

task prompt

"Set up a realistic demo store called 'Demo Shop' with 3 categories,
10 products across those categories, 5 customers, and 3 sample orders
in different fulfilment states. Add discount code DEMO20 for 20% off."

🧪

Generate QA test fixtures

Lab / LIMS system · ~20 API calls

QA Engineering

Create a complete set of test records for an in-sprint feature — no seed script required.

1Create 4 analyst user accounts with different permission levels
2Create 3 test methods (HPLC, GC, UV-Vis)
3Create 10 samples across 2 batches
4Submit test results for 8 samples — 2 intentionally out-of-spec
5Open OOS investigation records for the 2 failing samples

task prompt

"Create a complete QA fixture set for testing the OOS investigation workflow.
Include 4 analysts, 3 test methods (HPLC assay, GC purity, UV dissolution),
10 samples in batch B-2024-01, enter results for all 10 where 2 are out-of-spec,
and open OOS investigation records for those 2 samples."

🚀

Automate customer onboarding

B2B SaaS · ~8 API calls

Customer Success

Stand up a new customer instance from a plain-English brief — no engineer needed.

1Create the organisation record with name, domain, plan
2Create the admin user and invite team members
3Configure default workspace settings and permissions
4Seed with customer-specific starter data from their brief

task prompt

"Onboard new customer Acme Pharma Ltd on the Pro plan. Admin is
sarah.jones@acme.com. Invite john.smith@acme.com and raj.patel@acme.com.
Set timezone to Europe/London and currency to GBP."

🔍

Explore what your API can do

Any product · discovery run

Developer

Upload your spec and ask Forge to demonstrate every major capability.

task prompt

"Walk through every resource in this API. For each one: create a sample record,
read it back, update one field, then list all records. Show me which endpoints
exist and confirm they work end to end."

TypeScript / JavaScript SDK

Install the official SDK for Node.js and browser environments.

bash

npm install @forgeagent/sdk

typescript

import { ForgeClient } from '@forgeagent/sdk'

const forge = new ForgeClient({ apiKey: process.env.FORGE_API_KEY })

const { sessionId } = await forge.sessions.create({
  product: 'MyApp',
  baseUrl: 'https://api.myapp.com',
  erd: erdJson,
  swagger: swaggerJson,
  frs: 'MyApp is a project management tool...',
  auth: { type: 'bearer', token: 'myapp_token' },
})

const { planId } = await forge.plans.create(sessionId, {
  task: 'Create a demo project with 5 tasks and 3 team members'
})
await forge.plans.approve(sessionId, planId)

for await (const event of forge.execute(sessionId, planId)) {
  if (event.type === 'step_done') {
    console.log('Step ' + event.step + ': ' + event.status)
  }
}

Errors

Status	Meaning
400	Invalid request body or parameters
401	Missing or invalid API key
402	Execution credit limit reached — upgrade
403	Session belongs to a different key
404	Session, plan or resource not found
422	Schema validation failed — see `details` field
429	Too many requests — retry after 60s
500	Unexpected server error

json — error shape

{ "error": "Human-readable message", "code": "VALIDATION", "details": { ... } }

Rate Limits

Plan	Executions	Plans	Req/min
Free	5 lifetime	Unlimited	60
Starter	100/month	Unlimited	120
Pro	500/month	Unlimited	300
Enterprise	Unlimited	Unlimited	Custom

API Reference

Interactive reference — try any endpoint directly from this page.