write

Tools that create or update in-app state

Draft a change set

POST

https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp

/api/v1/tools/changes_draft

Bearer (ck_ endpoint token)

Open a DRAFT change set for this organization — the container a human later reviews and approves. Nothing is applied to any ad platform by this call, or by anything else you can do: after changes_add_item and changes_submit the set sits in PENDING review until a person approves it in the Bellaso app. The draft is owned by this API endpoint, so only this endpoint can add items to it or submit it.

Draft a change set › Request Body

title

string · minLength: 1 · maxLength: 200 · required

Short human-readable title for the change set — the reviewer sees this first. Say what changes and why, e.g. "Cut spend on non-converting search campaigns".

management_connection_id

string · pattern: ^[0-9a-fA-F]{8}-[0-9… · required

Which ad-platform connection these changes will be applied through. Get valid ids from list_management_connections.

requires_finance

boolean

Route the set through finance approval before admin approval. Use it for budget increases.

Draft a change set › Responses

The tool ran

ToolResult

ok

boolean · const · required

Const value:

tool

string · required

data

required

The tool's payload — byte-identical to what the same tool returns over MCP.

Add an item to a change set

POST

https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp

/api/v1/tools/changes_add_item

Bearer (ck_ endpoint token)

Append one proposed operation (a budget change, a status change, …) to a DRAFT change set you drafted. Items can only be added while the set is a DRAFT — once submitted, its contents are frozen so a reviewer approves exactly what they read. Re-adding an identical operation is refused as a duplicate rather than queued twice.

Add an item to a change set › Request Body

change_set_id

string · pattern: ^[0-9a-fA-F]{8}-[0-9… · required

The DRAFT change set to append to (from changes_draft).

operation_type

string · minLength: 1 · maxLength: 120 · required

The operation this item performs, e.g. "google.campaign_budget_micros" or "meta.adset_daily_budget".

object · required

The operation's arguments, matching the operation type — e.g. { customerId, campaignId, budgetMicros } for google.campaign_budget_micros.

schema_version

integer · min: 1 · max: 100

Payload schema version (defaults to 1). Leave unset unless you know the operation has a newer shape.

Add an item to a change set › Responses

The tool ran

ToolResult

ok

boolean · const · required

Const value:

tool

string · required

data

required

The tool's payload — byte-identical to what the same tool returns over MCP.

Submit a change set for review

POST

https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp

/api/v1/tools/changes_submit

Bearer (ck_ endpoint token)

Hand a DRAFT change set you drafted to its human reviewers: it moves to PENDING_ADMIN, or PENDING_FINANCE when the set was flagged as requiring finance. This does NOT apply anything — approval is a person's decision in the Bellaso app, and this surface cannot approve. A set that is not a DRAFT is refused.

Submit a change set for review › Request Body

change_set_id

string · pattern: ^[0-9a-fA-F]{8}-[0-9… · required

The DRAFT change set to submit for human review.

Submit a change set for review › Responses

The tool ran

ToolResult

ok

boolean · const · required

Const value:

tool

string · required

data

required

The tool's payload — byte-identical to what the same tool returns over MCP.

Create an audience

POST

https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp

/api/v1/tools/audience_create

Bearer (ck_ endpoint token)

Build and save an intent audience from a plain-English description. SIDE EFFECT: this creates a feed at the ContactBased intent provider and CONSUMES this organization's Engage audience quota — it is not a free preview, so confirm the query with the user before calling it. There is a per-organization cap on saved audiences; when it is reached the call is refused and no quota is spent. The audience is created unattached: nothing is pushed to any ad platform until a destination is configured and a person runs a push.

Create an audience › Request Body

name

string · minLength: 1 · maxLength: 200 · required

Name for the saved audience, shown in the Bellaso app.

nl_query

string · minLength: 1 · maxLength: 500 · pattern: \S · required

Plain-English description of the people to reach, e.g. "homeowners shopping for solar panels". This is the intent query the audience is built from.

lookback_days

integer · min: 1 · max: 14

How many days of intent signal to draw on (1–14, default 14). Values outside the range are clamped.

similarity_preset

string · enum

Match precision: high = fewer, closer matches; low = broader reach. Default medium.

Enum values:

low

medium

high

output_type

string · enum

Whether the audience is people (consumer, the default) or companies/professionals (business).

Enum values:

consumer

business

object[] · maxItems: 20

Firmographic/professional filters, e.g. [{ field: "job_title", operator: "contains", value: "engineer" }]. Unknown fields or operators are dropped silently rather than rejected — read the saved audience back to see what was kept.

object[] · maxItems: 20

Consumer filters, e.g. [{ field: "state", operator: "in", value: ["CA","NV"] }]. Unknown fields or operators are dropped silently.

Create an audience › Responses

The tool ran

ToolResult

ok

boolean · const · required

Const value:

tool

string · required

data

required

The tool's payload — byte-identical to what the same tool returns over MCP.

POST/api/v1/tools/audience_create

curl https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp/api/v1/tools/audience_create \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "name",
  "nl_query": "nl_query",
  "lookback_days": 1,
  "similarity_preset": "low",
  "output_type": "consumer",
  "business_filters": [
    {
      "field": "field",
      "operator": "operator",
      "value": {}
    }
  ],
  "consumer_filters": [
    {
      "field": "field",
      "operator": "operator",
      "value": {}
    }
  ]
}'

Example Request Body

{
  "name": "name",
  "nl_query": "nl_query",
  "lookback_days": 1,
  "similarity_preset": "low",
  "output_type": "consumer",
  "business_filters": [
    {
      "field": "field",
      "operator": "operator",
      "value": {}
    }
  ],
  "consumer_filters": [
    {
      "field": "field",
      "operator": "operator",
      "value": {}
    }
  ]
}

json

Example Responses

{
  "ok": true,
  "tool": "tool",
  "data": {}
}

json

application/json

Update audience filters

POST

https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp

/api/v1/tools/audience_update_filters

Bearer (ck_ endpoint token)

Replace a saved audience's structured filters WITHOUT rebuilding it — no ContactBased feed is created and no quota is spent. Only the filter sets you supply are touched; an omitted set is left as it was. Unknown filter fields are dropped by the server, so supplying only unrecognised clauses CLEARS that filter set — read the returned audience to confirm what was kept.

Update audience filters › Request Body

audience_id

string · minLength: 1 · maxLength: 64 · required

The audience to edit.

object[] · maxItems: 20

Consumer filters, e.g. [{ field: "state", operator: "in", value: ["CA","NV"] }]. Unknown fields or operators are dropped silently.

Update audience filters › Responses

The tool ran

ToolResult

ok

boolean · const · required

Const value:

tool

string · required

data

required

The tool's payload — byte-identical to what the same tool returns over MCP.

POST/api/v1/tools/audience_update_filters

curl https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp/api/v1/tools/audience_update_filters \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "audience_id": "audience_id",
  "business_filters": [
    {
      "field": "field",
      "operator": "operator",
      "value": {}
    }
  ],
  "consumer_filters": [
    {
      "field": "field",
      "operator": "operator",
      "value": {}
    }
  ]
}'

Example Request Body

{
  "audience_id": "audience_id",
  "business_filters": [
    {
      "field": "field",
      "operator": "operator",
      "value": {}
    }
  ],
  "consumer_filters": [
    {
      "field": "field",
      "operator": "operator",
      "value": {}
    }
  ]
}

json

Example Responses

{
  "ok": true,
  "tool": "tool",
  "data": {}
}

json

application/json

Add an audience destination

POST

https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp

/api/v1/tools/audience_add_destination

Bearer (ck_ endpoint token)

Configure where an audience will be pushed: one ad account on meta, google or linkedin. This only SAVES the destination in a pending state — it does not push anything, and this API cannot push. The ad account must be one this organization has already synced; any other id is refused by name.

Add an audience destination › Request Body

audience_id

string · minLength: 1 · maxLength: 64 · required

The audience to configure a destination for.

platform

string · enum · required

Which ad platform the audience will be pushed to.

Enum values:

Add an audience destination › Responses

The tool ran

ToolResult

ok

boolean · const · required

Const value:

tool

string · required

data

required

The tool's payload — byte-identical to what the same tool returns over MCP.

Rename or hide an ad account

POST

https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp

/api/v1/tools/account_update

Bearer (ck_ endpoint token)

Set an ad account's display name and/or hide it from the app's pickers and tables. These are the only two account fields this API can touch — both are cosmetic. Product and KPI MAPPINGS are deliberately not exposed: changing one rebuilds the organization's warehouse models and re-cuts every reported number, which is a decision for a person in the Bellaso app.

Rename or hide an ad account › Request Body

account_id

string · minLength: 1 · maxLength: 128 · required

The ad account to update, as its warehouse id (e.g. "facebook_ads_123456"). Get ids from get_accounts_performance.

display_name

string · minLength: 1 · maxLength: 200

A friendlier label for this account across the app. Cosmetic only: it never changes any metric.

hidden

boolean

Hide (true) or unhide (false) the account in the app's account pickers and tables. Cosmetic only: hiding does not delete data or stop syncing.

Rename or hide an ad account › Responses

The tool ran

ToolResult

ok

boolean · const · required

Const value:

tool

string · required

data

required

The tool's payload — byte-identical to what the same tool returns over MCP.

Update Slack digest settings

POST

https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp

/api/v1/tools/org_update_digest_settings

Bearer (ck_ endpoint token)

Set how often this organization's Slack performance digest posts, and optionally which channel it posts to. Setting the frequency to 'off' also stops proactive KPI-change alerts. This changes notification delivery only — it touches no data, no billing and no ad platform.

Update Slack digest settings › Request Body

digest_frequency

string · enum · required

How often the Slack performance digest posts: daily, weekly, or off. 'off' is the master switch — it also silences proactive KPI-change alerts.

Enum values:

daily

weekly

off

Slack channel id to post into (e.g. "C08ABCDEF"), or null to clear it. Omit to leave the current channel unchanged. This is the raw channel id, not the #name — an id that is not in the workspace simply means nothing posts.

Update Slack digest settings › Responses

The tool ran

ToolResult

ok

boolean · const · required

Const value:

tool

string · required

data

required

The tool's payload — byte-identical to what the same tool returns over MCP.

Create or update a conversion page rule

POST

https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp

/api/v1/tools/signal_page_rule_upsert

Bearer (ck_ endpoint token)

Create a page rule, or update an existing one. A matching pageview records a synthetic form submission named by the rule, so it feeds conversion counts, attribution and any Conversions-API destination — write patterns narrowly. Rules are evaluated on every pageview, so only three literal match types exist (exact / prefix / contains) and there is no regex.

Create or update a conversion page rule › Request Body

id

string · pattern: ^[0-9a-fA-F]{8}-[0-9…

Omit to CREATE a rule; supply it to UPDATE that rule.

site_id

string · pattern: ^[0-9a-fA-F]{8}-[0-9…

Which tracked site the rule belongs to (required when creating). A rule never moves between sites — delete and recreate instead.

name

string · minLength: 1 · maxLength: 120

The conversion name recorded when the rule matches, e.g. "Quote request". Must be unique per site.

match_type

string · enum

How the pattern is compared: exact and prefix test the URL PATH (so their patterns must start with "/"); contains tests the full URL. There is no regex option.

Enum values:

exact

prefix

contains

pattern

string · minLength: 1 · maxLength: 500

The path or substring to match, e.g. "/thank-you". Validated against the match type — a pattern-only update is checked against the rule's stored match type.

is_active

boolean

Whether the rule is evaluated on incoming pageviews (defaults to true on create).

Create or update a conversion page rule › Responses

The tool ran

ToolResult

ok

boolean · const · required

Const value:

tool

string · required

data

required

The tool's payload — byte-identical to what the same tool returns over MCP.

Delete a conversion page rule

POST

https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp

/api/v1/tools/signal_page_rule_delete

Bearer (ck_ endpoint token)

Remove a page rule so its pattern stops counting as a conversion. Historical conversions already recorded by the rule are NOT deleted — only future pageviews stop matching.

Delete a conversion page rule › Request Body

id

string · pattern: ^[0-9a-fA-F]{8}-[0-9… · required

The page rule to delete.

Delete a conversion page rule › Responses

The tool ran

ToolResult

ok

boolean · const · required

Const value:

tool

string · required

data

required

The tool's payload — byte-identical to what the same tool returns over MCP.

Create or update a form group

POST

https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp

/api/v1/tools/signal_form_group_upsert

Bearer (ck_ endpoint token)

Group the step form names of one multi-step form under a single name, so conversion rules and send-deduplication treat them as one form rather than one conversion per step. Supplying form_names on an update REPLACES the whole list.

Create or update a form group › Request Body

id

string · pattern: ^[0-9a-fA-F]{8}-[0-9…

Omit to CREATE a group; supply it to UPDATE that group.

name

string · minLength: 1 · maxLength: 80

Group name, unique in the organization, e.g. "Quote wizard".

form_names

string[] · minItems: 1 · maxItems: 50

The observed form names that are steps of ONE form, e.g. ["aq-step1","aq-step2"]. Blanks are dropped and duplicates de-duped; 1–50 unique entries survive.

Create or update a form group › Responses

The tool ran

ToolResult

ok

boolean · const · required

Const value:

tool

string · required

data

required

The tool's payload — byte-identical to what the same tool returns over MCP.

Create or update an attribution model

POST

https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp

/api/v1/tools/signal_attribution_model_upsert

Bearer (ck_ endpoint token)

Create an attribution model, or update one in place. Models are computed ON READ, so changing one re-cuts how credit is reported across channels immediately and retroactively — say which model you changed when you report results. name and model_type are required on both create and update (an update replaces the model's whole definition).

Create or update an attribution model › Request Body

name

string · minLength: 1 · maxLength: 120 · required

Model name shown in the Signal attribution views.

model_type

string · enum · required

How credit is split across a contact's touchpoints.

Enum values:

first_touch

last_touch

linear

time_decay

position_based

id

string · pattern: ^[0-9a-fA-F]{8}-[0-9…

Omit to CREATE a model; supply it to UPDATE that model.

object

Model-specific settings, e.g. { half_life_days: 7 } for time_decay or { first: 0.4, last: 0.4 } for position_based. Unknown keys are stored as-is.

lookback_days

integer · min: 1 · max: 730

How far before a conversion touchpoints still earn credit (1–730, default 90).

is_active

boolean

Whether the model runs in the standard attribution computation (default true).

is_default

boolean

Whether this model is the organization's default view (default false).

Create or update an attribution model › Responses

The tool ran

ToolResult

ok

boolean · const · required

Const value:

tool

string · required

data

required

The tool's payload — byte-identical to what the same tool returns over MCP.

POST/api/v1/tools/signal_attribution_model_upsert

curl https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp/api/v1/tools/signal_attribution_model_upsert \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "id": "id",
  "name": "name",
  "model_type": "first_touch",
  "config": {
    "key": {}
  },
  "lookback_days": 1,
  "is_active": true,
  "is_default": true
}'

Example Request Body

{
  "id": "id",
  "name": "name",
  "model_type": "first_touch",
  "config": {
    "key": {}
  },
  "lookback_days": 1,
  "is_active": true,
  "is_default": true
}

json

Example Responses

{
  "ok": true,
  "tool": "tool",
  "data": {}
}

json

application/json

Update a conversions destination's config

POST

https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp

/api/v1/tools/signal_destination_update_config

Bearer (ck_ endpoint token)

Adjust an EXISTING Conversions-API destination: its name, event map, lookback window, de-duplication window, and whether it is sending. Pausing (is_enabled false) stops outbound conversion sends immediately; resuming also clears the failure counters. Credentials, platform config and the destination's platform cannot be changed here, and destinations cannot be created or deleted through this API.

Update a conversions destination's config › Request Body

destination_id

string · pattern: ^[0-9a-fA-F]{8}-[0-9… · required

The existing Conversions-API destination to reconfigure.

name

string · minLength: 1 · maxLength: 80

Display name for the destination.

object

Which platform event each Bellaso event type sends as, e.g. { form_submit: "Lead" }. Replaces the whole map.

lookback_days

integer · min: 1 · max: 90

How many days back conversions are eligible to send (1–90).

dedupe_window_hours

integer · min: 0 · max: 720

At most one send per (rule, person) within this many hours; 0 disables de-duplication.

is_enabled

boolean

Resume (true → status active, which also clears the failure counters) or pause (false → status paused) sending.

Update a conversions destination's config › Responses

The tool ran

ToolResult

ok

boolean · const · required

Const value:

tool

string · required

data

required

The tool's payload — byte-identical to what the same tool returns over MCP.

POST/api/v1/tools/signal_destination_update_config

curl https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp/api/v1/tools/signal_destination_update_config \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "destination_id": "destination_id",
  "name": "name",
  "event_map": {
    "key": "string"
  },
  "lookback_days": 1,
  "dedupe_window_hours": 0,
  "is_enabled": true
}'

Example Request Body

{
  "destination_id": "destination_id",
  "name": "name",
  "event_map": {
    "key": "string"
  },
  "lookback_days": 1,
  "dedupe_window_hours": 0,
  "is_enabled": true
}

json

Example Responses

{
  "ok": true,
  "tool": "tool",
  "data": {}
}

json

application/json

Delete Signal session recording

POST

https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp

/api/v1/tools/signal_session_delete

Bearer (ck_ endpoint token)

Soft-delete a Signal session recording immediately (denies further playback). Object cleanup is asynchronous.

Delete Signal session recording › Request Body

session_id

string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-… · required

Delete Signal session recording › Responses

The tool ran

ToolResult

ok

boolean · const · required

Const value:

tool

string · required

data

required

The tool's payload — byte-identical to what the same tool returns over MCP.

Enqueue Signal session analysis

POST

https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp

/api/v1/tools/signal_session_enqueue_analysis

Bearer (ck_ endpoint token)

Enqueue a budgeted LLM analysis job for a session. Idempotent on (session_id, input_hash, model_version, prompt_version). Honors signal_replay_settings analysis_enabled and monthly USD budget. Does not run the model — only enqueues.

Enqueue Signal session analysis › Request Body

session_id

string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-… · required

model_version

string · minLength: 1 · maxLength: 128

prompt_version

string · minLength: 1 · maxLength: 128

Enqueue Signal session analysis › Responses

The tool ran

ToolResult

ok

boolean · const · required

Const value:

tool

string · required

data

required

The tool's payload — byte-identical to what the same tool returns over MCP.

read ads