Mementom API v1

Marketing API

Connect your company’s marketing tools to Mementom. Build audiences, manage content, create campaign drafts and read results through the same workspace your marketers use.

Start with your workspace

Version: v1
Base URL: https://mementom.app/api/v1/marketing
Format: application/json
Access: Scoped server credential

Your application, one marketing workspace

The API and marketing console use the same records, validation and permissions. An audience or draft saved by your integration is the one your team sees in the console.

An insight is a registered, non-identifying field. An audience selects permitted insight values. Content holds an offer, questions or an insight request. A campaign draft combines audiences, content and planned terms.

The API works with your company’s application and catalog. The separate Aster demonstration is a teaching example you can replace with your own configuration.

From your server to the marketing console

Use returned IDs and revisions through the whole workflow.

Read the workspace
Get your application’s current catalog and revision.
Build an audience
Save filters using registered values, then count eligible matches.
Save content
Create an offer, questionnaire or insight request.
Create a draft
Combine the saved records with planned fees and budgets.
Verify the result
Read back IDs, inspect message traces and open the same console workspace.

Authentication and scopes

Send a scoped marketing credential from your backend over HTTPS. Each credential belongs to one company, one application and an active staff account. It is separate from the Developer API’s company credential.

Create, rotate and revoke credentials in Marketing API credentials. Keep secrets in your server secret store. Do not expose them in browser JavaScript, logs, URLs or AI prompts. Requests with browser Origin or Sec-Fetch-Site headers are rejected.

The default lifetime is 30 days; choose 1–90 days. Current membership, role, company/application status, expiry and revocation are checked on every request. A company switch or additional agency account requires its own authorized application credential.

Request headers

Header	Value
`Authorization`	`Bearer {marketingCredential}`
`Content-Type`	`application/json` for JSON requests

Scopes

Scope	Allows
`marketing:read`	List applications, read workspace, count an audience, read reports and activity.
`marketing:audiences:write`	Create or replace audiences.
`marketing:content:write`	Create, edit or duplicate content.
`marketing:campaigns:write`	Create campaign drafts.
`marketing:pricing:write`	Set planning assumptions.
`marketing:insights:propose`	Propose custom insight definitions for review.
`marketing:objective:write`	Set the workspace objective.

marketing:read is mandatory. Add only the write scopes your integration needs. Console credential management requires an owner, admin or marketing session; a Bearer credential cannot create another credential.

Server SDK

import { MementomMarketingClient }
  from './mementom-sdk.mjs';

const client = new MementomMarketingClient({
  baseUrl: 'https://mementom.app',
  credential: process.env.MEMENTOM_MARKETING_TOKEN,
  timeoutMs: 10000,
  onTrace: trace => console.log(trace)
});

// onTrace contains only safe request metadata.
const { applications } = await client.getApplications();

Revisions and safe retries

Read the workspace before saving. Every mutation requires its latest expectedRevision and a payload. A successful write returns the complete workspace and advances its revision. Use that response for the next call.

Concurrent writes with the same revision cannot both succeed. A stale write returns 409. Content edits additionally check expectedContentRevision. Unknown fields are rejected.

After a conflict, timeout or lost response, read back the workspace and reconcile saved IDs before writing again. There is no idempotency-key contract or automatic SDK retry. Blindly refreshing the revision and repeating a create can create another draft.

Multi-step workflows are not one transaction. Keep earlier successful records when a later operation fails. Response examples below show selected fields; every accepted mutation returns the full Workspace response.

Mutation envelope

{
  "expectedRevision": 12,
  "payload": {
    "objective": "return_visitors"
  }
}

409 response

{
  "error": "insight_workspace_invalid",
  "message": "This workspace changed. Refresh before saving again.",
  "activityId": "mact_request_reference"
}

Errors and limits

Errors return a machine-readable error, an optional message and, when available, activityId. The SDK exposes these as code, message, status and activityId.

HTTP	Meaning and recovery
400	Invalid JSON, fields, enum values, catalog bindings or planning assumptions. Correct the input.
401	Credential/session is absent, expired, revoked or no longer authorized.
403	Scope, role, browser-origin restriction or console-only operation. Use the correct access path.
404	Resource is unavailable in this company/application. Foreign IDs are not disclosed.
409	Workspace/content revision or immutable definition conflict. Refresh and reconcile.
413	Request exceeds its body limit, or report exceeds its supported event count.
429	Rate limit or sign-in cooldown. Honor Retry-After when supplied.
500 / 503	Service/dependency failure. Save the correlation ID and reconcile uncertain writes.

Count and credential-issue JSON bodies are limited to 32 KiB. Authenticated content and campaign writes allow 4 MiB of total JSON, including every base64 image. Other workspace writes retain the 192 KiB limit. The marketing console prepares uploaded images automatically; direct API clients must keep the encoded request within its limit. Reports support up to 10,000 stored events per campaign/mode.

Each application supports 100 non-starter-pack audiences, content records, campaign drafts and definitions. Activity pages accept offsets 0–10,000 and limits 1–100. See the guide for field-specific limits.

403 response

{
  "error": "marketing_scope_required",
  "message": "This credential does not permit that operation.",
  "activityId": "mact_request_reference"
}

Safe SDK error handling

