{ "openapi": "3.1.0", "info": { "title": "Forlena CRM API", "version": "v1", "summary": "Headless CRM API for deals, contacts, pipeline, AI analysis, and webhooks.", "description": "Forlena CRM API. All requests require a CRM API key (fc_ prefix) via Bearer auth. Organization isolation is enforced server-side by org_id.", "contact": { "name": "Forlena Support", "email": "david@forlena.com" } }, "servers": [ { "url": "https://forlena.com/api/v1/crm", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Deals" }, { "name": "Contacts" }, { "name": "Pipeline" }, { "name": "Search" }, { "name": "AI" }, { "name": "Webhooks" } ], "paths": { "/deals": { "get": { "tags": [ "Deals" ], "operationId": "listDeals", "summary": "List deals", "description": "Rate limit: public/v1-crm-crud (200/min)", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "lifecycle_stage", "in": "query", "schema": { "type": "string" } }, { "name": "pipeline_id", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deals list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "tags": [ "Deals" ], "operationId": "createDeal", "summary": "Create a deal", "description": "Rate limit: public/v1-crm-crud (200/min)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealCreateRequest" } } } }, "responses": { "201": { "description": "Deal created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deal" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/deals/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Deals" ], "operationId": "getDeal", "summary": "Get a deal", "description": "Returns deal, stakeholders, and recent activities.", "responses": { "200": { "description": "Deal details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealDetailResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "tags": [ "Deals" ], "operationId": "updateDeal", "summary": "Update a deal", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealUpdateRequest" } } } }, "responses": { "200": { "description": "Deal updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deal" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "tags": [ "Deals" ], "operationId": "deleteDeal", "summary": "Delete a deal", "responses": { "200": { "description": "Deal deleted", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "const": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/deals/{id}/analyze": { "post": { "tags": [ "AI", "Deals" ], "operationId": "analyzeDeal", "summary": "Analyze a deal with IMPACT AI", "description": "Rate limit: public/v1-crm-ai (30/min)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Analysis result", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "deal": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "company_name": { "type": [ "string", "null" ] } } }, "win_probability": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 }, "total_score": { "type": [ "number", "null" ] }, "score_band": { "type": [ "string", "null" ] }, "breakdown": { "type": [ "object", "null" ], "additionalProperties": true }, "summary": { "type": [ "string", "null" ] }, "recommended_actions": { "type": "array", "items": { "type": "string" } }, "risk_factors": { "type": "array", "items": { "type": "string" } }, "win_factors": { "type": "array", "items": { "type": "string" } }, "pillar_analyses": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "stage_readiness": { "type": [ "object", "null" ], "additionalProperties": true } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/deals/{id}/predict": { "post": { "tags": [ "AI", "Deals" ], "operationId": "predictDealWinProbability", "summary": "Predict deal win probability", "description": "Rate limit: public/v1-crm-ai (30/min)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Prediction result", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "deal": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "company_name": { "type": [ "string", "null" ] } } }, "win_probability": { "type": "integer", "minimum": 0, "maximum": 100 }, "confidence": { "type": "integer", "minimum": 0, "maximum": 100 }, "risk_factors": { "type": "array", "items": { "$ref": "#/components/schemas/PredictionFactor" } }, "positive_indicators": { "type": "array", "items": { "$ref": "#/components/schemas/PredictionFactor" } }, "recommendations": { "type": "array", "items": { "$ref": "#/components/schemas/PredictionRecommendation" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/contacts": { "get": { "tags": [ "Contacts" ], "operationId": "listContacts", "summary": "List contacts", "description": "Rate limit: public/v1-crm-crud (200/min)", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "q", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Contacts list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "tags": [ "Contacts" ], "operationId": "createContact", "summary": "Create a contact", "description": "Rate limit: public/v1-crm-crud (200/min)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactCreateRequest" } } } }, "responses": { "201": { "description": "Contact created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Contact" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/contacts/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Contacts" ], "operationId": "getContact", "summary": "Get a contact", "responses": { "200": { "description": "Contact details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactDetailResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "tags": [ "Contacts" ], "operationId": "updateContact", "summary": "Update a contact", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactUpdateRequest" } } } }, "responses": { "200": { "description": "Contact updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Contact" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/pipeline/stages": { "get": { "tags": [ "Pipeline" ], "operationId": "listPipelineStages", "summary": "List pipeline stages", "responses": { "200": { "description": "Stages list", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineStage" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/pipeline/health": { "get": { "tags": [ "Pipeline" ], "operationId": "getPipelineHealth", "summary": "Get pipeline health", "responses": { "200": { "description": "Pipeline health metrics", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PipelineHealth" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/search": { "get": { "tags": [ "Search" ], "operationId": "searchDealsAndContacts", "summary": "Search deals and contacts", "description": "Rate limit: public/v1-crm-search (60/min)", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2 } } ], "responses": { "200": { "description": "Search result", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SearchResponse" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/briefing": { "get": { "tags": [ "AI" ], "operationId": "getDailyBriefing", "summary": "Get daily briefing", "description": "Rate limit: public/v1-crm-ai (30/min)", "responses": { "200": { "description": "Daily briefing", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BriefingResponse" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/coaching": { "get": { "tags": [ "AI" ], "operationId": "getCoachingInsights", "summary": "Get coaching insights", "description": "Rate limit: public/v1-crm-ai (30/min)", "responses": { "200": { "description": "Coaching response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CoachingResponse" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhooks", "summary": "List webhook endpoints", "description": "Rate limit: public/v1-crm-webhooks (30/min)", "responses": { "200": { "description": "Webhook list", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "tags": [ "Webhooks" ], "operationId": "createWebhook", "summary": "Create webhook endpoint", "description": "Returns webhook secret once at creation time.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreateRequest" } } } }, "responses": { "201": { "description": "Webhook created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreateResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/webhooks/{id}": { "delete": { "tags": [ "Webhooks" ], "operationId": "deleteWebhook", "summary": "Delete webhook endpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Webhook deleted", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "const": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/usage": { "get": { "tags": [ "AI" ], "operationId": "getUsage", "summary": "Get current month API usage and quotas", "description": "Returns org-level API usage with monthly total API quota and monthly AI quota status.", "responses": { "200": { "description": "Usage and quota status", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/UsageResponse" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key" } }, "responses": { "BadRequest": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseWithCode" } } } }, "NotFound": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimited": { "description": "Rate limit or quota exceeded", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorResponseWithCode" }, { "type": "object", "properties": { "retry_after_seconds": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1 }, "used": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "reset_at": { "type": "string", "format": "date-time" } } } ] } } } }, "InternalError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "ErrorResponseWithCode": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } } }, "PaginationMeta": { "type": "object", "required": [ "total", "limit", "offset" ], "properties": { "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1 }, "offset": { "type": "integer", "minimum": 0 } } }, "Deal": { "type": "object", "required": [ "id", "title", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "company_name": { "type": [ "string", "null" ] }, "value": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ], "default": "USD" }, "win_probability": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 }, "deal_health": { "type": [ "string", "null" ] }, "lifecycle_stage": { "type": [ "string", "null" ] }, "stage_id": { "type": [ "string", "null" ], "format": "uuid" }, "stage_name": { "type": [ "string", "null" ] }, "stage_type": { "type": [ "string", "null" ] }, "pipeline_id": { "type": [ "string", "null" ], "format": "uuid" }, "pipeline_name": { "type": [ "string", "null" ] }, "owner_name": { "type": [ "string", "null" ] }, "contact_name": { "type": [ "string", "null" ] }, "contact_email": { "type": [ "string", "null" ], "format": "email" }, "contact_phone": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "lead_source": { "type": [ "string", "null" ] }, "expected_close_date": { "type": [ "string", "null" ], "format": "date-time" }, "last_activity_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "DealListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Deal" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "DealCreateRequest": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "minLength": 1 }, "company_name": { "type": "string" }, "value": { "type": "number" }, "currency": { "type": "string" }, "contact_name": { "type": "string" }, "contact_email": { "type": "string", "format": "email" }, "notes": { "type": "string" }, "lead_source": { "type": "string" }, "expected_close_date": { "type": "string", "format": "date-time" }, "pipeline_id": { "type": "string", "format": "uuid" }, "stage_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, "DealUpdateRequest": { "type": "object", "properties": { "title": { "type": [ "string", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "value": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "contact_name": { "type": [ "string", "null" ] }, "contact_email": { "type": [ "string", "null" ], "format": "email" }, "contact_phone": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "lead_source": { "type": [ "string", "null" ] }, "expected_close_date": { "type": [ "string", "null" ], "format": "date-time" }, "pipeline_id": { "type": [ "string", "null" ], "format": "uuid" }, "stage_id": { "type": [ "string", "null" ], "format": "uuid" }, "lifecycle_stage": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "Stakeholder": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ], "format": "email" }, "title": { "type": [ "string", "null" ] }, "role_type": { "type": [ "string", "null" ] }, "influence_level": { "type": [ "string", "null" ] }, "engagement_level": { "type": [ "string", "null" ] }, "sentiment": { "type": [ "string", "null" ] } } }, "Activity": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "DealDetailResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "deal", "stakeholders", "recent_activities" ], "properties": { "deal": { "$ref": "#/components/schemas/Deal" }, "stakeholders": { "type": "array", "items": { "$ref": "#/components/schemas/Stakeholder" } }, "recent_activities": { "type": "array", "items": { "$ref": "#/components/schemas/Activity" } } } } } }, "Contact": { "type": "object", "required": [ "id", "name", "deal_id", "role_type", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ], "format": "email" }, "title": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "deal_id": { "type": "string", "format": "uuid" }, "role_type": { "type": "string", "enum": [ "economic_buyer", "champion", "technical_buyer", "end_user", "influencer", "executive_sponsor", "blocker", "unknown" ] }, "department": { "type": [ "string", "null" ] }, "influence_level": { "type": [ "string", "null" ], "enum": [ "high", "medium", "low", null ] }, "engagement_level": { "type": [ "string", "null" ], "enum": [ "high", "medium", "low", "unknown", null ] }, "sentiment": { "type": [ "string", "null" ], "enum": [ "positive", "neutral", "negative", "unknown", null ] }, "linkedin_url": { "type": [ "string", "null" ], "format": "uri" }, "notes": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ContactListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "ContactCreateRequest": { "type": "object", "required": [ "name", "deal_id" ], "properties": { "name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email" }, "title": { "type": "string" }, "phone": { "type": "string" }, "deal_id": { "type": "string", "format": "uuid" }, "role_type": { "type": "string", "enum": [ "economic_buyer", "champion", "technical_buyer", "end_user", "influencer", "executive_sponsor", "blocker", "unknown" ], "default": "unknown" } }, "additionalProperties": false }, "ContactUpdateRequest": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "title": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "role_type": { "type": [ "string", "null" ], "enum": [ "economic_buyer", "champion", "technical_buyer", "end_user", "influencer", "executive_sponsor", "blocker", "unknown", null ] }, "department": { "type": [ "string", "null" ] }, "influence_level": { "type": [ "string", "null" ], "enum": [ "high", "medium", "low", null ] }, "engagement_level": { "type": [ "string", "null" ], "enum": [ "high", "medium", "low", "unknown", null ] }, "sentiment": { "type": [ "string", "null" ], "enum": [ "positive", "neutral", "negative", "unknown", null ] }, "linkedin_url": { "type": [ "string", "null" ], "format": "uri" }, "notes": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "ContactDetailResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Contact" }, { "type": "object", "properties": { "deal": { "type": "object", "properties": { "title": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] } } } } } ] } } }, "PipelineStage": { "type": "object", "required": [ "id", "name", "position", "color", "is_closed" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "stage_type": { "type": [ "string", "null" ] }, "position": { "type": "integer" }, "color": { "type": "string" }, "is_closed": { "type": "boolean" }, "probability": { "type": [ "number", "null" ] } } }, "PipelineHealth": { "type": "object", "required": [ "total_deals", "healthy_deals", "healthy_percentage", "stale_deals", "pending_actions", "critical_actions", "stale_threshold_days" ], "properties": { "total_deals": { "type": "integer" }, "healthy_deals": { "type": "integer" }, "healthy_percentage": { "type": "integer", "minimum": 0, "maximum": 100 }, "stale_deals": { "type": "integer" }, "pending_actions": { "type": "integer" }, "critical_actions": { "type": "integer" }, "stale_threshold_days": { "type": "integer" } } }, "SearchDeal": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "company_name": { "type": [ "string", "null" ] }, "stage": { "type": [ "string", "null" ] }, "value": { "type": [ "number", "null" ] }, "health": { "type": [ "string", "null" ] }, "win_probability": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 } } }, "SearchContact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ], "format": "email" }, "title": { "type": [ "string", "null" ] }, "role_type": { "type": [ "string", "null" ] }, "deal_id": { "type": [ "string", "null" ], "format": "uuid" }, "deal_title": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] } } }, "SearchResponse": { "type": "object", "properties": { "deals": { "type": "array", "items": { "$ref": "#/components/schemas/SearchDeal" } }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/SearchContact" } } } }, "BriefingResponse": { "type": "object", "properties": { "greeting": { "type": "string" }, "summary": { "type": "object", "properties": { "total_pipeline_value": { "type": "number" }, "active_deals": { "type": "integer" }, "at_risk_deals": { "type": "integer" } } }, "closing_this_week": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "stale_deals": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "at_risk_deals": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "signals_last_7_days": { "type": "object", "properties": { "positive": { "type": "integer" }, "negative": { "type": "integer" }, "competitor_mentions": { "type": "integer" } } } } }, "CoachingResponse": { "type": "object", "properties": { "period": { "type": "string" }, "win_rate": { "type": "string" }, "deals_won": { "type": "integer" }, "deals_lost": { "type": "integer" }, "avg_cycle_days": { "type": [ "integer", "null" ] }, "coaching_tips": { "type": "array", "items": { "type": "string" } } } }, "Webhook": { "type": "object", "required": [ "id", "url", "events", "is_active", "failure_count", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "is_active": { "type": "boolean" }, "failure_count": { "type": "integer", "minimum": 0 }, "last_triggered_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "WebhookCreateRequest": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/WebhookEvent" } } }, "additionalProperties": false }, "WebhookCreateResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "secret", "url", "events" ], "properties": { "id": { "type": "string", "format": "uuid" }, "secret": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } } } } } }, "WebhookEvent": { "type": "string", "enum": [ "deal.created", "deal.updated", "deal.stage_changed", "deal.won", "deal.lost", "contact.created", "contact.updated", "analysis.completed" ] }, "PredictionFactor": { "type": "object", "properties": { "factor": { "type": "string" }, "impact": { "type": "string", "enum": [ "high", "medium", "low" ] }, "description": { "type": "string" } } }, "PredictionRecommendation": { "type": "object", "properties": { "action": { "type": "string" }, "priority": { "type": "string", "enum": [ "high", "medium", "low" ] }, "reason": { "type": "string" } } }, "AiApiQuotaStatus": { "type": "object", "required": [ "used", "limit", "remaining", "reset_at" ], "properties": { "used": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1 }, "remaining": { "type": "integer", "minimum": 0 }, "reset_at": { "type": "string", "format": "date-time" } } }, "ApiQuotaStatus": { "type": "object", "required": [ "used", "limit", "remaining", "reset_at" ], "properties": { "used": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1 }, "remaining": { "type": "integer", "minimum": 0 }, "reset_at": { "type": "string", "format": "date-time" } } }, "UsageResponse": { "type": "object", "required": [ "period", "api_quota", "ai_api_quota", "api_calls" ], "properties": { "period": { "type": "object", "required": [ "start", "end" ], "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" } } }, "api_quota": { "$ref": "#/components/schemas/ApiQuotaStatus" }, "ai_api_quota": { "$ref": "#/components/schemas/AiApiQuotaStatus" }, "api_calls": { "type": "object", "required": [ "total_this_month", "by_key" ], "properties": { "total_this_month": { "type": "integer", "minimum": 0 }, "by_key": { "type": "array", "items": { "type": "object", "required": [ "keyId", "keyName", "count" ], "properties": { "keyId": { "type": "string", "format": "uuid" }, "keyName": { "type": "string" }, "count": { "type": "integer", "minimum": 0 } } } } } } } } } } }