{ "openapi": "3.1.0", "info": { "title": "Growth Intel API & MCP Server", "description": "Growth Intel is an AI-powered revenue intelligence, omni-channel attribution, and B2B CRM engine. This document describes the REST API and Model Context Protocol (MCP) endpoints for autonomous agents, LLMs, and developer integrations.\n", "version": "1.0.0", "contact": { "name": "Growth Intel Developer Support", "url": "https://growthintel.net/docs", "email": "contact@growthintel.net" } }, "servers": [ { "url": "https://growthintel.net", "description": "Production Server" } ], "paths": { "/api": { "get": { "operationId": "getApiCatalog", "summary": "API Root Catalog & Health Status", "description": "Returns API operational health status, versions, documentation links, and sandbox testing credentials.", "responses": { "200": { "description": "Operational health status and catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCatalogResponse" } } } } } } }, "/api/v1": { "get": { "operationId": "getApiV1Status", "summary": "API v1 Service Catalog", "description": "Returns active endpoints, MCP discovery URLs, and sandbox mode parameters for v1.", "responses": { "200": { "description": "Active v1 endpoints and capabilities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV1StatusResponse" } } } } } } }, "/api/v1/leads": { "post": { "operationId": "createLead", "summary": "Ingest & Score Inbound Lead", "description": "Ingests an inbound lead from an advertising platform (Meta, Google, TikTok), webhook, or web form. Triggers real-time intent scoring (0-100) and instant sales rep assignment.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLeadRequest" } } } }, "responses": { "201": { "description": "Lead successfully ingested and scored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadRecord" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/api/v1/leads/semantic-search": { "get": { "operationId": "searchLeadsSemantic", "summary": "Semantic Search Across Leads", "description": "Vector similarity search across lead context, tags, notes, and activity history using 1536-dimensional embeddings.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Natural language search query", "schema": { "type": "string", "example": "High-intent healthcare prospects asking about CRM pricing" } } ], "responses": { "200": { "description": "Ranked array of matching leads", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SemanticLeadMatch" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/webhooks/conversions": { "post": { "operationId": "storeConversionFeedback", "summary": "Ingest Closed Deal Conversion Signal", "description": "Ingests offline conversion signals from external billing or CRM systems. Sends offline conversions back to Google Ads and Meta Ads to optimize smart bidding.", "security": [ { "ConversionWebhookAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversionRequest" } } } }, "responses": { "200": { "description": "Conversion signal stored and forwarded", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Conversion feedback recorded successfully." } } } } } }, "401": { "description": "Unauthorized webhook request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mcp/leads": { "post": { "operationId": "mcpLeadsStream", "summary": "Model Context Protocol (MCP) Stream", "description": "Connects autonomous AI agents to the Growth Intel Lead Intelligence Server via Model Context Protocol (HTTP Stream / SSE).", "security": [ { "BearerAuth": [] }, { "OAuth2": [] } ], "responses": { "200": { "description": "Streamed MCP protocol response" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Tenant API Bearer token. For automated testing and sandbox exploration, use 'gi_sandbox_live_demo_key'." }, "ConversionWebhookAuth": { "type": "apiKey", "in": "header", "name": "X-Conversion-Secret" }, "OAuth2": { "type": "oauth2", "description": "MCP OAuth 2.0 Authorization Code flow", "flows": { "authorizationCode": { "authorizationUrl": "https://growthintel.net/oauth/authorize", "tokenUrl": "https://growthintel.net/oauth/token", "scopes": { "read:crm": "Read CRM pipeline, lead scores, and ad attribution data" } } } } }, "schemas": { "ApiCatalogResponse": { "type": "object", "required": [ "status", "name", "version", "mcp_server", "openapi_spec", "documentation" ], "properties": { "status": { "type": "string", "example": "operational" }, "name": { "type": "string", "example": "Growth Intel Revenue Intelligence API" }, "version": { "type": "string", "example": "1.0.0" }, "mcp_server": { "type": "string", "example": "https://growthintel.net/mcp/leads" }, "openapi_spec": { "type": "string", "example": "https://growthintel.net/openapi.json" }, "openapi_yaml": { "type": "string", "example": "https://growthintel.net/openapi.yaml" }, "documentation": { "type": "string", "example": "https://growthintel.net/docs" }, "sandbox_token": { "type": "string", "example": "gi_sandbox_live_demo_key" } } }, "ApiV1StatusResponse": { "type": "object", "required": [ "status", "name", "version", "endpoints" ], "properties": { "status": { "type": "string", "example": "operational" }, "name": { "type": "string", "example": "Growth Intel API v1" }, "version": { "type": "string", "example": "1.0.0" }, "endpoints": { "type": "object", "properties": { "leads": { "type": "string" }, "semantic_search": { "type": "string" }, "conversions": { "type": "string" } } }, "mcp_server": { "type": "string" }, "openapi_spec": { "type": "string" }, "documentation": { "type": "string" }, "sandbox_token": { "type": "string" } } }, "CreateLeadRequest": { "type": "object", "required": [ "source" ], "properties": { "source": { "type": "string", "description": "Lead channel source", "example": "meta_ads" }, "campaign_id": { "type": "string", "description": "External campaign identifier", "example": "1202094829384" }, "metadata": { "type": "object", "description": "Custom lead fields and behavioral attributes", "example": { "industry": "Healthcare", "company_size": "50-200", "interest": "revenue_radar" } } } }, "LeadRecord": { "type": "object", "required": [ "id", "status", "intent_score" ], "properties": { "id": { "type": "integer", "example": 1042 }, "status": { "type": "string", "example": "new" }, "intent_score": { "type": "integer", "description": "Real-time intent score between 0 and 100", "example": 87 }, "source": { "type": "string", "example": "meta_ads" }, "created_at": { "type": "string", "format": "date-time" } } }, "SemanticLeadMatch": { "type": "object", "required": [ "id", "similarity_score" ], "properties": { "id": { "type": "integer", "example": 852 }, "similarity_score": { "type": "number", "format": "float", "example": 0.89 }, "status": { "type": "string", "example": "contacted" }, "budget_tier": { "type": "string", "example": "growth" } } }, "ConversionRequest": { "type": "object", "required": [ "lead_id", "value" ], "properties": { "lead_id": { "type": "integer", "example": 852 }, "value": { "type": "number", "example": 12500 }, "currency": { "type": "string", "example": "USD" }, "conversion_date": { "type": "string", "format": "date-time" } } }, "ErrorDetail": { "type": "object", "required": [ "code", "message", "resolution_hint" ], "properties": { "code": { "type": "string", "example": "UNAUTHORIZED" }, "message": { "type": "string", "example": "Missing API token." }, "resolution_hint": { "type": "string", "example": "Provide a valid token via 'Authorization: Bearer ' or use sandbox token 'gi_sandbox_live_demo_key'." } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/ErrorDetail" } } }, "ValidationErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "resolution_hint", "details" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string", "example": "The given data was invalid." }, "resolution_hint": { "type": "string", "example": "Align request attributes with OpenAPI schema at https://growthintel.net/openapi.json." }, "details": { "type": "object" } } } } } } } }