inkeep · amikofalvy · Sep 30, 2025
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -31,8 +31,14 @@ inkeep push agent-configurations/graph.graph.ts
 inkeep chat
 
 # Documentation development (from agents-docs directory)
-pnpm dev              # Start documentation site (port 3000)
+pnpm dev              # Start documentation site (port 3010)
 pnpm build           # Build documentation for production
+
+# API Reference documentation (requires both APIs running)
+pnpm dev:apis        # Start both Run API (3003) and Manage API (3002) from root
+pnpm fetch-openapi   # Fetch latest OpenAPI specs from running APIs
+pnpm generate-openapi # Generate static docs from OpenAPI specs
+pnpm update-api-docs # Combined: fetch + generate in one command
 ```
 
 

diff --git a/agents-docs/content/docs/api-reference/index.mdx b/agents-docs/content/docs/api-reference/index.mdx
@@ -1,5 +1,81 @@
 ---
-title: Inkeep Chat API
+title: API Reference Overview
+icon: "LuBookOpen"
+description: Overview of Inkeep Agent Framework APIs
+---
+
+The Inkeep Agent Framework provides two separate APIs for different purposes:
+
+## Run API
+
+The **Run API** is the runtime execution API for interacting with your agents. It provides:
+
+- **Chat Completions** - OpenAI-compatible streaming chat completions endpoint
+- **A2A Protocol** - Agent-to-Agent communication following Google's A2A specification
+- **MCP Integration** - Model Context Protocol for agent capabilities
+- **Vercel AI SDK** - Data stream protocol for real-time updates
+
+**Base URL:** `http://localhost:3003` (development)
+
+[View Run API Reference →](/api-reference/run-api)
+
+[Run API Authentication →](/api-reference/authentication/run-api)
+
+## Manage API
+
+The **Manage API** is the management/configuration API for building and maintaining your agent graphs. It provides:
+
+- **CRUD Operations** - Full management of projects, agents, graphs, tools, and relationships
+- **Graph Management** - Create and update complete agent graphs with all dependencies
+- **Tool Management** - Register and configure MCP servers and external tools
+- **OAuth Integration** - Handle OAuth flows for MCP tools requiring authentication
+- **API Key Management** - Generate and manage API keys for the Run API
+
+**Base URL:** `http://localhost:3002` (development)
+
+[View Manage API Reference →](/api-reference/manage-api)
+
+[Manage API Authentication →](/api-reference/authentication/manage-api)
+
+## Quick Start
+
+1. **Development Setup**
+   ```bash
+   # Start both APIs
+   pnpm dev:apis
+   ```
+
+2. **Use Run API** for runtime agent interactions
+   ```bash
+   curl -X POST http://localhost:3003/v1/chat/completions \
+     -H "x-inkeep-tenant-id: your-tenant" \
+     -H "x-inkeep-project-id: your-project" \
+     -H "x-inkeep-graph-id: your-graph" \
+     -H "Content-Type: application/json" \
+     -d '{"messages": [{"role": "user", "content": "Hello!"}]}'
+   ```
+
+3. **Use Manage API** for configuration
+   ```bash
+   curl http://localhost:3002/tenants/your-tenant/crud/projects
+   ```
+
+---
+
+<Callout type="info">
+**Old API Reference**
+
+The previous combined API reference at this URL has been split into separate documentation for the Run API and Manage API. Please use the links above to access the specific API documentation you need.
+</Callout>
+
+{/* Old generated content removed - see run-api.mdx and manage-api.mdx instead */}
+
+---
+
+OLD_CONTENT_BELOW_DO_NOT_MODIFY
+
+---
+title: Inkeep Chat API (DEPRECATED - DO NOT USE)
 icon: "LuBookOpen"
 full: true
 _openapi:

diff --git a/agents-docs/content/docs/api-reference/manage-api.mdx b/agents-docs/content/docs/api-reference/manage-api.mdx
@@ -0,0 +1,32 @@
+---
+title: Manage API Reference
+icon: "LuSettings"
+description: Management and configuration API for agent graphs
+full: true
+---
+
+{/* This file is auto-generated by fumadocs-openapi. Do not edit manually. */}
+
+The **Manage API** provides comprehensive CRUD operations for managing all aspects of your agent framework.
+
+## Key Features
+
+- **Project Management** - Organize agents into projects and tenants
+- **Agent CRUD** - Create, update, and delete agents with full configuration
+- **Graph Management** - Define agent relationships (transfers and delegations)
+- **Tool Integration** - Register MCP servers and external tools
+- **OAuth Support** - Handle authentication flows for external services
+- **API Key Management** - Generate and manage keys for the Run API
+
+## Base URL
+
+- **Development:** `http://localhost:3002`
+- **Production:** Configure via `AGENTS_MANAGE_API_URL` environment variable
+
+## Authentication
+
+See [Manage API Authentication](/api-reference/authentication/manage-api) for authentication options.
+
+---
+
+<APIPage document={"./src/lib/manage-api.json"} hasHead={true} />