--- title: "POST /plans/{id}/lines: Add a creator | distribution.tech" description: "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." canonical: https://distribution.tech/docs/api/post-plans-id-lines generator: md-live-route generated: 2026-10-21T23:54:10.623Z --- # POST /plans/{id}/lines: Add a creator | distribution.tech - [Getting started](https://distribution.tech/docs) - [Guides](https://distribution.tech/docs/help/plan-a-campaign) - [API reference](https://distribution.tech/docs/api) - [MCP and agents](https://distribution.tech/docs/agents) - [Changelog](https://distribution.tech/docs/changelog) Search the docs Docs - Using the API › - [API reference](https://distribution.tech/docs/api) - [Authentication](https://distribution.tech/docs/api/authentication) - [Scopes](https://distribution.tech/docs/api/scopes) - [Errors](https://distribution.tech/docs/api/errors) - Inventory and audience › - [GET /audience](https://distribution.tech/docs/api/get-audience) - [GET /inventory](https://distribution.tech/docs/api/get-inventory) - Creators › - [GET /creators](https://distribution.tech/docs/api/get-creators) - [GET /creators/{id}](https://distribution.tech/docs/api/get-creators-id) - [POST /creators/{id}/price-request](https://distribution.tech/docs/api/post-creators-id-price-request) - Campaigns › - [GET /campaigns](https://distribution.tech/docs/api/get-campaigns) - [POST /campaigns](https://distribution.tech/docs/api/post-campaigns) - [GET /campaigns/{id}](https://distribution.tech/docs/api/get-campaigns-id) - [PATCH /campaigns/{id}](https://distribution.tech/docs/api/patch-campaigns-id) - [DELETE /campaigns/{id}](https://distribution.tech/docs/api/delete-campaigns-id) - [POST /campaigns/{id}/archive](https://distribution.tech/docs/api/post-campaigns-id-archive) - [POST /campaigns/{id}/creator-guidelines](https://distribution.tech/docs/api/post-campaigns-id-creator-guidelines) - Plans › - [POST /plans/{id}/approve](https://distribution.tech/docs/api/post-plans-id-approve) - [POST /plans/{id}/dates](https://distribution.tech/docs/api/post-plans-id-dates) - [POST /plans/{id}/lines](https://distribution.tech/docs/api/post-plans-id-lines) - [GET /plans/{id}/quote](https://distribution.tech/docs/api/get-plans-id-quote) - [DELETE /plans/{id}/lines/{line\_id}](https://distribution.tech/docs/api/delete-plans-id-lines-line-id) - [POST /plans/{id}/lines/{line\_id}/swap](https://distribution.tech/docs/api/post-plans-id-lines-line-id-swap) - Proof and results › - [GET /evidence](https://distribution.tech/docs/api/get-evidence) - [GET /results](https://distribution.tech/docs/api/get-results) - Company context › - [GET /brain](https://distribution.tech/docs/api/get-brain) - Feedback › - [GET /feedback](https://distribution.tech/docs/api/get-feedback) - [POST /feedback](https://distribution.tech/docs/api/post-feedback) 1. [distribution](https://distribution.tech/) 2. / [Docs](https://distribution.tech/docs) 3. / [API reference](https://distribution.tech/docs#api) 4. / Plans API reference, Plans # Add a creator POST /plans/{id}/lines 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. Copy page as markdown [View .md](https://distribution.tech/docs/api/post-plans-id-lines.md) ## 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. Scope: campaigns:write. MCP tool: plan\_add\_creator. Endpoint `POST https://app.distribution.tech/api/v1/plans/{id}/lines` Scope `campaigns:write` Changes data Yes, send an Idempotency-Key header MCP tool [plan\_add\_creator](https://distribution.tech/docs/mcp/tools/plan-add-creator) ## Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string (uuid) or one of "current" | Yes | A plan id, or current: the brand's newest plan awaiting approval, or a new plan started for this creator. | | `Idempotency-Key` | header | string | Yes | 8 to 128 letters, digits or . \_ : -. Retry with the same key and the same request to get the same answer; it never runs twice. | ## Request body | Name | Type | Required | Description | | --- | --- | --- | --- | | `unit_id` | string (uuid) | Yes | A format's unit\_id from /creators. | JSON body, every field ``` { "unit_id": "" } ``` ## Request with curl Set `DISTRIBUTION_API_KEY` to a key from Developers with the `campaigns:write` scope, and each path variable to an id from an earlier answer. The body carries the required fields. curl ``` curl -X POST "https://app.distribution.tech/api/v1/plans/$PLAN_ID/lines" \ -H "Authorization: Bearer $DISTRIBUTION_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "unit_id": "" }' ``` ## Response `200` OK. The body has these fields: | Name | Type | Required | Description | | --- | --- | --- | --- | | `line_id` | string (uuid) | Yes | | | `plan` | object | Yes | A plan as the person sees it and as an agent signs it (v1-product-spec 8.5 Quote). | 200 response body, every field with its type ``` { "line_id": "", "plan": { "plan_id": "", "campaign_id": "", "version": 0, "status": "awaiting_approval", "currency": "", "launch_window_start": "", "launch_window_end": "", "terms_fingerprint": "", "total_cents": 0, "totals": {}, "lines": [ { "id": "", "creator": { "id": "", "name": "", "handle": "", "profile_url": "", "avatar_url": "", "followers": 0 }, "creator_id": "", "unit_id": "", "stage_id": "planned", "stage": "", "channel": "", "channel_label": "", "format": "", "deliverable": "", "scheduled_date": "", "price_cents": 0, "vetting": "", "reason": "", "expected_views_low": 0, "expected_views_high": 0, "on_sale": false } ], "payment_options": [ { "rail": "checkout", "label": "", "clears": "" } ], "agent_payment": "checkout", "brand_terms": { "current_version": "", "current_number": 0, "url": "", "accepted_for_this_key": "", "accepted_number_for_this_key": 0 }, "mandate": { "key_id": "", "version": 0, "max_plan_cents": 0, "monthly_cap_cents": 0, "channels": [ "" ], "may_approve": false, "may_exceed_budget": false, "expires_at": "", "updated_at": "", "spent_this_month_cents": 0, "terms_version": "", "terms_accepted_at": "", "terms_accepted_email": "" }, "policy": { "allowed": false, "refusal": {} }, "blocked_lines": [ "" ], "over_budget": { "budget_cents": 0, "total_cents": 0, "over_by_cents": 0 }, "order": {}, "valid_while": "terms_fingerprint_unchanged" } } ``` ## Errors | Status | When | | --- | --- | | `400` | A parameter is not valid: details.problems names each field and what it accepts. | | `401` | No API key, an unknown one, or a revoked one. | | `403` | The key lacks the scope, or the mandate refuses (mandate\_refused, with the limit and how much over). | | `404` | No plan, line or creator of yours has that id. | | `409` | conflict (with a reason), idempotency\_conflict, or in\_progress (Retry-After). | | `422` | unprocessable: the body is readable but a value cannot be used (a blank or too long name, a campaign that cannot be planned yet); details.problems names each field when there are several. | | `429` | Too many requests for this key in the current minute (60); Retry-After and RateLimit-Reset say when to try again. On POST /campaigns and on POST /plans/current/lines when it starts a plan: the brand's 3 new campaigns in 24 hours are used (details.reason daily\_campaign\_limit); details.resets\_at and Retry-After say when the limit reopens, a rolling 24 hours from the first of them, not a calendar day; archiving or deleting a campaign does not give its slot back. On GET /creators and GET /creators/{id}: a creator read limit is used (details.reason per\_minute, daily\_lists, daily\_reveals, daily\_seen or locked). daily\_seen is your workspace's one pool of 300 creator views a day (300 different creators shown or opened since midnight UTC), shared by the app and every API key of the brand: details.scope workspace and details.limit 300; a creator already seen today, in the app or through any key, still opens and costs nothing. daily\_lists is the day's list calls (each GET /creators page or creators\_search is one; details.limit, 60): it is counted apart from creator views, resets at midnight UTC, and Retry-After says when. daily\_reveals is the day's creator profiles opened (details.limit, 60). The other reasons are this key's own limit (details.scope key) or the brand's ceiling over all its keys (details.scope api). | | `500` | internal: the request failed on our side. Retry it with the same Idempotency-Key. | | `503` | unavailable: writes are not available right now (for an approval: payments are not open yet). | ## Related endpoints - [`POST /plans/{id}/approve`](https://distribution.tech/docs/api/post-plans-id-approve): Approve and get the pay link - [`POST /plans/{id}/dates`](https://distribution.tech/docs/api/post-plans-id-dates): Move a plan's dates - [`GET /plans/{id}/quote`](https://distribution.tech/docs/api/get-plans-id-quote): A plan as you sign it - [`DELETE /plans/{id}/lines/{line_id}`](https://distribution.tech/docs/api/delete-plans-id-lines-line-id): Remove a creator - [`POST /plans/{id}/lines/{line_id}/swap`](https://distribution.tech/docs/api/post-plans-id-lines-line-id-swap): Swap a creator ## Get access Keys are created in Developers once your brand is approved. [Connect an agent](https://distribution.tech/distribution#access) to ask for access, then read [the agent guide](https://distribution.tech/docs/agents) for the full flow. On this page - [Overview](#overview) - [Parameters](#parameters) - [Request body](#request-body) - [Request with curl](#curl) - [Response](#response) - [Errors](#errors) - [Related endpoints](#related) - [Get access](#access) [![distribution.tech](https://distribution.tech/brand/wordmark-light.svg)![distribution.tech](https://distribution.tech/brand/wordmark.svg)](https://distribution.tech/) Your agent buys your distribution. Distribution we run for - ClickUp - Gushwork - Tab Platform - [How it works](https://distribution.tech/how-it-works) - [Network](https://distribution.tech/network) - [Workspace](https://app.distribution.tech/login) - [For your agents](https://distribution.tech/distribution) Solutions - [Product launch](https://distribution.tech/solutions/product-launch) - [Funding announcement](https://distribution.tech/solutions/funding-announcement) - [Feature release](https://distribution.tech/solutions/feature-release) - [For brands](https://distribution.tech/for-brands) - [For creators](https://distribution.tech/for-creators) Resources - [Blog](https://distribution.tech/blog) - [Launch playbook](https://distribution.tech/playbook) - [X creator rates](https://distribution.tech/rates/x-creators) Company - [Customers](https://distribution.tech/customers) - [Pricing](https://distribution.tech/pricing) - [Changelog](https://distribution.tech/changelog) - [Build a distribution plan](https://app.distribution.tech/login) - [Join the creator network](https://distribution.tech/for-creators#apply) - [Log in](https://app.distribution.tech/login) Legal - [Privacy](https://distribution.tech/privacy) - [Terms](https://distribution.tech/terms) © 2026 distribution.tech [Contact: team@distribution.tech](mailto:team@distribution.tech)Cookie settings Light Dark System