{"service":"ForgeOS Engine","version":"3.0.1","description":"AI-powered software governance platform. Build, review, test, and ship software with cryptographic audit trails.","base_url":"/","documentation_url":"https://forgeos.synctek.io/docs","quick_start":{"steps":[{"step":1,"action":"Register an account","method":"POST","endpoint":"/auth/register","body":{"email":"you@company.com","password":"secure_password"},"returns":"User object with user_id, email, role, trial info. Use /auth/register-agent for a one-call flow that also returns an API key."},{"step":2,"action":"Create a project","method":"POST","endpoint":"/api/projects","body":{"name":"My App","platform":"web","description":"A web application"},"returns":"Project object with id, name, status"},{"step":3,"action":"Generate a specification","method":"POST","endpoint":"/api/projects/{project_id}/specs/generate","body":{},"returns":"AI-generated specification document"},{"step":4,"action":"Start the build pipeline","method":"POST","endpoint":"/api/projects/{project_id}/build","body":{},"returns":"Build status with 8 phases: specification, architecture, implementation, review, testing, hardening, validation, delivery"},{"step":5,"action":"Approve gates to advance","method":"POST","endpoint":"/api/projects/{project_id}/build/approve/{phase}","body":{},"returns":"Updated build status with next phase active"},{"step":6,"action":"Get delivery packet","method":"GET","endpoint":"/api/projects/{project_id}/deliver","returns":"Complete delivery packet with all artifacts, test results, and governance trail"}]},"authentication":{"methods":[{"type":"api_key","header":"X-ForgeOS-API-Key","description":"Per-user API key. Prefix: fos_, 44 characters total. Create via POST /auth/register-agent (one-call) or in dashboard Settings.","recommended_for":"AI agents, CLI tools, CI/CD"},{"type":"session_cookie","cookie":"forge_session","description":"Set by POST /auth/login. Used by dashboard browser sessions.","recommended_for":"Browser-based dashboard access"}],"one_call_agent_registration":{"endpoint":"POST /auth/register-agent","description":"Register + get API key in a single call. Designed for AI agents. Automatically activates a 14-day Pro trial.","body":{"email":"agent@company.com","password":"secure_password","org_name":"Company"},"returns":{"user_id":"...","org_id":"...","api_key":"fos_...","trial_activated":true}},"rate_limits":{"general":"100 requests/minute per API key","ai_endpoints":"10 requests/minute per API key (spec generation, builds, reviews, tests)","note":"Rate limits reset on a rolling per-minute window."},"idempotency":{"header":"Idempotency-Key","description":"Include an Idempotency-Key header on POST, PUT, or PATCH requests to prevent duplicate resource creation on retries. When you retry a request that failed due to a network timeout or a 429, include the same key to receive the original response instead of creating a duplicate.","key_format":"Any non-empty string up to 255 characters. UUIDs (v4) are recommended: e.g. '550e8400-e29b-41d4-a716-446655440000'.","scope":"Keys are scoped per user or API key — different users cannot collide with each other's idempotency keys.","ttl":"Cached responses expire after 1 hour.","replay_header":"Replayed (cached) responses include the header 'Idempotency-Replay: true' so callers can distinguish a fresh response from a cached one.","safe_methods":"GET, HEAD, and OPTIONS requests ignore the header entirely. Idempotency enforcement applies only to POST, PUT, and PATCH.","example":{"method":"POST","endpoint":"/api/projects/{id}/initiatives","headers":{"X-ForgeOS-API-Key":"fos_...","Idempotency-Key":"550e8400-e29b-41d4-a716-446655440000"},"note":"If this request is retried with the same Idempotency-Key within 1 hour, the cached 201 response is returned without creating a second initiative."},"errors":{"400":"Returned when the Idempotency-Key header is present but empty, or exceeds 255 characters."}},"guide_endpoint":"GET /auth/apikey-guide"},"endpoints":{"projects":[{"method":"POST","path":"/api/projects","description":"Create a new project","auth":"required"},{"method":"GET","path":"/api/projects","description":"List all projects","auth":"required"},{"method":"GET","path":"/api/projects/{id}","description":"Get project detail","auth":"required"},{"method":"DELETE","path":"/api/projects/{id}","description":"Delete project","auth":"required"}],"build_pipeline":[{"method":"POST","path":"/api/projects/{id}/build","description":"Start 8-phase build pipeline","auth":"required"},{"method":"GET","path":"/api/projects/{id}/build/status","description":"Get build status with all phases","auth":"required"},{"method":"POST","path":"/api/projects/{id}/build/approve/{phase}","description":"Approve gate to advance pipeline","auth":"required"}],"specifications":[{"method":"POST","path":"/api/projects/{id}/specs/generate","description":"Generate AI specification","auth":"required","rate_limited":true},{"method":"GET","path":"/api/projects/{id}/specs","description":"Get latest specification","auth":"required"}],"initiatives":[{"method":"POST","path":"/api/projects/{id}/initiatives","description":"Create initiative","auth":"required"},{"method":"GET","path":"/api/projects/{id}/initiatives","description":"List initiatives","auth":"required"},{"method":"GET","path":"/api/projects/{id}/initiatives/{init_id}","description":"Get initiative detail","auth":"required"}],"changesets":[{"method":"POST","path":"/api/projects/{id}/changesets","description":"Propose changeset with risk profiling","auth":"required"},{"method":"GET","path":"/api/projects/{id}/changesets","description":"List changesets","auth":"required"},{"method":"GET","path":"/api/projects/{id}/changesets/{cs_id}","description":"Get changeset detail with risk profile","auth":"required"},{"method":"GET","path":"/api/projects/{id}/changesets/{cs_id}/gates","description":"Get gate pipeline status","auth":"required"},{"method":"GET","path":"/api/projects/{id}/changesets/{cs_id}/release-check","description":"Check release readiness","auth":"required"}],"reviews":[{"method":"POST","path":"/api/projects/{id}/changesets/{cs_id}/reviews","description":"Request quality review","auth":"required","rate_limited":true},{"method":"GET","path":"/api/projects/{id}/changesets/{cs_id}/reviews","description":"List reviews","auth":"required"}],"sessions":[{"method":"POST","path":"/api/sessions","description":"Start developer session","auth":"required"},{"method":"GET","path":"/api/sessions","description":"List sessions","auth":"required"},{"method":"PATCH","path":"/api/sessions/{id}","description":"End session","auth":"required"},{"method":"POST","path":"/api/sessions/{id}/tasks","description":"Create task in session","auth":"required"}],"governance":[{"method":"GET","path":"/api/projects/{id}/ledger","description":"Query hash-chained audit ledger","auth":"required"},{"method":"GET","path":"/api/projects/{id}/ledger/stats","description":"Ledger statistics","auth":"required"},{"method":"GET","path":"/api/projects/{id}/ledger/verify","description":"Verify chain integrity","auth":"required"}],"shared_mind":[{"method":"GET","path":"/api/shared-mind/{team_id}/stats","description":"Knowledge base statistics","auth":"required"},{"method":"GET","path":"/api/shared-mind/{team_id}/domains","description":"List knowledge domains","auth":"required"},{"method":"POST","path":"/api/shared-mind/{team_id}/observe","description":"Record observation","auth":"required"}],"team":[{"method":"GET","path":"/api/org/members","description":"List org members","auth":"required"},{"method":"POST","path":"/api/org/invite","description":"Invite member by email","auth":"org_admin"},{"method":"PATCH","path":"/api/org/members/{id}","description":"Change member role","auth":"org_admin"},{"method":"DELETE","path":"/api/org/members/{id}","description":"Remove member","auth":"org_admin"},{"method":"GET","path":"/api/org/stats","description":"Org statistics","auth":"required"}],"billing":[{"method":"GET","path":"/api/billing/status","description":"Subscription status","auth":"required"},{"method":"GET","path":"/api/billing/spend","description":"Current month AI spend","auth":"required"},{"method":"GET","path":"/api/billing/spend/history","description":"Daily spend breakdown","auth":"required","params":"?days=30"}],"auth":[{"method":"POST","path":"/auth/register","description":"Register account (starts 14-day trial)","auth":"none"},{"method":"POST","path":"/auth/login","description":"Login (sets session cookie)","auth":"none"},{"method":"POST","path":"/auth/register-agent","description":"One-call agent registration — returns API key immediately","auth":"none"},{"method":"GET","path":"/auth/me","description":"Current user info","auth":"required"},{"method":"GET","path":"/auth/apikey-guide","description":"Machine-readable auth guide","auth":"none"},{"method":"POST","path":"/auth/forgot-password","description":"Request password reset","auth":"none"},{"method":"POST","path":"/auth/reset-password","description":"Reset password with token","auth":"none"}],"delivery":[{"method":"GET","path":"/api/projects/{id}/deliver","description":"Get delivery packet","auth":"required"},{"method":"POST","path":"/api/projects/{id}/test","description":"Run VTE persona tests","auth":"required","rate_limited":true}]},"concepts":{"project":"A software project managed by ForgeOS. Has a platform (web/mobile/api/cli/desktop), status, and governance ledger.","build_pipeline":"8-phase AI pipeline: specification → architecture → implementation → review → testing → hardening → validation → delivery. Each phase has a gate requiring approval.","initiative":"A scoped work item within a project. Tracks priority (low/medium/high/critical), status, and risk level.","changeset":"A proposed code change with AI risk profiling (low/medium/high/critical) and a gate pipeline for review/approval.","review":"Quality review by AI reviewers across security, architecture, performance, and other domains. Produces findings with severity levels.","governance_ledger":"Tamper-evident, hash-chained audit trail. Every action is cryptographically linked to the previous one. Verifiable via /api/projects/{id}/ledger/verify.","shared_mind":"Institutional knowledge base. Stores observations, patterns, anti-patterns, and lessons learned across projects.","session":"A developer work session with task tracking. Linked to projects and initiatives.","gate":"An approval checkpoint in the build pipeline or changeset review process. Must be explicitly approved to advance.","risk_profile":"AI-generated risk assessment for changesets. Includes risk_level, scope, change_type, patterns, and estimated_review_hours."},"discovery":{"health":"GET /health","auth_guide":"GET /auth/apikey-guide","this_document":"GET /docs"}}