distribution.techdistribution.tech
Get a plan

MCP tool

Swap a creator

plan_swap_creator

Replace one line of a plan awaiting approval (line_id from plan_quote) with another creator's format (unit_id from creators_search or creator_get) at its.

Overview

Replace one line of a plan awaiting approval (line_id from plan_quote) with another creator's format (unit_id from creators_search or creator_get) at its current all-in price, in one step: both happen or neither does, so the plan is never left with both creators or with none. The plan's total after the swap must fit the key's mandate and the campaign's budget: a creator at or under the removed creator's price always swaps in, a dearer one that would go over the budget is refused (conflict, reason over_budget, budget_cents, remaining_cents). A creator already on the plan is refused (already_in_plan); to change a creator's format, remove the line and add the format. Returns the new line_id, the removed_line_id and the plan as plan_quote returns it. Needs an idempotency_key.

Server
https://app.distribution.tech/api/mcp
Scope
campaigns:write
Changes data
Yes, pass an idempotency_key
REST endpoint
POST /plans/{id}/lines/{line_id}/swap

Arguments

Arguments of plan_swap_creator
NameTypeRequiredDescription
idempotency_keystringYesYour unique id for this request. Retry with the same id and the same arguments to get the same answer; it never runs twice.
plan_idstring (uuid)YesThe plan, from campaign_status or plan_quote.
line_idstring (uuid)YesThe line to replace, from plan_quote.
unit_idstring (uuid)YesThe new creator's format: a unit_id from creators_search or creator_get.

Call with curl

The server speaks streamable HTTP, so one JSON-RPC tools/call request runs the tool. Set DISTRIBUTION_API_KEY to a key from Developers with the campaigns:write scope; the arguments shown are the required ones.

curl
curl -X POST "https://app.distribution.tech/api/mcp" \
  -H "Authorization: Bearer $DISTRIBUTION_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "plan_swap_creator",
    "arguments": {
      "idempotency_key": "<string>",
      "plan_id": "<uuid>",
      "line_id": "<uuid>",
      "unit_id": "<uuid>"
    }
  }
}'

Result

The answer's structuredContent follows the tool's output schema (the same JSON is in its text content). It has these fields:

Result fields of plan_swap_creator
NameTypeRequiredDescription
line_idstring (uuid)Yes
removed_line_idstring (uuid)Yes
planobjectYesA plan as the person sees it and as an agent signs it (v1-product-spec 8.5 Quote).
structuredContent, every field with its type
{
  "line_id": "<uuid>",
  "removed_line_id": "<uuid>",
  "plan": {
    "plan_id": "<uuid>",
    "campaign_id": "<uuid>",
    "version": 0,
    "status": "awaiting_approval",
    "currency": "<string>",
    "launch_window_start": "<date>",
    "launch_window_end": "<date>",
    "terms_fingerprint": "<string>",
    "total_cents": 0,
    "totals": {},
    "lines": [
      {
        "id": "<uuid>",
        "creator": {
          "id": "<uuid>",
          "name": "<string>",
          "handle": "<string>",
          "profile_url": "<string>",
          "avatar_url": "<uri>",
          "followers": 0
        },
        "creator_id": "<uuid>",
        "unit_id": "<uuid>",
        "stage_id": "planned",
        "stage": "<string>",
        "channel": "<string>",
        "channel_label": "<string>",
        "format": "<string>",
        "deliverable": "<string>",
        "scheduled_date": "<date>",
        "price_cents": 0,
        "vetting": "<string>",
        "reason": "<string>",
        "expected_views_low": 0,
        "expected_views_high": 0,
        "on_sale": false
      }
    ],
    "payment_options": [
      {
        "rail": "checkout",
        "label": "<string>",
        "clears": "<string>"
      }
    ],
    "agent_payment": "checkout",
    "brand_terms": {
      "current_version": "<string>",
      "current_number": 0,
      "url": "<string>",
      "accepted_for_this_key": "<string>",
      "accepted_number_for_this_key": 0
    },
    "mandate": {
      "key_id": "<uuid>",
      "version": 0,
      "max_plan_cents": 0,
      "monthly_cap_cents": 0,
      "channels": [
        "<string>"
      ],
      "may_approve": false,
      "may_exceed_budget": false,
      "expires_at": "<date-time>",
      "updated_at": "<date-time>",
      "spent_this_month_cents": 0,
      "terms_version": "<string>",
      "terms_accepted_at": "<date-time>",
      "terms_accepted_email": "<string>"
    },
    "policy": {
      "allowed": false,
      "refusal": {}
    },
    "blocked_lines": [
      "<uuid>"
    ],
    "over_budget": {
      "budget_cents": 0,
      "total_cents": 0,
      "over_by_cents": 0
    },
    "order": {},
    "valid_while": "terms_fingerprint_unchanged"
  }
}

Get access

Keys are created in Developers once your brand is approved. Connect an agent to ask for access, then read the agent guide for the full flow.