# Forge
> Field service CRM for contractors. Multi-tenant. Agent-first API.

Base: https://forge.kin.team
API: https://forge.kin.team/api/v1
Docs: https://forge.kin.team/developers
Discovery: https://forge.kin.team/.well-known/api.json
MCP: https://forge.kin.team/.well-known/mcp.json
OpenAPI: https://forge.kin.team/api/v1/openapi.yaml
Agent bootstrap (READ ON CONNECT): https://forge.kin.team/api/v1/agent/bootstrap
Agent guide: https://forge.kin.team/api/v1/agent-guide
Agent laws: https://forge.kin.team/api/v1/agent-laws
Health: https://forge.kin.team/api/v1/health
MCP tools (live): 145
Agent laws version: 2.0.0 (Product Law Balanced)
Discovery version: 2.1.0
Bootstrap version: 1.0.0

## Auth
Authorization: Bearer fk_live_...
Create keys in Forge → Settings → API Keys (one tenant per key).
OAuth 2.1 also supported: /.well-known/oauth-authorization-server

## On connect (mandatory)
GET https://forge.kin.team/api/v1/agent/bootstrap
Authorization: Bearer fk_live_... (optional but recommended — includes tenant tax/timezone)
Inject standingInstructions into the agent system/identity context before any CRM tool use.
MCP: resource forge://agent-instructions or tool forge_get_agent_instructions.
Refresh when bootstrap/guide/laws version headers change.

## Preferred integration (do this first)
POST https://forge.kin.team/api/v1/agent/run
Content-Type: application/json
Idempotency-Key: <uuid>
Body: { "message": "<user words>", "dryRun": false, "autoSend": false }

Timeout: >= 120s
MCP equivalent tool: forge_agent

Do NOT rebuild multi-step CRM flows with thin create-only tools.
Do NOT create a new job to "update" an existing job — use forge_update_job / PATCH /jobs/:id or forge_agent.
Do NOT create a new invoice to fix a sent/draft one — use forge_update_invoice / forge_revise_invoice on the same INV-#### (targetTotal for price-only fixes). If your platform only exposes create tools, call POST /api/v1/agent/run (forge_agent) instead of cloning.
Do NOT recreate a quote to clean up descriptions — use forge_update_quote (prices merge if omitted).
Do NOT leave site address only in title/notes — set propertyId (or propertyAddress/propertyLabel on create) or the PDF shows Bill To only.

## Agent laws (mandatory) — Product Law v2 Balanced
Full JSON: https://forge.kin.team/api/v1/agent-laws (version 2.0.0)

1. Never create to update — same J-#### / Q-#### / INV-#### / client id.
2. Unpaid issued/emailed invoices revise in place (no INV-0040 workaround).
3. On errors, call recovery.suggestedTool with recovery.suggestedArgs — do not invent unlock endpoints.
4. Product Law Balanced on all commercial creates (client/property/quote/job/invoice):
   - Clear email/phone/name → reuse client (no twin).
   - Site in fields or notes → link/create Property; do not leave address only in notes.
   - Ambiguous matches → stop and ask (never candidates[0]).
   - One open invoice per job → revise, do not mint twin.
   - force:true is exception-only; pass forceReason (audited). Prefer recovery tools.
5. Same constitution for UI, REST, MCP, and native agent — hosts must not strip recovery envelopes.

## Other paths
- MCP server: https://forge.kin.team/api/mcp (145 tools — live registry)
  Surface: clients, contacts, properties, quotes (CRUD+send+approve/decline/mark-sent/convert/duplicate), invoices (CRUD+send+mark-sent+revise/void),
  jobs (list/get/update + duplicate guard + unscheduled), schedule board + crew roster/availability,
  invoices (create/update/revise/reopen/void/send + QB + batch send + public link),
  payments (list/get/record/void), AR aging + overdue + payment reminders, deposits,
  change orders, visits (CRUD+reschedule+complete),
  time entries (CRUD) + corrections approve/deny + time-off + payroll periods/summary + team roster,
  timesheets approve + pay-period lock, receipts (link/approve), job photos, crew assign/unassign,
  services catalog (list/match/create) + tax rates + custom fields get/set,
  trash/restore, search, agent memory, forge_agent
- Full tool list: https://forge.kin.team/.well-known/api.json → mcp.tools
- REST CRUD: OpenAPI above
- Quote quality rules: GET /api/v1/agent-guide
- Quote lifecycle: approve → convert_quote_to_job (idempotent). Never create a job to bypass convert.
- Collections: forge_get_ar_summary / forge_list_overdue_invoices / forge_send_payment_reminder
- Time/payroll: forge_create_time_entry / forge_list_time_off / forge_get_payroll_period / forge_list_team
- Catalog/tax/fields: forge_match_service / forge_list_tax_rates / forge_set_custom_field_values

## Field aliases (clients)
email → billingEmail
phone → billingPhone
address → billingAddress

## Job / quote / invoice IDs
Accept UUID or human numbers: J-0042, Q-0016, INV-0038

## Quote line items
- Description-only PATCH/update merges existing unitPrice/qty by line id or index
- Dirty money accepted: "$2.80/sq ft", "2,583"
- Prefer multi-line bullet scope with real newlines

## Human docs
- https://forge.kin.team/docs/INTEGRATION_QUICKSTART.md
- https://forge.kin.team/docs/FORGE_AGENT_API.md
- https://forge.kin.team/docs/KIN_FORGE_TOOLS.md
- https://forge.kin.team/ai-agents