distribution.techdistribution.tech
Get a plan

MCP tool

Add a creator

plan_add_creator

Add a creator to a plan awaiting approval by its unit_id (a format's unit_id from creators_search or creator_get), at that format's current all-in price.

Overview

Add a creator to a plan awaiting approval by its unit_id (a format's unit_id from creators_search or creator_get), at that format's current all-in price, the same as the brand adding it in the workspace. Leave out plan_id (REST: POST /api/v1/plans/current/lines) to add to the brand's newest plan awaiting approval, or to start a plan for this creator when none waits; that also needs the mandate to allow starting a campaign, and counts toward the brand's 3 new campaigns in 24 hours. Only approved creators on sale can be added (not_approved otherwise). A creator who would take the plan's all-in total over the mandate's maximum plan total, or this month's signed spend plus that total over its monthly cap, is refused (mandate_refused, over_max_plan_total or over_monthly_cap) and the plan is left as it was. A creator who would take the plan's all-in total over its campaign's budget is refused for everyone (conflict, reason over_budget, with budget_cents and remaining_cents, the room left before this creator) and the plan is left as it was; pick a creator priced within remaining_cents or remove one first. Returns the new 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

Arguments

Arguments of plan_add_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.
unit_idstring (uuid)YesA format's unit_id from creators_search or creator_get.
plan_idstring (uuid)NoThe plan to add to. Leave out to add to the brand's newest plan awaiting approval, or to start one for this creator.

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_add_creator",
    "arguments": {
      "idempotency_key": "<string>",
      "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_add_creator
NameTypeRequiredDescription
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>",
  "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.