{"slug":"architecture/PLATFORM_API","title":"IntegrateWise Platform API — Full Reference","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/PLATFORM_API.mdx","bytes":26834,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n## 🚀 Platform URLs\n\n**Production Gateway:** `https://gateway.integratewise.ai`\n\n**Test Gateway:** `https://gateway.test.integratewise.ai`\n\nSet the Gateway origin per environment. Clients must never call a worker or\nplatform service directly; every request enters through the Gateway.\n\n**Base Path:** `/api/v1`\n\n---\n\n## 🔐 Authentication\n\nAll authenticated endpoints require:\n\n```bash\nAuthorization: Bearer YOUR_INTEGRATEWISE_API_TOKEN\nx-tenant-id: YOUR_INTEGRATEWISE_TENANT_ID\nx-user-id: your-user-id           # optional\nx-user-role: owner|admin|manager|member|viewer  # optional\n```\n\n### Auth Endpoints (Clerk)\n\n| Endpoint        | URL                                                               |\n| --------------- | ----------------------------------------------------------------- |\n| Sign In         | `https://accounts.integratewise.ai/sign-in`                       |\n| Sign Up         | `https://accounts.integratewise.ai/sign-up`                       |\n| OAuth Authorize | `https://integratewise.ai/clerk/oauth/authorize`                  |\n| OAuth Token     | `https://integratewise.ai/clerk/oauth/token`                      |\n| User Info       | `https://integratewise.ai/clerk/oauth/userinfo`                   |\n| Token Info      | `https://integratewise.ai/clerk/oauth/token_info`                 |\n| OpenID Config   | `https://integratewise.ai/clerk/.well-known/openid-configuration` |\n| Organization    | `https://accounts.integratewise.ai/organization`                  |\n| Create Org      | `https://accounts.integratewise.ai/create-organization`           |\n| OAuth Consent   | `https://accounts.integratewise.ai/oauth-consent`                 |\n\n### Get Token\n\n```bash\n# 1. Sign in via Clerk\nopen \"https://accounts.integratewise.ai/sign-in\"\n\n# 2. After login, get token from OAuth flow\nexport INTEGRATEWISE_API_TOKEN=\"eyJhbGci...\"\nexport INTEGRATEWISE_TENANT_ID=\"tenant_abc123\"\n```\n\n---\n\n## 📋 All Endpoints by Category\n\n### Health & Status (No Auth Required)\n\n| Method | Endpoint        | Description                         | Response                                                 |\n| ------ | --------------- | ----------------------------------- | -------------------------------------------------------- |\n| `GET`  | `/health`       | Gateway health check                | `{\"status\":\"ok\",\"service\":\"gateway\",\"ts\":1784601533721}` |\n| `GET`  | `/health/ready` | Full readiness probe (all services) | `{\"status\":\"ready\",\"services\":[...]}`                    |\n\n---\n\n### Platform Discovery (No Auth Required)\n\nThese read-only, cacheable endpoints let packages, external frontends, and\nintegration tooling discover the public contract before a user signs in. They\nare safe for cross-origin reads and intentionally exclude worker bindings,\ndirect service addresses, credentials, and tenant connection details.\n\n| Method | Endpoint                        | Description                                                            |\n| ------ | ------------------------------- | ---------------------------------------------------------------------- |\n| `GET`  | `/api/v1/platform`              | Platform API entry point and resource links                            |\n| `GET`  | `/api/v1/platform/packages`     | Public packages: SDK and canonical Spine schema                        |\n| `GET`  | `/api/v1/platform/services`     | Gateway-visible platform service contracts                             |\n| `GET`  | `/api/v1/platform/endpoints`    | Stable endpoint catalogue, authentication, and governance requirements |\n| `GET`  | `/api/v1/platform/openapi.json` | OpenAPI 3.1 description of the Gateway contract                        |\n\n```bash\ncurl https://gateway.integratewise.ai/api/v1/platform/packages\n\n# → {\"version\":\"integratewise-platform-catalog.v1\",\"packages\":[...]}\n```\n\nThe service catalogue describes how to consume a service, not how to bypass the\nGateway. In particular, capability plans remain immutable until an explicit\napproval, and no catalogue response contains a direct execution route.\n\n---\n\n### Workspace & Projection\n\n| Method | Endpoint                                         | Description                  | Response                                 |\n| ------ | ------------------------------------------------ | ---------------------------- | ---------------------------------------- |\n| `GET`  | `/api/v1/workspace/projection/:department`       | Full department workbench    | SharedWorkbench                          |\n| `GET`  | `/api/v1/workspace/entities?type=:type&limit=:n` | Entities filtered by type    | `{\"entities\":[...],\"provenance\":{}}`     |\n| `GET`  | `/api/v1/workspace/readiness`                    | Department readiness scores  | `{\"overall_score\":0.85,\"buckets\":[...]}` |\n| `GET`  | `/api/v1/workspace/metadata`                     | Workspace metadata           | `{\"domains\":[...],\"connectors\":[...]}`   |\n| `GET`  | `/api/v1/pipeline/entities`                      | Dashboard entities (limited) | `{\"entities\":[...],\"provenance\":{}}`     |\n\n**Department Codes:** `SALES`, `CUSTOMER_SUCCESS`, `MARKETING`, `PRODUCT_ENGINEERING`, `FINANCE`, `SERVICE`, `PROCUREMENT`, `BIZOPS`, `PERSONAL`, `REVOPS`\n\n**Entity Types:** `account`, `person`, `deal`, `task`, `signal`, `event`, `document`, `campaign`, `invoice`, `ticket`, `project`, `incident`, `vendor`, `contract`, `engagement`, `note`\n\n**Example Request:**\n\n```bash\ncurl -H \"Authorization: Bearer $INTEGRATEWISE_API_TOKEN\" \\\n     -H \"x-tenant-id: $INTEGRATEWISE_TENANT_ID\" \\\n     \"https://gateway.dev.integratewise.ai/api/v1/workspace/projection/SALES\"\n```\n\n**Example Response:**\n\n```json\n{\n  \"workspace_id\": \"ws_123\",\n  \"tenant_id\": \"tenant_456\",\n  \"department\": \"SALES\",\n  \"domain\": \"SALES\",\n  \"entities\": {\n    \"account\": [\n      {\n        \"id\": \"acc_001\",\n        \"entity_type\": \"account\",\n        \"name\": \"Acme Corp\",\n        \"status\": \"active\",\n        \"metadata\": {\"industry\": \"Technology\", \"ARR\": 120000},\n        \"source_tool\": \"salesforce\",\n        \"created_at\": \"2026-07-01T10:00:00Z\",\n        \"updated_at\": \"2026-07-21T14:30:00Z\"\n      }\n    ],\n    \"person\": [...],\n    \"deal\": [...],\n    \"task\": [...]\n  },\n  \"relationships\": [\n    {\"source\": \"acc_001\", \"target\": \"per_001\", \"type\": \"has_contact\"}\n  ],\n  \"signals\": [\n    {\"id\": \"sig_001\", \"severity\": \"info\", \"title\": \"New deal created\", \"timestamp\": \"2026-07-21T10:30:00Z\"}\n  ],\n  \"capabilities\": [\n    {\"name\": \"salesforce:read-accounts\", \"status\": \"active\"}\n  ],\n  \"governance\": [\n    {\"id\": \"gov_001\", \"decision\": \"approved\", \"capability\": \"salesforce:write-opportunities\"}\n  ],\n  \"readiness\": {\n    \"overall_score\": 0.85,\n    \"overall_state\": \"live\",\n    \"buckets\": [\n      {\"capability\": \"accounts\", \"state\": \"live\", \"score\": 0.9, \"coverage\": 0.95}\n    ]\n  },\n  \"provenance\": {\n    \"source\": \"spine\",\n    \"confidence\": 0.95,\n    \"last_sync\": \"2026-07-21T10:30:00Z\"\n  },\n  \"composed_at\": \"2026-07-21T10:30:00Z\",\n  \"composed_by\": \"projection-engine\",\n  \"projection_version\": \"1.0.0\"\n}\n```\n\n---\n\n### Connectors\n\nConnectors are **tenant-level assets**. Once connected, all apps share the same connection.\n\n```\n                    Tenant\n\n                       │\n\n               Connector Registry\n\n                       │\n\n      Salesforce (Connected)\n      Slack (Connected)\n      Gmail (Connected)\n      GitHub (Connected)\n\n           │           │          │\n\n     Customer Zero   Marketplace   Admin\n           │           │          │\n           └───────────┼──────────┘\n                       │\n                 Same Connections\n```\n\n**Connector ownership:**\n\n```\nTenant\n    ├── Connector\n    │     id\n    │     provider\n    │     auth\n    │     scopes\n    │     status\n    │     owner\n    │     permissions\n```\n\n**What's shared at tenant level:**\n\n- OAuth tokens\n- Refresh tokens\n- Webhooks\n- Sync cursors\n- Provider schemas\n- Field mappings\n- Connector configuration\n\n**What's frontend-specific:**\n\n- UI preferences (layout, recent views, local state)\n\n| Method | Endpoint                                      | Description                   | Response                                           |\n| ------ | --------------------------------------------- | ----------------------------- | -------------------------------------------------- |\n| `GET`  | `/api/v1/workspace/connectors`                | List installed connectors     | `{\"connectors\":[...]}`                             |\n| `GET`  | `/api/v1/workspace/connectors/catalog`        | Full connector catalog (100+) | `{\"connectors\":[...],\"domain\":\"SALES\",\"total\":45}` |\n| `POST` | `/api/v1/workspace/connectors/nango-session`  | Create sync session           | `{\"session_id\":\"...\",\"status\":\"active\"}`           |\n| `POST` | `/api/v1/workspace/connectors/:id/disconnect` | Disconnect connector          | `{\"success\":true}`                                 |\n| `POST` | `/api/v1/workspace/register-connector`        | Register new connector        | `{\"success\":true,\"connector_id\":\"...\"}`            |\n\n**Flow Types:**\n\n- `A` — OAuth (Nango-managed)\n- `B` — API Key\n- `C` — AI Provider\n\n**Example Request — Register Connector:**\n\n```bash\ncurl -X POST \\\n  -H \"Authorization: Bearer $INTEGRATEWISE_API_TOKEN\" \\\n  -H \"x-tenant-id: $INTEGRATEWISE_TENANT_ID\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"provider\":\"salesforce\",\"flowType\":\"A\"}' \\\n  \"https://gateway.dev.integratewise.ai/api/v1/workspace/register-connector\"\n```\n\n**Example Response — Catalog:**\n\n```json\n{\n  \"connectors\": [\n    {\n      \"id\": \"salesforce\",\n      \"name\": \"Salesforce\",\n      \"category\": \"crm\",\n      \"flowType\": \"A\",\n      \"connectionMethod\": \"nango\",\n      \"status\": \"available\",\n      \"capabilities\": {\n        \"auth\": true,\n        \"webhook\": true,\n        \"mcp\": [\"mcp:tools\", \"mcp:resources\"]\n      },\n      \"departments\": [\"SALES\", \"CUSTOMER_SUCCESS\"],\n      \"industries\": [\"technology\", \"saas\"],\n      \"mcpTools\": [\"sf_accounts\", \"sf_contacts\", \"sf_opportunities\"],\n      \"supportedEntities\": [\"account\", \"person\", \"deal\"],\n      \"authType\": \"oauth\"\n    },\n    {\n      \"id\": \"hubspot\",\n      \"name\": \"HubSpot\",\n      \"category\": \"crm\",\n      \"flowType\": \"A\",\n      \"connectionMethod\": \"nango\",\n      \"status\": \"available\",\n      \"capabilities\": {\"auth\": true, \"webhook\": true, \"mcp\": []},\n      \"departments\": [\"SALES\", \"MARKETING\"],\n      \"industries\": [\"technology\", \"saas\", \"ecommerce\"],\n      \"mcpTools\": [],\n      \"supportedEntities\": [\"account\", \"person\", \"deal\"],\n      \"authType\": \"oauth\"\n    }\n  ],\n  \"domain\": \"SALES\",\n  \"total\": 45,\n  \"catalogSize\": 100,\n  \"source\": \"integratewise-connectors\",\n  \"accelerators\": [...]\n}\n```\n\n---\n\n### Integrations\n\n| Method   | Endpoint                                   | Description                 | Request Body | Response                                 |\n| -------- | ------------------------------------------ | --------------------------- | ------------ | ---------------------------------------- |\n| `GET`    | `/api/v1/integrations`                     | List connected integrations | -            | `[{id, provider, status, ...}]`          |\n| `GET`    | `/api/v1/integrations/:provider`           | Connection status           | -            | `{id, provider, status, last_sync, ...}` |\n| `POST`   | `/api/v1/integrations/:provider/authorize` | Start OAuth flow            | -            | `{auth_url, state}`                      |\n| `DELETE` | `/api/v1/integrations/:provider`           | Disconnect integration      | -            | `{success: true}`                        |\n| `GET`    | `/api/v1/integrations/callback`            | OAuth callback (public)     | -            | Redirect to app                          |\n\n**Example Request — Start OAuth:**\n\n```bash\ncurl -X POST \\\n  -H \"Authorization: Bearer $INTEGRATEWISE_API_TOKEN\" \\\n  -H \"x-tenant-id: $INTEGRATEWISE_TENANT_ID\" \\\n  \"https://gateway.dev.integratewise.ai/api/v1/integrations/salesforce/authorize\"\n```\n\n**Example Response:**\n\n```json\n{\n  \"auth_url\": \"https://connect.nango.dev/oauth/authorize?...\",\n  \"state\": \"iw_state_abc123\"\n}\n```\n\n**Example Response — List Integrations:**\n\n```json\n[\n  {\n    \"id\": \"conn_abc123\",\n    \"provider\": \"salesforce\",\n    \"status\": \"active\",\n    \"last_sync\": \"2026-07-21T10:30:00Z\",\n    \"entities_synced\": 1250,\n    \"health\": \"healthy\"\n  },\n  {\n    \"id\": \"conn_def456\",\n    \"provider\": \"hubspot\",\n    \"status\": \"active\",\n    \"last_sync\": \"2026-07-21T10:25:00Z\",\n    \"entities_synced\": 890,\n    \"health\": \"healthy\"\n  }\n]\n```\n\n---\n\n### Capabilities\n\n| Method | Endpoint                                         | Description                                               | Request Body               | Response                                    |\n| ------ | ------------------------------------------------ | --------------------------------------------------------- | -------------------------- | ------------------------------------------- |\n| `POST` | `/api/v1/workbench/capabilities/resolve`         | Resolve the server-owned, active capability manifest      | -                          | `{activeContext, capabilities}`             |\n| `POST` | `/api/v1/workbench/capabilities/:id/invoke`      | Prepare an immutable capability plan                      | `{input}`                  | `{status:\"pending_approval\", plan}`         |\n| `POST` | `/api/v1/workbench/capability-plans/:id/approve` | Explicitly approve and execute the reviewed plan          | `{confirmation:\"approve\"}` | `{status:\"executed\", planId, result}`       |\n| `GET`  | `/api/v1/workbench/connected-ecosystem`          | Read active governed capabilities and connection evidence | -                          | `{routes, integrations, activeWorkContext}` |\n\nThe Gateway derives identity and tenant scope from the authenticated session.\nThe caller cannot provide a provider URL, connection ID, or direct execute\ninstruction.\n\n**Example Request — Prepare a Capability Plan:**\n\n```bash\ncurl -X POST \\\n  -H \"Authorization: Bearer $INTEGRATEWISE_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"input\":{\"channel\":\"#revenue\",\"text\":\"Renewal review is ready.\"}}' \\\n  \"https://gateway.test.integratewise.ai/api/v1/workbench/capabilities/slack.message.send/invoke\"\n```\n\n**Example Response:**\n\n```json\n{\n  \"status\": \"pending_approval\",\n  \"plan\": {\n    \"id\": \"wcp_123\",\n    \"capabilityId\": \"slack.message.send\",\n    \"provider\": \"slack\",\n    \"risk\": \"medium\",\n    \"review\": { \"channel\": \"#revenue\", \"text\": \"Renewal review is ready.\" }\n  }\n}\n```\n\n---\n\n### Cognitive & Intelligence\n\n| Method | Endpoint                     | Description           | Request Body       | Response                |\n| ------ | ---------------------------- | --------------------- | ------------------ | ----------------------- |\n| `POST` | `/api/v1/brainstorm`         | AI brainstorm session | `{query, context}` | `{insights:[...]}`      |\n| `POST` | `/api/v1/cognitive/twin`     | Twin reasoning        | `{query, context}` | `{response, reasoning}` |\n| `GET`  | `/api/v1/cognitive/insights` | Get insights          | -                  | `{insights:[...]}`      |\n\n---\n\n### Twin & Proposals\n\n| Method | Endpoint                           | Description           | Request Body          | Response               |\n| ------ | ---------------------------------- | --------------------- | --------------------- | ---------------------- |\n| `POST` | `/api/v1/twin/handoff`             | Twin handoff to human | `{proposal, context}` | `{handoff_id, status}` |\n| `POST` | `/api/v1/twin/handoff/:id/approve` | Approve twin action   | `{reason}`            | `{success, decision}`  |\n| `POST` | `/api/v1/twin/handoff/:id/reject`  | Reject twin action    | `{reason}`            | `{success, decision}`  |\n\n---\n\n### MCP (Model Context Protocol)\n\n| Method | Endpoint             | Description          | Response                 |\n| ------ | -------------------- | -------------------- | ------------------------ |\n| `GET`  | `/tools`             | List available tools | `{tools:[...]}`          |\n| `POST` | `/tools/invoke`      | Invoke a tool        | `{result}`               |\n| `GET`  | `/mcp`               | MCP server info      | `{name, version, tools}` |\n| `GET`  | `/sessions`          | Active sessions      | `{sessions:[...]}`       |\n| `GET`  | `/config/mcp-server` | MCP server config    | `{config}`               |\n| `GET`  | `/v1/mcp/*`          | MCP endpoints        | -                        |\n\n---\n\n### Continuity Bridge\n\n| Method | Endpoint                      | Description                 |\n| ------ | ----------------------------- | --------------------------- |\n| `*`    | `/api/v1/continuity-bridge/*` | Continuity state management |\n\n---\n\n### Webhooks (Inbound)\n\n| Method | Endpoint             | Auth      | Description              |\n| ------ | -------------------- | --------- | ------------------------ |\n| `POST` | `/webhooks/stripe`   | Signature | Stripe webhooks          |\n| `POST` | `/webhooks/razorpay` | Signature | Razorpay webhooks        |\n| `POST` | `/webhooks/hubspot`  | Signature | HubSpot webhooks         |\n| `POST` | `/webhooks/slack`    | Signature | Slack events             |\n| `POST` | `/webhooks/github`   | Signature | GitHub webhooks          |\n| `POST` | `/webhooks/billing`  | Signature | Generic billing webhooks |\n\n**Webhook Event Types:**\n\n- `contact.created`, `contact.updated`\n- `deal.created`, `deal.updated`\n- `sync.completed`\n- `ai.insight.generated`\n- `billing.subscription.changed`, `billing.payment.failed`\n\n---\n\n### Public (No Auth)\n\n| Method | Endpoint                    | Description             | Request Body             | Response          |\n| ------ | --------------------------- | ----------------------- | ------------------------ | ----------------- |\n| `POST` | `/api/v1/public/contact`    | Contact form submission | `{name, email, message}` | `{success: true}` |\n| `POST` | `/api/v1/public/newsletter` | Newsletter signup       | `{email}`                | `{success: true}` |\n\n---\n\n### Metrics\n\n| Method | Endpoint           | Auth | Description                         | Response                                           |\n| ------ | ------------------ | ---- | ----------------------------------- | -------------------------------------------------- |\n| `GET`  | `/metrics/signals` | Yes  | Signal metrics and pipeline latency | `{recent_signals, hitl_pending, pipeline_latency}` |\n\n---\n\n## 📊 Entity Shapes\n\n### SpineEntity\n\n```json\n{\n  \"id\": \"string\",\n  \"entity_type\": \"account|person|deal|task|signal|event|document|campaign|invoice|ticket|project|incident|vendor|contract|engagement|note\",\n  \"name\": \"string\",\n  \"status\": \"string\",\n  \"metadata\": {},\n  \"source_tool\": \"string\",\n  \"source_id\": \"string\",\n  \"tenant_id\": \"string\",\n  \"created_at\": \"ISO8601\",\n  \"updated_at\": \"ISO8601\",\n  \"provenance\": {\n    \"source_tool_id\": \"string\",\n    \"source_tool_name\": \"string\",\n    \"raw_id\": \"string\",\n    \"synced_at\": \"ISO8601\",\n    \"confidence\": 0.95\n  }\n}\n```\n\n### SharedWorkbench\n\n```json\n{\n  \"workspace_id\": \"string\",\n  \"tenant_id\": \"string\",\n  \"department\": \"string\",\n  \"domain\": \"string\",\n  \"user\": {\n    \"id\": \"string\",\n    \"name\": \"string\",\n    \"role\": \"string\"\n  },\n  \"entities\": {\n    \"account\": [SpineEntity],\n    \"person\": [SpineEntity],\n    \"deal\": [SpineEntity],\n    \"task\": [SpineEntity],\n    \"signal\": [SpineEntity],\n    \"event\": [SpineEntity],\n    \"document\": [SpineEntity]\n  },\n  \"relationships\": [\n    {\n      \"source\": \"string\",\n      \"target\": \"string\",\n      \"type\": \"string\",\n      \"metadata\": {}\n    }\n  ],\n  \"timeline\": [\n    {\n      \"id\": \"string\",\n      \"type\": \"string\",\n      \"title\": \"string\",\n      \"timestamp\": \"ISO8601\"\n    }\n  ],\n  \"memory\": [\n    {\n      \"id\": \"string\",\n      \"type\": \"string\",\n      \"content\": {},\n      \"tags\": [\"string\"]\n    }\n  ],\n  \"knowledge\": {\n    \"topic_summaries\": [],\n    \"learnings\": [],\n    \"conversations\": []\n  },\n  \"signals\": [\n    {\n      \"id\": \"string\",\n      \"severity\": \"info|warning|critical\",\n      \"title\": \"string\",\n      \"timestamp\": \"ISO8601\"\n    }\n  ],\n  \"capabilities\": [\n    {\n      \"name\": \"string\",\n      \"status\": \"active|inactive|error\",\n      \"last_sync\": \"ISO8601\"\n    }\n  ],\n  \"governance\": [\n    {\n      \"id\": \"string\",\n      \"decision\": \"approved|rejected|pending\",\n      \"capability\": \"string\"\n    }\n  ],\n  \"readiness\": {\n    \"overall_score\": 0.85,\n    \"overall_state\": \"live|seeded|empty\",\n    \"buckets\": [\n      {\n        \"capability\": \"string\",\n        \"state\": \"live|seeded|empty\",\n        \"score\": 0.9,\n        \"coverage\": 0.95\n      }\n    ]\n  },\n  \"actions\": [],\n  \"twinContext\": {},\n  \"provenance\": {\n    \"source\": \"spine\",\n    \"confidence\": 0.95,\n    \"last_sync\": \"ISO8601\"\n  },\n  \"composed_at\": \"ISO8601\",\n  \"composed_by\": \"projection-engine\",\n  \"projection_version\": \"1.0.0\"\n}\n```\n\n### Connector\n\n```json\n{\n  \"id\": \"string\",\n  \"name\": \"string\",\n  \"category\": \"crm|marketing|communication|project_management|productivity|analytics|finance|support|ecommerce|ai\",\n  \"flowType\": \"A|B|C\",\n  \"connectionMethod\": \"nango|api_wrapper|ai_provider\",\n  \"status\": \"available|connected|error\",\n  \"capabilities\": {\n    \"auth\": true,\n    \"webhook\": true,\n    \"mcp\": [\"mcp:tools\", \"mcp:resources\"]\n  },\n  \"departments\": [\"SALES\", \"MARKETING\"],\n  \"industries\": [\"technology\", \"saas\"],\n  \"mcpTools\": [\"sf_accounts\", \"sf_contacts\"],\n  \"supportedEntities\": [\"account\", \"person\", \"deal\"],\n  \"authType\": \"oauth|api_key|none\"\n}\n```\n\n### Capability\n\n```json\n{\n  \"name\": \"string\",\n  \"description\": \"string\",\n  \"min_tier\": \"free|pro|enterprise\",\n  \"channel\": \"sync|async|webhook\"\n}\n```\n\n---\n\n## ⏱️ Rate Limits\n\n| Category     | Limit        | Window   |\n| ------------ | ------------ | -------- |\n| General API  | 100 requests | 1 minute |\n| AI/Cognitive | 10 requests  | 1 minute |\n\n**Headers:**\n\n```\nX-RateLimit-Limit: 100\nX-RateLimit-Remaining: 95\nX-RateLimit-Reset: 1721580060\n```\n\n---\n\n## 🔄 Common Patterns\n\n### Making a Request\n\n```bash\ncurl -X GET \\\n  https://gateway.dev.integratewise.ai/api/v1/workspace/projection/SALES \\\n  -H \"Authorization: Bearer $INTEGRATEWISE_API_TOKEN\" \\\n  -H \"x-tenant-id: $INTEGRATEWISE_TENANT_ID\"\n```\n\n### With JSON Body\n\n```bash\ncurl -X POST \\\n  https://gateway.test.integratewise.ai/api/v1/workbench/capabilities/resolve \\\n  -H \"Authorization: Bearer $INTEGRATEWISE_API_TOKEN\" \\\n  -H \"Content-Type: application/json\"\n```\n\n### With Query Parameters\n\n```bash\ncurl -X GET \\\n  \"https://gateway.dev.integratewise.ai/api/v1/workspace/entities?type=deal&limit=20\" \\\n  -H \"Authorization: Bearer $INTEGRATEWISE_API_TOKEN\" \\\n  -H \"x-tenant-id: $INTEGRATEWISE_TENANT_ID\"\n```\n\n---\n\n## 📊 Response Format\n\n### Success (2xx)\n\n```json\n{\n  \"status\": \"success\",\n  \"data\": {\n    /* response data */\n  }\n}\n```\n\n### Error (4xx/5xx)\n\n```json\n{\n  \"error\": \"Error message\",\n  \"code\": \"ERROR_CODE\",\n  \"status\": 400,\n  \"details\": {\n    /* optional details */\n  }\n}\n```\n\n---\n\n## 🚨 Error Codes\n\n| Code                  | Status | Meaning                  |\n| --------------------- | ------ | ------------------------ |\n| `Unauthorized`        | 401    | Missing or invalid JWT   |\n| `Forbidden`           | 403    | Insufficient permissions |\n| `Not Found`           | 404    | Resource not found       |\n| `Rate Limit Exceeded` | 429    | Too many requests        |\n| `Service Unavailable` | 503    | Downstream service down  |\n\n---\n\n## 🔌 Connector Categories\n\n| Category           | Connectors                                                       |\n| ------------------ | ---------------------------------------------------------------- |\n| CRM                | Salesforce, HubSpot, Pipedrive, Zoho CRM, Freshsales, Close      |\n| Marketing          | Mailchimp, Marketo, SendGrid, Segment, Braze, Customer.io        |\n| Communication      | Slack, Discord, Microsoft Teams, Gmail, Outlook, Zoom, Twilio    |\n| Project Management | Jira, GitHub, GitLab, Linear, Asana, Bitbucket                   |\n| Productivity       | Notion, Google Sheets, Google Drive, Airtable, Dropbox, OneDrive |\n| Analytics          | Mixpanel, Amplitude, Heap, Google Analytics, Tableau, Metabase   |\n| Finance            | Stripe, Razorpay, QuickBooks, Xero, Chargebee, Paddle            |\n| Support            | Zendesk, Freshdesk, Intercom, Help Scout, Kustomer, Front        |\n| E-commerce         | Shopify, WooCommerce, BigCommerce                                |\n| AI/LLM             | OpenAI, Anthropic, Cohere, Perplexity                            |\n\n---\n\n## 🛠️ Integration Sources\n\n| Source          | Description           |\n| --------------- | --------------------- |\n| `salesforce`    | Salesforce CRM        |\n| `hubspot`       | HubSpot CRM           |\n| `slack`         | Slack workspace       |\n| `github`        | GitHub repositories   |\n| `notion`        | Notion databases      |\n| `jira`          | Jira projects         |\n| `stripe`        | Stripe payments       |\n| `google-sheets` | Google Sheets         |\n| `gmail`         | Gmail inbox           |\n| `quickbooks`    | QuickBooks accounting |\n\n---\n\n## 📚 SDK\n\n```bash\nnpm install @integratewise/sdk\n```\n\n```typescript\n\nconst platform = createPlatformClient({\n  baseUrl: \"https://gateway.integratewise.ai\",\n  getAccessToken: () => getSessionToken(),\n});\n\n// No session is needed to discover the public integration contract.\nconst { packages } = await platform.platform.packages();\nconst { services } = await platform.platform.services();\nconst openApi = await platform.platform.openApi();\n\nconst manifest = await platform.capability.resolve();\n\nconst prepared = await platform.capability.prepare(\"slack.message.send\", {\n  channel: \"#revenue\",\n  text: \"Renewal review is ready.\",\n});\n\n// Invoke only after the user reviews the immutable plan.\nawait platform.capability.approve(prepared.plan.id);\n```\n\n---\n\n## 🎯 Get Started\n\n1. **Discover the contract** — `GET /api/v1/platform` or use `platform.platform.catalogue()`.\n2. **Get credentials** — Sign in via Clerk at `https://accounts.integratewise.ai/sign-in`.\n3. **Set environment variables** — `INTEGRATEWISE_API_TOKEN` and `INTEGRATEWISE_TENANT_ID`.\n4. **Verify access** — `GET /health`.\n5. **Explore connectors** — `GET /api/v1/workspace/connectors/catalog`.\n6. **Connect a source** — `POST /api/v1/workspace/register-connector`.\n7. **Read workbench** — `GET /api/v1/workspace/projection/SALES`.\n8. **Resolve → prepare → approve** — use the governed Workbench capability endpoints above.\n\n---\n\n**Platform Status:** Release candidate — test deployment and npm publication are gated by environment validation and registry authentication.\n**Gateway (test):** `https://gateway.test.integratewise.ai`\n**Last Updated:** July 22, 2026\n"}