{ "openapi": "3.1.0", "info": { "title": "Mementom Marketing API", "version": "1.0.0", "description": "Company-neutral server API for a company or agency to integrate marketing automation and MCP tools. External clients and the marketing console share one validation/persistence path. Scoped Bearer credentials are bound to a company, active staff membership and one application. Aster is a replaceable teaching example, not a required application or API dependency. Resolve real company/application IDs, insight definitions and versions from the selected workspace and provide company-specific content and landing URLs. Draft planning, permission-aware aggregate counts and reports are available. The separately documented Marketing MCP server uses these operations. Every tool adapter must preserve current membership, scope, revision and privacy checks." }, "servers": [ { "url": "https://mementom.app/api/v1/marketing", "description": "Public application service. Do not send marketing credentials to the separately served authorization origin." } ], "tags": [ { "name": "Credentials" }, { "name": "Workspace" }, { "name": "Drafts" }, { "name": "Measurement" }, { "name": "Diagnostics" } ], "security": [ { "marketingBearer": [] } ], "paths": { "/api-tokens": { "get": { "tags": [ "Credentials" ], "operationId": "listMarketingCredentials", "summary": "List API credentials visible to this staff account", "description": "Console session only. Owners/admins see company credentials; marketers see their own. Secrets are never returned.", "security": [ { "marketingConsoleCookie": [] } ], "responses": { "200": { "description": "Success", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialList" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "405": { "$ref": "#/components/responses/405" }, "409": { "$ref": "#/components/responses/409" }, "413": { "$ref": "#/components/responses/413" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } } }, "post": { "tags": [ "Credentials" ], "operationId": "issueMarketingCredential", "summary": "Issue a scoped, expiring server credential", "description": "Console session plus same-origin write protection. Secret returned once, no-store. It is bound to the current company, application and issuing staff account. A Bearer credential cannot mint another credential.", "security": [ { "marketingConsoleCookie": [] } ], "responses": { "201": { "description": "Success", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialIssued" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "405": { "$ref": "#/components/responses/405" }, "409": { "$ref": "#/components/responses/409" }, "413": { "$ref": "#/components/responses/413" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialIssue" }, "example": { "applicationId": "app_your_company", "label": "Marketing automation", "scopes": [ "marketing:read", "marketing:audiences:write", "marketing:content:write", "marketing:campaigns:write" ], "expiresInDays": 30 } } } } } }, "/api-tokens/{tokenId}": { "parameters": [ { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^mkt_[a-f0-9]{32}$" } } ], "delete": { "tags": [ "Credentials" ], "operationId": "revokeMarketingCredential", "summary": "Revoke a credential", "description": "Console session and same-origin write. Idempotent for an already-revoked visible credential. Owner/admin can revoke company credentials; marketers can revoke their own.", "security": [ { "marketingConsoleCookie": [] } ], "responses": { "200": { "description": "Success", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credential" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "405": { "$ref": "#/components/responses/405" }, "409": { "$ref": "#/components/responses/409" }, "413": { "$ref": "#/components/responses/413" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } } } }, "/applications": { "get": { "tags": [ "Workspace" ], "operationId": "listMarketingApplications", "summary": "List accessible applications", "description": "Bearer result contains only its one active bound application. Console session result contains the active applications accessible in that company.", "security": [ { "marketingBearer": [] }, { "marketingConsoleCookie": [] } ], "responses": { "200": { "description": "Success", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationList" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "405": { "$ref": "#/components/responses/405" }, "409": { "$ref": "#/components/responses/409" }, "413": { "$ref": "#/components/responses/413" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } }, "x-required-scope": "marketing:read" } }, "/applications/{applicationId}/workspace": { "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApplicationId" } } ], "get": { "tags": [ "Workspace" ], "operationId": "getMarketingWorkspace", "summary": "Read marketing workspace and current revision", "description": "Read current IDs, definition versions, saved drafts, capabilities and provenance. This is the same workspace used by the marketing console.", "security": [ { "marketingBearer": [] }, { "marketingConsoleCookie": [] } ], "responses": { "200": { "description": "Success", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "405": { "$ref": "#/components/responses/405" }, "409": { "$ref": "#/components/responses/409" }, "413": { "$ref": "#/components/responses/413" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } }, "x-required-scope": "marketing:read" } }, "/applications/{applicationId}/workspace/audiences": { "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApplicationId" } } ], "post": { "tags": [ "Drafts" ], "operationId": "saveMarketingAudience", "summary": "Create or replace an audience", "description": "Omit audienceId to create; supply it to edit. Simple and structured criteria share the console validator. Every accepted mutation returns the complete current marketing workspace. Replace illustrative IDs and expectedRevision with values read from that application. Aster values in examples teach the message flow only. Replace their definition IDs/values, record names, content and landing URL with registered values for your own company.", "security": [ { "marketingBearer": [] }, { "marketingConsoleCookie": [] } ], "responses": { "200": { "description": "Success", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "405": { "$ref": "#/components/responses/405" }, "409": { "$ref": "#/components/responses/409" }, "413": { "$ref": "#/components/responses/413" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } }, "x-required-scope": "marketing:audiences:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudienceMutation" }, "example": { "expectedRevision": 0, "payload": { "name": "Visitors who authorized entry", "mode": "all", "rules": [ { "definitionId": "aster_activity_definition_id", "version": 1, "operator": "equals", "value": "entry_authorized" } ] } } } } } } }, "/applications/{applicationId}/workspace/content": { "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApplicationId" } } ], "post": { "tags": [ "Drafts" ], "operationId": "saveMarketingContent", "summary": "Create, revise or duplicate saved content", "description": "Content revisions are separate from the workspace revision. Copy the complete author-controlled fields when selecting a saved edition in a campaign. Every accepted mutation returns the complete current marketing workspace. Replace illustrative IDs and expectedRevision with values read from that application. Aster values in examples teach the message flow only. Replace their definition IDs/values, record names, content and landing URL with registered values for your own company.", "security": [ { "marketingBearer": [] }, { "marketingConsoleCookie": [] } ], "responses": { "200": { "description": "Success", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "405": { "$ref": "#/components/responses/405" }, "409": { "$ref": "#/components/responses/409" }, "413": { "$ref": "#/components/responses/413" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } }, "x-required-scope": "marketing:content:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentMutation" }, "example": { "expectedRevision": 0, "payload": { "name": "Next service invitation", "type": "offer", "content": { "headline": "Ready for the next step?", "body": "Explore the next service option for your home.", "cta": "See options", "landingUrl": "https://mementom.app/aster/", "image": "" }, "questions": [], "requestedInsightIds": [] } } } } } } }, "/applications/{applicationId}/workspace/campaigns": { "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApplicationId" } } ], "post": { "tags": [ "Drafts" ], "operationId": "createMarketingCampaign", "summary": "Create or update a campaign draft", "description": "Creates a draft, or edits an existing draft using campaignId and expectedCampaignRevision. Published creative is immutable; duplicate it to make changes. Publishing uses its separate operation and permission. Returns the current workspace.", "security": [ { "marketingBearer": [] }, { "marketingConsoleCookie": [] } ], "responses": { "200": { "description": "Success", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "405": { "$ref": "#/components/responses/405" }, "409": { "$ref": "#/components/responses/409" }, "413": { "$ref": "#/components/responses/413" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } }, "x-required-scope": "marketing:campaigns:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignMutation" }, "example": { "expectedRevision": 0, "payload": { "schemaVersion": 2, "name": "Next service follow-up", "objective": "return_visitors", "startAt": null, "endAt": null, "budgetMinor": 10000, "dailyCapMinor": 1000, "responseWindowHours": 72, "engagements": [ { "name": "Next service invitation", "type": "offer", "content": { "headline": "Ready for the next step?", "body": "Explore the next service option for your home.", "cta": "See options", "landingUrl": "https://mementom.app/aster/", "image": "" }, "questions": [], "requestedInsightIds": [], "audienceIds": [ "saved_audience_id" ], "excludedAudienceIds": [], "refinements": [], "engagementMinor": 100, "purchaseMinor": 0, "contentId": "saved_content_id", "contentRevision": 1 } ] } } } } } } }, "/applications/{applicationId}/workspace/pricing": { "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApplicationId" } } ], "post": { "tags": [ "Drafts" ], "operationId": "saveMarketingPricing", "summary": "Set planning assumptions", "description": "Policy or one outside insight profile per write. Recomputes audience planning prices and marks existing campaign drafts pricingChanged. Every accepted mutation returns the complete current marketing workspace. Replace illustrative IDs and expectedRevision with values read from that application. Aster values in examples teach the message flow only. Replace their definition IDs/values, record names, content and landing URL with registered values for your own company.", "security": [ { "marketingBearer": [] }, { "marketingConsoleCookie": [] } ], "responses": { "200": { "description": "Success", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "405": { "$ref": "#/components/responses/405" }, "409": { "$ref": "#/components/responses/409" }, "413": { "$ref": "#/components/responses/413" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } }, "x-required-scope": "marketing:pricing:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingMutation" }, "example": { "expectedRevision": 0, "payload": { "policy": { "schemaVersion": 1, "brandTier": "pro", "marketTier": "retail", "baseCPA": 5 } } } } } } } }, "/applications/{applicationId}/workspace/proposals": { "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApplicationId" } } ], "post": { "tags": [ "Drafts" ], "operationId": "proposeMarketingInsight", "summary": "Propose a non-identifying insight", "description": "Creates a pending_review definition. It cannot be used for matching until reviewed. Standard template registration, approval and ingestion remain developer operations. Every accepted mutation returns the complete current marketing workspace. Replace illustrative IDs and expectedRevision with values read from that application. Aster values in examples teach the message flow only. Replace their definition IDs/values, record names, content and landing URL with registered values for your own company.", "security": [ { "marketingBearer": [] }, { "marketingConsoleCookie": [] } ], "responses": { "200": { "description": "Success", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "405": { "$ref": "#/components/responses/405" }, "409": { "$ref": "#/components/responses/409" }, "413": { "$ref": "#/components/responses/413" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } }, "x-required-scope": "marketing:insights:propose", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalMutation" }, "example": { "expectedRevision": 0, "payload": { "key": "service.followup_interest", "label": "Follow-up interest", "description": "Whether someone is interested in another service visit.", "type": "boolean", "windowDays": 30, "ttlDays": 30 } } } } } } }, "/applications/{applicationId}/workspace/objective": { "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApplicationId" } } ], "post": { "tags": [ "Drafts" ], "operationId": "saveMarketingObjective", "summary": "Set the workspace objective", "description": "Changes workspace suggestions; campaign objectives are selected separately. Every accepted mutation returns the complete current marketing workspace. Replace illustrative IDs and expectedRevision with values read from that application. Aster values in examples teach the message flow only. Replace their definition IDs/values, record names, content and landing URL with registered values for your own company.", "security": [ { "marketingBearer": [] }, { "marketingConsoleCookie": [] } ], "responses": { "200": { "description": "Success", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "405": { "$ref": "#/components/responses/405" }, "409": { "$ref": "#/components/responses/409" }, "413": { "$ref": "#/components/responses/413" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } }, "x-required-scope": "marketing:objective:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectiveMutation" }, "example": { "expectedRevision": 0, "payload": { "objective": "return_visitors" } } } } } } }, "/applications/{applicationId}/workspace/count": { "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApplicationId" } } ], "post": { "tags": [ "Measurement" ], "operationId": "countMarketingAudience", "summary": "Count currently eligible matching holders", "description": "Read-only matching using the current workspace revision. Returns aggregate count and structured-node breakdown, never holder IDs. A sample-definition audience returns available:false and count:null; it is not zero live reach. Aster values in examples teach the message flow only. Replace their definition IDs/values, record names, content and landing URL with registered values for your own company.", "security": [ { "marketingBearer": [] }, { "marketingConsoleCookie": [] } ], "responses": { "200": { "description": "Success", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResult" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "405": { "$ref": "#/components/responses/405" }, "409": { "$ref": "#/components/responses/409" }, "413": { "$ref": "#/components/responses/413" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } }, "x-required-scope": "marketing:read", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountRequest" }, "example": { "expectedRevision": 0, "audience": { "name": "Visitors who authorized entry", "mode": "all", "rules": [ { "definitionId": "aster_activity_definition_id", "version": 1, "operator": "equals", "value": "entry_authorized" } ] } } } } } } }, "/applications/{applicationId}/workspace/report": { "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApplicationId" } } ], "get": { "tags": [ "Measurement" ], "operationId": "getMarketingReport", "summary": "Read aggregate campaign results", "description": "Choose live or explicitly synthetic test data. No mutation is performed. A draft has no live delivery; modeled spend is never settled payment. Keep report mode and limitations visible.", "security": [ { "marketingBearer": [] }, { "marketingConsoleCookie": [] } ], "responses": { "200": { "description": "Success", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "405": { "$ref": "#/components/responses/405" }, "409": { "$ref": "#/components/responses/409" }, "413": { "$ref": "#/components/responses/413" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } }, "x-required-scope": "marketing:read", "parameters": [ { "name": "campaignId", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "live", "test" ], "default": "live" } } ] } }, "/applications/{applicationId}/workspace/activity": { "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApplicationId" } } ], "get": { "tags": [ "Diagnostics" ], "operationId": "getMarketingActivity", "summary": "Read safe marketing request traces", "description": "Application/company-scoped operational trace. Use x-mementom-activity-id from the response to correlate a request. No secrets, raw content or consumer records are returned.", "security": [ { "marketingBearer": [] }, { "marketingConsoleCookie": [] } ], "responses": { "200": { "description": "Success", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityList" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "405": { "$ref": "#/components/responses/405" }, "409": { "$ref": "#/components/responses/409" }, "413": { "$ref": "#/components/responses/413" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } }, "x-required-scope": "marketing:read", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0, "maximum": 10000 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "activityId", "in": "query", "schema": { "type": "string", "maxLength": 100, "pattern": "^mact_[A-Za-z0-9_-]+$" } } ] } }, "/applications/{applicationId}/workspace/campaignpublish": { "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApplicationId" } } ], "post": { "tags": [ "Drafts" ], "operationId": "publishMarketingCampaign", "summary": "Publish or resume a validated campaign", "description": "Publish or resume a validated campaign. Requires current workspace and campaign revisions. Never automatically replay an uncertain write.", "security": [ { "marketingBearer": [] }, { "marketingConsoleCookie": [] } ], "responses": { "200": { "description": "Success", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "405": { "$ref": "#/components/responses/405" }, "409": { "$ref": "#/components/responses/409" }, "413": { "$ref": "#/components/responses/413" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } }, "x-required-scope": "marketing:campaigns:publish", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignIdentityMutation" } } } } } }, "/applications/{applicationId}/workspace/campaignstate": { "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApplicationId" } } ], "post": { "tags": [ "Drafts" ], "operationId": "setMarketingCampaignState", "summary": "Pause or stop a published campaign", "description": "Pause or stop a published campaign. Requires current workspace and campaign revisions. Never automatically replay an uncertain write.", "security": [ { "marketingBearer": [] }, { "marketingConsoleCookie": [] } ], "responses": { "200": { "description": "Success", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "405": { "$ref": "#/components/responses/405" }, "409": { "$ref": "#/components/responses/409" }, "413": { "$ref": "#/components/responses/413" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } }, "x-required-scope": "marketing:campaigns:manage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignStateMutation" } } } } } }, "/applications/{applicationId}/workspace/campaigndelete": { "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApplicationId" } } ], "post": { "tags": [ "Drafts" ], "operationId": "deleteMarketingCampaign", "summary": "Delete a campaign while retaining history", "description": "Delete a campaign while retaining history. Requires current workspace and campaign revisions. Never automatically replay an uncertain write.", "security": [ { "marketingBearer": [] }, { "marketingConsoleCookie": [] } ], "responses": { "200": { "description": "Success", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "405": { "$ref": "#/components/responses/405" }, "409": { "$ref": "#/components/responses/409" }, "413": { "$ref": "#/components/responses/413" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } }, "x-required-scope": "marketing:campaigns:manage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignIdentityMutation" } } } } } }, "/applications/{applicationId}/workspace/campaignduplicate": { "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApplicationId" } } ], "post": { "tags": [ "Drafts" ], "operationId": "duplicateMarketingCampaign", "summary": "Create an independent editable draft copy", "description": "Create an independent editable draft copy. Requires current workspace and campaign revisions. Never automatically replay an uncertain write.", "security": [ { "marketingBearer": [] }, { "marketingConsoleCookie": [] } ], "responses": { "200": { "description": "Success", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "405": { "$ref": "#/components/responses/405" }, "409": { "$ref": "#/components/responses/409" }, "413": { "$ref": "#/components/responses/413" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } }, "x-required-scope": "marketing:campaigns:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignDuplicateMutation" } } } } } }, "/applications/{applicationId}/workspace/campaignaudiences": { "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApplicationId" } } ], "post": { "tags": [ "Drafts" ], "operationId": "setMarketingCampaignAudiences", "summary": "Set the included and excluded campaign audiences", "description": "Set the included and excluded campaign audiences. Requires current workspace and campaign revisions. Never automatically replay an uncertain write.", "security": [ { "marketingBearer": [] }, { "marketingConsoleCookie": [] } ], "responses": { "200": { "description": "Success", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "405": { "$ref": "#/components/responses/405" }, "409": { "$ref": "#/components/responses/409" }, "413": { "$ref": "#/components/responses/413" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } }, "x-required-scope": "marketing:campaigns:manage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignAudiencesMutation" } } } } } }, "/applications/{applicationId}/workspace/campaignaudience": { "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApplicationId" } } ], "post": { "tags": [ "Drafts" ], "operationId": "editMarketingCampaignAudience", "summary": "Edit an attached published campaign audience", "description": "Edit an attached published campaign audience. Requires current workspace and campaign revisions. Never automatically replay an uncertain write.", "security": [ { "marketingBearer": [] }, { "marketingConsoleCookie": [] } ], "responses": { "200": { "description": "Success", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "405": { "$ref": "#/components/responses/405" }, "409": { "$ref": "#/components/responses/409" }, "413": { "$ref": "#/components/responses/413" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } }, "x-required-scope": "marketing:campaigns:manage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignAudienceMutation" } } } } } }, "/applications/{applicationId}/workspace/reportcomparison": { "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApplicationId" } } ], "get": { "tags": [ "Measurement" ], "operationId": "getMarketingCampaignComparison", "summary": "Compare campaign performance", "description": "Compare campaign participations, which may include the same person in more than one campaign. Omit campaignIds to select current nondeleted campaigns; explicit same-application deleted IDs remain reportable. Rates use summed numerators and denominators, with separate mature windows. Costs are modeled and revenue may be unknown. Unknown, empty or duplicate IDs and repeated or unknown query keys are rejected.", "security": [ { "marketingBearer": [] }, { "marketingConsoleCookie": [] } ], "responses": { "200": { "description": "Success", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignComparison" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "405": { "$ref": "#/components/responses/405" }, "409": { "$ref": "#/components/responses/409" }, "413": { "$ref": "#/components/responses/413" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } }, "x-required-scope": "marketing:read", "parameters": [ { "name": "campaignIds", "in": "query", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "uniqueItems": true } }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "live", "test" ], "default": "live" } } ] } }, "/applications/{applicationId}/workspace/products": { "get": { "summary": "List or search authoritative company products", "operationId": "marketing_products", "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApplicationId" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "sku", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "color", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "archived" ] } }, { "name": "available", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Current authorized result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductList" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "500": { "$ref": "#/components/responses/500" } }, "x-required-scope": "marketing:read" } }, "/applications/{applicationId}/workspace/product": { "get": { "summary": "Resolve canonical product or registered alias", "operationId": "marketing_product", "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApplicationId" } }, { "name": "productId", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 120 } }, { "name": "variantId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 } } ], "responses": { "200": { "description": "Current authorized result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResult" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "500": { "$ref": "#/components/responses/500" } }, "x-required-scope": "marketing:read" } }, "/applications/{applicationId}/workspace/financialterms": { "get": { "summary": "Inspect financial event semantics", "operationId": "marketing_financialterms", "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApplicationId" } }, { "name": "campaignId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current authorized result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinancialTerms" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "500": { "$ref": "#/components/responses/500" } }, "x-required-scope": "marketing:read" } }, "/applications/{applicationId}/workspace/paymentagreement": { "get": { "summary": "Inspect payment agreement or explicit unavailability", "operationId": "marketing_paymentagreement", "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApplicationId" } }, { "name": "campaignId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "agreementId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Read exact terms for an available agreement ID, or test its coverage of campaignId." } ], "responses": { "200": { "description": "Current authorized result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentAgreement" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "500": { "$ref": "#/components/responses/500" } }, "x-required-scope": "marketing:read" } }, "/applications/{applicationId}/workspace/campaignvalidate": { "post": { "summary": "Read-only campaign preflight", "operationId": "marketing_campaignvalidate", "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApplicationId" } } ], "responses": { "200": { "description": "Current authorized result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignPreflight" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "500": { "$ref": "#/components/responses/500" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignPreflightRequest" } } } }, "x-required-scope": "marketing:read" } }, "/applications/{applicationId}/workspace/productoffer": { "post": { "summary": "Save offer from verified current product", "operationId": "marketing_productoffer", "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApplicationId" } } ], "responses": { "200": { "description": "Current authorized result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "500": { "$ref": "#/components/responses/500" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductOfferMutation" } } } }, "x-required-scope": "marketing:content:write" } }, "/applications/{applicationId}/workspace/mutationreceipt": { "get": { "summary": "Read a retained mutation receipt without repeating a write", "operationId": "marketing_mutationreceipt", "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApplicationId" } }, { "name": "operation", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "audiences", "content", "productoffer", "campaigns", "campaignPublish", "campaignDuplicate", "campaignState", "campaignDelete", "campaignAudience", "campaignAudiences", "pricing", "objective", "definitions" ] } }, { "name": "idempotencyKey", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,120}$", "description": "Optional application/actor/operation-scoped key. Identical retries return original saved receipt; changed payload returns 409. No expiry; capacity 2000 per workspace." } } ], "responses": { "200": { "description": "Original committed receipt and current record identity/status; actor/application/operation scoped", "content": { "application/json": { "schema": { "type": "object", "properties": { "applicationId": { "$ref": "#/components/schemas/ApplicationId" }, "receipt": { "type": "object" }, "current": { "type": [ "object", "null" ] } }, "required": [ "applicationId", "receipt", "current" ] } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "500": { "$ref": "#/components/responses/500" } }, "x-required-scope": "marketing:read" } }, "/applications/{applicationId}/workspace/agreementcreate": { "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApplicationId" } } ], "post": { "tags": [ "Drafts" ], "operationId": "paymentAgreementCreate", "summary": "Create a payment agreement", "description": "Owner/admin operation with explicit agreements scope, exact reviewable terms, revision protection and auditable idempotent receipt. Does not authorize or settle a payment.", "security": [ { "marketingBearer": [] }, { "marketingConsoleCookie": [] } ], "responses": { "200": { "description": "Success", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "405": { "$ref": "#/components/responses/405" }, "409": { "$ref": "#/components/responses/409" }, "413": { "$ref": "#/components/responses/413" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } }, "x-required-scope": "marketing:campaigns:publish", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentAgreementCreateMutation" } } } } } }, "/applications/{applicationId}/workspace/agreementaccept": { "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApplicationId" } } ], "post": { "tags": [ "Drafts" ], "operationId": "paymentAgreementAccept", "summary": "Accept a payment agreement", "description": "Owner/admin operation with explicit agreements scope, exact reviewable terms, revision protection and auditable idempotent receipt. Does not authorize or settle a payment.", "security": [ { "marketingBearer": [] }, { "marketingConsoleCookie": [] } ], "responses": { "200": { "description": "Success", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "405": { "$ref": "#/components/responses/405" }, "409": { "$ref": "#/components/responses/409" }, "413": { "$ref": "#/components/responses/413" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } }, "x-required-scope": "marketing:campaigns:publish", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentAgreementAcceptMutation" } } } } } }, "/apps/{applicationId}/campaigns/{campaignId}/purchase-receipts": { "post": { "operationId": "recordVerifiedPurchase", "summary": "Company-server verified purchase or reversal", "description": "Requires dedicated server API token with marketing:purchase:write; no MCP/OAuth/console acceptance. Bind prior verified landing, delivery, canonical product and transaction. Full reversals match original amount and currency; transaction deduplication is application-wide. This records measured outcomes, not settled payments.", "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseReceipt" } } } }, "responses": { "200": { "description": "Verified receipt accepted or duplicate reported." } } } } }, "components": { "securitySchemes": { "marketingBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "mkt_.", "description": "Server only. Required operation scope is listed in x-required-scope. Browser Origin/Sec-Fetch-Site requests are rejected. Expiry, revocation, active company/account/membership and current role are checked on every call." }, "marketingConsoleCookie": { "type": "apiKey", "in": "cookie", "name": "mementom_marketing_session", "description": "Established same-origin marketing console session (owner/admin/marketing). Credential management requires this session; a server Bearer credential cannot use those routes. Cookie writes require same-origin protection." } }, "responses": { "400": { "description": "Invalid JSON, fields, catalog bindings, type/range, query or pricing assumptions.", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked credential/session; or current company/account/app access ended.", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or company role, browser-origin bearer use, wrong surface or unsupported operation.", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Application/credential/campaign is unavailable in the authorized scope. Foreign application IDs are not disclosed.", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed.", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Workspace/content revision conflict or duplicate immutable insight key. Refresh and reconcile before another write.", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body or report event limit exceeded.", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Service rate limit or sign-in cooldown. Honor Retry-After when present; no fixed public quota is promised.", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Optional retry delay supplied by the service or gateway." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure; record the activity ID and reconcile any mutation before retrying.", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service or backing dependency unavailable. Reconcile mutations after recovery; do not blindly replay writes.", "headers": { "x-mementom-activity-id": { "description": "Opaque correlation ID for debugging. Save this value, not Authorization. Early transport/proxy failures may not carry it.", "schema": { "$ref": "#/components/schemas/ActivityId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "ApplicationId": { "type": "string", "pattern": "^app_[A-Za-z0-9_-]+$" }, "ActivityId": { "type": "string", "description": "Opaque request correlation ID. Also returned in x-mementom-activity-id." }, "Scope": { "type": "string", "enum": [ "marketing:read", "marketing:audiences:write", "marketing:content:write", "marketing:campaigns:write", "marketing:pricing:write", "marketing:insights:propose", "marketing:objective:write", "marketing:campaigns:manage", "marketing:campaigns:publish", "marketing:agreements:write", "marketing:agreements:accept", "marketing:purchase:write" ] }, "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string" }, "activityId": { "$ref": "#/components/schemas/ActivityId" } }, "required": [ "error" ] }, "Application": { "type": "object", "properties": { "applicationId": { "$ref": "#/components/schemas/ApplicationId" }, "displayName": { "type": "string" } }, "required": [ "applicationId", "displayName" ], "additionalProperties": false }, "ApplicationList": { "type": "object", "properties": { "applications": { "type": "array", "items": { "$ref": "#/components/schemas/Application" } }, "activityId": { "$ref": "#/components/schemas/ActivityId" } }, "required": [ "applications" ] }, "CredentialIssue": { "type": "object", "properties": { "applicationId": { "$ref": "#/components/schemas/ApplicationId" }, "label": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/Scope" }, "minItems": 1, "uniqueItems": true, "contains": { "const": "marketing:read" } }, "expiresInDays": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30 } }, "required": [ "applicationId", "label", "scopes" ], "additionalProperties": false }, "Credential": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^mkt_[a-f0-9]{32}$" }, "label": { "type": "string" }, "applicationId": { "$ref": "#/components/schemas/ApplicationId" }, "developerAccountId": { "type": "string", "description": "Issuing staff account; this is never a consumer identity." }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/Scope" } }, "createdAt": { "type": "integer", "minimum": 0, "description": "Unix milliseconds." }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Unix milliseconds." }, "revokedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "Unix milliseconds." }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ] } }, "required": [ "id", "label", "applicationId", "developerAccountId", "scopes", "createdAt", "expiresAt", "revokedAt", "status" ] }, "CredentialIssued": { "allOf": [ { "$ref": "#/components/schemas/Credential" }, { "type": "object", "properties": { "credential": { "type": "string", "pattern": "^mkt_[a-f0-9]{32}\\.[A-Za-z0-9_-]{43}$", "description": "Secret displayed once. Move directly into a server secret store; never embed it in a web app or record it in a trace.", "readOnly": true } }, "required": [ "credential" ] } ] }, "CredentialList": { "type": "object", "properties": { "credentials": { "type": "array", "items": { "$ref": "#/components/schemas/Credential" } }, "availableScopes": { "type": "array", "items": { "$ref": "#/components/schemas/Scope" } } }, "required": [ "credentials", "availableScopes" ] }, "Rule": { "type": "object", "properties": { "definitionId": { "type": "string", "minLength": 1 }, "version": { "type": "integer", "minimum": 1 }, "operator": { "type": "string", "enum": [ "equals", "contains", "gte", "lte", "matches" ] }, "value": { "oneOf": [ { "type": [ "string", "number", "boolean" ] }, { "$ref": "#/components/schemas/EventMatch" } ] } }, "required": [ "definitionId", "version", "operator", "value" ], "additionalProperties": false, "description": "Use an ID/version from this workspace. equals supports enum/boolean/numeric; gte/lte numeric; contains enumset. Values must match the definition domain. matches requires an EventMatch value for a registered event; property types, catalog membership and lookback are validated against its definition." }, "Criterion": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,80}$" }, "definitionId": { "type": "string", "minLength": 1 }, "version": { "type": "integer", "minimum": 1 }, "operator": { "type": "string", "enum": [ "equals", "contains", "gte", "lte", "matches" ] }, "value": { "oneOf": [ { "type": [ "string", "number", "boolean" ] }, { "$ref": "#/components/schemas/EventMatch" } ] } }, "required": [ "id", "definitionId", "version", "operator", "value" ], "additionalProperties": false }, "AudienceLeaf": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,80}$" }, "insight": { "type": "string", "description": "ID of a criterion in criteria." }, "logic": { "type": "string", "enum": [ "AND", "OR" ] } }, "required": [ "id", "insight" ], "additionalProperties": false }, "AudienceGroup": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,80}$" }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "peerLogic": { "type": "string", "enum": [ "AND", "OR" ] }, "children": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/AudienceLeaf" }, { "$ref": "#/components/schemas/AudienceGroup" } ] }, "minItems": 1 } }, "required": [ "id", "children" ], "additionalProperties": false, "description": "Groups evaluate children left to right, using leaf logic or group peerLogic. Defaults are AND. Whole tree: at most 256 nodes and depth 16; node IDs are unique." }, "AudienceSimple": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "mode": { "type": "string", "enum": [ "all", "any" ] }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/Rule" }, "minItems": 1, "maxItems": 8 }, "tags": { "$ref": "#/components/schemas/Tags" }, "minimumCvbRating": { "$ref": "#/components/schemas/CvbThreshold" } }, "required": [ "name", "mode", "rules" ], "additionalProperties": false, "description": "A definition ID may appear only once in a simple audience." }, "AudienceStructured": { "type": "object", "properties": { "schemaVersion": { "const": 2 }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "logic": { "allOf": [ { "$ref": "#/components/schemas/AudienceGroup" }, { "properties": { "id": { "const": "head" } } } ] }, "criteria": { "type": "array", "items": { "$ref": "#/components/schemas/Criterion" }, "minItems": 1, "maxItems": 64 }, "tags": { "$ref": "#/components/schemas/Tags" }, "minimumCvbRating": { "$ref": "#/components/schemas/CvbThreshold" } }, "required": [ "schemaVersion", "name", "logic", "criteria" ], "additionalProperties": false, "description": "Every criterion ID is unique and used by at least one leaf. Root id is head." }, "AudienceInput": { "oneOf": [ { "$ref": "#/components/schemas/AudienceSimple" }, { "$ref": "#/components/schemas/AudienceStructured" } ] }, "AudienceSave": { "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "mode": { "type": "string", "enum": [ "all", "any" ] }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/Rule" }, "minItems": 1, "maxItems": 8 }, "audienceId": { "type": "string" }, "tags": { "$ref": "#/components/schemas/Tags" }, "minimumCvbRating": { "$ref": "#/components/schemas/CvbThreshold" } }, "required": [ "name", "mode", "rules" ], "additionalProperties": false }, { "type": "object", "properties": { "schemaVersion": { "const": 2 }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "logic": { "allOf": [ { "$ref": "#/components/schemas/AudienceGroup" }, { "properties": { "id": { "const": "head" } } } ] }, "criteria": { "type": "array", "items": { "$ref": "#/components/schemas/Criterion" }, "minItems": 1, "maxItems": 64 }, "audienceId": { "type": "string" }, "tags": { "$ref": "#/components/schemas/Tags" }, "minimumCvbRating": { "$ref": "#/components/schemas/CvbThreshold" } }, "required": [ "schemaVersion", "name", "logic", "criteria" ], "additionalProperties": false } ], "description": "Omit audienceId to create; provide an existing same-app ID to replace its definition. Referencing campaign drafts retain snapshots and are marked audienceChanged." }, "AudienceMutation": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0 }, "payload": { "$ref": "#/components/schemas/AudienceSave" }, "idempotencyKey": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,120}$", "description": "Optional application/actor/operation-scoped key. Identical retries return original saved receipt; changed payload returns 409. No expiry; capacity 2000 per workspace." } }, "required": [ "expectedRevision", "payload" ], "additionalProperties": false }, "CountRequest": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0 }, "audience": { "$ref": "#/components/schemas/AudienceInput" } }, "required": [ "expectedRevision", "audience" ], "additionalProperties": false }, "CountResult": { "oneOf": [ { "type": "object", "properties": { "available": { "const": true }, "count": { "type": "integer", "minimum": 0 }, "eligible": { "type": "integer", "minimum": 0 }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "logic": { "type": "string" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "id", "logic", "count" ], "additionalProperties": false } }, "asOf": { "type": "string", "format": "date-time" }, "basis": { "type": "string" }, "sample": { "const": false }, "activityId": { "$ref": "#/components/schemas/ActivityId" } }, "required": [ "available", "count", "eligible", "breakdown", "asOf", "basis", "sample" ] }, { "type": "object", "properties": { "available": { "const": false }, "count": { "type": "null" }, "reason": { "type": "string" }, "activityId": { "$ref": "#/components/schemas/ActivityId" } }, "required": [ "available", "count", "reason" ] } ] }, "Creative": { "type": "object", "properties": { "headline": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "body": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "cta": { "type": "string", "minLength": 1, "maxLength": 60, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "landingUrl": { "type": "string", "description": "Optional public HTTPS company destination, without username, password, query string or fragment. Empty uses the saved Mementom offer page." }, "image": { "type": "string", "description": "Optional PNG/JPEG/WebP base64 data URL. Creative writes use a 4 MiB JSON request envelope; uploaded files may be prepared automatically before saving." }, "brandName": { "type": "string", "maxLength": 80, "description": "Brand shown on the creative. Empty leaves the brand line blank. Plain text only." }, "offerLabel": { "type": "string", "maxLength": 120, "description": "Authored offer label or badge. No reward or completion wording is inserted automatically. Plain text only." }, "terms": { "type": "string", "maxLength": 1000, "description": "Offer terms shown as authored. Plain text only." }, "promoCode": { "type": "string", "maxLength": 80, "description": "Optional promotional code. Plain text only." }, "imageAlt": { "type": "string", "maxLength": 180, "description": "Description of the creative image for assistive technology. Plain text only." }, "design": { "$ref": "#/components/schemas/CreativeDesign" }, "productId": { "type": "string", "maxLength": 120, "description": "Canonical same-application ID from get_product. Aliases resolve only through registered mappings. Audience choices are not inventory." }, "landingDetails": { "type": "string", "maxLength": 5000 }, "discount": { "oneOf": [ { "type": "object", "properties": { "percent": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "percent" ], "additionalProperties": false }, { "type": "null" } ], "description": "Offer discount requires a productId. Omit or supply null for no discount." } }, "required": [ "headline", "body", "cta" ], "additionalProperties": false }, "QuestionInsight": { "type": "object", "properties": { "definitionId": { "type": "string" }, "version": { "type": "integer", "minimum": 1 } }, "required": [ "definitionId", "version" ], "additionalProperties": false }, "QuestionV1": { "type": "object", "properties": { "schemaVersion": { "const": 1 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 240, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "questionType": { "type": "string", "enum": [ "multipleChoice", "boolean", "slider" ] }, "answerType": { "type": "string", "enum": [ "single", "multiple" ] }, "maxAnswers": { "type": "integer", "minimum": 1, "maximum": 20 }, "step": { "type": "integer", "minimum": 1 }, "insight": { "$ref": "#/components/schemas/QuestionInsight" } }, "required": [ "schemaVersion", "prompt", "questionType", "answerType", "maxAnswers", "insight" ], "additionalProperties": false, "description": "Use an approved or standard company insight of the same type. Multiple choice uses enum choices; boolean and slider require single answer and maxAnswers=1. Slider requires integer step dividing the registered integer range; other types forbid step. Choice count and maxAnswers must fit the registered domain." }, "LegacyQuestion": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "maxLength": 240, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "options": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "minItems": 2, "maxItems": 8, "uniqueItems": true } }, "required": [ "prompt", "options" ], "additionalProperties": false, "description": "Existing unbound question compatibility. New integrations should use QuestionV1 for typed answers and registered insight provenance." }, "QuestionInput": { "oneOf": [ { "$ref": "#/components/schemas/QuestionV1" }, { "$ref": "#/components/schemas/LegacyQuestion" } ] }, "ContentFields": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "type": { "type": "string", "enum": [ "offer", "questionnaire", "insight_request" ] }, "content": { "$ref": "#/components/schemas/Creative" }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/QuestionInput" }, "maxItems": 10 }, "requestedInsightIds": { "type": "array", "items": { "type": "string" }, "maxItems": 20, "uniqueItems": true }, "tags": { "$ref": "#/components/schemas/Tags" }, "engagementMinor": { "type": "integer", "minimum": 0, "maximum": 100000, "multipleOf": 2, "description": "Default combined fee in cents. Omission preserves a saved or duplicated value; new content defaults to 200. Campaign placements may select their own fee." }, "purchaseMinor": { "type": "integer", "minimum": 0, "maximum": 100000, "multipleOf": 2, "description": "Default combined fee in cents. Omission preserves a saved or duplicated value; new content defaults to 0. Campaign placements may select their own fee." } }, "required": [ "name", "type", "content", "questions", "requestedInsightIds" ], "additionalProperties": false, "description": "Questionnaire: 1\u201310 questions. Other types: questions must be empty. Insight request: at least one requestedInsightId. All insight IDs belong to this workspace catalog." }, "ContentSave": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "type": { "type": "string", "enum": [ "offer", "questionnaire", "insight_request" ] }, "content": { "$ref": "#/components/schemas/Creative" }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/QuestionInput" }, "maxItems": 10 }, "requestedInsightIds": { "type": "array", "items": { "type": "string" }, "maxItems": 20, "uniqueItems": true }, "contentId": { "type": "string" }, "expectedContentRevision": { "type": "integer", "minimum": 1 }, "duplicateFromId": { "type": "string" }, "tags": { "$ref": "#/components/schemas/Tags" }, "engagementMinor": { "type": "integer", "minimum": 0, "maximum": 100000, "multipleOf": 2, "description": "Company completion fee. Offers: verified accepted arrival, not a click; questionnaires: completed response. Consumer and platform each receive half; settlement is separate." }, "purchaseMinor": { "type": "integer", "minimum": 0, "maximum": 100000, "multipleOf": 2, "description": "Independent cumulative company fee for verified purchase after accepted arrival. Event validation exists; no production callback endpoint or settlement. Zero disables this fee." }, "verifiedLandingMinor": { "type": "integer", "minimum": 0, "maximum": 100000, "multipleOf": 2, "description": "Offer-only alias for engagementMinor. Must agree if both are supplied. Verified arrival_confirmed only, never a raw click." }, "cpcMinor": { "type": "integer", "minimum": 0, "maximum": 100000, "multipleOf": 2, "description": "Company total fee for one distinct confirmed event; cumulative with configured landing/purchase fees, split equally between consumer and platform." } }, "required": [ "name", "type", "content", "questions", "requestedInsightIds" ], "additionalProperties": false, "description": "Omit IDs to create. Edit with contentId and its current expectedContentRevision. Duplicate with duplicateFromId and a complete payload; do not combine it with contentId. A new/duplicate record forbids expectedContentRevision. Historical editions remain available for campaign snapshots." }, "ContentMutation": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0 }, "payload": { "$ref": "#/components/schemas/ContentSave" }, "idempotencyKey": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,120}$", "description": "Optional application/actor/operation-scoped key. Identical retries return original saved receipt; changed payload returns 409. No expiry; capacity 2000 per workspace." } }, "required": [ "expectedRevision", "payload" ], "additionalProperties": false }, "Engagement": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "type": { "type": "string", "enum": [ "offer", "questionnaire", "insight_request" ] }, "content": { "$ref": "#/components/schemas/Creative" }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/QuestionInput" }, "maxItems": 10 }, "requestedInsightIds": { "type": "array", "items": { "type": "string" }, "maxItems": 20, "uniqueItems": true }, "audienceIds": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 20, "uniqueItems": true }, "excludedAudienceIds": { "type": "array", "items": { "type": "string" }, "maxItems": 20, "uniqueItems": true }, "refinements": { "type": "array", "items": { "$ref": "#/components/schemas/Rule" }, "maxItems": 8 }, "engagementMinor": { "type": "integer", "minimum": 0, "maximum": 100000, "multipleOf": 2, "description": "Company completion fee. Offers: verified accepted arrival, not a click; questionnaires: completed response. Consumer and platform each receive half; settlement is separate." }, "purchaseMinor": { "type": "integer", "minimum": 0, "maximum": 100000, "multipleOf": 2, "description": "Independent cumulative company fee for verified purchase after accepted arrival. Event validation exists; no production callback endpoint or settlement. Zero disables this fee." }, "contentId": { "type": "string" }, "contentRevision": { "type": "integer", "minimum": 1 }, "tags": { "$ref": "#/components/schemas/Tags" }, "verifiedLandingMinor": { "type": "integer", "minimum": 0, "maximum": 100000, "multipleOf": 2, "description": "Offer-only alias for engagementMinor. Must agree if both are supplied. Verified arrival_confirmed only, never a raw click." }, "cpcMinor": { "type": "integer", "minimum": 0, "maximum": 100000, "multipleOf": 2, "description": "Company total fee for one distinct confirmed event; cumulative with configured landing/purchase fees, split equally between consumer and platform." } }, "required": [ "name", "type", "content", "questions", "requestedInsightIds", "audienceIds", "purchaseMinor" ], "additionalProperties": false, "description": "Include at least one same-app saved audience; included/excluded IDs must be disjoint. Combined engagement and purchase fees must be positive. Purchase fees only apply to offers. Optional saved contentId/contentRevision require the full unchanged author-controlled content of that edition; the service snapshots definitions and content." }, "CampaignV2": { "type": "object", "properties": { "schemaVersion": { "const": 2 }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "objective": { "type": "string", "enum": [ "return_visitors", "learn_preferences", "collect_insights" ] }, "startAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "budgetMinor": { "type": "integer", "minimum": 1, "maximum": 100000000 }, "dailyCapMinor": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100000000 }, { "type": "null" } ], "description": "Optional daily cap. Omitted/null means no separate daily limit; total budget remains enforced." }, "responseWindowHours": { "type": "integer", "enum": [ 24, 72, 168 ] }, "emailDelivery": { "type": "string", "enum": [ "mementom", "company" ], "default": "mementom", "description": "Mementom automatically emails authorized campaign matches. Choose company to defer automatic email to company delivery through campaign aliases; Personal Agent publication continues." }, "engagements": { "type": "array", "items": { "$ref": "#/components/schemas/Engagement" }, "minItems": 1, "maxItems": 10 }, "tags": { "$ref": "#/components/schemas/Tags" }, "minimumCvbRating": { "$ref": "#/components/schemas/CvbThreshold" }, "currency": { "type": "string", "enum": [ "USD" ] }, "paymentAgreementId": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Explicit applicable agreement ID from get_payment_agreement; required when multiple agreements apply." } }, "required": [ "schemaVersion", "name", "objective", "startAt", "endAt", "budgetMinor", "responseWindowHours", "engagements" ], "additionalProperties": false, "description": "Creates a draft. Published creative is immutable. Total and optional daily budget must cover maximum click + completion + purchase + insight exposure per delivery. Currency USD, integer cents. Fees are company total costs; configured fees are not settled payments." }, "LegacyCampaign": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "audienceId": { "type": "string" }, "engagementMinor": { "type": "integer", "minimum": 2, "maximum": 100000, "multipleOf": 2 }, "budgetMinor": { "type": "integer", "minimum": 2, "maximum": 100000000 }, "tags": { "$ref": "#/components/schemas/Tags" } }, "required": [ "name", "audienceId", "engagementMinor", "budgetMinor" ], "additionalProperties": false, "description": "Legacy simple draft compatibility; new integrations should use CampaignV2." }, "CampaignInput": { "oneOf": [ { "$ref": "#/components/schemas/CampaignV2" }, { "$ref": "#/components/schemas/LegacyCampaign" }, { "$ref": "#/components/schemas/CampaignUpdate" } ] }, "CampaignMutation": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0 }, "payload": { "$ref": "#/components/schemas/CampaignInput" }, "idempotencyKey": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,120}$", "description": "Optional application/actor/operation-scoped key. Identical retries return original saved receipt; changed payload returns 409. No expiry; capacity 2000 per workspace." } }, "required": [ "expectedRevision", "payload" ], "additionalProperties": false }, "PricingPolicy": { "type": "object", "properties": { "schemaVersion": { "const": 1 }, "brandTier": { "type": "string", "enum": [ "free", "basic", "pro", "enterprise" ] }, "marketTier": { "type": "string", "enum": [ "economy", "retail", "mid", "luxury", "ultra" ] }, "sourceWeight": { "type": "number", "minimum": 0, "maximum": 1 }, "dataPointWeight": { "type": "number", "minimum": 0, "maximum": 1 }, "uniquenessWeight": { "type": "number", "minimum": 0, "maximum": 1 }, "confidenceWeight": { "type": "number", "minimum": 0, "maximum": 1 }, "baseCPA": { "type": "number", "minimum": 0, "maximum": 1000, "description": "Scenario base purchase fee in dollars; this is not a charge." }, "splitAddOnCostsWithCPA": { "type": "boolean" } }, "additionalProperties": false, "description": "Planning assumptions. Omitted fields reset to documented defaults: version 1, pro/retail, weights .15/.1/.5/1, baseCPA 5, split false. This is not a patch against prior custom settings." }, "PricingProfile": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "demographic", "location", "behavior", "question" ] }, "purchaseType": { "type": "string", "enum": [ "general", "precision", "subscription" ] }, "baseMinor": { "type": "integer", "minimum": 0, "maximum": 100000 }, "sourceCount": { "type": "integer", "minimum": 1, "maximum": 100 }, "dataPointCount": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "uniqueness": { "type": "number", "minimum": 0, "maximum": 1 }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "ageDays": { "type": "number", "minimum": 0, "maximum": 36500 }, "halfLifeDays": { "type": "number", "minimum": 1, "maximum": 3650 }, "expiresAfterDays": { "type": "number", "minimum": 1, "maximum": 3650 } }, "additionalProperties": false, "description": "One outside-catalog definition only. Omitted values use default behavior/general, counts 1, uniqueness 0, confidence 1, age 0, half-life 30, expiry 90. No paid license or settlement is created." }, "PricingInput": { "oneOf": [ { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/PricingPolicy" } }, "required": [ "policy" ], "additionalProperties": false }, { "type": "object", "properties": { "definitionId": { "type": "string" }, "profile": { "$ref": "#/components/schemas/PricingProfile" } }, "required": [ "definitionId", "profile" ], "additionalProperties": false } ] }, "PricingMutation": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0 }, "payload": { "$ref": "#/components/schemas/PricingInput" }, "idempotencyKey": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,120}$", "description": "Optional application/actor/operation-scoped key. Identical retries return original saved receipt; changed payload returns 409. No expiry; capacity 2000 per workspace." } }, "required": [ "expectedRevision", "payload" ], "additionalProperties": false }, "InsightProposal": { "oneOf": [ { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]*(?:\\.[a-z][a-z0-9_]*)+$", "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "description": { "type": "string", "minLength": 1, "maxLength": 240, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "windowDays": { "type": "integer", "minimum": 1, "maximum": 30 }, "ttlDays": { "type": "integer", "minimum": 1, "maximum": 30 }, "type": { "const": "enum" }, "values": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 48, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "minItems": 2, "maxItems": 20, "uniqueItems": true } }, "required": [ "key", "label", "description", "windowDays", "ttlDays", "type", "values" ], "additionalProperties": false }, { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]*(?:\\.[a-z][a-z0-9_]*)+$", "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "description": { "type": "string", "minLength": 1, "maxLength": 240, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "windowDays": { "type": "integer", "minimum": 1, "maximum": 30 }, "ttlDays": { "type": "integer", "minimum": 1, "maximum": 30 }, "type": { "const": "boolean" } }, "required": [ "key", "label", "description", "windowDays", "ttlDays", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]*(?:\\.[a-z][a-z0-9_]*)+$", "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "description": { "type": "string", "minLength": 1, "maxLength": 240, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "windowDays": { "type": "integer", "minimum": 1, "maximum": 30 }, "ttlDays": { "type": "integer", "minimum": 1, "maximum": 30 }, "type": { "const": "integer" }, "minimum": { "type": "integer", "minimum": 0, "maximum": 99 }, "maximum": { "type": "integer", "minimum": 0, "maximum": 99 } }, "required": [ "key", "label", "description", "windowDays", "ttlDays", "type", "minimum", "maximum" ], "additionalProperties": false } ], "description": "Non-identifying custom definition only. No email, phone, address, identifiers, links or long numeric strings in metadata. Maximum >= minimum. Categories unique after normalization and case folding. Saved pending_review; an authorized developer owner/admin must review before use. Existing keys are immutable; standard template keys cannot be proposed." }, "ProposalMutation": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0 }, "payload": { "$ref": "#/components/schemas/InsightProposal" }, "idempotencyKey": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,120}$", "description": "Optional application/actor/operation-scoped key. Identical retries return original saved receipt; changed payload returns 409. No expiry; capacity 2000 per workspace." } }, "required": [ "expectedRevision", "payload" ], "additionalProperties": false }, "ObjectiveInput": { "type": "object", "properties": { "objective": { "type": "string", "enum": [ "return_visitors", "learn_preferences" ] } }, "required": [ "objective" ], "additionalProperties": false }, "ObjectiveMutation": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0 }, "payload": { "$ref": "#/components/schemas/ObjectiveInput" }, "idempotencyKey": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,120}$", "description": "Optional application/actor/operation-scoped key. Identical retries return original saved receipt; changed payload returns 409. No expiry; capacity 2000 per workspace." } }, "required": [ "expectedRevision", "payload" ], "additionalProperties": false }, "InsightDefinition": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "version": { "type": "integer", "minimum": 1 }, "label": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "enum", "enumset", "boolean", "integer", "number" ] }, "values": { "type": "array", "items": { "type": [ "string", "number", "boolean" ] } }, "minimum": { "type": "number" }, "maximum": { "type": "number" }, "windowDays": { "type": "integer", "minimum": 0 }, "ttlDays": { "type": "integer", "minimum": 0 }, "status": { "type": "string" }, "source": { "type": "string" }, "priceMinor": { "type": "integer", "minimum": 0 }, "isSample": { "type": "boolean" }, "sample": { "type": "object" }, "pricing": { "$ref": "#/components/schemas/PricingEstimate" } }, "required": [ "id", "key", "version", "label", "type" ] }, "PricingEstimate": { "type": "object", "properties": { "status": { "const": "planning_estimate" }, "version": { "type": "string" }, "currency": { "const": "USD" }, "dataMinor": { "type": "integer", "minimum": 0 }, "engagementMinor": { "type": "integer", "minimum": 0 }, "totalMinor": { "type": "integer", "minimum": 0 }, "consumerMinor": { "type": "number" }, "platformMinor": { "type": "number" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PricingLine" } }, "quoteAvailable": { "const": false }, "outsideConsentRequired": { "type": "boolean" }, "expiredDefinitionIds": { "type": "array", "items": { "type": "string" } }, "scope": { "type": "string" }, "reference": { "type": "object" }, "policy": { "$ref": "#/components/schemas/PricingPolicy" } }, "description": "Planning estimate, not a live quote, authorized charge or settled payment. Per-field valuations also have this status and may expose factors/profile/baseMinor/priceMinor." }, "SavedAudience": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "schemaVersion": { "const": 2 }, "mode": { "type": "string", "enum": [ "all", "any", "structured" ] }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/Rule" } }, "logic": { "$ref": "#/components/schemas/AudienceGroup" }, "criteria": { "type": "array", "items": { "$ref": "#/components/schemas/Criterion" } }, "status": { "const": "draft" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "pricing": { "$ref": "#/components/schemas/PricingEstimate" }, "isSample": { "type": "boolean" }, "sample": { "type": "object" }, "tags": { "$ref": "#/components/schemas/Tags" } }, "required": [ "id", "name", "mode", "rules", "status", "pricing" ] }, "SavedContent": { "type": "object", "properties": { "id": { "type": "string" }, "revision": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "offer", "questionnaire", "insight_request" ] }, "content": { "$ref": "#/components/schemas/Creative" }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/SavedQuestion" } }, "requestedInsightIds": { "type": "array", "items": { "type": "string" } }, "requestedInsights": { "type": "array", "items": { "$ref": "#/components/schemas/InsightDefinition" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "editions": { "type": "array", "items": { "$ref": "#/components/schemas/ContentEdition" } }, "duplicatedFromId": { "type": "string" }, "isSample": { "type": "boolean" }, "tags": { "$ref": "#/components/schemas/Tags" }, "engagementMinor": { "type": "integer", "minimum": 0, "maximum": 100000, "multipleOf": 2, "description": "Company completion fee. Offers: verified accepted arrival, not a click; questionnaires: completed response. Consumer and platform each receive half; settlement is separate." }, "purchaseMinor": { "type": "integer", "minimum": 0, "maximum": 100000, "multipleOf": 2, "description": "Independent cumulative company fee for verified purchase after accepted arrival. Event validation exists; no production callback endpoint or settlement. Zero disables this fee." }, "hostedUrl": { "type": "string", "format": "uri", "readOnly": true, "description": "Mementom offer preview for the owning company session. Draft saving does not publish it." }, "verifiedLandingMinor": { "type": "integer", "minimum": 0, "maximum": 100000, "multipleOf": 2, "description": "Offer-only alias for engagementMinor. Must agree if both are supplied. Verified arrival_confirmed only, never a raw click." }, "cpcMinor": { "type": "integer", "minimum": 0, "maximum": 100000, "multipleOf": 2, "description": "Company total fee for one distinct confirmed event; cumulative with configured landing/purchase fees, split equally between consumer and platform." } }, "required": [ "id", "revision", "name", "type", "content", "questions", "requestedInsightIds" ] }, "SavedCampaign": { "type": "object", "properties": { "id": { "type": "string" }, "schemaVersion": { "const": 2 }, "revision": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "stopped", "deleted" ] }, "objective": { "type": "string", "enum": [ "return_visitors", "learn_preferences", "collect_insights" ] }, "engagements": { "type": "array", "items": { "$ref": "#/components/schemas/SavedEngagement" } }, "budgetMinor": { "type": "integer", "minimum": 0 }, "dailyCapMinor": { "type": "integer", "minimum": 0 }, "responseWindowHours": { "type": "integer", "minimum": 0 }, "startAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "routing": { "const": "first_matching_engagement" }, "frequency": { "const": "once_per_campaign" }, "audienceChanged": { "type": "boolean" }, "pricingChanged": { "type": "boolean" }, "isSample": { "type": "boolean" }, "pricing": { "$ref": "#/components/schemas/PricingEstimate" }, "tags": { "$ref": "#/components/schemas/Tags" }, "targetingRevision": { "type": "integer", "minimum": 0 }, "duplicatedFromId": { "type": "string" }, "duplicatedFromRevision": { "type": "integer", "minimum": 1 }, "minimumCvbRating": { "$ref": "#/components/schemas/CvbThreshold" }, "consoleUrl": { "type": "string", "format": "uri", "description": "Service-returned campaign detail link; preserves selected application and campaign through normal key authorization." } }, "required": [ "id", "name", "status", "budgetMinor", "createdAt" ] }, "Workspace": { "type": "object", "properties": { "applicationId": { "$ref": "#/components/schemas/ApplicationId" }, "revision": { "type": "integer", "minimum": 0 }, "definitions": { "type": "array", "items": { "$ref": "#/components/schemas/InsightDefinition" } }, "outsideCatalog": { "type": "array", "items": { "$ref": "#/components/schemas/InsightDefinition" } }, "captureCatalog": { "type": "array", "items": { "$ref": "#/components/schemas/InsightDefinition" } }, "audiences": { "type": "array", "items": { "$ref": "#/components/schemas/SavedAudience" } }, "contentLibrary": { "type": "array", "items": { "$ref": "#/components/schemas/SavedContent" } }, "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/SavedCampaign" } }, "objective": { "type": "string", "enum": [ "return_visitors", "learn_preferences" ] }, "pricingPolicy": { "$ref": "#/components/schemas/PricingPolicy" }, "pricingProfiles": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/PricingProfile" } }, "pricingUpdatedAt": { "type": "string", "format": "date-time" }, "suggestions": { "type": "array", "items": { "type": "object" } }, "sampleSummary": { "type": "object" }, "market": { "type": "object", "description": "Aggregate catalog coverage and provenance; earnings may be unavailable." }, "capabilities": { "type": "object", "properties": { "consumerIngestion": { "const": true }, "companyInsightMatching": { "const": true }, "holderPermissionRequired": { "const": false }, "outreach": { "const": false }, "billing": { "const": false }, "samples": { "const": true }, "campaignTests": { "type": "boolean", "description": "Local QA capability, not authorization for bearer credentials to simulate." } }, "required": [ "consumerIngestion", "companyInsightMatching", "holderPermissionRequired", "outreach", "billing" ] }, "readiness": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time" }, "activityId": { "$ref": "#/components/schemas/ActivityId" } }, "required": [ "applicationId", "revision", "definitions", "outsideCatalog", "audiences", "contentLibrary", "campaigns", "objective", "pricingPolicy", "pricingProfiles", "capabilities", "readiness", "generatedAt" ], "description": "Same saved records as the marketing console. Marketing responses omit developer-only templates, datasets and ingestion receipts. Respect isSample and market provenance; catalog planning examples are not paid inventory." }, "ReportMetrics": { "type": "object", "properties": { "delivered": { "type": "integer", "minimum": 0 }, "viewed": { "type": "integer", "minimum": 0 }, "started": { "type": "integer", "minimum": 0 }, "responded": { "type": "integer", "minimum": 0 }, "completed": { "type": "integer", "minimum": 0 }, "arrivals": { "type": "integer", "minimum": 0 }, "insightsReleased": { "type": "integer", "minimum": 0 }, "purchases": { "type": "integer", "minimum": 0 }, "reversals": { "type": "integer", "minimum": 0 }, "netPurchases": { "type": "integer", "minimum": 0 }, "optedOut": { "type": "integer", "minimum": 0 }, "mature": { "type": "integer", "minimum": 0 }, "matureResponded": { "type": "integer", "minimum": 0 }, "matureStarted": { "type": "integer", "minimum": 0 }, "matureCompleted": { "type": "integer", "minimum": 0 }, "matureArrivals": { "type": "integer", "minimum": 0 }, "matureNetPurchases": { "type": "integer", "minimum": 0 }, "pending": { "type": "integer", "minimum": 0 }, "timedResponders": { "type": "integer", "minimum": 0 }, "viewTimedResponders": { "type": "integer", "minimum": 0 }, "modeledSpendMinor": { "type": "integer", "minimum": 0 }, "modeledConsumerMinor": { "type": "integer", "minimum": 0 }, "responseRate": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "matureResponseRate": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "medianResponseMs": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "p90ResponseMs": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "medianViewedResponseMs": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "costPerResponseMinor": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "costPerPurchaseMinor": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "revenueMinor": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "settledMinor": { "type": "null", "description": "No settlement integration." }, "windows": { "type": "array", "items": { "type": "object", "properties": { "hours": { "type": "integer", "minimum": 0 }, "eligible": { "type": "integer", "minimum": 0 }, "responded": { "type": "integer", "minimum": 0 } }, "required": [ "hours", "eligible", "responded" ], "additionalProperties": false } }, "clicks": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "modeledClickMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "modeledCompletionMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "modeledPurchaseMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "modeledInsightMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 } }, "required": [ "delivered", "viewed", "started", "responded", "completed", "arrivals", "insightsReleased", "purchases", "reversals", "netPurchases", "optedOut", "mature", "matureResponded", "matureStarted", "matureCompleted", "matureArrivals", "matureNetPurchases", "pending", "timedResponders", "viewTimedResponders", "modeledSpendMinor", "modeledConsumerMinor", "responseRate", "matureResponseRate", "medianResponseMs", "p90ResponseMs", "medianViewedResponseMs", "costPerResponseMinor", "costPerPurchaseMinor", "revenueMinor", "settledMinor", "windows" ], "description": "Counts are aggregate. Rates and monetary ratios are null when their denominator is zero. Revenue is null unless all net purchases carry recorded amounts. Modeled costs are not settled spend." }, "Report": { "type": "object", "properties": { "schemaVersion": { "const": 1 }, "campaignId": { "type": "string" }, "campaignRevision": { "type": "integer", "minimum": 1 }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "generatedAt": { "type": "string", "format": "date-time" }, "windowHours": { "type": "integer", "minimum": 0 }, "overview": { "$ref": "#/components/schemas/ReportMetrics" }, "budgetMinor": { "type": "integer", "minimum": 0 }, "isSample": { "type": "boolean" }, "recommendations": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "evidence": { "type": "string" }, "action": { "type": "string" }, "confidence": { "type": "string" } }, "required": [ "title", "evidence", "action", "confidence" ], "additionalProperties": false } }, "engagements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "offer", "questionnaire", "insight_request" ] }, "audiences": { "type": "array", "items": { "type": "string" } }, "metrics": { "$ref": "#/components/schemas/ReportMetrics" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "prompt": { "type": "string" }, "questionType": { "type": "string" }, "answerType": { "type": "string" }, "insight": { "anyOf": [ { "$ref": "#/components/schemas/QuestionInsight" }, { "type": "null" } ] }, "insightLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "provenance": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "answered": { "type": "integer", "minimum": 0 }, "distribution": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "label", "count" ], "additionalProperties": false } }, { "type": "null" } ] } }, "required": [ "id", "prompt", "answered", "distribution" ] } }, "tags": { "$ref": "#/components/schemas/Tags" } }, "required": [ "id", "name", "type", "audiences", "metrics", "questions" ], "additionalProperties": false } }, "limitations": { "type": "array", "items": { "type": "string" } }, "activityId": { "$ref": "#/components/schemas/ActivityId" }, "tags": { "$ref": "#/components/schemas/Tags" } }, "required": [ "schemaVersion", "campaignId", "campaignRevision", "mode", "generatedAt", "windowHours", "overview", "budgetMinor", "isSample", "recommendations", "engagements", "limitations" ], "description": "Read-only aggregate report. Test is synthetic, never live evidence. Starter-pack examples can generate an unpersisted synthetic preview. Zero events do not prove delivery. Live question distributions are withheld below five answers." }, "ActivityEvent": { "type": "object", "properties": { "eventId": { "type": "string" }, "eventType": { "type": "string" }, "result": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "activityId": { "$ref": "#/components/schemas/ActivityId" }, "operation": { "type": "string" }, "method": { "type": "string" }, "status": { "type": "integer", "minimum": 100, "maximum": 599 }, "revision": { "type": "integer", "minimum": 0 }, "error": { "type": "string" }, "source": { "type": "string", "enum": [ "server", "console", "mcp" ] }, "blockers": { "type": "array", "items": { "$ref": "#/components/schemas/PreflightIssue" } } }, "required": [ "eventId", "eventType", "result", "createdAt" ], "description": "Safe operational projection. Never contains Authorization, credentials, raw request content, images, captions, or consumer identifiers." }, "ActivityList": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityEvent" } }, "total": { "type": "integer", "minimum": 0 }, "offset": { "type": "integer", "minimum": 0, "maximum": 10000 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "activityId": { "$ref": "#/components/schemas/ActivityId" } }, "required": [ "events", "total" ] }, "SavedEngagement": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "type": { "type": "string", "enum": [ "offer", "questionnaire", "insight_request" ] }, "content": { "$ref": "#/components/schemas/Creative" }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/SavedQuestion" } }, "requestedInsightIds": { "type": "array", "items": { "type": "string" }, "maxItems": 20, "uniqueItems": true }, "audienceIds": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 20, "uniqueItems": true }, "excludedAudienceIds": { "type": "array", "items": { "type": "string" }, "maxItems": 20, "uniqueItems": true }, "refinements": { "type": "array", "items": { "$ref": "#/components/schemas/Rule" }, "maxItems": 8 }, "engagementMinor": { "type": "integer", "minimum": 0, "maximum": 100000, "multipleOf": 2, "description": "Company completion fee. Offers: verified accepted arrival, not a click; questionnaires: completed response. Consumer and platform each receive half; settlement is separate." }, "purchaseMinor": { "type": "integer", "minimum": 0, "maximum": 100000, "multipleOf": 2, "description": "Independent cumulative company fee for verified purchase after accepted arrival. Event validation exists; no production callback endpoint or settlement. Zero disables this fee." }, "contentId": { "type": "string" }, "contentRevision": { "type": "integer", "minimum": 1 }, "id": { "type": "string" }, "audienceSnapshots": { "type": "array", "items": { "$ref": "#/components/schemas/SavedAudience" } }, "excludedAudienceSnapshots": { "type": "array", "items": { "$ref": "#/components/schemas/SavedAudience" } }, "requestedInsights": { "type": "array", "items": { "$ref": "#/components/schemas/InsightDefinition" } }, "contentSnapshot": { "$ref": "#/components/schemas/ContentEdition" }, "pricing": { "$ref": "#/components/schemas/PricingEstimate" }, "releasePricing": { "$ref": "#/components/schemas/PricingEstimate" }, "completionEvent": { "type": "string", "enum": [ "arrival_confirmed", "response_completed", "insight_release_completed" ] }, "tags": { "$ref": "#/components/schemas/Tags" }, "hostedUrl": { "type": "string", "format": "uri", "readOnly": true, "description": "Saved Mementom offer preview. Requires the owning company marketing session; saving a draft does not publish it." }, "verifiedLandingMinor": { "type": "integer", "minimum": 0, "maximum": 100000, "multipleOf": 2, "description": "Offer-only alias for engagementMinor. Must agree if both are supplied. Verified arrival_confirmed only, never a raw click." }, "cpcMinor": { "type": "integer", "minimum": 0, "maximum": 100000, "multipleOf": 2, "description": "Company total fee for one distinct confirmed event; cumulative with configured landing/purchase fees, split equally between consumer and platform." } }, "required": [ "id", "name", "type", "audienceIds", "audienceSnapshots", "excludedAudienceIds", "excludedAudienceSnapshots", "refinements", "content", "questions", "requestedInsightIds", "requestedInsights", "engagementMinor", "purchaseMinor", "pricing", "releasePricing", "completionEvent" ], "additionalProperties": true }, "SavedQuestion": { "type": "object", "properties": { "schemaVersion": { "const": 1 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 240, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "questionType": { "type": "string", "enum": [ "multipleChoice", "boolean", "slider" ] }, "answerType": { "type": "string", "enum": [ "single", "multiple" ] }, "maxAnswers": { "type": "integer", "minimum": 1, "maximum": 20 }, "step": { "type": "integer", "minimum": 1 }, "insight": { "$ref": "#/components/schemas/QuestionInsight" }, "id": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } }, "insightDefinition": { "$ref": "#/components/schemas/InsightDefinition" }, "provenance": { "const": "self_reported" }, "answerChoices": { "type": "array", "items": { "type": [ "string", "boolean", "number" ] } }, "answerMinValue": { "type": "integer", "minimum": 0 }, "answerMaxValue": { "type": "integer", "minimum": 0 }, "answerTrueLabel": { "type": "string" }, "answerFalseLabel": { "type": "string" } }, "required": [ "id", "prompt", "options" ], "additionalProperties": true, "description": "Typed questions include the registered definition snapshot and finite answer domain. Legacy questions retain id, prompt and options without an insight binding." }, "ContentEdition": { "type": "object", "properties": { "id": { "type": "string" }, "revision": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "offer", "questionnaire", "insight_request" ] }, "content": { "$ref": "#/components/schemas/Creative" }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/SavedQuestion" } }, "requestedInsightIds": { "type": "array", "items": { "type": "string" } }, "requestedInsights": { "type": "array", "items": { "$ref": "#/components/schemas/InsightDefinition" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "duplicatedFromId": { "type": "string" }, "isSample": { "type": "boolean" }, "tags": { "$ref": "#/components/schemas/Tags" }, "engagementMinor": { "type": "integer", "minimum": 0, "maximum": 100000, "multipleOf": 2, "description": "Default combined fee in cents. Omission preserves a saved or duplicated value; new content defaults to 200. Campaign placements may select their own fee." }, "purchaseMinor": { "type": "integer", "minimum": 0, "maximum": 100000, "multipleOf": 2, "description": "Default combined fee in cents. Omission preserves a saved or duplicated value; new content defaults to 0. Campaign placements may select their own fee." }, "hostedUrl": { "type": "string", "format": "uri", "readOnly": true, "description": "Mementom offer preview for the owning company session. Draft saving does not publish it." } }, "required": [ "id", "revision", "name", "type", "content", "questions", "requestedInsightIds" ], "additionalProperties": true, "description": "A saved content snapshot without its editions collection." }, "PricingLine": { "type": "object", "properties": { "definitionId": { "type": "string" }, "label": { "type": "string" }, "source": { "type": "string" }, "priceMinor": { "type": "integer", "minimum": 0 }, "currency": { "const": "USD" }, "licenseDays": { "type": "integer", "minimum": 0 }, "assumption": { "type": "boolean" }, "valuation": { "$ref": "#/components/schemas/PricingEstimate" } }, "required": [ "definitionId", "label", "source", "priceMinor", "currency" ], "additionalProperties": true }, "Tags": { "type": "array", "maxItems": 12, "items": { "type": "string", "minLength": 1, "maxLength": 40 }, "description": "Classification tags. IDs are trimmed, lowercased, whitespace is hyphenated, and explicit taxonomy aliases are canonicalized. Up to 12 distinct tags. Metadata does not grant access or change audience matching. Omitted tags preserve existing tags when editing; an empty array clears them." }, "CreativeDesign": { "type": "object", "additionalProperties": false, "properties": { "layout": { "type": "string", "enum": [ "image-top", "background", "text" ], "description": "Default: image-top." }, "backgroundColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Six-digit hexadecimal color. Default: #ffffff." }, "textColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Six-digit hexadecimal color. Default: #182840." }, "accentColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Six-digit hexadecimal color. Default: #245cdb." }, "buttonTextColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Six-digit hexadecimal color. Default: #ffffff." }, "overlayColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Six-digit hexadecimal color. Default: #000000." }, "overlayOpacity": { "type": "number", "minimum": 0, "maximum": 85, "description": "Overlay opacity as a percentage. Default: 45." }, "imagePosition": { "type": "string", "enum": [ "center", "top", "bottom", "left", "right" ], "description": "Default: center." }, "textAlign": { "type": "string", "enum": [ "left", "center" ], "description": "Default: left." }, "contentPosition": { "type": "string", "enum": [ "top", "center", "bottom" ], "description": "Default: bottom." }, "fontFamily": { "type": "string", "enum": [ "sans", "serif" ], "description": "Default: sans." }, "headlineSize": { "type": "string", "enum": [ "small", "medium", "large" ], "description": "Default: medium." }, "buttonStyle": { "type": "string", "enum": [ "rounded", "pill", "square" ], "description": "Default: rounded." }, "imageFit": { "type": "string", "enum": [ "cover", "contain" ], "description": "Default: cover." } }, "description": "Optional controlled creative styling. Omitted fields use the documented defaults. Unknown settings, arbitrary CSS, null and values outside these enums/ranges are rejected." }, "EventFilter": { "type": "object", "properties": { "property": { "type": "string" }, "operator": { "type": "string", "enum": [ "equals", "gte", "lte" ] }, "value": { "type": [ "string", "number", "boolean" ] } }, "required": [ "property", "operator", "value" ], "additionalProperties": false, "description": "Use a registered event property and its permitted value. Numeric properties support equals/gte/lte; other properties support equals. Catalog values must belong to this application." }, "EventMatch": { "type": "object", "properties": { "filters": { "type": "array", "items": { "$ref": "#/components/schemas/EventFilter" }, "maxItems": 8 }, "lookbackDays": { "type": "integer", "minimum": 1 } }, "required": [ "filters" ], "additionalProperties": false, "description": "All filters must match the same event record. Empty filters match any current event. Omit lookbackDays to use the registered window; an explicit lookback cannot exceed that window. Observation timestamps come from the service." }, "CampaignUpdate": { "type": "object", "properties": { "schemaVersion": { "const": 2 }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "objective": { "type": "string", "enum": [ "return_visitors", "learn_preferences", "collect_insights" ] }, "startAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "budgetMinor": { "type": "integer", "minimum": 1, "maximum": 100000000 }, "dailyCapMinor": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100000000 }, { "type": "null" } ], "description": "Optional daily cap. Omitted/null means no separate daily limit; total budget remains enforced." }, "responseWindowHours": { "type": "integer", "enum": [ 24, 72, 168 ] }, "emailDelivery": { "type": "string", "enum": [ "mementom", "company" ], "description": "Mementom automatic email or explicit company email deferment. Omission preserves the saved draft setting." }, "engagements": { "type": "array", "items": { "$ref": "#/components/schemas/Engagement" }, "minItems": 1, "maxItems": 10 }, "tags": { "$ref": "#/components/schemas/Tags" }, "campaignId": { "type": "string", "minLength": 1 }, "expectedCampaignRevision": { "type": "integer", "minimum": 1 }, "minimumCvbRating": { "$ref": "#/components/schemas/CvbThreshold" }, "currency": { "type": "string", "enum": [ "USD" ] }, "dailyCapConfigured": { "type": "boolean", "description": "Preserves declared optional-cap state from saved campaign." } }, "required": [ "schemaVersion", "name", "objective", "startAt", "endAt", "budgetMinor", "responseWindowHours", "engagements", "campaignId", "expectedCampaignRevision" ], "additionalProperties": false, "description": "Replaces an existing editable draft using current workspace and campaign revisions. Published campaigns must be duplicated to change creative." }, "CampaignUpdateMutation": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0 }, "payload": { "$ref": "#/components/schemas/CampaignUpdate" }, "idempotencyKey": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,120}$", "description": "Optional application/actor/operation-scoped key. Identical retries return original saved receipt; changed payload returns 409. No expiry; capacity 2000 per workspace." } }, "required": [ "expectedRevision", "payload" ], "additionalProperties": false }, "CampaignIdentityMutation": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0 }, "payload": { "type": "object", "properties": { "campaignId": { "type": "string", "minLength": 1 }, "expectedCampaignRevision": { "type": "integer", "minimum": 1 } }, "required": [ "campaignId", "expectedCampaignRevision" ], "additionalProperties": false }, "idempotencyKey": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,120}$", "description": "Optional application/actor/operation-scoped key. Identical retries return original saved receipt; changed payload returns 409. No expiry; capacity 2000 per workspace." } }, "required": [ "expectedRevision", "payload" ], "additionalProperties": false }, "CampaignDuplicateMutation": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0 }, "payload": { "type": "object", "properties": { "campaignId": { "type": "string", "minLength": 1 }, "expectedCampaignRevision": { "type": "integer", "minimum": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "campaignId", "expectedCampaignRevision" ], "additionalProperties": false }, "idempotencyKey": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,120}$", "description": "Optional application/actor/operation-scoped key. Identical retries return original saved receipt; changed payload returns 409. No expiry; capacity 2000 per workspace." } }, "required": [ "expectedRevision", "payload" ], "additionalProperties": false }, "CampaignStateMutation": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0 }, "payload": { "type": "object", "properties": { "campaignId": { "type": "string", "minLength": 1 }, "expectedCampaignRevision": { "type": "integer", "minimum": 1 }, "state": { "type": "string", "enum": [ "paused", "stopped" ] } }, "required": [ "campaignId", "expectedCampaignRevision", "state" ], "additionalProperties": false }, "idempotencyKey": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,120}$", "description": "Optional application/actor/operation-scoped key. Identical retries return original saved receipt; changed payload returns 409. No expiry; capacity 2000 per workspace." } }, "required": [ "expectedRevision", "payload" ], "additionalProperties": false }, "CampaignAudiencesMutation": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0 }, "payload": { "type": "object", "properties": { "campaignId": { "type": "string", "minLength": 1 }, "expectedCampaignRevision": { "type": "integer", "minimum": 1 }, "engagementId": { "type": "string", "minLength": 1 }, "expectedTargetingRevision": { "type": "integer", "minimum": 0 }, "audienceIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 20, "uniqueItems": true }, "excludedAudienceIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 20, "uniqueItems": true } }, "required": [ "campaignId", "expectedCampaignRevision", "engagementId", "expectedTargetingRevision", "audienceIds", "excludedAudienceIds" ], "additionalProperties": false }, "idempotencyKey": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,120}$", "description": "Optional application/actor/operation-scoped key. Identical retries return original saved receipt; changed payload returns 409. No expiry; capacity 2000 per workspace." } }, "required": [ "expectedRevision", "payload" ], "additionalProperties": false }, "CampaignAudienceMutation": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0 }, "payload": { "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "mode": { "type": "string", "enum": [ "all", "any" ] }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/Rule" }, "minItems": 1, "maxItems": 8 }, "tags": { "$ref": "#/components/schemas/Tags" }, "campaignId": { "type": "string", "minLength": 1 }, "expectedCampaignRevision": { "type": "integer", "minimum": 1 }, "engagementId": { "type": "string", "minLength": 1 }, "expectedTargetingRevision": { "type": "integer", "minimum": 0 }, "audienceId": { "type": "string", "minLength": 1 }, "minimumCvbRating": { "$ref": "#/components/schemas/CvbThreshold" } }, "required": [ "name", "mode", "rules", "campaignId", "expectedCampaignRevision", "engagementId", "expectedTargetingRevision", "audienceId" ], "additionalProperties": false, "description": "A definition ID may appear only once in a simple audience." }, { "type": "object", "properties": { "schemaVersion": { "const": 2 }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "logic": { "allOf": [ { "$ref": "#/components/schemas/AudienceGroup" }, { "properties": { "id": { "const": "head" } } } ] }, "criteria": { "type": "array", "items": { "$ref": "#/components/schemas/Criterion" }, "minItems": 1, "maxItems": 64 }, "tags": { "$ref": "#/components/schemas/Tags" }, "campaignId": { "type": "string", "minLength": 1 }, "expectedCampaignRevision": { "type": "integer", "minimum": 1 }, "engagementId": { "type": "string", "minLength": 1 }, "expectedTargetingRevision": { "type": "integer", "minimum": 0 }, "audienceId": { "type": "string", "minLength": 1 }, "minimumCvbRating": { "$ref": "#/components/schemas/CvbThreshold" } }, "required": [ "schemaVersion", "name", "logic", "criteria", "campaignId", "expectedCampaignRevision", "engagementId", "expectedTargetingRevision", "audienceId" ], "additionalProperties": false, "description": "Every criterion ID is unique and used by at least one leaf. Root id is head." } ] }, "idempotencyKey": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,120}$", "description": "Optional application/actor/operation-scoped key. Identical retries return original saved receipt; changed payload returns 409. No expiry; capacity 2000 per workspace." } }, "required": [ "expectedRevision", "payload" ], "additionalProperties": false }, "CvbThreshold": { "type": "number", "minimum": 0, "maximum": 5, "multipleOf": 0.1, "description": "Minimum CVB rating from 0.0 to 5.0 in steps of 0.1. Omit for a new campaign to default to 0; draft MCP edits retain the current threshold when omitted. Supply 0 explicitly to remove the threshold." }, "CampaignComparisonRequest": { "type": "object", "properties": { "campaignIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "uniqueItems": true }, "mode": { "type": "string", "enum": [ "live", "test" ], "default": "live" } }, "required": [], "additionalProperties": false }, "CampaignLandingTotals": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 }, "companyMinor": { "type": "integer", "minimum": 0 }, "consumerMinor": { "type": "integer", "minimum": 0 } }, "required": [ "count", "companyMinor", "consumerMinor" ], "additionalProperties": false }, "CampaignComparisonTotals": { "type": "object", "properties": { "delivered": { "type": "integer", "minimum": 0 }, "viewed": { "type": "integer", "minimum": 0 }, "started": { "type": "integer", "minimum": 0 }, "responded": { "type": "integer", "minimum": 0 }, "completed": { "type": "integer", "minimum": 0 }, "arrivals": { "type": "integer", "minimum": 0 }, "insightsReleased": { "type": "integer", "minimum": 0 }, "purchases": { "type": "integer", "minimum": 0 }, "reversals": { "type": "integer", "minimum": 0 }, "netPurchases": { "type": "integer", "minimum": 0 }, "optedOut": { "type": "integer", "minimum": 0 }, "mature": { "type": "integer", "minimum": 0 }, "matureResponded": { "type": "integer", "minimum": 0 }, "matureStarted": { "type": "integer", "minimum": 0 }, "matureCompleted": { "type": "integer", "minimum": 0 }, "matureArrivals": { "type": "integer", "minimum": 0 }, "matureNetPurchases": { "type": "integer", "minimum": 0 }, "pending": { "type": "integer", "minimum": 0 }, "timedResponders": { "type": "integer", "minimum": 0 }, "viewTimedResponders": { "type": "integer", "minimum": 0 }, "modeledSpendMinor": { "type": "integer", "minimum": 0 }, "modeledConsumerMinor": { "type": "integer", "minimum": 0 }, "responseRate": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "matureResponseRate": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "costPerResponseMinor": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "costPerPurchaseMinor": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "revenueMinor": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "settledMinor": { "type": "null", "description": "No settlement integration." }, "windows": { "type": "array", "items": { "type": "object", "properties": { "hours": { "type": "integer", "minimum": 0 }, "eligible": { "type": "integer", "minimum": 0 }, "responded": { "type": "integer", "minimum": 0 }, "responseRate": { "type": [ "number", "null" ], "minimum": 0 } }, "required": [ "hours", "eligible", "responded", "responseRate" ], "additionalProperties": false } }, "campaigns": { "type": "integer", "minimum": 0 }, "budgetMinor": { "type": "integer", "minimum": 0 }, "dailyCapMinor": { "type": [ "integer", "null" ], "minimum": 0 }, "landingTotals": { "$ref": "#/components/schemas/CampaignLandingTotals" }, "clicks": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "modeledClickMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "modeledCompletionMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "modeledPurchaseMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "modeledInsightMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 } }, "required": [ "delivered", "viewed", "started", "responded", "completed", "arrivals", "insightsReleased", "purchases", "reversals", "netPurchases", "optedOut", "mature", "matureResponded", "matureStarted", "matureCompleted", "matureArrivals", "matureNetPurchases", "pending", "timedResponders", "viewTimedResponders", "modeledSpendMinor", "modeledConsumerMinor", "responseRate", "matureResponseRate", "costPerResponseMinor", "costPerPurchaseMinor", "revenueMinor", "settledMinor", "windows", "campaigns", "budgetMinor", "dailyCapMinor", "landingTotals" ], "description": "Campaign participation totals. Rates divide summed numerators by summed eligible denominators; latency percentiles are not aggregated. Revenue remains unknown unless recorded for all net purchases." }, "CampaignComparisonEntry": { "type": "object", "properties": { "campaignRevision": { "type": "integer", "minimum": 1 }, "windowHours": { "type": "integer", "minimum": 0 }, "budgetMinor": { "type": "integer", "minimum": 0 }, "isSample": { "type": "boolean" }, "overview": { "$ref": "#/components/schemas/ReportMetrics" }, "recommendations": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "evidence": { "type": "string" }, "action": { "type": "string" }, "confidence": { "type": "string" } }, "required": [ "title", "evidence", "action", "confidence" ], "additionalProperties": false } }, "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "stopped", "deleted" ] }, "dailyCapMinor": { "type": [ "integer", "null" ], "minimum": 0 }, "landingTotals": { "$ref": "#/components/schemas/CampaignLandingTotals" } }, "required": [ "campaignRevision", "windowHours", "budgetMinor", "isSample", "overview", "recommendations", "id", "name", "status", "dailyCapMinor", "landingTotals" ], "additionalProperties": false }, "CampaignComparison": { "type": "object", "properties": { "schemaVersion": { "const": 1 }, "applicationId": { "$ref": "#/components/schemas/ApplicationId" }, "mode": { "type": "string", "enum": [ "live", "test" ], "default": "live" }, "generatedAt": { "type": "string", "format": "date-time" }, "countingUnit": { "const": "campaign_participations" }, "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignComparisonEntry" } }, "totals": { "$ref": "#/components/schemas/CampaignComparisonTotals" }, "limitations": { "type": "array", "items": { "type": "string" } }, "activityId": { "$ref": "#/components/schemas/ActivityId" } }, "required": [ "schemaVersion", "applicationId", "mode", "generatedAt", "countingUnit", "campaigns", "totals", "limitations" ], "additionalProperties": false }, "ProductSearch": { "type": "object", "properties": { "q": { "type": "string", "maxLength": 200 }, "sku": { "type": "string", "maxLength": 200 }, "color": { "type": "string", "maxLength": 200 }, "category": { "type": "string", "maxLength": 200 }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "available": { "type": "boolean" }, "offset": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [], "additionalProperties": false }, "ProductLookup": { "type": "object", "properties": { "productId": { "type": "string", "minLength": 1, "maxLength": 120 }, "variantId": { "type": "string", "maxLength": 120 } }, "required": [ "productId" ], "additionalProperties": false }, "CampaignPreflightRequest": { "type": "object", "properties": { "campaignId": { "type": "string", "minLength": 1 }, "expectedRevision": { "type": "integer", "minimum": 0 }, "expectedCampaignRevision": { "type": "integer", "minimum": 1 } }, "required": [ "campaignId" ], "additionalProperties": false }, "ProductOfferMutation": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0 }, "idempotencyKey": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,120}$", "description": "Optional application/actor/operation-scoped key. Identical retries return original saved receipt; changed payload returns 409. No expiry; capacity 2000 per workspace." }, "payload": { "type": "object", "properties": { "productId": { "type": "string", "minLength": 1, "maxLength": 120 }, "expectedProductRevision": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "discount": { "oneOf": [ { "type": "object", "properties": { "percent": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "percent" ], "additionalProperties": false }, { "type": "null" } ], "description": "Offer discount requires a productId. Omit or supply null for no discount." }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "content": { "type": "object", "properties": { "headline": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "body": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "cta": { "type": "string", "minLength": 1, "maxLength": 60, "description": "Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable." }, "image": { "type": "string", "description": "Optional PNG/JPEG/WebP base64 data URL. Creative writes use a 4 MiB JSON request envelope; uploaded files may be prepared automatically before saving." }, "brandName": { "type": "string", "maxLength": 80, "description": "Brand shown on the creative. Empty leaves the brand line blank. Plain text only." }, "offerLabel": { "type": "string", "maxLength": 120, "description": "Authored offer label or badge. No reward or completion wording is inserted automatically. Plain text only." }, "terms": { "type": "string", "maxLength": 1000, "description": "Offer terms shown as authored. Plain text only." }, "promoCode": { "type": "string", "maxLength": 80, "description": "Optional promotional code. Plain text only." }, "imageAlt": { "type": "string", "maxLength": 180, "description": "Description of the creative image for assistive technology. Plain text only." }, "design": { "$ref": "#/components/schemas/CreativeDesign" }, "landingDetails": { "type": "string", "maxLength": 5000 } }, "required": [], "additionalProperties": false }, "engagementMinor": { "type": "integer", "minimum": 0, "maximum": 100000, "multipleOf": 2 }, "verifiedLandingMinor": { "type": "integer", "minimum": 0, "maximum": 100000, "multipleOf": 2 }, "purchaseMinor": { "type": "integer", "minimum": 0, "maximum": 100000, "multipleOf": 2 }, "cpcMinor": { "type": "integer", "minimum": 0, "maximum": 100000, "multipleOf": 2, "description": "Company total fee for one distinct confirmed event; cumulative with configured landing/purchase fees, split equally between consumer and platform." } }, "required": [ "productId", "expectedProductRevision" ], "additionalProperties": false } }, "required": [ "expectedRevision", "payload" ], "additionalProperties": false }, "Product": { "type": "object", "properties": { "id": { "type": "string" }, "canonicalProductId": { "type": "string" }, "applicationId": { "$ref": "#/components/schemas/ApplicationId" }, "name": { "type": "string" }, "description": { "type": "string" }, "identity": { "type": "object", "additionalProperties": true }, "variants": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "priceMinor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "imageUrl": { "type": [ "string", "null" ] }, "images": { "type": "array", "items": { "type": "string" } }, "sku": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "size": { "type": [ "string", "null" ] }, "available": { "type": "boolean" }, "status": { "type": "string" }, "stock": { "type": [ "integer", "null" ] }, "stockTracked": { "type": "boolean" }, "supportedOfferTypes": { "type": "array", "items": { "type": "string" } }, "eligibility": { "type": "object", "additionalProperties": true }, "redemption": { "type": "object", "additionalProperties": true }, "revision": { "type": "string" }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "canonicalProductId", "applicationId", "name", "revision", "eligibility" ], "additionalProperties": true }, "PreflightIssue": { "type": "object", "properties": { "code": { "type": "string" }, "fieldPath": { "type": "string" }, "engagementId": { "type": [ "string", "null" ] }, "productId": { "type": "string" }, "agreementId": { "type": "string" }, "message": { "type": "string" }, "correctiveAction": { "type": "string" } }, "required": [ "code", "fieldPath", "message", "correctiveAction" ], "additionalProperties": true }, "CampaignPreflight": { "type": "object", "additionalProperties": true, "properties": { "valid": { "type": "boolean" }, "blockers": { "type": "array", "items": { "$ref": "#/components/schemas/PreflightIssue" } }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/PreflightIssue" } }, "applicationId": { "$ref": "#/components/schemas/ApplicationId" }, "activityId": { "$ref": "#/components/schemas/ActivityId" }, "revision": { "type": "integer" }, "campaignId": { "type": [ "string", "null" ] }, "campaignRevision": { "type": [ "integer", "null" ] }, "products": { "type": "array", "items": { "type": "object" } }, "financialTerms": { "$ref": "#/components/schemas/CampaignFinancialTerms" }, "paymentAgreement": { "$ref": "#/components/schemas/CampaignPaymentAgreement" }, "deliveryEligibility": { "type": "object" }, "validatedAt": { "type": "string", "format": "date-time" } }, "required": [ "applicationId", "revision", "campaignId", "valid", "blockers", "warnings", "products", "deliveryEligibility", "validatedAt" ] }, "FinancialTerms": { "type": "object", "properties": { "applicationId": { "$ref": "#/components/schemas/ApplicationId" }, "activityId": { "$ref": "#/components/schemas/ActivityId" }, "financialTerms": { "$ref": "#/components/schemas/CampaignFinancialTerms" } }, "required": [ "applicationId", "financialTerms" ], "additionalProperties": true }, "PaymentAgreement": { "type": "object", "properties": { "applicationId": { "$ref": "#/components/schemas/ApplicationId" }, "activityId": { "$ref": "#/components/schemas/ActivityId" }, "paymentAgreement": { "$ref": "#/components/schemas/CampaignPaymentAgreement" } }, "required": [ "applicationId", "paymentAgreement" ], "additionalProperties": true }, "ProductList": { "type": "object", "properties": { "applicationId": { "$ref": "#/components/schemas/ApplicationId" }, "activityId": { "$ref": "#/components/schemas/ActivityId" }, "revision": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "total": { "type": "integer" }, "offset": { "type": "integer" }, "limit": { "type": "integer" }, "hasMore": { "type": "boolean" }, "nextOffset": { "type": [ "integer", "null" ] }, "searchableAttributes": { "type": "array", "items": { "type": "string" } } }, "required": [ "applicationId", "revision", "items", "total", "hasMore", "nextOffset" ], "additionalProperties": true }, "ProductResult": { "type": "object", "properties": { "applicationId": { "$ref": "#/components/schemas/ApplicationId" }, "activityId": { "$ref": "#/components/schemas/ActivityId" }, "revision": { "type": "integer" }, "product": { "$ref": "#/components/schemas/Product" }, "resolution": { "type": "object", "properties": { "requestedId": { "type": "string" }, "canonicalProductId": { "type": [ "string", "null" ] }, "kind": { "enum": [ "canonical", "legacy_alias", "unresolved" ] }, "variantId": { "type": [ "string", "null" ] } }, "required": [], "additionalProperties": true }, "reasons": { "type": "array", "items": { "$ref": "#/components/schemas/PreflightIssue" } } }, "required": [ "applicationId", "revision", "product", "resolution", "reasons" ], "additionalProperties": true }, "CampaignFinancialTerms": { "type": "object", "properties": { "schemaVersion": { "const": 1 }, "amountMeaning": { "const": "company_total_cost" }, "currency": { "const": "USD" }, "amountUnit": { "const": "minor" }, "budgetMinor": { "type": [ "integer", "null" ] }, "dailyCapMinor": { "type": [ "integer", "null" ] }, "dailyCapConfigured": { "type": "boolean" }, "effectiveDailyCapMinor": { "type": [ "integer", "null" ] }, "supportedTriggers": { "type": "object" }, "budgetEnforcement": { "type": "object" }, "attribution": { "type": "object" }, "engagements": { "type": "array", "items": { "type": "object", "properties": { "engagementId": { "type": "string" }, "cpcMinor": { "type": "integer", "minimum": 0, "maximum": 100000, "multipleOf": 2, "description": "Company total fee for one distinct confirmed event; cumulative with configured landing/purchase fees, split equally between consumer and platform." }, "verifiedLandingMinor": { "type": "integer" }, "completion": { "type": "object" }, "purchase": { "type": "object" }, "insights": { "type": "object" }, "maximumPerDeliveryMinor": { "type": "integer" } }, "required": [], "additionalProperties": true } }, "settlement": { "type": "object" }, "paymentAgreement": { "$ref": "#/components/schemas/CampaignPaymentAgreement" } }, "required": [ "schemaVersion", "amountMeaning", "currency", "budgetMinor", "dailyCapMinor", "engagements", "settlement", "paymentAgreement" ], "additionalProperties": true }, "CampaignPaymentAgreement": { "type": "object", "properties": { "status": { "type": "string" }, "agreement": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] }, "informationAvailable": { "type": "boolean" }, "campaignCovered": { "type": [ "boolean", "null" ] }, "additionalAcceptanceRequired": { "type": [ "boolean", "null" ] } }, "required": [ "status", "agreement", "informationAvailable", "campaignCovered", "additionalAcceptanceRequired" ], "additionalProperties": true }, "PaymentAgreementTerms": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 20000 }, "currency": { "const": "USD" }, "effectiveFrom": { "type": "string", "format": "date-time" }, "effectiveUntil": { "type": "string", "format": "date-time" }, "maxCampaignBudgetMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "maxDailyCapMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "maxCpcMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "maxVerifiedLandingMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "maxPurchaseMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "maxInsightMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "campaignIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "minItems": 1, "maxItems": 100 } }, "additionalProperties": false, "required": [ "text", "currency", "effectiveFrom", "effectiveUntil", "maxCampaignBudgetMinor", "maxDailyCapMinor", "maxCpcMinor", "maxVerifiedLandingMinor", "maxPurchaseMinor", "maxInsightMinor" ] }, "PaymentAgreementCreateMutation": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0 }, "idempotencyKey": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,120}$" }, "payload": { "type": "object", "properties": { "version": { "type": "string", "minLength": 1, "maxLength": 80 }, "terms": { "$ref": "#/components/schemas/PaymentAgreementTerms" } }, "required": [ "version", "terms" ], "additionalProperties": false } }, "required": [ "expectedRevision", "idempotencyKey", "payload" ], "additionalProperties": false }, "PaymentAgreementAcceptMutation": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0 }, "idempotencyKey": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,120}$" }, "payload": { "type": "object", "properties": { "agreementId": { "type": "string", "maxLength": 120 }, "expectedAgreementRevision": { "type": "integer", "minimum": 1 }, "termsDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "accept": { "const": true } }, "required": [ "agreementId", "expectedAgreementRevision", "termsDigest", "accept" ], "additionalProperties": false } }, "required": [ "expectedRevision", "idempotencyKey", "payload" ], "additionalProperties": false }, "PurchaseReceipt": { "type": "object", "properties": { "eventId": { "type": "string", "minLength": 1, "maxLength": 200 }, "deliveryId": { "type": "string", "minLength": 1, "maxLength": 200 }, "engagementId": { "type": "string", "minLength": 1, "maxLength": 200 }, "transactionId": { "type": "string", "minLength": 1, "maxLength": 200 }, "productId": { "type": "string", "minLength": 1, "maxLength": 200 }, "type": { "enum": [ "purchase_confirmed", "purchase_reversed" ] }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "currency": { "const": "USD" }, "occurredAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "required": [ "eventId", "deliveryId", "engagementId", "transactionId", "productId", "type", "amountMinor", "currency", "occurredAt" ] } } }, "externalDocs": { "description": "Company integration guide, configurable Aster example, automation and planned MCP mappings", "url": "https://mementom.app/developers/guides/marketing-api.md" } }