Build on Forge

Three integration paths

Pick the lightest path that fits your host. Chat agents should almost always use Path 1.

5-minute quickstart

1. 1

   Create a tenant API key

   In Forge: Settings → API Keys. Copy fk_live_.... One key = one company. Store it in your secret vault — never in the client.

2. 2

   Register one tool on your platform

   Name it run_forge_agent. Map to the request below. Client timeout ≥ 120s.

   POST https://forge.kin.team/api/v1/agent/run
   Authorization: Bearer fk_live_...
   Content-Type: application/json
   Idempotency-Key: <uuid>
   
   {
     "message": "Quote Acme Corp drywall unit 12 $2400. Full scope in detail. Do not send.",
     "dryRun": false,
     "conversationId": null,
     "autoSend": false
   }

3. 3

   System prompt (copy-paste)

   For any Forge CRM work (clients, quotes, jobs, invoices, updates),
   call run_forge_agent with the user's words.
   Do not invent line-item JSON.
   Do not create a second job or quote to apply an edit — update instead.
   Never set autoSend true unless the user explicitly asks to send.
   Show the human: summary, artifact links, and any needsApproval items.

4. 4

   Handle the response

   {
     "ok": true,
     "runId": "...",
     "status": "completed | needs_approval | failed | dry_run",
     "summary": "Created quote Q-0016 for Acme…",
     "artifacts": [{ "type": "quote", "number": "Q-0016", "url": "..." }],
     "needsApproval": [],
     "actions": [{ "tool": "forge_create_quote", "ok": true }]
   }

   Approvals: POST /api/v1/agent/approvals/{id}/approve or …/reject. Poll: GET /api/v1/agent/runs/{runId}.

curl -X POST https://forge.kin.team/api/v1/agent/run \
  -H "Authorization: Bearer fk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"message":"Quote Acme drywall $2400. Do not send.","autoSend":false}'

Authentication

Authorization: Bearer fk_live_...

Rules that prevent broken agents

MCP

Remote MCP server for Claude Desktop, Cursor, and other hosts. Tool list is generated from the live registry — never a stale subset.

{
  "mcpServers": {
    "forge": {
      "type": "http",
      "url": "https://forge.kin.team/api/mcp"
    }
  }
}

Discovery: https://forge.kin.team/.well-known/mcp.json · 145 tools generated from the live registry · Prefer forge_agent for multi-step; use forge_list_jobs / forge_update_job / forge_update_quote for direct edits.

REST highlights

Full contract in openapi.yaml. Common writes:

Machine discovery

Human docs

• Integration quickstart
• Native agent API
• Tool matrix (MCP / REST / thin)
• Native agent architecture
• AI product page

Scopes

Request only what you need (OAuth and API keys).