{ "openapi": "3.1.0", "info": { "title": "ConveRact Service Operations session API", "version": "1.0.0", "description": "Authenticated tenant workspace API. Requires session cookies and CSRF for writes; external API keys are not accepted. Live providers require configured credentials. See service-operations-guide.md for exact limits." }, "servers": [ { "url": "/api/v1" } ], "components": { "securitySchemes": { "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "atlas_access" } } }, "paths": { "/operations": { "get": { "tags": [ "Service Operations" ], "summary": "Read tenant support cases, configuration, approvals and recent evidence; staff receive restricted views", "x-roles": [ "TENANT_ADMIN", "STAFF" ], "security": [ { "cookieAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Session-scoped result in { success: true, data }. Workflow execution may return a persisted FAILED run; inspect status and traces." }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "402": { "description": "Workspace service unavailable" }, "403": { "description": "Forbidden role or invalid CSRF" }, "404": { "description": "Record unavailable in this tenant" }, "409": { "description": "Stale version, conflicting operation or unmet prerequisite" }, "422": { "description": "Unsupported or incomplete source content" }, "429": { "description": "Request cooldown" }, "502": { "description": "Unconfirmed provider result or invalid AI evidence" } } } }, "/operations/tickets": { "post": { "tags": [ "Service Operations" ], "summary": "Create a support case without changing orders or payments", "x-roles": [ "TENANT_ADMIN", "STAFF" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string" }, "title": { "type": "string", "minLength": 3, "maxLength": 200 }, "category": { "type": "string", "enum": [ "SUPPORT", "RETURN", "EXCHANGE", "REFUND", "WARRANTY", "DELIVERY" ] }, "priority": { "type": "string", "enum": [ "LOW", "NORMAL", "HIGH", "URGENT" ] }, "ownerId": { "type": "string" }, "slaHours": { "type": "integer", "minimum": 1, "maximum": 720, "default": 24 } }, "required": [ "conversationId", "title" ] } } } }, "responses": { "201": { "description": "Session-scoped result in { success: true, data }. Workflow execution may return a persisted FAILED run; inspect status and traces." }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "402": { "description": "Workspace service unavailable" }, "403": { "description": "Forbidden role or invalid CSRF" }, "404": { "description": "Record unavailable in this tenant" }, "409": { "description": "Stale version, conflicting operation or unmet prerequisite" }, "422": { "description": "Unsupported or incomplete source content" }, "429": { "description": "Request cooldown" }, "502": { "description": "Unconfirmed provider result or invalid AI evidence" } } } }, "/operations/tickets/{id}": { "patch": { "tags": [ "Service Operations" ], "summary": "Assign, update or resolve a ticket; resolution requires at least 10 characters", "x-roles": [ "TENANT_ADMIN", "STAFF" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OPEN", "IN_PROGRESS", "RESOLVED" ] }, "ownerId": { "type": "string" }, "resolution": { "type": "string", "maxLength": 3000 } }, "required": [ "status", "ownerId" ] } } } }, "responses": { "200": { "description": "Session-scoped result in { success: true, data }. Workflow execution may return a persisted FAILED run; inspect status and traces." }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "402": { "description": "Workspace service unavailable" }, "403": { "description": "Forbidden role or invalid CSRF" }, "404": { "description": "Record unavailable in this tenant" }, "409": { "description": "Stale version, conflicting operation or unmet prerequisite" }, "422": { "description": "Unsupported or incomplete source content" }, "429": { "description": "Request cooldown" }, "502": { "description": "Unconfirmed provider result or invalid AI evidence" } } } }, "/operations/connections": { "post": { "tags": [ "Service Operations" ], "summary": "Save an encrypted CRM credential; no provider request occurs", "x-roles": [ "TENANT_ADMIN" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "provider": { "type": "string", "enum": [ "HUBSPOT", "SALESFORCE", "ZOHO" ] }, "origin": { "type": "string", "format": "uri" }, "token": { "type": "string", "minLength": 10, "maxLength": 8000, "writeOnly": true }, "externalIdField": { "type": "string", "default": "ConveRact_ID__c" } }, "required": [ "name", "provider", "origin", "token" ] } } } }, "responses": { "201": { "description": "Session-scoped result in { success: true, data }. Workflow execution may return a persisted FAILED run; inspect status and traces." }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "402": { "description": "Workspace service unavailable" }, "403": { "description": "Forbidden role or invalid CSRF" }, "404": { "description": "Record unavailable in this tenant" }, "409": { "description": "Stale version, conflicting operation or unmet prerequisite" }, "422": { "description": "Unsupported or incomplete source content" }, "429": { "description": "Request cooldown" }, "502": { "description": "Unconfirmed provider result or invalid AI evidence" } } } }, "/operations/connections/{id}": { "patch": { "tags": [ "Service Operations" ], "summary": "Rotate the token or disconnect and erase it", "x-roles": [ "TENANT_ADMIN" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "writeOnly": true, "minLength": 10, "maxLength": 8000 }, "disconnect": { "type": "boolean" } }, "required": [] } } } }, "responses": { "200": { "description": "Session-scoped result in { success: true, data }. Workflow execution may return a persisted FAILED run; inspect status and traces." }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "402": { "description": "Workspace service unavailable" }, "403": { "description": "Forbidden role or invalid CSRF" }, "404": { "description": "Record unavailable in this tenant" }, "409": { "description": "Stale version, conflicting operation or unmet prerequisite" }, "422": { "description": "Unsupported or incomplete source content" }, "429": { "description": "Request cooldown" }, "502": { "description": "Unconfirmed provider result or invalid AI evidence" } } } }, "/operations/connections/{id}/sync": { "post": { "tags": [ "Service Operations" ], "summary": "Upsert a selected customer as a HubSpot contact or Salesforce/Zoho lead", "x-roles": [ "TENANT_ADMIN" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string" }, "confirmed": { "const": true } }, "required": [ "conversationId", "confirmed" ] } } } }, "responses": { "200": { "description": "Session-scoped result in { success: true, data }. Workflow execution may return a persisted FAILED run; inspect status and traces." }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "402": { "description": "Workspace service unavailable" }, "403": { "description": "Forbidden role or invalid CSRF" }, "404": { "description": "Record unavailable in this tenant" }, "409": { "description": "Stale version, conflicting operation or unmet prerequisite" }, "422": { "description": "Unsupported or incomplete source content" }, "429": { "description": "Request cooldown" }, "502": { "description": "Unconfirmed provider result or invalid AI evidence" } } } }, "/operations/actions": { "post": { "tags": [ "Service Operations" ], "summary": "Create a paused reusable HTTPS API action", "x-roles": [ "TENANT_ADMIN" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "method": { "type": "string", "enum": [ "GET", "POST", "PATCH" ] }, "token": { "type": "string", "writeOnly": true }, "body": { "type": "string", "maxLength": 12000, "default": "{}" } }, "required": [ "name", "url", "method" ] } } } }, "responses": { "201": { "description": "Session-scoped result in { success: true, data }. Workflow execution may return a persisted FAILED run; inspect status and traces." }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "402": { "description": "Workspace service unavailable" }, "403": { "description": "Forbidden role or invalid CSRF" }, "404": { "description": "Record unavailable in this tenant" }, "409": { "description": "Stale version, conflicting operation or unmet prerequisite" }, "422": { "description": "Unsupported or incomplete source content" }, "429": { "description": "Request cooldown" }, "502": { "description": "Unconfirmed provider result or invalid AI evidence" } } } }, "/operations/actions/{id}": { "patch": { "tags": [ "Service Operations" ], "summary": "Enable, pause, rotate or erase API action credentials", "x-roles": [ "TENANT_ADMIN" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "token": { "type": "string", "minLength": 10, "writeOnly": true }, "disconnect": { "type": "boolean" } }, "required": [] } } } }, "responses": { "200": { "description": "Session-scoped result in { success: true, data }. Workflow execution may return a persisted FAILED run; inspect status and traces." }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "402": { "description": "Workspace service unavailable" }, "403": { "description": "Forbidden role or invalid CSRF" }, "404": { "description": "Record unavailable in this tenant" }, "409": { "description": "Stale version, conflicting operation or unmet prerequisite" }, "422": { "description": "Unsupported or incomplete source content" }, "429": { "description": "Request cooldown" }, "502": { "description": "Unconfirmed provider result or invalid AI evidence" } } } }, "/operations/workflows": { "post": { "tags": [ "Service Operations" ], "summary": "Save a paused visual workflow", "x-roles": [ "TENANT_ADMIN" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 3, "maxLength": 120 }, "steps": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "TICKET", "HANDOFF", "LEAD_STATUS", "CRM_SYNC", "API_ACTION" ] }, "value": { "type": "string", "maxLength": 200 }, "when": { "type": "string", "enum": [ "ALWAYS", "NEGATIVE", "HIGH_INTENT" ] } }, "required": [ "kind" ] }, "minItems": 1, "maxItems": 12 } }, "required": [ "name", "steps" ] } } } }, "responses": { "201": { "description": "Session-scoped result in { success: true, data }. Workflow execution may return a persisted FAILED run; inspect status and traces." }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "402": { "description": "Workspace service unavailable" }, "403": { "description": "Forbidden role or invalid CSRF" }, "404": { "description": "Record unavailable in this tenant" }, "409": { "description": "Stale version, conflicting operation or unmet prerequisite" }, "422": { "description": "Unsupported or incomplete source content" }, "429": { "description": "Request cooldown" }, "502": { "description": "Unconfirmed provider result or invalid AI evidence" } } } }, "/operations/workflows/{id}": { "patch": { "tags": [ "Service Operations" ], "summary": "Toggle enablement or save a paused new version with optimistic concurrency", "x-roles": [ "TENANT_ADMIN" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 3, "maxLength": 120 }, "steps": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "TICKET", "HANDOFF", "LEAD_STATUS", "CRM_SYNC", "API_ACTION" ] }, "value": { "type": "string", "maxLength": 200 }, "when": { "type": "string", "enum": [ "ALWAYS", "NEGATIVE", "HIGH_INTENT" ] } }, "required": [ "kind" ] }, "minItems": 1, "maxItems": 12 }, "expectedVersion": { "type": "integer", "minimum": 1 } }, "required": [ "name", "steps", "expectedVersion" ] } ] } } } }, "responses": { "200": { "description": "Session-scoped result in { success: true, data }. Workflow execution may return a persisted FAILED run; inspect status and traces." }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "402": { "description": "Workspace service unavailable" }, "403": { "description": "Forbidden role or invalid CSRF" }, "404": { "description": "Record unavailable in this tenant" }, "409": { "description": "Stale version, conflicting operation or unmet prerequisite" }, "422": { "description": "Unsupported or incomplete source content" }, "429": { "description": "Request cooldown" }, "502": { "description": "Unconfirmed provider result or invalid AI evidence" } } } }, "/operations/workflows/{id}/runs": { "post": { "tags": [ "Service Operations" ], "summary": "Request a pending approval without executing steps", "x-roles": [ "TENANT_ADMIN" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string" } }, "required": [ "conversationId" ] } } } }, "responses": { "201": { "description": "Session-scoped result in { success: true, data }. Workflow execution may return a persisted FAILED run; inspect status and traces." }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "402": { "description": "Workspace service unavailable" }, "403": { "description": "Forbidden role or invalid CSRF" }, "404": { "description": "Record unavailable in this tenant" }, "409": { "description": "Stale version, conflicting operation or unmet prerequisite" }, "422": { "description": "Unsupported or incomplete source content" }, "429": { "description": "Request cooldown" }, "502": { "description": "Unconfirmed provider result or invalid AI evidence" } } } }, "/operations/runs/{id}/review": { "post": { "tags": [ "Service Operations" ], "summary": "Reject or approve and execute one immutable run; prior steps remain applied on failure", "x-roles": [ "TENANT_ADMIN" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "approve": { "type": "boolean" }, "note": { "type": "string", "minLength": 10, "maxLength": 1000 } }, "required": [ "approve", "note" ] } } } }, "responses": { "200": { "description": "Session-scoped result in { success: true, data }. Workflow execution may return a persisted FAILED run; inspect status and traces." }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "402": { "description": "Workspace service unavailable" }, "403": { "description": "Forbidden role or invalid CSRF" }, "404": { "description": "Record unavailable in this tenant" }, "409": { "description": "Stale version, conflicting operation or unmet prerequisite" }, "422": { "description": "Unsupported or incomplete source content" }, "429": { "description": "Request cooldown" }, "502": { "description": "Unconfirmed provider result or invalid AI evidence" } } } }, "/operations/qa": { "post": { "tags": [ "Service Operations" ], "summary": "Generate a cited QA review of up to 48 recent public messages", "x-roles": [ "TENANT_ADMIN" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string" } }, "required": [ "conversationId" ] } } } }, "responses": { "201": { "description": "Session-scoped result in { success: true, data }. Workflow execution may return a persisted FAILED run; inspect status and traces." }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "402": { "description": "Workspace service unavailable" }, "403": { "description": "Forbidden role or invalid CSRF" }, "404": { "description": "Record unavailable in this tenant" }, "409": { "description": "Stale version, conflicting operation or unmet prerequisite" }, "422": { "description": "Unsupported or incomplete source content" }, "429": { "description": "Request cooldown" }, "502": { "description": "Unconfirmed provider result or invalid AI evidence" } } } }, "/operations/sources": { "post": { "tags": [ "Service Operations" ], "summary": "Configure a paused knowledge source", "x-roles": [ "TENANT_ADMIN" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "provider": { "type": "string", "enum": [ "WEBSITE", "GOOGLE_DOC", "NOTION", "CONFLUENCE" ] }, "origin": { "type": "string", "format": "uri" }, "documentId": { "type": "string" }, "token": { "type": "string", "writeOnly": true }, "accountEmail": { "type": "string" } }, "required": [ "name", "provider", "origin" ] } } } }, "responses": { "201": { "description": "Session-scoped result in { success: true, data }. Workflow execution may return a persisted FAILED run; inspect status and traces." }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "402": { "description": "Workspace service unavailable" }, "403": { "description": "Forbidden role or invalid CSRF" }, "404": { "description": "Record unavailable in this tenant" }, "409": { "description": "Stale version, conflicting operation or unmet prerequisite" }, "422": { "description": "Unsupported or incomplete source content" }, "429": { "description": "Request cooldown" }, "502": { "description": "Unconfirmed provider result or invalid AI evidence" } } } }, "/operations/sources/{id}": { "get": { "tags": [ "Service Operations" ], "summary": "Read staged source text and version hash", "x-roles": [ "TENANT_ADMIN" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session-scoped result in { success: true, data }. Workflow execution may return a persisted FAILED run; inspect status and traces." }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "402": { "description": "Workspace service unavailable" }, "403": { "description": "Forbidden role or invalid CSRF" }, "404": { "description": "Record unavailable in this tenant" }, "409": { "description": "Stale version, conflicting operation or unmet prerequisite" }, "422": { "description": "Unsupported or incomplete source content" }, "429": { "description": "Request cooldown" }, "502": { "description": "Unconfirmed provider result or invalid AI evidence" } } }, "patch": { "tags": [ "Service Operations" ], "summary": "Toggle hourly sync, renew a token or withdraw published knowledge", "x-roles": [ "TENANT_ADMIN" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "token": { "type": "string", "minLength": 10, "writeOnly": true }, "withdraw": { "type": "boolean" } }, "required": [] } } } }, "responses": { "200": { "description": "Session-scoped result in { success: true, data }. Workflow execution may return a persisted FAILED run; inspect status and traces." }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "402": { "description": "Workspace service unavailable" }, "403": { "description": "Forbidden role or invalid CSRF" }, "404": { "description": "Record unavailable in this tenant" }, "409": { "description": "Stale version, conflicting operation or unmet prerequisite" }, "422": { "description": "Unsupported or incomplete source content" }, "429": { "description": "Request cooldown" }, "502": { "description": "Unconfirmed provider result or invalid AI evidence" } } } }, "/operations/sources/{id}/sync": { "post": { "tags": [ "Service Operations" ], "summary": "Fetch and stage source text without automatically publishing", "x-roles": [ "TENANT_ADMIN" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] } } } }, "responses": { "200": { "description": "Session-scoped result in { success: true, data }. Workflow execution may return a persisted FAILED run; inspect status and traces." }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "402": { "description": "Workspace service unavailable" }, "403": { "description": "Forbidden role or invalid CSRF" }, "404": { "description": "Record unavailable in this tenant" }, "409": { "description": "Stale version, conflicting operation or unmet prerequisite" }, "422": { "description": "Unsupported or incomplete source content" }, "429": { "description": "Request cooldown" }, "502": { "description": "Unconfirmed provider result or invalid AI evidence" } } } }, "/operations/sources/{id}/publish": { "post": { "tags": [ "Service Operations" ], "summary": "Publish the exact reviewed source version into tenant answer retrieval", "x-roles": [ "TENANT_ADMIN" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reviewed": { "const": true }, "hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "reviewed", "hash" ] } } } }, "responses": { "200": { "description": "Session-scoped result in { success: true, data }. Workflow execution may return a persisted FAILED run; inspect status and traces." }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "402": { "description": "Workspace service unavailable" }, "403": { "description": "Forbidden role or invalid CSRF" }, "404": { "description": "Record unavailable in this tenant" }, "409": { "description": "Stale version, conflicting operation or unmet prerequisite" }, "422": { "description": "Unsupported or incomplete source content" }, "429": { "description": "Request cooldown" }, "502": { "description": "Unconfirmed provider result or invalid AI evidence" } } } } } }