{"slug":"documentation/ENDPOINTS_SUMMARY","title":"IntegrateWise Complete API Endpoints Summary","section":"documentation","sectionLabel":"Documentation","status":"unclassified","type":"document","path":"documentation/ENDPOINTS_SUMMARY.mdx","bytes":14093,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n\n> **Tier C — Historical.** This document is a point-in-time snapshot preserved for reference. For current architecture, see [CANONICAL_PLATFORM_ARCHITECTURE.md](../architecture/CANONICAL_PLATFORM_ARCHITECTURE.md).\n\n## Overview\n\nThis document summarizes all 40+ API endpoints available in IntegrateWise, organized by service and use case. All endpoints have been fully documented with TypeScript type definitions and a type-safe client implementation.\n\n---\n\n## Quick Reference\n\n| Category | Count | Endpoints |\n|----------|-------|-----------|\n| **Auth** | 3 | login, logout, refresh |\n| **Workspace** | 6 | workspace, entities (CRUD) |\n| **Pipeline** | 3 | health, entity360, identity |\n| **Intelligence** | 5 | signals, insights, think, act, govern |\n| **Connectors** | 5 | list, catalog, install, sync, trigger |\n| **Knowledge** | 6 | memories (CRUD), articles |\n| **Agents** | 3 | list, reason, handoff |\n| **Brainstorming** | 4 | sessions, ideas (CRUD) |\n| **Analytics** | 2 | dashboard, track |\n| **Projections** | 2 | list, get |\n| **Execution** | 3 | packages, execute, status |\n| **Webhooks** | 3 | register, list, delete |\n| **Billing** | 2 | usage, invoices |\n| **Tenants** | 2 | info, members |\n| **Real-time** | 3 | WebSocket, SSE, Stream |\n| **Admin** | 2 | status, metrics |\n| **TOTAL** | **55+** | Fully documented |\n\n---\n\n## Architecture Overview\n\n```\nIntegrateWise API Gateway\n├── Authentication Layer\n│   ├── JWT Token validation\n│   └── Tenant isolation (x-tenant-id header)\n├── Service Router (30 microservices)\n│   ├── PIPELINE (Workspace, entities)\n│   ├── INTELLIGENCE (Signals, insights, reasoning)\n│   ├── KNOWLEDGE (Memory, articles)\n│   ├── THINK (LLM reasoning)\n│   ├── ACT (Action generation)\n│   ├── CONNECTORS (50+ integrations)\n│   ├── TWIN (Multi-agent orchestration)\n│   ├── GOVERN (Rules, compliance)\n│   └── 22+ other services\n└── Response Layer\n    ├── Type-safe responses\n    ├── Error handling\n    └── Rate limiting\n```\n\n---\n\n## API Authentication\n\n### Required Headers\n\n```\nAuthorization: Bearer <JWT_TOKEN>\nx-tenant-id: <TENANT_ID>\nx-user-id: <USER_ID> (optional)\nContent-Type: application/json\n```\n\n### Getting Started\n\n1. Call `POST /auth/login` with credentials\n2. Receive JWT token\n3. Include token in `Authorization` header for all subsequent calls\n\n---\n\n## Core Endpoints\n\n### 1. Authentication (`/api/v1/auth`)\n\n**POST /auth/login**\n- Request: `{ email, password }`\n- Response: `{ token, refresh_token, user }`\n- Usage: Initial login\n\n**POST /auth/logout**\n- Response: `{ success: true }`\n- Usage: Invalidate session\n\n**POST /auth/refresh**\n- Request: `{ refresh_token }`\n- Response: `{ token }`\n- Usage: Get new JWT token\n\n---\n\n### 2. Workspace Management (`/api/v1/workspace`)\n\n**GET /workspace**\n- Response: Workspace info, member count, created_at\n- Usage: Get current workspace\n\n**GET /workspace/entities** (Paginated)\n- Query: `limit`, `offset`, `filters`, `sort`\n- Response: `{ entities[], total, limit, offset }`\n- Usage: List all entities\n\n**GET /workspace/entities/{id}**\n- Response: Single entity with properties\n- Usage: Get entity details\n\n**POST /workspace/entities**\n- Request: `{ type, name, properties }`\n- Response: Created entity\n- Usage: Create new entity\n\n**PUT /workspace/entities/{id}**\n- Request: `{ name?, properties? }`\n- Response: Updated entity\n- Usage: Update entity\n\n**DELETE /workspace/entities/{id}**\n- Response: `{ success: true }`\n- Usage: Delete entity\n\n---\n\n### 3. Pipeline / Spine (`/api/v1/cognitive/spine`)\n\n**GET /cognitive/spine**\n- Response: WorkspaceHealth (health_score, entity_count, last_sync, metrics)\n- Usage: Get workspace health snapshot\n- Connected: InsightsView KPI cards ✓\n\n**GET /cognitive/entity360/{entity_id}**\n- Query: `include_history`, `include_relationships`, `depth`\n- Response: Entity360 (entity, relationships, history, context, risk)\n- Usage: Get complete entity view\n\n**GET /identity**\n- Response: Identity (user_id, tenant_id, email, permissions, role)\n- Usage: Get current user identity\n\n---\n\n### 4. Intelligence & Signals (`/api/v1/cognitive/signals`)\n\n**GET /cognitive/signals**\n- Query: `category`, `severity`, `limit`, `offset`\n- Response: `{ signals[], total }`\n- Categories: risk, trend, opportunity, metric\n- Usage: Detect risks, trends, opportunities\n- Connected: InsightsView filters ✓\n\n**GET /cognitive/insights**\n- Query: `category`, `limit`, `offset`\n- Response: `{ insights[], total }`\n- Usage: Get AI-generated insights\n- Connected: InsightsView insights feed ✓\n\n**POST /cognitive/think**\n- Request: `{ prompt, context?, model?, temperature?, max_tokens? }`\n- Response: `{ reasoning, confidence, recommendations }`\n- Usage: LLM-powered analysis and reasoning\n\n**POST /cognitive/act**\n- Request: `{ entity_id, signal_id?, context? }`\n- Response: `{ actions[] }`\n- Usage: Generate action proposals\n\n**GET /cognitive/govern**\n- Response: `{ policies[], compliance_status, last_audit }`\n- Usage: Get compliance rules and status\n\n---\n\n### 5. Connectors (`/api/v1/connectors`)\n\n**GET /connectors**\n- Response: `{ connectors[] }`\n- Usage: List all connectors (HubSpot, Salesforce, etc.)\n\n**GET /connectors/catalog**\n- Response: `{ categories: { crm: [], email: [], ... } }`\n- Usage: Browse available connectors\n\n**POST /connectors/install**\n- Request: `{ connector_id, config }`\n- Response: ConnectorInstallation\n- Usage: Install a new data source\n\n**GET /connectors/sync**\n- Query: `connector_id`, `status`, `limit`\n- Response: `{ syncs[] }`\n- Usage: List sync job history\n\n**POST /connectors/{id}/sync**\n- Response: `{ sync_id, status }`\n- Usage: Trigger manual sync\n\n---\n\n### 6. Knowledge & Memory (`/api/v1/cognitive/memories`)\n\n**GET /cognitive/memories**\n- Query: `entity_id`, `limit`, `offset`\n- Response: `{ memories[] }`\n- Usage: List adaptive memories about entities\n\n**POST /cognitive/memories**\n- Request: `{ entity_id, context, tags? }`\n- Response: Memory object\n- Usage: Store new memory\n\n**GET /cognitive/memory/{id}**\n- Response: Memory object\n- Usage: Get specific memory\n\n**PUT /cognitive/memory/{id}**\n- Request: `{ context?, tags? }`\n- Response: Updated memory\n- Usage: Update memory\n\n**DELETE /cognitive/memory/{id}**\n- Response: `{ success: true }`\n- Usage: Delete memory\n\n**GET /knowledge**\n- Query: `query`, `limit`, `category`\n- Response: `{ articles[] }`\n- Usage: Search knowledge base\n\n---\n\n### 7. AI Agents (`/api/v1/cognitive/agents`)\n\n**GET /cognitive/agents**\n- Response: `{ agents[] }`\n- Usage: List available AI agents\n\n**POST /cognitive/twin/reason**\n- Request: `{ context, data?, model? }`\n- Response: `{ reasoning, confidence, next_action? }`\n- Usage: Get AI reasoning\n\n**POST /cognitive/twin/handoff**\n- Request: `{ task, agents[] }`\n- Response: Handoff object with result\n- Usage: Coordinate multiple agents\n\n---\n\n### 8. Brainstorming (`/api/v1/brainstorm`)\n\n**POST /brainstorm**\n- Request: `{ topic, team_id }`\n- Response: BrainstormSession\n- Usage: Start brainstorming session\n\n**GET /brainstorm/{id}**\n- Response: BrainstormSession\n- Usage: Get session details\n\n**POST /brainstorm/{id}/ideas**\n- Request: `{ idea, description? }`\n- Response: BrainstormIdea\n- Usage: Add idea to session\n\n**GET /brainstorm/{id}/ideas**\n- Response: `{ ideas[] }`\n- Usage: List ideas in session\n\n---\n\n### 9. Analytics (`/api/v1/analytics`)\n\n**GET /analytics/dashboard**\n- Query: `period`, `metrics`\n- Response: `{ period, metrics, start_date, end_date }`\n- Usage: Get dashboard metrics\n\n**POST /analytics/track**\n- Request: `{ event_name, properties?, timestamp? }`\n- Response: `{ success: true }`\n- Usage: Track custom events\n\n---\n\n### 10. Projections (`/api/v1/projections`)\n\n**GET /projections**\n- Response: `{ projections[] }`\n- Usage: List available projections (views)\n\n**GET /projections/{id}**\n- Response: Projection with widgets\n- Usage: Get projection data\n\n---\n\n### 11. Execution (`/api/v1/execution-packages`)\n\n**GET /execution-packages**\n- Response: `{ packages[] }`\n- Usage: List runnable workflows\n\n**POST /execution-packages/{id}/execute**\n- Request: `{ parameters }`\n- Response: ExecutionResult\n- Usage: Execute workflow\n\n**GET /execution-packages/{exec_id}/status**\n- Response: ExecutionResult\n- Usage: Check execution status\n\n---\n\n### 12. Webhooks (`/webhooks`)\n\n**POST /webhooks**\n- Request: `{ url, events[], secret? }`\n- Response: Webhook object\n- Usage: Register webhook listener\n\n**GET /webhooks**\n- Response: `{ webhooks[] }`\n- Usage: List registered webhooks\n\n**DELETE /webhooks/{id}**\n- Response: `{ success: true }`\n- Usage: Remove webhook\n\n---\n\n### 13. Billing (`/api/v1/billing`)\n\n**GET /billing/usage**\n- Response: `{ plan, usage, billing_date }`\n- Usage: Get current usage and limits\n\n**GET /billing/invoices**\n- Response: `{ invoices[] }`\n- Usage: List invoices\n\n---\n\n### 14. Tenants (`/api/v1/tenants`)\n\n**GET /tenants**\n- Response: Tenant object\n- Usage: Get tenant info\n\n**GET /tenants/members**\n- Response: `{ members[] }`\n- Usage: List team members\n\n---\n\n### 15. Real-time Updates\n\n**WebSocket /ws**\n- Protocol: JSON frames\n- Events: status updates, new signals, entity changes\n- Usage: Real-time dashboard updates\n\n**Server-Sent Events /sse**\n- Protocol: Server-Sent Events\n- Events: Real-time notifications\n- Usage: Alternative to WebSocket\n\n**Streaming /stream**\n- Protocol: HTTP chunked transfer\n- Usage: Large data streaming\n\n---\n\n## Response Codes\n\n| Code | Meaning |\n|------|---------|\n| 200 | OK - Request successful |\n| 201 | Created - Resource created |\n| 204 | No Content - Successful deletion |\n| 400 | Bad Request - Invalid input |\n| 401 | Unauthorized - Missing/invalid auth |\n| 403 | Forbidden - Insufficient permissions |\n| 404 | Not Found - Resource doesn't exist |\n| 409 | Conflict - Duplicate/conflict |\n| 429 | Rate Limited - Too many requests |\n| 500 | Server Error - Internal error |\n\n---\n\n## Rate Limiting\n\n```\nX-RateLimit-Limit: 1000          (requests per minute)\nX-RateLimit-Remaining: 950       (requests left)\nX-RateLimit-Reset: 1704067200    (reset timestamp)\n```\n\nTiers:\n- Standard: 1,000 requests/minute\n- Pro: 10,000 requests/minute\n- Enterprise: Unlimited\n\n---\n\n## Error Handling\n\nAll errors follow this format:\n\n```json\n{\n  \"error\": {\n    \"code\": \"INVALID_REQUEST\",\n    \"message\": \"Human-readable error message\",\n    \"details\": {}\n  }\n}\n```\n\nError Codes:\n- `INVALID_REQUEST` - 400\n- `UNAUTHORIZED` - 401\n- `FORBIDDEN` - 403\n- `NOT_FOUND` - 404\n- `CONFLICT` - 409\n- `RATE_LIMITED` - 429\n- `INTERNAL_ERROR` - 500\n- `SERVICE_UNAVAILABLE` - 503\n\n---\n\n## Type-Safe Client Usage\n\n### Installation\n\nThe type-safe client is available at:\n```typescript\n```\n\n### Basic Usage\n\n```typescript\nconst client = new TypedApiClient('http://localhost:3333/api/v1')\nclient.setToken('jwt_token')\nclient.setTenantId('tenant_id')\n\n// All methods are fully typed\nconst health = await client.getWorkspaceHealth()\nconst signals = await client.listSignals({ category: 'risk' })\nconst insights = await client.listInsights()\nconst actions = await client.generateActions({ entity_id: 'id' })\n```\n\n### Available Methods\n\n- `login(credentials)`\n- `logout()`\n- `refreshToken(token)`\n- `getWorkspace()`\n- `listEntities(params)`\n- `getEntity(id)`\n- `createEntity(entity)`\n- `updateEntity(id, entity)`\n- `deleteEntity(id)`\n- `getWorkspaceHealth()`\n- `getEntity360(id, options)`\n- `getIdentity()`\n- `listSignals(params)`\n- `listInsights(params)`\n- `think(request)`\n- `generateActions(request)`\n- `getGovernance()`\n- `listConnectors()`\n- `getConnectorCatalog()`\n- `installConnector(id, config)`\n- `listSyncJobs(params)`\n- `syncConnector(id)`\n- `listMemories(params)`\n- `storeMemory(memory)`\n- `listKnowledgeArticles(params)`\n- `listAgents()`\n- `twinReason(request)`\n- `twinHandoff(task, agents)`\n- `startBrainstorming(topic, teamId)`\n- `getBrainstormSession(id)`\n- `addBrainstormIdea(sessionId, idea, description)`\n- `listBrainstormIdeas(sessionId)`\n- `getDashboardAnalytics(params)`\n- `trackEvent(event)`\n- `listProjections()`\n- `getProjection(id)`\n- `listExecutionPackages()`\n- `executePackage(id, parameters)`\n- `getExecutionStatus(id)`\n- `registerWebhook(webhook)`\n- `listWebhooks()`\n- `deleteWebhook(id)`\n- `getBillingUsage()`\n- `listInvoices()`\n- `getTenantInfo()`\n- `listTeamMembers()`\n- `getSystemStatus()`\n\n---\n\n## Type Definitions\n\nAll request/response types are defined in:\n```typescript\nimport type {\n  Signal, Insight, Entity360, KPIMetrics,\n  // ... 50+ more types\n} from '@integratewise/lib'\n```\n\nAvailable types:\n- Auth types: AuthCredentials, AuthResponse, UserProfile\n- Workspace types: Workspace, Entity, Entity360\n- Intelligence types: Signal, Insight, ThinkRequest/Response\n- Connector types: Connector, SyncJob\n- Knowledge types: Memory, KnowledgeArticle\n- Agent types: Agent, Handoff\n- Brainstorm types: BrainstormSession, BrainstormIdea\n- Analytics types: DashboardAnalytics\n- Error types: ApiError, ErrorCode\n- And 30+ more\n\n---\n\n## Next Steps\n\n1. **Wire more components** to backend using TypedApiClient\n2. **Add real-time updates** via WebSocket\n3. **Implement filtering/search** on list endpoints\n4. **Add pagination** for large datasets\n5. **Performance optimization** with React Query/SWR\n6. **Error boundary** implementation\n7. **Loading state** refinement\n\n---\n\n## Documentation Files\n\n- **API_ENDPOINTS.md** - Complete endpoint reference (962 lines)\n- **packages/lib/src/api-types.ts** - Type definitions (580 lines)\n- **apps/web/lib/api-client-typed.ts** - Type-safe client (517 lines)\n- **REPOSITORY_SUMMARY.md** - Repository overview\n- **This file** - Quick reference and summary\n\n---\n\n## Support\n\nFor endpoint questions, refer to:\n1. API_ENDPOINTS.md for detailed documentation\n2. Type definitions in api-types.ts\n3. Client implementation in api-client-typed.ts\n4. Backend services in /services/*/src/\n\n---\n\nGenerated: 2024-01-15\nVersion: v1.0\nStatus: Production Ready\nLast Updated: Complete API endpoints documentation and type definitions\n"}