try {
  workspace = await client.getWorkspace(applicationId);
} catch (error) {
  console.error({
    status: error.status,
    code: error.code,
    activityId: error.activityId
  });
  // Reconcile uncertain writes before any retry.
}

SDK and integration downloads

Use Node.js 22 or later. Save the server module outside your public web directory and pin the reviewed version in your company repository. No Mementom database or private package access is needed.

Use your registered application, insight definitions and landing URLs. Aster is optional. The Developer API covers registration, protected actions and permitted company insight ingestion.

Read, then save

const workspace = await client.getWorkspace(applicationId);

const updated = await client.setObjective(
  applicationId,
  workspace.revision,
  { objective: 'return_visitors' }
);

// Continue with updated.revision.
console.log(updated.activityId);

GET/applications

List applications

Read the active application available to this credential.

Required scope: marketing:read

Request fields

Field	Meaning
`No request body`	The credential selects one company/application. Console sessions can list their authorized company applications.

Use the returned applicationId for every workspace call. A foreign application ID returns 404; possession of an ID grants no access.

Node.js SDK

const result = await client.getApplications();

200 response · selected fields

{
  "applications": [
    {
      "applicationId": "app_your_company",
      "displayName": "Your company"
    }
  ],
  "activityId": "mact_request_reference"
}

GET/applications/{applicationId}/workspace

Read the workspace

Read the current catalog, saved marketing records and revision.

Required scope: marketing:read

Request fields

Field	Meaning
`applicationId`	Required path ID from List applications.
`No request body`	Returns catalog definitions, saved records, revision, planning assumptions and capabilities.

Marketing responses omit developer-only templates, datasets and ingestion receipts. Keep sample provenance and unavailable capabilities visible.

Node.js SDK

const workspace = await client.getWorkspace(applicationId);

200 response · selected fields

{
  "applicationId": "app_your_company",
  "revision": 12,
  "definitions": [
    {
      "id": "shopping_interest_definition_id",
      "key": "shopping.interest",
      "version": 1,
      "status": "standard",
      "type": "enum",
      "values": [
        "browsed",
        "compared",
        "added_to_cart",
        "purchased"
      ]
    }
  ],
  "audiences": [],
  "contentLibrary": [],
  "campaigns": [],
  "capabilities": {
    "outreach": false,
    "billing": false,
    "holderPermissionRequired": true
  },
  "activityId": "mact_request_reference"
}

POST/applications/{applicationId}/workspace/audiences

Save an audience

Build a saved audience from registered, permitted insight values.

Required scope: marketing:audiences:write

Request fields

Field	Meaning
`expectedRevision`	Current workspace revision.
`payload.name`	Plain text, 1–100 characters; describes the audience.
`payload.mode / rules`	Simple format: all or any; 1–8 rules, one per definition.
`payload.schemaVersion / logic / criteria`	Grouped format: schemaVersion 2; root head; 1–64 criteria, maximum 256 nodes and depth 16.
`payload.audienceId`	Optional same-app ID to replace an audience; omit to create.

Editing an audience preserves its ID. Referencing campaigns keep their snapshots and are marked audienceChanged. Sample-derived audiences retain isSample.

See rules, grouped logic and criterion bindings.

JSON request

{
  "expectedRevision": 12,
  "payload": {
    "name": "Visitors comparing products",
    "mode": "all",
    "rules": [
      {
        "definitionId": "shopping_interest_definition_id",
        "version": 1,
        "operator": "equals",
        "value": "compared"
      }
    ]
  }
}

200 response · selected fields

{
  "applicationId": "app_your_company",
  "revision": 13,
  "audiences": [
    {
      "name": "Visitors comparing products",
      "mode": "all",
      "rules": [
        {
          "definitionId": "shopping_interest_definition_id",
          "version": 1,
          "operator": "equals",
          "value": "compared"
        }
      ],
      "id": "saved_audience_id",
      "status": "draft"
    }
  ],
  "activityId": "mact_request_reference"
}

Full response: the complete workspace, including new revision and activityId.

POST/applications/{applicationId}/workspace/count

Count an audience

Count holders matching a proposed audience using current permissions and unexpired insights.

Required scope: marketing:read

Request fields

Field	Meaning
`expectedRevision`	Current workspace revision, checked even though counting does not save.
`audience`	A simple or structured audience definition. This is not a payload mutation envelope.

A sample-based audience returns available:false, count:null and a reason. That is unavailable live reach, not zero. No holder IDs or individual insight values are returned.

JSON request

{
  "expectedRevision": 13,
  "audience": {
    "name": "Visitors comparing products",
    "mode": "all",
    "rules": [
      {
        "definitionId": "shopping_interest_definition_id",
        "version": 1,
        "operator": "equals",
        "value": "compared"
      }
    ]
  }
}

200 response · selected fields

{
  "available": true,
  "count": 0,
  "eligible": 0,
  "breakdown": [],
  "asOf": "2026-10-02T12:00:00.000Z",
  "basis": "Current, permitted company and external insights",
  "sample": false,
  "activityId": "mact_request_reference"
}

POST/applications/{applicationId}/workspace/content

Save content

Create an offer, questionnaire or insight request, or revise a saved content record.

Required scope: marketing:content:write

Request fields

Field	Meaning
`expectedRevision`	Current workspace revision.
`payload`	Complete author-controlled content fields; see Content save model.
`payload.contentId / expectedContentRevision`	For editing: existing content ID and its current content revision.
`payload.duplicateFromId`	For duplicating: existing same-app content ID. Do not combine with contentId or expectedContentRevision.

