{ "openapi": "3.1.0", "info": { "title": "Vision CRM Authenticated API", "version": "3.0.0", "description": "The commercial-domain API consumed by authenticated Vision clients. Vision supplies identity; CRM authorizes workspace and domain capabilities." }, "tags": [ { "name": "Operations" }, { "name": "Vision CRM" } ], "paths": { "/api/health": { "get": { "tags": [ "Operations" ], "summary": "Process liveness", "responses": { "200": { "description": "The process is alive" } }, "security": [] } }, "/api/ready": { "get": { "tags": [ "Operations" ], "summary": "Authenticated API database readiness", "responses": { "200": { "description": "The CRM authenticated schema is ready" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "security": [] } }, "/api/crm/v1/meta": { "get": { "tags": [ "Vision CRM" ], "summary": "Contract and version metadata", "responses": { "200": { "description": "Supported contracts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiMetadata" } } } } }, "security": [] } }, "/api/crm/v1/today": { "get": { "tags": [ "Vision CRM" ], "summary": "Explainable CRM attention queue", "security": [ { "visionBearer": [] } ], "responses": { "200": { "description": "Current workspace attention items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Today" } } } }, "401": { "$ref": "#/components/responses/AuthenticationFailure" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-required-scope": "crm:today:read" } }, "/api/crm/v1/intake-submissions": { "get": { "tags": [ "Vision CRM" ], "summary": "Paginated quarantined intake queue", "security": [ { "visionBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/IntakeStatus" } }, { "name": "state", "in": "query", "description": "Mutually exclusive with status", "schema": { "enum": [ "pending", "final", "all" ] } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "minLength": 20, "maxLength": 500 } } ], "responses": { "200": { "description": "Intake queue page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntakeQueue" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/AuthenticationFailure" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-required-scope": "crm:intake:read" } }, "/api/crm/v1/intake-submissions/{reference}": { "get": { "tags": [ "Vision CRM" ], "summary": "Quarantined intake detail and provenance", "security": [ { "visionBearer": [] } ], "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^IN-[A-F0-9]{12}$" } } ], "responses": { "200": { "description": "Intake detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntakeDetail" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/AuthenticationFailure" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-required-scope": "crm:intake:read" } }, "/api/crm/v1/people": { "get": { "tags": [ "Vision CRM" ], "summary": "Browse canonical people", "security": [ { "visionBearer": [] } ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "status", "in": "query", "schema": { "enum": [ "active", "inactive", "suppressed", "archived" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "People page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeoplePage" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/AuthenticationFailure" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-required-scope": "crm:people:read" } }, "/api/crm/v1/people/{reference}": { "get": { "tags": [ "Vision CRM" ], "summary": "Read a canonical person briefing", "security": [ { "visionBearer": [] } ], "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^PER-[A-F0-9]{12}$" } } ], "responses": { "200": { "description": "Person briefing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonDetail" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/AuthenticationFailure" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-required-scope": "crm:people:read" } }, "/api/crm/v1/organizations": { "get": { "tags": [ "Vision CRM" ], "summary": "Browse canonical organizations", "security": [ { "visionBearer": [] } ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "status", "in": "query", "schema": { "enum": [ "active", "inactive", "archived" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organizations page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationsPage" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/AuthenticationFailure" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-required-scope": "crm:organizations:read" } }, "/api/crm/v1/organizations/{reference}": { "get": { "tags": [ "Vision CRM" ], "summary": "Read a canonical organization briefing", "security": [ { "visionBearer": [] } ], "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ORG-[A-F0-9]{12}$" } } ], "responses": { "200": { "description": "Organization briefing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDetail" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/AuthenticationFailure" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-required-scope": "crm:organizations:read" } }, "/api/crm/v1/opportunities": { "get": { "tags": [ "Vision CRM" ], "summary": "Browse the authoritative commercial pipeline", "security": [ { "visionBearer": [] } ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "stage", "in": "query", "schema": { "$ref": "#/components/schemas/OpportunityStage" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "owner", "in": "query", "required": false, "schema": { "oneOf": [ { "const": "none" }, { "type": "string", "pattern": "^ACR-[A-F0-9]{12}$" } ] }, "description": "\"none\" lists opportunities nobody owns -- the pool. An ACR- actor reference lists one actor's work." } ], "responses": { "200": { "description": "Opportunity page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunitiesPage" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/AuthenticationFailure" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-required-scope": "crm:opportunities:read" } }, "/api/crm/v1/opportunities/{reference}": { "get": { "tags": [ "Vision CRM" ], "summary": "Read authoritative opportunity detail", "security": [ { "visionBearer": [] } ], "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^OP-[A-F0-9]{12}$" } } ], "responses": { "200": { "description": "Opportunity detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityDetail" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/AuthenticationFailure" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-required-scope": "crm:opportunities:read" } }, "/api/crm/v1/tasks": { "get": { "tags": [ "Vision CRM" ], "summary": "Browse assigned CRM work", "security": [ { "visionBearer": [] } ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "status", "in": "query", "schema": { "enum": [ "open", "in_progress", "waiting", "completed", "cancelled" ] } }, { "name": "owner", "in": "query", "schema": { "enum": [ "mine", "all" ], "default": "mine" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TasksPage" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/AuthenticationFailure" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-required-scope": "crm:tasks:read" } }, "/api/crm/v1/search": { "get": { "tags": [ "Vision CRM" ], "summary": "Search authorized canonical CRM records", "security": [ { "visionBearer": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "Bounded search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Search" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/AuthenticationFailure" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-required-scope": "crm:search:read" } }, "/api/crm/v1/commands": { "post": { "tags": [ "Vision CRM" ], "summary": "Apply a controlled human CRM record command", "description": "Creates or changes a canonical Person, Organization, Opportunity, Activity, or Task with scope checks, role checks, idempotency, optimistic versions, audit evidence, and an outbox event. Projects delivery records remain outside CRM.", "security": [ { "visionBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrmCommand" } } } }, "responses": { "201": { "description": "Command committed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrmCommandResult" } } } }, "200": { "description": "Exact replay returned its durable result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrmCommandResult" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/AuthenticationFailure" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Invalid state, stale version, or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-required-scope": [ "crm:opportunities:write", "crm:organizations:write", "crm:people:write", "crm:tasks:write" ] } }, "/api/crm/v1/intake-review-commands": { "post": { "tags": [ "Vision CRM" ], "summary": "Apply an authorized, idempotent intake-review command", "security": [ { "visionBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntakeReviewCommand" } } } }, "responses": { "201": { "description": "The review command committed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntakeReviewResult" } } } }, "200": { "description": "An exact replay returned its durable result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntakeReviewResult" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/AuthenticationFailure" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Invalid state, stale version, or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-required-scope": "crm:intake:review" } }, "/api/crm/v1/people/{reference}/timeline": { "get": { "tags": [ "Vision CRM" ], "summary": "Chronological activity timeline for a person", "operationId": "getPersonTimeline", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^PER-[A-F0-9]{12}$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque signed cursor from a previous response's nextCursor." } ], "responses": { "200": { "description": "One chronological timeline for the person", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Timeline" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "visionBearer": [] } ], "x-required-scope": "crm:people:read" } }, "/api/crm/v1/funnel": { "get": { "tags": [ "Vision CRM" ], "summary": "Pipeline funnel: occupancy, flow and dwell per stage", "operationId": "getFunnel", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Window start for entered/exited counts. Defaults to 30 days before `to`." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Window end. Defaults to now." } ], "responses": { "200": { "description": "The pipeline as of now, with flow measured over the window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funnel" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" } }, "security": [ { "visionBearer": [] } ], "x-required-scope": "crm:opportunities:read" } }, "/api/crm/v1/actors": { "get": { "tags": [ "Vision CRM" ], "summary": "Actors who can own work here, with current workload", "operationId": "getActors", "parameters": [], "responses": { "200": { "description": "Actors with active workspace membership", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Actors" } } } } }, "security": [ { "visionBearer": [] } ], "x-required-scope": "crm:today:read" } }, "/api/crm/v1/presentation": { "get": { "tags": [ "Vision CRM" ], "summary": "CRM's navigation, views and actions, filtered to this caller", "description": "Returns only what the caller can reach. Filtering is by effective permission -- granted scope narrowed by identity class -- so an agent is never offered an action its own authorizer would refuse. The endpoint grants nothing: every section returned is one the caller could already call directly.", "operationId": "getPresentation", "parameters": [], "responses": { "200": { "description": "The descriptor as this caller may see it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Presentation" } } } } }, "security": [ { "visionBearer": [] } ], "x-required-scope": "crm:today:read" } } }, "components": { "securitySchemes": { "visionBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Vision-issued access token (JWT). Obtain via the token endpoint of the identity provider configured for this installation." } }, "responses": { "AuthenticationFailure": { "description": "Authentication is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PermissionDenied": { "description": "The authenticated actor lacks the CRM capability or workspace binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "InvalidRequest": { "description": "The request is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "No accessible CRM record was found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "DependencyUnavailable": { "description": "The CRM dependency or authenticated API configuration is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "ApiMetadata": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "service", "status", "contracts", "openapiPath" ], "properties": { "schemaVersion": { "const": "vision-crm-authenticated.v1" }, "service": { "const": "vision-crm" }, "status": { "const": "available" }, "contracts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "name", "version" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" } } } }, "openapiPath": { "const": "/api/crm/v1/openapi.json" } } }, "Error": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "status", "code", "message", "retryable", "correlationId", "fieldIssues", "conflict" ], "properties": { "schemaVersion": { "const": "vision-crm-error.v1" }, "status": { "const": "failed" }, "code": { "enum": [ "AUTHENTICATION_REQUIRED", "INVALID_CREDENTIAL", "PERMISSION_DENIED", "INVALID_REQUEST", "INVALID_STATE", "NOT_FOUND", "STALE_VERSION", "IDEMPOTENCY_CONFLICT", "DEPENDENCY_UNAVAILABLE", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "correlationId": { "type": "string", "format": "uuid" }, "fieldIssues": { "type": "array", "items": { "type": "object" } }, "conflict": { "oneOf": [ { "type": "null" }, { "type": "object" } ] } } }, "Priority": { "type": "object", "additionalProperties": false, "required": [ "score", "reasonCodes", "explanation" ], "properties": { "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "reasonCodes": { "type": "array", "items": { "enum": [ "overdue", "due_soon", "waiting_on_ivision", "stale", "missing_next_action" ] } }, "explanation": { "type": "string" } } }, "AttentionItem": { "type": "object", "additionalProperties": false, "required": [ "type", "publicReference", "title", "summary", "owner", "dueAt", "priority", "recordVersion" ], "properties": { "type": { "enum": [ "task", "opportunity" ] }, "publicReference": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": [ "string", "null" ] }, "owner": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "publicReference", "displayName" ], "properties": { "publicReference": { "type": "string", "pattern": "^ACR-[A-F0-9]{12}$" }, "displayName": { "type": "string" } } }, { "type": "null" } ], "description": "Null when unassigned. publicReference replaced identity_subject, which leaked the identity provider's id for a human into this contract." }, "dueAt": { "type": [ "string", "null" ], "format": "date-time" }, "priority": { "$ref": "#/components/schemas/Priority" }, "recordVersion": { "type": "integer", "minimum": 1 } } }, "Today": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "generatedAt", "workspace", "counts", "attention", "recentChanges" ], "properties": { "schemaVersion": { "const": "vision-crm-today.v1" }, "generatedAt": { "type": "string", "format": "date-time" }, "workspace": { "type": "string" }, "counts": { "type": "object" }, "attention": { "type": "array", "items": { "$ref": "#/components/schemas/AttentionItem" } }, "recentChanges": { "type": "array", "maxItems": 25, "items": { "type": "object", "required": [ "action", "subjectType", "publicReference", "occurredAt", "actor" ], "properties": { "action": { "type": "string" }, "subjectType": { "enum": [ "task", "opportunity", "intake_submission" ] }, "publicReference": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "actor": { "type": "object", "required": [ "displayName" ], "properties": { "displayName": { "type": "string" } } } } } } } }, "RecordOwner": { "type": "object", "additionalProperties": false, "required": [ "subject", "displayName" ], "properties": { "subject": { "type": "string" }, "displayName": { "type": "string" } } }, "OpportunityStage": { "enum": [ "new", "review_needed", "exploring", "qualified", "solution_shaping", "proposal_or_decision", "won", "deferred", "closed_not_proceeding" ] }, "PeoplePage": { "type": "object", "additionalProperties": false, "description": "Exact item fields are enforced by the v1 runtime schema and compatibility fixture.", "required": [ "schemaVersion", "items", "nextCursor" ], "properties": { "schemaVersion": { "const": "vision-crm-people-page.v2" }, "items": { "type": "array", "maxItems": 50, "items": { "type": "object" } }, "nextCursor": { "type": [ "string", "null" ] } } }, "PersonDetail": { "type": "object", "additionalProperties": false, "description": "Canonical person and bounded organization, opportunity, and open-task links. Exact fields are enforced by the v1 runtime schema and fixture.", "required": [ "schemaVersion", "publicReference", "displayName", "owner", "organizations", "opportunities", "openTasks", "recordVersion" ], "properties": { "schemaVersion": { "const": "vision-crm-person-detail.v2" }, "publicReference": { "type": "string", "pattern": "^PER-[A-F0-9]{12}$" }, "displayName": { "type": "string" }, "owner": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "publicReference", "displayName" ], "properties": { "publicReference": { "type": "string", "pattern": "^ACR-[A-F0-9]{12}$" }, "displayName": { "type": "string" } } }, { "type": "null" } ], "description": "Null when unassigned. publicReference replaced identity_subject, which leaked the identity provider's id for a human into this contract." }, "organizations": { "type": "array", "items": { "type": "object" } }, "opportunities": { "type": "array", "items": { "type": "object" } }, "openTasks": { "type": "array", "items": { "type": "object" } }, "recordVersion": { "type": "integer", "minimum": 1 } } }, "OrganizationsPage": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "items", "nextCursor" ], "properties": { "schemaVersion": { "const": "vision-crm-organizations-page.v2" }, "items": { "type": "array", "maxItems": 50, "items": { "type": "object" } }, "nextCursor": { "type": [ "string", "null" ] } } }, "OrganizationDetail": { "type": "object", "additionalProperties": false, "description": "Canonical organization and bounded people, opportunity, and open-task links. Exact fields are enforced by the v1 runtime schema and fixture.", "required": [ "schemaVersion", "publicReference", "name", "owner", "people", "opportunities", "openTasks", "recordVersion" ], "properties": { "schemaVersion": { "const": "vision-crm-organization-detail.v2" }, "publicReference": { "type": "string", "pattern": "^ORG-[A-F0-9]{12}$" }, "name": { "type": "string" }, "owner": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "publicReference", "displayName" ], "properties": { "publicReference": { "type": "string", "pattern": "^ACR-[A-F0-9]{12}$" }, "displayName": { "type": "string" } } }, { "type": "null" } ], "description": "Null when unassigned. publicReference replaced identity_subject, which leaked the identity provider's id for a human into this contract." }, "people": { "type": "array", "items": { "type": "object" } }, "opportunities": { "type": "array", "items": { "type": "object" } }, "openTasks": { "type": "array", "items": { "type": "object" } }, "recordVersion": { "type": "integer", "minimum": 1 } } }, "OpportunitiesPage": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "items", "nextCursor" ], "properties": { "schemaVersion": { "const": "vision-crm-opportunities-page.v2" }, "items": { "type": "array", "maxItems": 50, "items": { "type": "object" } }, "nextCursor": { "type": [ "string", "null" ] } } }, "OpportunityDetail": { "type": "object", "additionalProperties": false, "description": "Authoritative opportunity state, participants, and open work. Exact fields are enforced by the v1 runtime schema and fixture.", "required": [ "schemaVersion", "publicReference", "problemStatement", "stage", "owner", "participants", "openTasks", "recordVersion" ], "properties": { "schemaVersion": { "const": "vision-crm-opportunity-detail.v2" }, "publicReference": { "type": "string", "pattern": "^OP-[A-F0-9]{12}$" }, "problemStatement": { "type": "string" }, "stage": { "$ref": "#/components/schemas/OpportunityStage" }, "owner": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "publicReference", "displayName" ], "properties": { "publicReference": { "type": "string", "pattern": "^ACR-[A-F0-9]{12}$" }, "displayName": { "type": "string" } } }, { "type": "null" } ], "description": "Null when unassigned. publicReference replaced identity_subject, which leaked the identity provider's id for a human into this contract." }, "participants": { "type": "array", "items": { "type": "object" } }, "openTasks": { "type": "array", "items": { "type": "object" } }, "recordVersion": { "type": "integer", "minimum": 1 } } }, "TasksPage": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "items", "nextCursor" ], "properties": { "schemaVersion": { "const": "vision-crm-tasks-page.v2" }, "items": { "type": "array", "maxItems": 50, "items": { "type": "object" } }, "nextCursor": { "type": [ "string", "null" ] } } }, "Search": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "query", "results" ], "properties": { "schemaVersion": { "const": "vision-crm-search.v1" }, "query": { "type": "string" }, "results": { "type": "array", "maxItems": 50, "items": { "type": "object" } } } }, "IntakeStatus": { "enum": [ "received", "screening", "review_needed", "accepted", "dismissed", "failed" ] }, "IntakeQueueItem": { "type": "object", "additionalProperties": false, "required": [ "publicReference", "status", "channel", "submittedName", "submittedOrganization", "statedProblem", "requestedRoute", "riskStatus", "receivedAt", "recordVersion" ], "properties": { "publicReference": { "type": "string" }, "status": { "$ref": "#/components/schemas/IntakeStatus" }, "channel": { "type": "string" }, "submittedName": { "type": [ "string", "null" ] }, "submittedOrganization": { "type": [ "string", "null" ] }, "statedProblem": { "type": "string" }, "requestedRoute": { "type": "string" }, "riskStatus": { "type": [ "string", "null" ] }, "receivedAt": { "type": "string", "format": "date-time" }, "recordVersion": { "type": "integer", "minimum": 1 } } }, "IntakeQueue": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "items", "nextCursor", "totalCount" ], "properties": { "schemaVersion": { "const": "vision-crm-intake-queue.v2" }, "items": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/IntakeQueueItem" } }, "nextCursor": { "type": [ "string", "null" ] }, "totalCount": { "type": "integer", "description": "How many submissions match the filter, independent of paging. The review queue badge reads this." } } }, "IntakeDetail": { "type": "object", "description": "Full quarantined intake, consent evidence, source attribution and processing history. The field-level contract is additionally enforced by the published Zod schema and compatibility fixture.", "required": [ "schemaVersion", "publicReference", "status", "contact", "processingEvents", "review", "linkedRecords", "reviewHistory", "recordVersion" ], "properties": { "schemaVersion": { "const": "vision-crm-intake-detail.v2" }, "publicReference": { "type": "string" }, "status": { "$ref": "#/components/schemas/IntakeStatus" }, "contact": { "type": "object" }, "processingEvents": { "type": "array", "items": { "type": "object" } }, "review": { "oneOf": [ { "type": "null" }, { "type": "object" } ] }, "linkedRecords": { "type": "object" }, "reviewHistory": { "type": "array", "maxItems": 100, "items": { "type": "object" } }, "recordVersion": { "type": "integer", "minimum": 1 } } }, "CrmCommand": { "type": "object", "description": "Strict discriminated command. Runtime validation applies command-specific data fields and reference formats.", "required": [ "schemaVersion", "commandType", "idempotencyKey", "data" ], "properties": { "schemaVersion": { "const": "vision-crm-command.v1" }, "commandType": { "enum": [ "person.create", "person.update", "organization.create", "organization.update", "opportunity.create", "opportunity.update", "opportunity.stage", "activity.create", "task.create", "task.update" ] }, "idempotencyKey": { "type": "string", "minLength": 16, "maxLength": 160 }, "targetReference": { "type": "string" }, "expectedVersion": { "type": "integer", "minimum": 1 }, "data": { "type": "object" } } }, "CrmCommandResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "commandReference", "commandType", "targetReference", "resultingVersion", "replayed" ], "properties": { "schemaVersion": { "const": "vision-crm-command-result.v1" }, "commandReference": { "type": "string", "pattern": "^CCM-[A-F0-9]{12}$" }, "commandType": { "type": "string" }, "targetReference": { "type": "string" }, "resultingVersion": { "type": "integer", "minimum": 1 }, "replayed": { "type": "boolean" } } }, "IntakeReviewCommand": { "type": "object", "description": "Strict discriminated command. See the compatibility request fixture and runtime schema for action-specific fields.", "required": [ "schemaVersion", "intakeReference", "expectedRecordVersion", "idempotencyKey", "action" ], "properties": { "schemaVersion": { "const": "vision-crm-intake-review-command.v1" }, "intakeReference": { "type": "string", "pattern": "^IN-[A-F0-9]{12}$" }, "expectedRecordVersion": { "type": "integer", "minimum": 1 }, "idempotencyKey": { "type": "string", "minLength": 16, "maxLength": 160 }, "action": { "enum": [ "accept_create", "accept_connect", "dismiss", "leave_pending", "request_information", "retry" ] } } }, "IntakeReviewResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "commandReference", "intakeReference", "disposition", "resultingRecordVersion", "linkedRecords", "replayed" ], "properties": { "schemaVersion": { "const": "vision-crm-intake-review-result.v1" }, "commandReference": { "type": "string", "pattern": "^CMD-[A-F0-9]{12}$" }, "intakeReference": { "type": "string", "pattern": "^IN-[A-F0-9]{12}$" }, "disposition": { "enum": [ "accepted", "dismissed", "pending", "information_requested", "retry_requested" ] }, "resultingRecordVersion": { "type": "integer", "minimum": 1 }, "linkedRecords": { "type": "object" }, "replayed": { "type": "boolean" } } }, "Timeline": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "subject", "entries", "nextCursor" ], "properties": { "schemaVersion": { "const": "vision-crm-timeline.v1" }, "subject": { "type": "object", "additionalProperties": false, "required": [ "kind", "publicReference", "displayName" ], "properties": { "kind": { "enum": [ "person", "organization", "opportunity" ] }, "publicReference": { "type": "string" }, "displayName": { "type": "string" } } }, "entries": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/TimelineEntry" } }, "nextCursor": { "type": [ "string", "null" ] } } }, "TimelineEntry": { "type": "object", "additionalProperties": false, "required": [ "publicReference", "type", "direction", "subject", "bodyText", "restricted", "occurredAt", "authorType", "authorName", "relatedTo" ], "properties": { "publicReference": { "type": "string", "pattern": "^ACT-[A-F0-9]{12}$" }, "type": { "type": "string" }, "direction": { "enum": [ "inbound", "outbound", "internal", "none" ] }, "subject": { "type": [ "string", "null" ] }, "bodyText": { "type": [ "string", "null" ], "description": "Null when restricted is true: withheld, not omitted." }, "restricted": { "type": "boolean" }, "occurredAt": { "type": "string", "format": "date-time" }, "authorType": { "enum": [ "user", "system", "provider", "ai" ] }, "authorName": { "type": [ "string", "null" ] }, "relatedTo": { "type": "array", "maxItems": 50, "items": { "type": "object", "additionalProperties": false, "required": [ "kind", "publicReference" ], "properties": { "kind": { "enum": [ "person", "organization", "opportunity", "task", "intake_submission" ] }, "publicReference": { "type": "string" } } } } } }, "FunnelStage": { "type": "object", "additionalProperties": false, "required": [ "stage", "openCount", "valueMinMinor", "valueMaxMinor", "currency", "enteredInWindow", "exitedInWindow", "medianHoursInStage", "medianHoursOpenSoFar" ], "properties": { "stage": { "type": "string" }, "openCount": { "type": "integer" }, "valueMinMinor": { "type": [ "integer", "null" ] }, "valueMaxMinor": { "type": [ "integer", "null" ] }, "currency": { "type": [ "string", "null" ] }, "enteredInWindow": { "type": "integer" }, "exitedInWindow": { "type": "integer" }, "medianHoursInStage": { "type": [ "number", "null" ], "description": "Median dwell of COMPLETED stays only. Opportunities still in the stage are excluded; counting their partial stay would drag every median toward zero." }, "medianHoursOpenSoFar": { "type": [ "number", "null" ], "description": "Median age of stays still in progress." } } }, "Funnel": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "window", "stages", "outcomes", "provenance" ], "properties": { "schemaVersion": { "const": "vision-crm-funnel.v1" }, "window": { "type": "object", "additionalProperties": false, "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } } }, "stages": { "type": "array", "maxItems": 40, "items": { "$ref": "#/components/schemas/FunnelStage" } }, "outcomes": { "type": "object", "additionalProperties": false, "required": [ "won", "deferred", "closedNotProceeding", "byCloseReason" ], "properties": { "won": { "type": "integer" }, "deferred": { "type": "integer" }, "closedNotProceeding": { "type": "integer" }, "byCloseReason": { "type": "array", "maxItems": 50, "items": { "type": "object", "additionalProperties": false, "required": [ "reasonCode", "count" ], "properties": { "reasonCode": { "type": "string" }, "count": { "type": "integer" } } } } } }, "provenance": { "type": "object", "additionalProperties": false, "required": [ "countsOpportunitiesCreatedBefore", "backfilledOpeningEvents" ], "properties": { "countsOpportunitiesCreatedBefore": { "type": "string", "format": "date-time" }, "backfilledOpeningEvents": { "type": "integer", "description": "Opening stage events synthesised by 0014 from created_at rather than observed. A metric that cannot distinguish recorded fact from inference invites conclusions it cannot support." } } } } }, "Actor": { "type": "object", "additionalProperties": false, "required": [ "publicReference", "displayName", "identityClass", "membershipRole", "status", "openOpportunities", "openTasks", "overdueTasks" ], "properties": { "publicReference": { "type": "string", "pattern": "^ACR-[A-F0-9]{12}$" }, "displayName": { "type": "string" }, "identityClass": { "enum": [ "human", "service", "worker", "agent" ], "description": "An actor is not necessarily a person. Agents own work on the same terms." }, "membershipRole": { "type": "string" }, "status": { "enum": [ "active", "suspended" ] }, "openOpportunities": { "type": "integer" }, "openTasks": { "type": "integer" }, "overdueTasks": { "type": "integer" } } }, "Actors": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "actors", "unassigned" ], "properties": { "schemaVersion": { "const": "vision-crm-actors.v1" }, "actors": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/Actor" } }, "unassigned": { "type": "object", "additionalProperties": false, "required": [ "openOpportunities", "openTasks", "people", "organizations" ], "properties": { "openOpportunities": { "type": "integer" }, "openTasks": { "type": "integer" }, "people": { "type": "integer" }, "organizations": { "type": "integer" } }, "description": "What nobody owns. Without it, work returned to the pool is invisible." } } }, "PresentationBadge": { "type": "object", "additionalProperties": false, "required": [ "source", "field", "tone" ], "properties": { "source": { "type": "string", "description": "An endpoint in this document. The shell reads the count from it." }, "field": { "type": "string", "description": "Dotted path to the number within that response." }, "tone": { "type": "string", "enum": [ "neutral", "attention", "urgent" ] } }, "description": "A live count the shell may render beside a navigation label. Nav that carries counts is a work surface rather than a menu." }, "PresentationSection": { "type": "object", "additionalProperties": false, "required": [ "id", "label", "icon", "route", "order", "requiredScope", "badge" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "icon": { "type": "string", "description": "A name from the core's icon set. A module ships no art." }, "route": { "type": "string", "description": "Relative to wherever the shell mounts CRM." }, "order": { "type": "integer" }, "requiredScope": { "type": "string" }, "badge": { "oneOf": [ { "$ref": "#/components/schemas/PresentationBadge" }, { "type": "null" } ] } } }, "PresentationField": { "type": "object", "additionalProperties": false, "required": [ "key", "label", "kind", "linkTo", "primary" ], "properties": { "key": { "type": "string", "description": "Dotted path into the view's source response." }, "label": { "type": "string" }, "kind": { "type": "string", "enum": [ "text", "longText", "reference", "actor", "stage", "status", "timestamp", "moneyRange", "count", "email", "phone" ], "description": "What kind of value it is, so the core renders it consistently. Never how it should look." }, "linkTo": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of the view to open when this value identifies another record." }, "primary": { "type": "boolean" } } }, "PresentationView": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "kind", "route", "source", "requiredScope", "fields", "filters", "emptyState", "actions" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "kind": { "type": "string", "enum": [ "list", "detail", "metrics", "timeline", "queue" ] }, "route": { "type": "string" }, "source": { "type": "string", "description": "The endpoint in this document that fills the view." }, "requiredScope": { "type": "string" }, "fields": { "type": "array", "maxItems": 40, "items": { "$ref": "#/components/schemas/PresentationField" } }, "filters": { "type": "array", "maxItems": 10, "items": { "type": "object", "additionalProperties": false, "required": [ "key", "label", "kind", "options" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string", "enum": [ "search", "enum", "boolean" ] }, "options": { "type": "array", "maxItems": 40, "items": { "type": "string" } } } } }, "emptyState": { "type": "object", "additionalProperties": false, "required": [ "headline", "body" ], "properties": { "headline": { "type": "string" }, "body": { "type": "string" } }, "description": "Shown when the view is empty. An invitation, not an apology." }, "actions": { "type": "array", "maxItems": 20, "items": { "type": "string" }, "description": "Ids of actions in this same response. Never an action the caller did not receive." } } }, "PresentationAction": { "type": "object", "additionalProperties": false, "required": [ "id", "label", "commandType", "requiredScope", "intent", "confirm", "fields" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "commandType": { "type": "string", "description": "A command CRM accepts on /commands or /intake-review-commands." }, "requiredScope": { "type": "string" }, "intent": { "type": "string", "enum": [ "primary", "secondary", "destructive" ] }, "confirm": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Prompt the shell must show first. Present on anything not trivially undone." }, "fields": { "type": "array", "maxItems": 30, "items": { "type": "object", "additionalProperties": false, "required": [ "key", "label", "kind", "required", "options" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string", "enum": [ "text", "longText", "enum", "actor", "date", "boolean", "moneyRange" ] }, "required": { "type": "boolean" }, "options": { "type": "array", "maxItems": 40, "items": { "type": "string" } } } }, "description": "Inputs the action needs. Each key is a dotted path from the command root -- data.displayName for a record command, intakeReference for a review command -- so the shell builds the request body by writing each value at its path." } } }, "Presentation": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "appId", "navigation", "views", "actions" ], "properties": { "schemaVersion": { "const": "vision-crm-presentation.v1" }, "appId": { "const": "crm" }, "navigation": { "type": "object", "additionalProperties": false, "required": [ "label", "icon", "landing", "sections" ], "properties": { "label": { "type": "string" }, "icon": { "type": "string" }, "landing": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of the section to open first, resolved after filtering: always one of the sections in this same response, or null when the caller can reach none." }, "sections": { "type": "array", "maxItems": 40, "items": { "$ref": "#/components/schemas/PresentationSection" } } } }, "views": { "type": "array", "maxItems": 60, "items": { "$ref": "#/components/schemas/PresentationView" } }, "actions": { "type": "array", "maxItems": 60, "items": { "$ref": "#/components/schemas/PresentationAction" } } }, "description": "CRM's interface, described rather than shipped. Nothing here is executable and nothing names a colour, a pixel or an asset: the core owns the design system, and a module that could ship code into the core has shipped UI into the core. Because it is declarative it is also legible to an agent, which a compiled bundle is not." } }, "x-scopes": { "crm:today:read": "Read explainable CRM attention items", "crm:intake:read": "Read quarantined intake and provenance", "crm:intake:review": "Apply controlled human intake dispositions", "crm:people:read": "Read canonical people and contact briefings", "crm:people:write": "Create and update canonical people", "crm:organizations:read": "Read canonical organizations and relationship briefings", "crm:organizations:write": "Create and update canonical organizations", "crm:opportunities:read": "Read the authoritative commercial pipeline", "crm:opportunities:write": "Create opportunities, log activities, and apply governed stage changes", "crm:tasks:read": "Read assigned CRM work", "crm:tasks:write": "Create and update CRM follow-up work", "crm:search:read": "Search authorized canonical CRM records" } }, "security": [ { "visionBearer": [] } ] }