{"openapi":"3.1.0","info":{"title":"ConnexMail Agent Operations API","version":"0.1.0","description":"Agent-native mailbox, communication, trust, workflow, and operations API for SaaS products, MCP servers, and agent platforms."},"servers":[{"url":"https://connexmail.com"}],"security":[],"paths":{"/api/connex/status":{"get":{"summary":"Describe the Connex status evaluation contract.","security":[],"responses":{"200":{"description":"Contract metadata and example payload."}}},"post":{"summary":"Evaluate a communication and return mapped app operations.","security":[{"serviceKey":[]},{"userSession":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusEvaluationRequest"}}}},"responses":{"200":{"description":"Status evaluation result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusEvaluationResponse"}}}},"401":{"description":"Missing or invalid Connex API key."},"403":{"description":"Service key lacks status:evaluate scope."},"429":{"description":"Rate or persistent quota exceeded."}}}},"/api/connex/key-check":{"get":{"summary":"Describe the Connex API-key validation and capability contract.","security":[],"responses":{"200":{"description":"Key-check metadata, scope mapping, and non-secret guarantees."}}},"post":{"summary":"Validate a Connex API key and return enabled endpoints without exposing secrets.","security":[{"serviceKey":[]}],"responses":{"200":{"description":"Service key is valid; enabled endpoints are returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyCheckResponse"}}}},"401":{"description":"Missing, invalid, or expired Connex API key."},"429":{"description":"Rate limit exceeded."}}}},"/api/connex/integration-event":{"get":{"summary":"Describe the unified Connex integration event contract.","security":[],"responses":{"200":{"description":"Integration event metadata and example payload."}}},"post":{"summary":"Ingest one SaaS, MCP, mailbox, or agent event and return status, operation buckets, graph hints, and a network envelope.","security":[{"serviceKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationEventRequest"}}}},"responses":{"200":{"description":"Unified integration event result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationEventResponse"}}}},"401":{"description":"Missing or invalid Connex API key."},"403":{"description":"Service key lacks status:evaluate scope."},"429":{"description":"Rate or persistent quota exceeded."}}}},"/api/connex/integration-preview":{"get":{"summary":"Describe the public no-storage integration preview contract.","security":[],"responses":{"200":{"description":"Preview metadata and example payload."}}},"post":{"summary":"Preview status, operation buckets, network envelope, and dry-run reasoning for any app/MCP/agent event without auth or persistence.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationEventRequest"}}}},"responses":{"200":{"description":"Summary-only preview result. No storage, no live model call, and no email sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationPreviewResponse"}}}},"400":{"description":"Invalid payload."},"413":{"description":"Preview payload too large."},"429":{"description":"Rate limit exceeded."}}}},"/api/connex/integration-outcome":{"get":{"summary":"Describe the Connex integration outcome contract.","security":[],"responses":{"200":{"description":"Outcome metadata and example payload."}}},"post":{"summary":"Record downstream results so Connex can learn which operations, agent relationships, and workflows create value.","security":[{"serviceKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationOutcomeRequest"}}}},"responses":{"200":{"description":"Outcome persisted, operation ledger updated when operationId matched, and learning signal returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationOutcomeResponse"}}}},"401":{"description":"Missing or invalid Connex API key."},"403":{"description":"Service key lacks status:evaluate scope."}}}},"/api/connex/integration-insights":{"get":{"summary":"Describe the Connex API-key integration intelligence contract.","security":[],"responses":{"200":{"description":"Integration insights metadata and non-secret guarantees."}}},"post":{"summary":"Return summary-only integration intelligence for a SaaS/app without exposing message bodies.","security":[{"serviceKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationInsightsRequest"}}}},"responses":{"200":{"description":"Tenant-scoped integration insights for the calling Connex API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationInsightsResponse"}}}},"401":{"description":"Missing or invalid Connex API key."},"403":{"description":"Service key lacks status:evaluate scope."},"429":{"description":"Rate limit exceeded."}}}},"/api/connex/trust":{"get":{"summary":"Describe the Connex trust and reputation signal contract.","security":[],"responses":{"200":{"description":"Trust metadata and non-secret guarantees."}}},"post":{"summary":"Return tenant-scoped trust and reputation signals for agent-network operations.","security":[{"serviceKey":[]}],"responses":{"200":{"description":"Trust score, band, signal breakdown, policy gates, and recommendation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrustResponse"}}}},"401":{"description":"Missing or invalid Connex API key."},"403":{"description":"Service key lacks status:evaluate scope."},"429":{"description":"Rate limit exceeded."}}}},"/api/connex/intelligence":{"get":{"summary":"Summarize integration events, operations, outcomes, and reasoning-provider use into network intelligence.","security":[{"userSession":[]}],"responses":{"200":{"description":"Network intelligence summary for the signed-in Connex tenant, including Mundo X/deterministic reasoning use."},"401":{"description":"Supabase user session required."}}}},"/api/connex/reasoning":{"get":{"summary":"Return safe reasoning-provider readiness for Connex and Mundo X.","security":[],"responses":{"200":{"description":"Reasoning provider status without endpoint URLs, API keys, prompts, or secrets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReasoningStatusResponse"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/connex/dispatch":{"post":{"summary":"Submit an account-gated agent task through Connex policy controls.","security":[{"userSession":[]}],"responses":{"200":{"description":"Dispatch accepted, blocked, or routed for approval."},"401":{"description":"Supabase user session required."}}}},"/api/connex/graph-event":{"post":{"summary":"Record account-gated relationship, opportunity, and agent graph events.","security":[{"userSession":[]}],"responses":{"200":{"description":"Graph event recorded and normalized."},"401":{"description":"Supabase user session required."}}}},"/api/connex/service-keys":{"get":{"summary":"List hashed Connex API-key records for the signed-in Connex user.","security":[{"userSession":[]}],"responses":{"200":{"description":"Connex API keys and allowed scopes."},"401":{"description":"Supabase user session required."}}},"post":{"summary":"Create a new Connex API key. Raw key is returned once.","security":[{"userSession":[]}],"responses":{"200":{"description":"Created key and non-secret record metadata."},"401":{"description":"Supabase user session required."}}}}},"components":{"securitySchemes":{"serviceKey":{"type":"http","scheme":"bearer","bearerFormat":"cxk_live_* Connex API key","description":"Create a Connex API key in Settings. Keys use the cxk_live_* format and should stay server-side. For status evaluation, include the status:evaluate scope."},"userSession":{"type":"apiKey","in":"cookie","name":"Supabase session","description":"Signed-in Connex Supabase session cookie used by the Connex web app and account-gated endpoints."}},"schemas":{"StatusEvaluationRequest":{"type":"object","required":["app","message"],"properties":{"app":{"type":"string","examples":["your-saas","mcp-server","buyboxclub"]},"currentStatus":{"type":"string","examples":["LOI Sent"]},"externalIds":{"type":"object","properties":{"accountId":{"type":"string"},"userId":{"type":"string"},"objectType":{"type":"string","examples":["opportunity","ticket","deal","task"]},"objectId":{"type":"string","examples":["opp_123"]},"threadId":{"type":"string"},"messageId":{"type":"string"}}},"message":{"type":"object","required":["subject","body"],"properties":{"from":{"type":"string"},"to":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"}}},"context":{"type":"object","additionalProperties":true,"properties":{"market":{"type":"string"},"propertyType":{"type":"string"},"askingPrice":{"type":"number"},"arv":{"type":"number"},"repairs":{"type":"number"}}},"workflow":{"type":"object","additionalProperties":true,"description":"Optional app-native statuses, inboxes, transitions, and canonical status mappings."}}},"KeyCheckResponse":{"type":"object","required":["ok","type","caller","enabledEndpoints"],"properties":{"ok":{"type":"boolean","const":true},"type":{"type":"string","const":"connex.key_check.result"},"caller":{"type":"object","properties":{"type":{"type":"string","const":"service_key"},"id":{"type":"string"},"tenantId":{"type":"string"},"userId":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}}}},"enabledEndpoints":{"type":"array","items":{"type":"object","properties":{"endpoint":{"type":"string"},"scope":{"type":"string"},"purpose":{"type":"string"},"enabled":{"type":"boolean"}}}},"recommendedMinimum":{"type":"object","additionalProperties":true}}},"IntegrationEventRequest":{"allOf":[{"$ref":"#/components/schemas/StatusEvaluationRequest"},{"type":"object","properties":{"eventType":{"type":"string","examples":["inbound_reply","outbound_sent","agent_task_created","mcp_tool_result"]},"sourceSystem":{"type":"string","examples":["your-saas","mcp-server","buyboxclub"]},"sourceEventId":{"type":"string","examples":["evt_123"]},"applyMode":{"type":"string","enum":["recommend","materialize_safe"],"default":"recommend"},"sourceMailbox":{"$ref":"#/components/schemas/SourceMailboxControl"},"actor":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"type":"string"}}},"object":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"type":"string"}}}}}]},"StatusEvaluationResponse":{"type":"object","required":["type","tenantId","canonical","mapped","operations","integration"],"properties":{"type":{"type":"string","const":"connex.status.evaluation"},"tenantId":{"type":"string"},"canonical":{"type":"object","properties":{"status":{"type":"string"},"priority":{"type":"string"},"confidence":{"type":"number"},"nextBestAction":{"type":"string"},"approvalRequired":{"type":"boolean"},"safeActions":{"type":"array","items":{"type":"string"}},"blockedActions":{"type":"array","items":{"type":"string"}},"fitScore":{"type":"number"}}},"mapped":{"type":"object","properties":{"appId":{"type":"string"},"appName":{"type":"string"},"currentStatus":{"type":["string","null"]},"status":{"type":"string"},"inbox":{"type":"string"},"taskType":{"type":"string"},"transitionAllowed":{"type":"boolean"},"transitionReason":{"type":"string"}}},"operations":{"type":"array","items":{"$ref":"#/components/schemas/AppOperation"}},"integration":{"type":"object","properties":{"mode":{"type":"string","const":"recommend"},"idempotencyKey":{"type":"string"},"applyOrder":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}}}}}},"IntegrationEventResponse":{"type":"object","required":["type","tenantId","status","operationBuckets","networkEnvelope","graphHints"],"properties":{"type":{"type":"string","const":"connex.integration.event.result"},"tenantId":{"type":"string"},"status":{"$ref":"#/components/schemas/StatusEvaluationResponse"},"operationBuckets":{"type":"object","properties":{"autoApply":{"type":"array","items":{"$ref":"#/components/schemas/AppOperation"}},"humanReview":{"type":"array","items":{"$ref":"#/components/schemas/AppOperation"}},"blocked":{"type":"array","items":{"$ref":"#/components/schemas/AppOperation"}},"drafts":{"type":"array","items":{"$ref":"#/components/schemas/AppOperation"}}}},"networkEnvelope":{"type":"object","properties":{"sourceSystem":{"type":"string"},"sourceEventId":{"type":"string"},"app":{"type":"string"},"objectType":{"type":"string"},"objectId":{"type":["string","null"]},"messageId":{"type":["string","null"]},"recommendedAgentAction":{"type":"string"},"trustRequired":{"type":"string","enum":["low","medium","high"]},"humanApprovalRequired":{"type":"boolean"}}},"materialization":{"type":"object","description":"Recommend by default. In materialize_safe mode, selected task/approval/draft operations become internal agent dispatch records.","properties":{"mode":{"type":"string","enum":["recommend","materialize_safe"]},"materialized":{"type":"boolean"},"dispatches":{"type":"array","items":{"type":"object","additionalProperties":true}},"skipped":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"graphHints":{"type":"object","description":"Suggested graph nodes/relationships for customers, MCP servers, and agent platforms that want relationship memory."},"shadowMessage":{"type":"object","description":"Receipt for the source-controlled mailbox copy, if Connex persisted it.","properties":{"persisted":{"type":"boolean"},"messageId":{"type":"string"},"threadId":{"type":"string"},"senderIdentityOwner":{"type":"string","enum":["connex","source_app","customer_domain"]},"replyPolicy":{"type":"string","enum":["connex_allowed","source_app_only","disabled"]},"externalReplyUrl":{"type":"string"},"reason":{"type":"string"}}},"reasoning":{"type":"object","description":"Dry-run or live supervised reasoning metadata. Mundo X can guide negotiation, but cannot auto-send or override Connex policy.","properties":{"provider":{"type":"string","enum":["deterministic","mundox"]},"mode":{"type":"string","enum":["disabled","dry_run","live"]},"model":{"type":"string"},"usedLiveModel":{"type":"boolean"},"negotiationSpecialist":{"type":"boolean"},"recommendedInstruction":{"type":"string"}}}}},"IntegrationPreviewResponse":{"type":"object","required":["type","previewOnly","persistence","status","operationBuckets","networkEnvelope","reasoning","guarantees"],"properties":{"type":{"type":"string","const":"connex.integration.preview.result"},"previewOnly":{"type":"boolean","const":true},"persistence":{"type":"object","properties":{"persisted":{"type":"boolean","const":false},"reason":{"type":"string","const":"public_preview_no_storage"}}},"status":{"type":"object","description":"Summary-only status evaluation with no message body echo."},"operationBuckets":{"type":"object","description":"Operation type names only; no draft body or confidential payloads."},"networkEnvelope":{"type":"object"},"reasoning":{"type":"object","properties":{"provider":{"type":"string","enum":["deterministic","mundox"]},"mode":{"type":"string","const":"dry_run"},"usedLiveModel":{"type":"boolean","const":false}}},"guarantees":{"type":"array","items":{"type":"string"}}}},"ReasoningStatusResponse":{"type":"object","required":["type","status"],"properties":{"type":{"type":"string","const":"connex.reasoning.status"},"status":{"type":"object","properties":{"provider":{"type":"string","enum":["deterministic","mundox"]},"mode":{"type":"string","enum":["disabled","dry_run","live"]},"model":{"type":"string"},"endpointConfigured":{"type":"boolean"},"liveCallsEnabled":{"type":"boolean"},"timeoutMs":{"type":"integer"},"specialistProfiles":{"type":"array","items":{"type":"object","additionalProperties":true}},"safetyInvariants":{"type":"array","items":{"type":"string"}},"integrationContract":{"type":"object","additionalProperties":true}}}}},"IntegrationOutcomeRequest":{"type":"object","required":["sourceSystem","sourceOutcomeId","outcomeType","valueScore"],"properties":{"sourceSystem":{"type":"string","examples":["your-saas","mcp-server","buyboxclub"]},"sourceOutcomeId":{"type":"string"},"integrationEventId":{"type":"string"},"operationId":{"type":"string"},"outcomeType":{"type":"string","enum":["operation_applied","operation_failed","human_approved","human_rejected","reply_sent","meeting_booked","deal_advanced","deal_won","deal_lost","bad_classification","spam_complaint","manual_override"]},"valueScore":{"type":"integer","minimum":-100,"maximum":100},"revenueCents":{"type":"integer"},"latencyMs":{"type":"integer"},"notes":{"type":"string"},"payload":{"type":"object","additionalProperties":true}}},"IntegrationOutcomeResponse":{"type":"object","required":["ok","tenantId","persistence","learning"],"properties":{"ok":{"type":"boolean"},"tenantId":{"type":"string"},"persistence":{"type":"object","properties":{"persisted":{"type":"boolean"},"outcomeId":{"type":"string"},"learningSignal":{"type":"string","enum":["positive_operation_signal","positive_outcome_signal","negative_classification_signal","deliverability_risk_signal","human_override_signal","integration_failure_signal","negative_outcome_signal","neutral_outcome_signal"]},"operation":{"type":"object","properties":{"requestedOperationId":{"type":["string","null"]},"matched":{"type":"boolean"},"appliedStatus":{"type":["string","null"],"enum":["recommended","applied","skipped","failed","approved","rejected",null]}}}}},"learning":{"type":"object","properties":{"signal":{"type":"string"},"operationMatched":{"type":"boolean"},"operationAppliedStatus":{"type":["string","null"]}}}}},"IntegrationInsightsRequest":{"type":"object","properties":{"sourceSystem":{"type":"string","examples":["your-saas","mcp-server","buyboxclub"]},"app":{"type":"string","examples":["your-saas","mcp-server","buyboxclub"]},"objectType":{"type":"string","examples":["opportunity","ticket","deal","task"]},"objectId":{"type":"string","examples":["opp_123"]},"limit":{"type":"integer","minimum":1,"maximum":100}}},"IntegrationInsightsResponse":{"type":"object","required":["ok","type","tenantId","summary","guarantees"],"properties":{"ok":{"type":"boolean","const":true},"type":{"type":"string","const":"connex.integration.insights.result"},"tenantId":{"type":"string"},"filters":{"type":"object","additionalProperties":true},"summary":{"type":"object","properties":{"events":{"type":"integer"},"operations":{"type":"integer"},"outcomes":{"type":"integer"},"approvalRate":{"type":"integer"},"blockedRate":{"type":"integer"},"appliedRate":{"type":"integer"},"avgValueScore":{"type":"integer"},"negativeOutcomes":{"type":"integer"},"reasoningEvents":{"type":"integer"}}},"byStatus":{"type":"array","items":{"type":"object","additionalProperties":true}},"byOutcome":{"type":"array","items":{"type":"object","additionalProperties":true}},"byReasoningProvider":{"type":"array","items":{"type":"object","additionalProperties":true}},"recentStatusTransitions":{"type":"array","items":{"type":"object","additionalProperties":true}},"recommendation":{"type":"string"},"guarantees":{"type":"array","items":{"type":"string"}}}},"SourceMailboxControl":{"type":"object","description":"Controls who owns the visible mailbox identity and whether Connex may reply. Required for source-app and customer-domain shadow copies.","properties":{"senderIdentityOwner":{"type":"string","enum":["connex","source_app","customer_domain"],"description":"connex means Connex owns the address; source_app means another app owns the thread; customer_domain means the customer's verified domain owns the visible sender."},"replyPolicy":{"type":"string","enum":["connex_allowed","source_app_only","disabled"],"description":"connex_allowed permits Connex-origin replies if policy allows; source_app_only stores/analyzes/routes while the source app replies; disabled hides reply actions."},"externalReplyUrl":{"type":"string","description":"Deep link the Connex UI can show when replies must happen in the source app."}}},"TrustResponse":{"type":"object","required":["ok","type","tenantId","score","band","policyGates","signals","guarantees"],"properties":{"ok":{"type":"boolean","const":true},"type":{"type":"string","const":"connex.trust.result"},"tenantId":{"type":"string"},"score":{"type":"integer","minimum":0,"maximum":100},"band":{"type":"string","enum":["high_trust","trusted","emerging","restricted"]},"policyGates":{"type":"object","properties":{"liveOutboundRequiresVerifiedDomain":{"type":"boolean"},"highRiskActionsRequireApproval":{"type":"boolean"},"modelGuidanceCannotAutoSend":{"type":"boolean"},"complaintPausesOutbound":{"type":"boolean"},"trustBelow70RestrictsNetworkDispatch":{"type":"boolean"}}},"signals":{"type":"object","additionalProperties":true},"recommendation":{"type":"string"},"guarantees":{"type":"array","items":{"type":"string"}}}},"AppOperation":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["write_audit_event","route_inbox","update_status","create_task","draft_reply","require_approval","suppress_contact"]},"label":{"type":"string"},"target":{"type":"object","properties":{"objectType":{"type":"string"},"objectId":{"type":["string","null"]}}},"payload":{"type":"object","additionalProperties":true},"approvalRequired":{"type":"boolean"},"blocked":{"type":"boolean"},"reason":{"type":"string"}}}}}}