Questionnaires require 1–10 questions; other types use an empty questions array. Insight requests need at least one requested insight. Up to 20 distinct requested insight IDs are allowed. Saving does not grant consent.

Leave content.landingUrl empty for the Mementom offer page, or provide your company’s HTTPS destination. Saved offers return a separate hostedUrl for the current edition. Opening that preview requires a marketing session for the owning company; saving a draft does not publish it.

See content save, creative and typed questions.

JSON request

{
  "expectedRevision": 13,
  "payload": {
    "name": "Product comparison invitation",
    "type": "offer",
    "content": {
      "headline": "Still considering your options?",
      "body": "Take another look at the choices that interested you.",
      "cta": "Explore options",
      "landingUrl": "",
      "image": ""
    },
    "questions": [],
    "requestedInsightIds": [],
    "engagementMinor": 200,
    "purchaseMinor": 0
  }
}

200 response · selected fields

{
  "applicationId": "app_your_company",
  "revision": 14,
  "contentLibrary": [
    {
      "id": "saved_content_id",
      "revision": 1,
      "name": "Product comparison invitation",
      "type": "offer",
      "content": {
        "headline": "Still considering your options?",
        "body": "Take another look at the choices that interested you.",
        "cta": "Explore options",
        "landingUrl": "",
        "image": ""
      },
      "questions": [],
      "requestedInsightIds": [],
      "engagementMinor": 200,
      "purchaseMinor": 0,
      "hostedUrl": "https://mementom.app/marketing/offers/app_your_company/content/saved_content_id/1"
    }
  ],
  "activityId": "mact_request_reference"
}

Full response: the complete workspace, including new revision and activityId.

POST/applications/{applicationId}/workspace/campaigns

Create a campaign draft

Create a campaign draft from your saved audiences and content.

Required scope: marketing:campaigns:write

Request fields

Field	Meaning
`expectedRevision`	Current workspace revision.
`payload.schemaVersion`	2 for the full engagement format.
`payload`	See Campaign draft and Engagement models for all fields.
`payload.engagements`	1–10 offer, questionnaire or insight-request engagements. References must belong to this application.

Both dates are null or both timezone-bearing with end after start. Daily cap cannot exceed total budget; both must cover a full engagement plus purchase. Fees are even USD cents and positive in combination; purchase fees apply only to offers. Saved status is always draft. There is no publish or delivery call.

See campaign fields and engagement fields. A referenced content edition must match its supplied creative (including authored offer details and design), questions, tags and requested insights. The campaign placement may use different engagement and purchase fees from the saved content defaults.

JSON request

{
  "expectedRevision": 14,
  "payload": {
    "schemaVersion": 2,
    "name": "Product comparison follow-up",
    "objective": "return_visitors",
    "startAt": null,
    "endAt": null,
    "budgetMinor": 10000,
    "dailyCapMinor": 1000,
    "responseWindowHours": 72,
    "engagements": [
      {
        "name": "Product comparison invitation",
        "type": "offer",
        "content": {
          "headline": "Still considering your options?",
          "body": "Take another look at the choices that interested you.",
          "cta": "Explore options",
          "landingUrl": "https://your-company.example/offers",
          "image": ""
        },
        "questions": [],
        "requestedInsightIds": [],
        "audienceIds": [
          "saved_audience_id"
        ],
        "excludedAudienceIds": [],
        "refinements": [],
        "contentId": "saved_content_id",
        "contentRevision": 1,
        "engagementMinor": 100,
        "purchaseMinor": 0
      }
    ]
  }
}

200 response · selected fields

{
  "applicationId": "app_your_company",
  "revision": 15,
  "campaigns": [
    {
      "id": "saved_campaign_id",
      "schemaVersion": 2,
      "revision": 1,
      "name": "Product comparison follow-up",
      "status": "draft",
      "budgetMinor": 10000,
      "dailyCapMinor": 1000,
      "responseWindowHours": 72,
      "routing": "first_matching_engagement",
      "frequency": "once_per_campaign"
    }
  ],
  "activityId": "mact_request_reference"
}

Full response: the complete workspace, including new revision and activityId.

GET/applications/{applicationId}/workspace/report

Read a campaign report

Read aggregate campaign and engagement measurements in one explicit mode.

Required scope: marketing:read

Request fields

Field	Meaning
`campaignId`	Required query parameter; saved campaign ID in this app.
`mode`	Optional query: live (default) or test. Test is synthetic.

A draft has no live delivery. Costs are modeled from draft terms; settledMinor is null. Rates/times are null when unavailable. Live question distributions are withheld below five answers. Sample starter campaigns may generate a synthetic preview in test mode.

Node.js SDK

const report = await client.getReport(
  applicationId, campaignId, 'live'
);

200 response · selected fields

{
  "schemaVersion": 1,
  "campaignId": "saved_campaign_id",
  "campaignRevision": 1,
  "mode": "live",
  "isSample": false,
  "overview": {
    "delivered": 0,
    "responded": 0,
    "responseRate": null,
    "modeledSpendMinor": 0,
    "settledMinor": null,
    "revenueMinor": null
  },
  "limitations": [
    "Saving a draft does not launch it."
  ],
  "activityId": "mact_request_reference"
}

