{ "openapi": "3.0.3", "info": { "title": "ConveRact Revenue Workspace API", "version": "1.0.0", "description": "Dashboard session endpoints for tenant administrators and authorized staff. These are separate from the external API-key API. Configure stores and workflows through the dashboard, or use the documented session contract in a trusted application. Customer actions require current permissions and configured live providers. Integration has no ConveRact installation or one-time fee; recurring plan, usage and provider charges apply." }, "servers": [ { "url": "https://api.converact.com/api/v1" } ], "components": { "securitySchemes": { "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "atlas_access" } } }, "paths": { "/growth": { "get": { "summary": "Get tenant revenue workspace records and configuration", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/stores": { "post": { "summary": "Configure a Shopify or WooCommerce connection with encrypted credentials", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "SHOPIFY", "WOOCOMMERCE" ] }, "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "url": { "type": "string", "maxLength": 500, "format": "uri" }, "credential": { "type": "string", "minLength": 10, "maxLength": 4000 }, "webhookSecret": { "type": "string", "minLength": 24, "maxLength": 500 } }, "required": [ "provider", "name", "url", "credential", "webhookSecret" ] } } } }, "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/stores/{id}/sync": { "post": { "summary": "Sync a bounded batch of store catalog, orders and checkouts", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/stores/{id}/disconnect": { "post": { "summary": "Disconnect a store and archive its imported catalog", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/customer-links": { "post": { "summary": "Record an explicit store-customer to conversation identity link", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerKey": { "type": "string", "minLength": 1, "maxLength": 300 }, "conversationId": { "type": "string", "minLength": 1 }, "evidence": { "type": "string", "minLength": 15, "maxLength": 1000 } }, "required": [ "customerKey", "conversationId", "evidence" ] } } } }, "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/customer-links/{id}": { "delete": { "summary": "Revoke a customer identity link and cancel pending jobs", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/consents": { "post": { "summary": "Record or revoke channel and purpose-specific contact permission", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "purpose": { "type": "string", "enum": [ "MARKETING", "BILLING" ] }, "allowed": { "type": "boolean" }, "evidence": { "type": "string", "minLength": 15, "maxLength": 1000 } }, "required": [ "conversationId", "purpose", "allowed", "evidence" ] } } } }, "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/journeys": { "post": { "summary": "Create a recovery, quote, subscription or replenishment journey", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "kind": { "type": "string", "enum": [ "CART", "QUOTE", "SUBSCRIPTION", "REPLENISHMENT" ] }, "enabled": { "default": false, "type": "boolean" }, "approvalRequired": { "default": true, "type": "boolean" }, "delayHours": { "default": [ 24, 72 ], "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "number", "minimum": 1, "maximum": 2160 } }, "maxPer30Days": { "default": 3, "type": "integer", "minimum": 1, "maximum": 6 }, "cooldownHours": { "default": 48, "type": "integer", "minimum": 24, "maximum": 720 }, "quietStartUtc": { "default": 20, "type": "integer", "minimum": 0, "maximum": 23 }, "quietEndUtc": { "default": 8, "type": "integer", "minimum": 0, "maximum": 23 }, "productIds": { "default": [], "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1 } }, "repeatAfterDays": { "default": 30, "type": "integer", "minimum": 1, "maximum": 365 }, "message": { "type": "string", "minLength": 10, "maxLength": 1400 }, "template": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 512 }, "language": { "type": "string", "minLength": 2, "maxLength": 20 }, "parameters": { "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 1024 } } }, "required": [ "name", "language", "parameters" ] }, "experimentId": { "type": "string", "minLength": 1 } }, "required": [ "name", "kind", "message" ] } } } }, "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/journeys/{id}": { "patch": { "summary": "Enable or pause a journey", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/journeys/plan": { "post": { "summary": "Plan due actions without delivering customer messages", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/jobs/{id}/approve": { "post": { "summary": "Approve a pending follow-up", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/jobs/{id}/send": { "post": { "summary": "Send a scheduled action only after current eligibility checks", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/jobs/{id}/cancel": { "post": { "summary": "Cancel an action that has not been dispatched", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/costs": { "post": { "summary": "Record a product unit cost in the product currency", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "minLength": 1 }, "unitCost": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "productId", "unitCost", "currency" ] } } } }, "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/offers": { "post": { "summary": "Validate and create a draft margin-controlled offer", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "lines": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "minLength": 1 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "required": [ "productId", "quantity" ] } }, "discountPercent": { "type": "number", "minimum": 0, "maximum": 50 }, "minimumMarginPercent": { "type": "number", "minimum": 0, "maximum": 100 }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "name", "lines", "discountPercent", "minimumMarginPercent", "expiresAt" ] } } } }, "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/offers/{id}/preview": { "get": { "summary": "Reprice an offer using current product cost and stock", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/offers/{id}/approve": { "post": { "summary": "Approve the current offer fingerprint", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/offers/{id}/revoke": { "post": { "summary": "Revoke an offer", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/offers/{id}/quote": { "post": { "summary": "Create an idempotent customer quote from an approved offer", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "requestId": { "type": "string", "minLength": 8, "maxLength": 160 } }, "required": [ "conversationId", "requestId" ] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/experiments": { "post": { "summary": "Create a draft randomized holdout experiment", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "holdoutPercent": { "default": 20, "type": "integer", "minimum": 10, "maximum": 50 }, "attributionDays": { "default": 14, "type": "integer", "minimum": 1, "maximum": 90 } }, "required": [ "name" ] } } } }, "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/experiments/{id}": { "patch": { "summary": "Start or stop an experiment", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "RUNNING", "STOPPED" ] } }, "required": [ "status" ] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/experiments/{id}/report": { "get": { "summary": "Read currency-separated experiment metrics and uncertainty", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/subscriptions/{id}/refresh": { "post": { "summary": "Read current hosted invoice and provider retry state without charging", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/objections/analyze": { "post": { "summary": "Generate a grounded internal ConveRact AI objection report", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/objections/{id}/suggestions/{index}/publish": { "post": { "summary": "Publish administrator-reviewed knowledge", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 5, "maxLength": 160 }, "content": { "type": "string", "minLength": 20, "maxLength": 3000 }, "reviewed": { "type": "boolean", "enum": [ true ] } }, "required": [ "title", "content", "reviewed" ] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "index", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/objections/{id}/suggestions/{index}/reject": { "post": { "summary": "Reject an AI knowledge suggestion", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "index", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/plan-proposals": { "post": { "summary": "Request review of an evidence-based capacity recommendation", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/plan-proposals/{id}/accept": { "post": { "summary": "Accept an offered plan and open secure recurring billing", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "acceptRecurringCharges": { "type": "boolean", "enum": [ true ] }, "currency": { "type": "string", "enum": [ "USD", "INR" ] } }, "required": [ "acceptRecurringCharges", "currency" ] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/plan-proposals/{id}/decline": { "post": { "summary": "Decline a plan proposal", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/agency-invitations/{id}/respond": { "post": { "summary": "Accept or revoke an agency agreement", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accept": { "type": "boolean" } }, "required": [ "accept" ] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/growth/agencies/{id}/operators": { "patch": { "summary": "Assign active workspace staff to agency summary access", "tags": [ "Revenue workspace" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operatorIds": { "maxItems": 100, "type": "array", "items": { "type": "string" } } }, "required": [ "operatorIds" ] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/platform/growth": { "get": { "summary": "Read platform agency and commercial review state", "tags": [ "Platform revenue" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/platform/growth/agencies": { "post": { "summary": "Create an agency associated with an active workspace", "tags": [ "Platform revenue" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "ownerTenantId": { "type": "string", "minLength": 1 } }, "required": [ "name", "ownerTenantId" ] } } } }, "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/platform/growth/agencies/{id}": { "patch": { "summary": "Pause or resume an agency", "tags": [ "Platform revenue" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ACTIVE", "PAUSED" ] } }, "required": [ "status" ] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/platform/growth/agency-clients": { "post": { "summary": "Invite a client with explicit commission terms", "tags": [ "Platform revenue" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agencyId": { "type": "string", "minLength": 1 }, "clientTenantId": { "type": "string", "minLength": 1 }, "commissionPercent": { "type": "number", "minimum": 0, "maximum": 50 }, "agreement": { "type": "string", "minLength": 30, "maxLength": 4000 } }, "required": [ "agencyId", "clientTenantId", "commissionPercent", "agreement" ] } } } }, "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/platform/growth/agencies/{id}/reconcile": { "post": { "summary": "Reconcile live paid subscription invoices and credit adjustments", "tags": [ "Platform revenue" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/platform/growth/agencies/{id}/payouts": { "post": { "summary": "Allocate a reconciled currency balance to a payout without transferring funds", "tags": [ "Platform revenue" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "currency" ] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/platform/growth/payouts/{id}/settle": { "post": { "summary": "Record a verified external settlement reference", "tags": [ "Platform revenue" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string", "minLength": 8, "maxLength": 200 }, "paidExternally": { "type": "boolean", "enum": [ true ] } }, "required": [ "reference", "paidExternally" ] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/platform/growth/plan-proposals/{id}/review": { "post": { "summary": "Offer or decline a capacity proposal", "tags": [ "Platform revenue" ], "description": "Authenticated dashboard session only; external API keys are not accepted. Mutations require CSRF protection. Tenant administrators configure workflows; staff may read their workspace and create approved offer quotes. Platform routes require PLATFORM_ADMIN. See /revenue-workspace-guide.md on the website for setup and operational requirements.", "security": [ { "cookieAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "offer": { "type": "boolean" } }, "required": [ "offer" ] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "csrfToken returned by sign-in. Send the session cookies with the request." } ], "responses": { "200": { "description": "Operation result in { success: true, data: ... }" }, "201": { "description": "Created record" }, "400": { "description": "Invalid input; field details are returned" }, "401": { "description": "Sign-in or CSRF authentication required" }, "403": { "description": "Role or tenant access denied" }, "409": { "description": "Approval, source data, consent, stock, provider configuration, or workflow state prevents this operation" }, "502": { "description": "The external store, payment provider, or AI returned an unusable response" } } } }, "/commerce/webhooks/{id}": { "post": { "summary": "Receive signed Shopify or WooCommerce webhook JSON", "description": "No dashboard session. Verify raw-body HMAC-SHA256 against the configured store signing secret. Use the provider signature/topic/event headers. Order events retrieve current provider state; delivery replays are deduplicated.", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Shopify-Hmac-Sha256", "in": "header", "schema": { "type": "string" } }, { "name": "X-WC-Webhook-Signature", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Received, ignored, or duplicate event" }, "401": { "description": "Invalid signature" }, "404": { "description": "Disconnected or unknown store" }, "502": { "description": "Current provider state could not be verified; retry later" } } } }, "/auth/login": { "post": { "summary": "Sign in to your ConveRact workspace", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" } } } } } }, "responses": { "200": { "description": "Sets HttpOnly session cookies and returns data.user and data.csrfToken." }, "401": { "description": "Invalid credentials." }, "429": { "description": "Sign-in rate limit exceeded." } } } } } }