GET/applications/{applicationId}/workspace/activity

Read API activity

Trace server and console requests for one authorized application.

Required scope: marketing:read

Request fields

Field	Meaning
`activityId`	Optional returned mact_ correlation ID, maximum 100 characters.
`offset`	Integer 0–10,000; default 0.
`limit`	Integer 1–100; default 20.
`Query validation`	Only these three query fields, each supplied once.

Safe events include result, timestamp, operation, method, status, revision/error when relevant, source and correlation ID. No credentials, raw content or holder identities are logged here. Activity reads do not recursively create trace events.

Node.js SDK

const activity = await client.getActivity(applicationId, {
  activityId: 'mact_request_reference',
  offset: 0, limit: 20
});

200 response · selected fields

{
  "events": [
    {
      "eventId": "mevt_event_reference",
      "eventType": "marketing.api.request",
      "result": "success",
      "createdAt": "2026-10-02T12:00:00.000Z",
      "activityId": "mact_request_reference",
      "operation": "audiences",
      "method": "POST",
      "status": 200,
      "revision": 13,
      "source": "server"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 20,
  "activityId": "mact_activity_read"
}

POST/applications/{applicationId}/workspace/pricing

Set pricing assumptions

Set pricing assumptions used to compare campaign plans.

Required scope: marketing:pricing:write

Request fields

Field	Meaning
`expectedRevision`	Current workspace revision.
`payload.policy`	Save a pricing policy. Do not combine with definitionId/profile.
`payload.definitionId / profile`	Alternatively, save planning assumptions for one outside-catalog definition.

Omitted policy/profile fields reset to defaults, rather than preserving prior customized values. Audience estimates are recalculated; existing campaign drafts are marked pricingChanged. These are assumptions, not quotes or settlement.

See policy defaults and insight profiles.

JSON request

{
  "expectedRevision": 15,
  "payload": {
    "policy": {
      "schemaVersion": 1,
      "brandTier": "pro",
      "marketTier": "retail",
      "baseCPA": 5
    }
  }
}

200 response · selected fields

{
  "applicationId": "app_your_company",
  "revision": 16,
  "pricingPolicy": {
    "schemaVersion": 1,
    "brandTier": "pro",
    "marketTier": "retail",
    "sourceWeight": 0.15,
    "dataPointWeight": 0.1,
    "uniquenessWeight": 0.5,
    "confidenceWeight": 1,
    "baseCPA": 5,
    "splitAddOnCostsWithCPA": false
  },
  "activityId": "mact_request_reference"
}

Full response: the complete workspace, including new revision and activityId.

POST/applications/{applicationId}/workspace/proposals

Propose an insight

Request a new non-identifying field for developer review.

Required scope: marketing:insights:propose

Request fields

Field	Meaning
`expectedRevision`	Current workspace revision.
`payload.key`	Unique dotted key, maximum 64 characters. Standard template keys cannot be proposed.
`payload.label / description`	Non-identifying plain text, maximum 80 / 240 characters.
`payload.type`	enum, boolean or integer.
`payload.values`	Enum only: 2–20 distinct categories, each maximum 48 characters.
`payload.minimum / maximum`	Integer only: whole numbers from 0–99, maximum at least minimum.
`payload.windowDays / ttlDays`	Both required, integers 1–30.

The definition is saved pending_review and cannot be used until reviewed. Marketing cannot approve it or register standard templates. Identifying metadata, URLs and tracking identifiers are rejected.

JSON request

{
  "expectedRevision": 16,
  "payload": {
    "key": "service.followup_interest",
    "label": "Follow-up interest",
    "description": "Whether someone is interested in another service visit.",
    "type": "boolean",
    "windowDays": 30,
    "ttlDays": 30
  }
}

200 response · selected fields

{
  "applicationId": "app_your_company",
  "revision": 17,
  "definitions": [
    {
      "id": "new_definition_id",
      "key": "service.followup_interest",
      "version": 1,
      "status": "pending_review",
      "type": "boolean",
      "windowDays": 30,
      "ttlDays": 30
    }
  ],
  "activityId": "mact_request_reference"
}

Full response: the complete workspace, including new revision and activityId.

POST/applications/{applicationId}/workspace/objective

Set the workspace objective

Choose the goal used for workspace suggestions.

Required scope: marketing:objective:write

Request fields

Field	Meaning
`expectedRevision`	Current workspace revision.
`payload.objective`	return_visitors or learn_preferences. This is separate from a campaign’s objective.

This changes workspace suggestions without changing an individual campaign’s saved objective.

JSON request

{
  "expectedRevision": 17,
  "payload": {
    "objective": "learn_preferences"
  }
}

200 response · selected fields

{
  "applicationId": "app_your_company",
  "revision": 18,
  "objective": "learn_preferences",
  "activityId": "mact_request_reference"
}

Full response: the complete workspace, including new revision and activityId.

GET/api-tokens

List credentials

List visible API credential metadata without revealing secrets.

Authentication: marketing console session only. Manage credentials.

Request fields

Field	Meaning
`Console session`	Required owner/admin/marketing session. Bearer credentials cannot use this route.
`No request body`	Owners/admins see company tokens; marketers see their own. Secrets are omitted.

Creation, expiry and revocation timestamps use Unix milliseconds. Credential metadata describes staff access, never consumer identity.

Console-session request

GET /api/v1/marketing/api-tokens
Cookie: mementom_marketing_session=<console-session>

200 response · selected fields

{
  "credentials": [
    {
      "id": "mkt_0123456789abcdef0123456789abcdef",
      "label": "Marketing automation",
      "applicationId": "app_your_company",
      "developerAccountId": "dev_issuing_staff_account",
      "scopes": [
        "marketing:read"
      ],
      "createdAt": 1790938800000,
      "expiresAt": 1793530800000,
      "revokedAt": null,
      "status": "active"
    }
  ],
  "availableScopes": [
    "marketing:read",
    "marketing:audiences:write",
    "marketing:content:write",
    "marketing:campaigns:write",
    "marketing:pricing:write",
    "marketing:insights:propose",
    "marketing:objective:write"
  ]
}

POST/api-tokens

Issue a credential

Issue one scoped, expiring server credential from the marketing console.

Authentication: marketing console session only. Manage credentials.

Request fields

Field	Meaning
`applicationId`	Active application owned by the current company.
`label`	Plain text, 1–80 characters.
`scopes`	Distinct documented scopes; marketing:read is required.
`expiresInDays`	Integer 1–90, default 30.
`Console session`	Required; same-origin write protection applies.

The 201 response returns the generated secret once with no-store. Store it directly in your server secret manager. The example below is redacted and cannot authenticate.

JSON request

{
  "applicationId": "app_your_company",
  "label": "Marketing automation",
  "scopes": [
    "marketing:read",
    "marketing:audiences:write",
    "marketing:content:write",
    "marketing:campaigns:write"
  ],
  "expiresInDays": 30
}

201 response · selected fields

{
  "id": "mkt_0123456789abcdef0123456789abcdef",
  "label": "Marketing automation",
  "applicationId": "app_your_company",
  "developerAccountId": "dev_issuing_staff_account",
  "scopes": [
    "marketing:read",
    "marketing:audiences:write",
    "marketing:content:write",
    "marketing:campaigns:write"
  ],
  "createdAt": 1790938800000,
  "expiresAt": 1793530800000,
  "revokedAt": null,
  "status": "active",
  "credential": "mkt_<generated-id>.<one-time-secret>"
}

DELETE/api-tokens/{tokenId}

Revoke a credential

End a credential’s access without deleting its audit history.

Authentication: marketing console session only. Manage credentials.

Request fields

Field	Meaning
`tokenId`	Required path ID returned by credential issue/list.
`Console session`	Owners/admins can revoke company credentials; marketers can revoke their own.
`No request body`	Revoking an already-revoked visible credential is safe.

Subsequent calls with the revoked credential fail. Rotation: issue a replacement, update the server secret, verify a read, then revoke the old one.

Console-session request

DELETE /api/v1/marketing/api-tokens/{tokenId}
Cookie: mementom_marketing_session=<console-session>

200 response · selected fields

{
  "id": "mkt_0123456789abcdef0123456789abcdef",
  "label": "Marketing automation",
  "applicationId": "app_your_company",
  "developerAccountId": "dev_issuing_staff_account",
  "scopes": [
    "marketing:read"
  ],
  "createdAt": 1790938800000,
  "expiresAt": 1793530800000,
  "revokedAt": 1790942400000,
  "status": "revoked"
}

Data model

Audience rule

Use an ID/version from this workspace. equals supports enum/boolean/numeric; gte/lte numeric; contains enumset. Values must match the definition domain.

Field	Type	Meaning
`definitionId`	string Required	1 minimum characters.
`version`	integer Required	1 minimum.
`operator`	`equals` / `contains` / `gte` / `lte` Required	See the example and validation rules.
`value`	string / number / boolean Required	See the example and validation rules.

Data model

Grouped audience logic

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.

Field	Type	Meaning
`id`	string Required	See the example and validation rules.
`logic`	`AND` / `OR` Optional	See the example and validation rules.
`peerLogic`	`AND` / `OR` Optional	See the example and validation rules.
`children`	array of AudienceLeaf or AudienceGroup Required	1 minimum items.

A leaf instead has id, insight (criterion ID) and optional logic. Root ID is head. Every criterion must be referenced. Joins evaluate left to right; this is not SQL operator precedence.

Data model

Criterion binding

Fields used by the corresponding operation.

Field	Type	Meaning
`id`	string Required	See the example and validation rules.
`definitionId`	string Required	1 minimum characters.
`version`	integer Required	1 minimum.
`operator`	`equals` / `contains` / `gte` / `lte` Required	See the example and validation rules.
`value`	string / number / boolean Required	See the example and validation rules.

Data model

Creative fields

Fields used by the corresponding operation.

Field	Type	Meaning
`headline`	string Required	1 minimum characters; 120 maximum characters. Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable.
`body`	string Required	1 minimum characters; 2000 maximum characters. Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable.
`cta`	string Required	1 minimum characters; 60 maximum characters. Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable.
`landingUrl`	string Optional	Optional company destination: a public HTTPS URL without username, password, query string or fragment. Omit or leave empty to use the Mementom offer page. The saved response supplies hostedUrl separately; keep landingUrl empty when using that default.
`image`	string Optional	Optional PNG/JPEG/WebP base64 data URL. There is no separate per-image character limit. The complete authenticated content or campaign request, including all images, must fit the 4 MiB JSON limit.
`brandName`	string Optional	Plain text, up to 80 characters. Brand shown on the creative; empty leaves the brand line blank.
`offerLabel`	string Optional	Plain text, up to 120 characters. Authored offer badge or benefit. No fee or completion wording is inserted automatically.
`terms`	string Optional	Plain text, up to 1000 characters. Offer terms shown as authored.
`promoCode`	string Optional	Plain text, up to 80 characters. Optional promotional code.
`imageAlt`	string Optional	Plain text, up to 180 characters. Description of the image for assistive technology.
`design`	Creative design Optional	Controlled background, layout, text, image and button settings. Omitted settings use defaults.

Data model

Creative design

Choose a layout, palette and typography for the authored creative. Only these settings are accepted; arbitrary CSS, unknown keys, null and out-of-range values are rejected. Older records use the defaults. Empty optional text and a default-equivalent design remain compatible with legacy saved content.

Field	Type	Meaning
`layout`	string Optional	`image-top`, `background`, `text`. Default: image-top.
`backgroundColor`	string Optional	Six-digit hexadecimal color. Default: #ffffff.
`textColor`	string Optional	Six-digit hexadecimal color. Default: #182840.
`accentColor`	string Optional	Six-digit hexadecimal color. Default: #245cdb.
`buttonTextColor`	string Optional	Six-digit hexadecimal color. Default: #ffffff.
`overlayColor`	string Optional	Six-digit hexadecimal color. Default: #000000.
`overlayOpacity`	number Optional	0–85. Overlay opacity as a percentage. Default: 45.
`imagePosition`	string Optional	`center`, `top`, `bottom`, `left`, `right`. Default: center.
`textAlign`	string Optional	`left`, `center`. Default: left.
`contentPosition`	string Optional	`top`, `center`, `bottom`. Default: bottom.
`fontFamily`	string Optional	`sans`, `serif`. Default: sans.
`headlineSize`	string Optional	`small`, `medium`, `large`. Default: medium.
`buttonStyle`	string Optional	`rounded`, `pill`, `square`. Default: rounded.
`imageFit`	string Optional	`cover`, `contain`. Default: cover.

Data model

Typed question

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.

Field	Type	Meaning
`schemaVersion`	`1` Required	See the example and validation rules.
`prompt`	string Required	1 minimum characters; 240 maximum characters. Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable.
`questionType`	`multipleChoice` / `boolean` / `slider` Required	See the example and validation rules.
`answerType`	`single` / `multiple` Required	See the example and validation rules.
`maxAnswers`	integer Required	1 minimum; 20 maximum.
`step`	integer Optional	1 minimum.
`insight`	QuestionInsight Required	See the example and validation rules.

Use an approved or standard company definition. Enum choices come from its finite domain; boolean and slider require one answer. Slider step must divide its registered integer range. Existing legacy prompt/options questions remain compatible; new integrations should bind a typed question to an insight.

Data model

Campaign engagement

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 unchanged creative, questions, tags and requested insights of that edition; the service snapshots definitions and content. Placement fees may differ from the saved content defaults.

Field	Type	Meaning
`name`	string Required	1 minimum characters; 100 maximum characters. Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable.
`type`	`offer` / `questionnaire` / `insight_request` Required	See the example and validation rules.
`content`	Creative Required	See the example and validation rules.
`questions`	array of QuestionInput Required	10 maximum items.
`requestedInsightIds`	array of string Required	20 maximum items; distinct values.
`audienceIds`	array of string Required	1 minimum items; 20 maximum items; distinct values.
`excludedAudienceIds`	array of string Optional	20 maximum items; distinct values.
`refinements`	array of Rule Optional	8 maximum items.
`engagementMinor`	integer Required	0 minimum; 100000 maximum.
`purchaseMinor`	integer Required	0 minimum; 100000 maximum.
`contentId`	string Optional	See the example and validation rules.
`contentRevision`	integer Optional	1 minimum.

Data model

Campaign draft fields

Preferred draft format. Both dates null or both valid timezone-bearing dates, end after start. Daily cap <= total budget. Both budgets must cover a full priced engagement plus purchase fee. Values are USD cents; all pricing remains a planning estimate. Campaigns are created, not updated or activated.

Field	Type	Meaning
`schemaVersion`	`2` Required	See the example and validation rules.
`name`	string Required	1 minimum characters; 100 maximum characters. Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable.
`objective`	`return_visitors` / `learn_preferences` / `collect_insights` Required	See the example and validation rules.
`startAt`	string or null Required	See the example and validation rules.
`endAt`	string or null Required	See the example and validation rules.
`budgetMinor`	integer Required	1 minimum; 100000000 maximum.
`dailyCapMinor`	integer Required	1 minimum; 100000000 maximum.
`responseWindowHours`	`24` / `72` / `168` Required	See the example and validation rules.
`engagements`	array of Engagement Required	1 minimum items; 10 maximum items.

Data model

Content save fields

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 and their saved offer previews. Optional engagementMinor and purchaseMinor set the default combined fees in even USD cents (0–100000 each, positive in combination; purchase fees apply only to offers). Omission preserves the current or duplicated record’s values. New content defaults to 200 and 0; these are defaults, not minimum fees.

Field	Type	Meaning
`name`	string Required	1 minimum characters; 100 maximum characters. Nonempty plain text. HTML, control characters and identifying fields are rejected where applicable.
`type`	`offer` / `questionnaire` / `insight_request` Required	See the example and validation rules.
`content`	Creative Required	See the example and validation rules.
`questions`	array of QuestionInput Required	10 maximum items.
`requestedInsightIds`	array of string Required	20 maximum items; distinct values.
`contentId`	string Optional	See the example and validation rules.
`expectedContentRevision`	integer Optional	1 minimum.
`duplicateFromId`	string Optional	See the example and validation rules.
`engagementMinor`	integer Optional	Even USD cents, 0–100000. Default combined engagement fee for campaign reuse. Omission preserves an existing or duplicated value; new content defaults to 200.
`purchaseMinor`	integer Optional	Even USD cents, 0–100000. Offer purchase fee. Omission preserves an existing or duplicated value; new content defaults to 0.

Data model

Pricing policy

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.

Field	Type	Meaning
`schemaVersion`	`1` Optional	See the example and validation rules.
`brandTier`	`free` / `basic` / `pro` / `enterprise` Optional	See the example and validation rules.
`marketTier`	`economy` / `retail` / `mid` / `luxury` / `ultra` Optional	See the example and validation rules.
`sourceWeight`	number Optional	0 minimum; 1 maximum.
`dataPointWeight`	number Optional	0 minimum; 1 maximum.
`uniquenessWeight`	number Optional	0 minimum; 1 maximum.
`confidenceWeight`	number Optional	0 minimum; 1 maximum.
`baseCPA`	number Optional	0 minimum; 1000 maximum. Scenario base purchase fee in dollars; this is not a charge.
`splitAddOnCostsWithCPA`	boolean Optional	See the example and validation rules.

Data model

Insight pricing profile

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.

Field	Type	Meaning
`type`	`demographic` / `location` / `behavior` / `question` Optional	See the example and validation rules.
`purchaseType`	`general` / `precision` / `subscription` Optional	See the example and validation rules.
`baseMinor`	integer Optional	0 minimum; 100000 maximum.
`sourceCount`	integer Optional	1 minimum; 100 maximum.
`dataPointCount`	integer Optional	1 minimum; 1000000 maximum.
`uniqueness`	number Optional	0 minimum; 1 maximum.
`confidence`	number Optional	0 minimum; 1 maximum.
`ageDays`	number Optional	0 minimum; 36500 maximum.
`halfLifeDays`	number Optional	1 minimum; 3650 maximum.
`expiresAfterDays`	number Optional	1 minimum; 3650 maximum.

Data model

Credential metadata

Fields used by the corresponding operation.

Field	Type	Meaning
`id`	string Required	See the example and validation rules.
`label`	string Required	See the example and validation rules.
`applicationId`	ApplicationId Required	See the example and validation rules.
`developerAccountId`	string Required	Issuing staff account; this is never a consumer identity.
`scopes`	array of Scope Required	See the example and validation rules.
`createdAt`	integer Required	0 minimum. Unix milliseconds.
`expiresAt`	integer Required	0 minimum. Unix milliseconds.
`revokedAt`	integer or null Required	See the example and validation rules.
`status`	`active` / `expired` / `revoked` Required	See the example and validation rules.

Data model

Workspace response

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.

Field	Type	Meaning
`applicationId`	ApplicationId Required	See the example and validation rules.
`revision`	integer Required	0 minimum.
`definitions`	array of InsightDefinition Required	See the example and validation rules.
`outsideCatalog`	array of InsightDefinition Required	See the example and validation rules.
`captureCatalog`	array of InsightDefinition Optional	See the example and validation rules.
`audiences`	array of SavedAudience Required	See the example and validation rules.
`contentLibrary`	array of SavedContent Required	See the example and validation rules.
`campaigns`	array of SavedCampaign Required	See the example and validation rules.
`objective`	`return_visitors` / `learn_preferences` Required	See the example and validation rules.
`pricingPolicy`	PricingPolicy Required	See the example and validation rules.
`pricingProfiles`	object Required	See the example and validation rules.
`pricingUpdatedAt`	string Optional	See the example and validation rules.
`suggestions`	array of object Optional	See the example and validation rules.
`sampleSummary`	object Optional	See the example and validation rules.
`market`	object Optional	Aggregate catalog coverage and provenance; earnings may be unavailable.
`capabilities`	object Required	See the example and validation rules.
`readiness`	string Required	See the example and validation rules.
`generatedAt`	string Required	See the example and validation rules.
`activityId`	ActivityId Optional	See the example and validation rules.

Every saved audience has an ID, rules, status and planning price. Content includes its ID, current revision and retained editions. Campaigns contain engagement IDs, audience/content/insight snapshots, completion-event names, pricing and draft terms. Saved offer content and offer engagements also include a read-only hostedUrl. Library previews use /marketing/offers/{appId}/content/{contentId}/{revision}; campaign previews use /marketing/offers/{appId}/campaign/{campaignId}/{campaignRevision}/{engagementId}. The returned absolute URL requires the owning company’s marketing session. It does not publish the draft or replace the authored content.landingUrl. Duplicates receive their own preview URL. The OpenAPI contract defines the complete saved-object shapes.

Data model

Report metrics

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.

Field	Type	Meaning
`delivered`	integer Required	0 minimum.
`viewed`	integer Required	0 minimum.
`started`	integer Required	0 minimum.
`responded`	integer Required	0 minimum.
`completed`	integer Required	0 minimum.
`arrivals`	integer Required	0 minimum.
`insightsReleased`	integer Required	0 minimum.
`purchases`	integer Required	0 minimum.
`reversals`	integer Required	0 minimum.
`netPurchases`	integer Required	0 minimum.
`optedOut`	integer Required	0 minimum.
`mature`	integer Required	0 minimum.
`matureResponded`	integer Required	0 minimum.
`matureStarted`	integer Required	0 minimum.
`matureCompleted`	integer Required	0 minimum.
`matureArrivals`	integer Required	0 minimum.
`matureNetPurchases`	integer Required	0 minimum.
`pending`	integer Required	0 minimum.
`timedResponders`	integer Required	0 minimum.
`viewTimedResponders`	integer Required	0 minimum.
`modeledSpendMinor`	integer Required	0 minimum.
`modeledConsumerMinor`	integer Required	0 minimum.
`responseRate`	number or null Required	See the example and validation rules.
`matureResponseRate`	number or null Required	See the example and validation rules.
`medianResponseMs`	number or null Required	See the example and validation rules.
`p90ResponseMs`	number or null Required	See the example and validation rules.
`medianViewedResponseMs`	number or null Required	See the example and validation rules.
`costPerResponseMinor`	number or null Required	See the example and validation rules.
`costPerPurchaseMinor`	number or null Required	See the example and validation rules.
`revenueMinor`	number or null Required	See the example and validation rules.
`settledMinor`	null Required	No settlement integration.
`windows`	array of object Required	See the example and validation rules.

The report also supplies campaignId, campaignRevision, mode, generatedAt, windowHours, budgetMinor, recommendations, per-engagement metrics/question distributions, isSample and limitations. These fields describe recorded evidence; they do not prove delivery, billing or causal lift.

Marketing automation and AI/MCP

Use the SDK from your company’s jobs, internal tools or agency backend. Keep server credentials separate per application and grant the minimum scopes. An integration must preserve current membership, company/application ownership and revision checks.

The Marketing MCP server exposes tools backed by these operations. Keep credentials, private photos/captions, keyring material and holder identities out of model input. Your backend supplies the credential after authorization. Persist returned IDs and reconcile uncertain writes.

Use hosted OAuth or local stdio as described in the MCP connection guide. Draft creation is not publishing or spending. A wrapper cannot add capabilities or permissions that the API does not grant.

Tool purpose	Existing SDK method
Read catalog and drafts	`getWorkspace`
Count an audience	`countAudience`
Save audience/content	`saveAudience / saveContent`
Create a draft	`createCampaign`
Read reports and traces	`getReport / getActivity`

See the flow in Aster

After reading the contract, use Aster to see actual messages, saved IDs and console readback in a concrete company example. Aster’s settings are replaceable; your company does not need an Aster account or Aster insight to integrate.

The downloadable example exports a configurable draft workflow. Replace the company name, insight key/value, content and landing URL with your registered application’s values. The API reference remains available without the demonstration or a signed-in session.

Open Aster marketing demo

Endpoint index

All paths are relative to https://mementom.app/api/v1/marketing. Credential lifecycle operations require a console session; other operations accept scoped server credentials.

Method	Path	Purpose
GET	`/applications`	List applications
GET	`/applications/{applicationId}/workspace`	Read the workspace
POST	`/applications/{applicationId}/workspace/audiences`	Save an audience
POST	`/applications/{applicationId}/workspace/count`	Count an audience
POST	`/applications/{applicationId}/workspace/content`	Save content
POST	`/applications/{applicationId}/workspace/campaigns`	Create a campaign draft
GET	`/applications/{applicationId}/workspace/report`	Read a campaign report
GET	`/applications/{applicationId}/workspace/activity`	Read API activity
POST	`/applications/{applicationId}/workspace/pricing`	Set pricing assumptions
POST	`/applications/{applicationId}/workspace/proposals`	Propose an insight
POST	`/applications/{applicationId}/workspace/objective`	Set the workspace objective
GET	`/api-tokens`	List credentials
POST	`/api-tokens`	Issue a credential
DELETE	`/api-tokens/{tokenId}`	Revoke a credential

Marketing API

Your application, one marketing workspace

From your server to the marketing console

Read the workspace

Build an audience

Save content

Create a draft

Verify the result

Authentication and scopes

Request headers

Scopes

Revisions and safe retries

Errors and limits

SDK and integration downloads

List applications

Request fields

Read the workspace

Request fields

Save an audience

Request fields

Count an audience

Request fields

Save content

Request fields

Create a campaign draft

Request fields

Read a campaign report

Request fields

Read API activity

Request fields

Set pricing assumptions

Request fields

Propose an insight

Request fields

Set the workspace objective

Request fields

List credentials

Request fields

Issue a credential

Request fields

Revoke a credential

Request fields

Audience rule

Grouped audience logic

Criterion binding

Creative fields

Creative design

Typed question

Campaign engagement

Campaign draft fields

Content save fields

Pricing policy

Insight pricing profile

Credential metadata

Workspace response

Report metrics

Marketing automation and AI/MCP

See the flow in Aster

Endpoint index