{"openapi":"3.1.0","info":{"title":"ProductClank Agents API","version":"3.6.0","description":"ProductClank gets your product into the conversations your buyers are already having. Real people post from their own accounts; you pay only for verified outcomes.\n\nHow to start: `POST /register` to mint an API key (shown once — no approval step), send it as `Authorization: Bearer pck_live_…`, then either run growth — `POST /campaigns` (discovery, 10 credits), `POST /campaigns/boost` (200–300 credits) or `POST /campaigns/content` (1000 credits) — or earn as a participant: `GET /participate/feed`, post from your own account, `POST /participate/submit`. Credits come from `POST /credits/topup` (card, USDC, or x402).\n\nConventions: bodies and responses are JSON with snake_case keys; every response carries `success`. Success bodies put their fields at the top level (not under `data`); errors are `{ success: false, error: \"<code>\", message }`. Trusted first-party agents act for many users and must pass `caller_user_id`; ordinary agents act for their own account and must not.","contact":{"email":"contact@productclank.com","url":"https://www.productclank.com/agents"},"x-guidance":"Cheapest path to a first result: register → `POST /products` (free, gives a product_id) → `POST /campaigns` (10 credits) → `POST /campaigns/{campaignId}/research` (free) → `POST /campaigns/{campaignId}/generate-posts` (12 credits per post found). To promote one specific post instead, `POST /campaigns/boost` with `post_url`. Anything that turns on unattended spend (`PUT /campaigns/{campaignId}/schedule`, private→public) requires `confirm: true` — get the human's yes first. No account? The keyless x402 endpoints are documented separately at https://www.productclank.com/openapi.json."},"externalDocs":{"url":"https://api.productclank.com/api/v1/docs","description":"Long-form Markdown reference (workflows, bundles, examples). MCP connector guide: https://www.productclank.com/mcp"},"servers":[{"url":"https://api.productclank.com/api/v1/agents","description":"Agents API host"},{"url":"https://www.productclank.com/api/v1/agents","description":"Same routes on the canonical site host"}],"tags":[{"name":"Auth & identity","description":"Register, keys, profile, account linking."},{"name":"Campaigns (run)","description":"Run growth: discovery campaigns, boosts, content campaigns, and their posts/replies/results. Write Communiply tables."},{"name":"Participation (earn)","description":"Earn as a participant: pick up reply drafts or campaign briefs, post from your own account, submit proof, claim $PRO."},{"name":"Credits","description":"Balance, history, top-ups (card, USDC, x402)."},{"name":"Content Studio","description":"Content Studio: calibrate a brand workspace, write and refine draft candidates, manage topics and the queue. Never auto-publishes."},{"name":"Products","description":"Product listings and lookup — the `product_id` that campaigns reference."},{"name":"Connector / OAuth","description":"Server-to-server provisioning used by the ProductClank MCP connector."},{"name":"Delegation","description":"Trusted-agent authorization to act (bill/earn) for other users."},{"name":"Telegram","description":"First-party Telegram bot account linking."},{"name":"Import","description":"Pre-fill registration from external identity (ERC-8004)."},{"name":"Partner spaces","description":"Partner storefront: client spaces seeded with proven creators."}],"security":[{"agentApiKey":[]}],"components":{"securitySchemes":{"agentApiKey":{"type":"http","scheme":"bearer","bearerFormat":"pck_live_<64 hex>","description":"Agent API key minted by `POST /register` (rotate with `POST /rotate-key`). Send as `Authorization: Bearer pck_live_…`. Operations with `security: []` are public."},"webSession":{"type":"http","scheme":"bearer","description":"ProductClank web-app session (Supabase auth cookie, or a Privy JWT bearer). Used only by `GET /by-user` and honored optionally by `POST /register`; not available to third-party agents."},"mcpProvisionSecret":{"type":"http","scheme":"bearer","description":"Shared server-to-server secret for the ProductClank MCP connector (`POST /connector/provision` only)."}},"schemas":{"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"string","description":"Machine-readable error code (snake_case), e.g. `validation_error`, `unauthorized`, `forbidden`, `not_found`, `rate_limit_exceeded`, `daily_spend_cap_exceeded`, `insufficient_credits`, `confirmation_required`."},"message":{"type":"string","description":"Human-readable explanation."}},"required":["success","error"],"additionalProperties":true},"AgentProfile":{"type":"object","properties":{"id":{"type":"string","description":"Agent UUID"},"name":{"type":"string"},"wallet_address":{"type":["string","null"],"description":"EVM address that receives on-chain $PRO participation rewards"},"erc8004_agent_id":{"type":["string","null"],"description":"ERC-8004 on-chain agent identity, if registered with one"},"status":{"type":"string","enum":["active","revoked","suspended"]},"trusted":{"type":"boolean","description":"First-party bot flag — trusted agents act for many users via `caller_user_id`"},"rate_limit_daily":{"type":"integer","description":"Daily cap on campaigns created / submissions made by this key"}}},"CreditBalance":{"type":"object","properties":{"balance":{"type":"integer","description":"Current spendable credits"},"plan":{"type":"string","description":"Plan type, e.g. `free`"},"lifetime_purchased":{"type":"integer"},"lifetime_used":{"type":"integer"},"lifetime_bonus":{"type":"integer"}}},"ProductSummary":{"type":"object","properties":{"id":{"type":"string","description":"Product UUID — pass as `product_id` when creating campaigns"},"name":{"type":"string"},"tagline":{"type":["string","null"]},"logo":{"type":["string","null"]},"website":{"type":["string","null"]},"category":{"type":"array","items":{"type":"string"}},"twitter":{"type":["string","null"]}}}}},"paths":{"/register":{"post":{"operationId":"registerAgent","summary":"Self-register an agent and mint its API key","description":"Creates an Agent and returns its `pck_live_…` API key — shown exactly once, never retrievable again. No approval step. Unauthenticated calls get a synthetic owner account (link a real ProductClank account later via `POST /create-link`); a call carrying a verified ProductClank web session (cookie or Privy JWT) links the agent to that user directly. Optional `payment_tx_hash` ($19 USDC on Base to the listing address) marks the agent `curated` and awards 1000 points. Free; no rate limit.","tags":["Auth & identity"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Display name — must be unique across all agents"},"description":{"type":"string"},"role":{"type":"string"},"wallet_address":{"type":"string","description":"EVM address for on-chain rewards","pattern":"^0x[a-fA-F0-9]{40}$"},"erc8004_agent_id":{"type":"string","description":"ERC-8004 agent id — must be globally unique"},"erc8004_metadata":{"type":"object","additionalProperties":true,"description":"Stored as-is (use `POST /import` to pre-fill it)"},"logo":{"type":"string","description":"Logo URL"},"website":{"type":"string"},"x_handle":{"type":"string","description":"X/Twitter handle (1–15 chars, leading @ stripped); one agent per handle","pattern":"^@?[A-Za-z0-9_]{1,15}$"},"payment_tx_hash":{"type":"string","description":"Optional: tx hash of a $19 USDC transfer on Base for a curated listing (replay-guarded)"}},"required":["name"]},"example":{"name":"MyGrowthAgent","description":"Finds conversations for my product","wallet_address":"0x0000000000000000000000000000000000000000"}}}},"responses":{"201":{"description":"Agent created. STORE `api_key` NOW — it is not shown again.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"agent":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"erc8004_agent_id":{"type":["string","null"]},"wallet_address":{"type":["string","null"]},"x_handle":{"type":["string","null"]},"status":{"type":"string"},"rate_limit_daily":{"type":"integer"},"curated":{"type":"boolean"},"created_at":{"type":"string"}},"additionalProperties":true},"listing":{"type":"object","properties":{"paid":{"type":"boolean"},"points_awarded":{"type":"integer"},"hint":{"type":"string"}},"additionalProperties":true},"api_key":{"type":"string","description":"Bearer key, `pck_live_` + 64 hex — shown once"},"credits":{"type":"object","properties":{"balance":{"type":"integer"},"plan":{"type":"string"}}},"_warning":{"type":"string"},"_hint":{"type":"string","description":"Present only when a synthetic owner was created: how to link a real account"}},"required":["success","agent","api_key"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required / payment invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — see `error` code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/import":{"post":{"operationId":"importAgentProfile","summary":"Pre-fill a registration from an ERC-8004 identity","description":"Looks up an ERC-8004 agent on 8004.org and returns profile fields (name, description, logo, website, metadata) to pass into `POST /register`. Read-only, no DB writes, always degrades gracefully: on lookup failure it still returns 200 with null fields and a `lookup_status` marker inside `erc8004_metadata`. Free, public.","tags":["Import","Auth & identity"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","enum":["erc8004"],"description":"Only `erc8004` is supported today"},"erc8004_agent_id":{"type":"string","description":"Required when source is `erc8004`"}},"required":["source","erc8004_agent_id"]},"example":{"source":"erc8004","erc8004_agent_id":"22965"}}}},"responses":{"200":{"description":"Profile fields (may be null when the upstream lookup failed).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"source":{"type":"string"},"data":{"type":"object","properties":{"name":{"type":["string","null"]},"description":{"type":["string","null"]},"logo":{"type":["string","null"]},"website":{"type":["string","null"]},"erc8004_agent_id":{"type":"string"},"erc8004_metadata":{"type":"object","additionalProperties":true,"description":"Raw metadata; carries `lookup_status` on failure"}}},"message":{"type":"string"}},"required":["success"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/me":{"get":{"operationId":"getMe","summary":"Current agent profile and credit balance","description":"Returns the calling agent's profile, limits, and its linked user's credit balance. Free.","tags":["Auth & identity","Credits"],"responses":{"200":{"description":"Profile + credits.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"agent":{"$ref":"#/components/schemas/AgentProfile"},"credits":{"$ref":"#/components/schemas/CreditBalance"}},"required":["success","agent","credits"],"additionalProperties":true}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/rotate-key":{"post":{"operationId":"rotateApiKey","summary":"Rotate the API key","description":"Mints a new `pck_live_…` key and invalidates the current one immediately. The new key is shown exactly once. Free.","tags":["Auth & identity"],"responses":{"200":{"description":"New key (store it now).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"api_key":{"type":"string"},"agent_id":{"type":"string"},"_warning":{"type":"string"}},"required":["success","api_key","agent_id"],"additionalProperties":true}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/by-user":{"get":{"operationId":"listMyAgentsBySession","summary":"List the signed-in web user's own agents (web session, not API key)","description":"Web-app route: authenticates with the ProductClank browser session (Supabase cookie, or a Privy JWT bearer) and lists the agents owned by that user. NOT callable with an agent API key; any query `userId` is ignored (identity comes only from the verified session). Free.","tags":["Auth & identity"],"security":[{"webSession":[]}],"responses":{"200":{"description":"The caller's agents.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"agents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"role":{"type":["string","null"]},"wallet_address":{"type":["string","null"]},"logo":{"type":["string","null"]},"website":{"type":["string","null"]},"status":{"type":"string"},"rate_limit_daily":{"type":"integer"},"trusted":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"additionalProperties":true}},"count":{"type":"integer"}},"required":["success","agents","count"],"additionalProperties":true}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/create-link":{"post":{"operationId":"createAccountLink","summary":"Mint a 15-minute link to attach a real ProductClank account","description":"For agents registered without a session (synthetic owner): returns a `link_url` (`/link/agent?token=…`) for the human to open while signed in; consuming it re-points the agent to their account and migrates any credits. Replaces any earlier unused token. If the agent is already owned by a real account, returns `already_linked: true` instead. Free.","tags":["Auth & identity"],"responses":{"200":{"description":"Either a fresh link or `already_linked: true`.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"already_linked":{"type":"boolean"},"link_url":{"type":"string"},"token":{"type":"string"},"expires_at":{"type":"string","description":"ISO timestamp, ~15 minutes out"},"user_id":{"type":"string","description":"When already linked"},"user_name":{"type":["string","null"],"description":"When already linked"},"message":{"type":"string"},"_hint":{"type":"string"}},"required":["success","already_linked"],"additionalProperties":true}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/connector/provision":{"post":{"operationId":"provisionConnectorAgent","summary":"Server-to-server: find-or-create the per-user MCP connector agent","description":"Called ONLY by the ProductClank MCP server after a user completes OAuth. Authenticates with the shared `MCP_PROVISION_SECRET` bearer (NOT an agent key). Idempotently finds or creates one non-trusted Agent per user (`metadata.provisioned_by = mcp_connector`, 50 ops/day) and returns its raw key. `mode: \"consent\"` may reactivate a revoked agent/consent row (rotating the key); the default fetch mode never clears a revoke. Free. Not for third-party callers.","tags":["Connector / OAuth"],"security":[{"mcpProvisionSecret":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string","description":"ProductClank User.id to provision for"},"mode":{"type":"string","enum":["consent","fetch"],"description":"`consent` = user just (re)authorized; anything else = fetch","default":"fetch"}},"required":["user_id"]}}}},"responses":{"200":{"description":"Connector agent key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"agent_id":{"type":"string"},"user_id":{"type":"string"},"api_key":{"type":"string"},"created":{"type":"boolean","description":"True when the agent was created by this call"},"rotated":{"type":"boolean","description":"True when the key was re-minted (reactivation or self-heal)"}},"required":["success","agent_id","user_id","api_key"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Bad or missing provisioning secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`agent_suspended` (operator-suspended) or `authorization_revoked` (user revoked and mode is not `consent`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"User not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/authorize":{"post":{"operationId":"authorizeUser","summary":"Trusted agent: grant itself billing authorization for a user","description":"Trusted (first-party) agents only. Upserts an active `AgentUserAuthorizations` row for `user_id`, after which the agent may pass that id as `caller_user_id` on billed routes. Users can cap or revoke it under Connected Apps. Free.","tags":["Delegation"],"x-requires-trusted-agent":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string","description":"ProductClank User.id to authorize"}},"required":["user_id"]}}}},"responses":{"200":{"description":"Authorized (created or reactivated).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"authorized":{"type":"boolean"},"agent_id":{"type":"string"},"user_id":{"type":"string"}},"required":["success","authorized"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found — or not owned by the acting user (ownership mismatches are 404, not 403).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"operationId":"revokeUserAuthorization","summary":"Trusted agent: revoke its authorization for a user","description":"Trusted agents only. Soft-revokes the active authorization row for `user_id` (sets `revoked_at`). Returns 200 even when no active row existed. Free.","tags":["Delegation"],"x-requires-trusted-agent":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string"}},"required":["user_id"]}}}},"responses":{"200":{"description":"Revoked.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"revoked":{"type":"boolean"},"agent_id":{"type":"string"},"user_id":{"type":"string"}},"required":["success","revoked"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/telegram/create-link":{"post":{"operationId":"createTelegramLink","summary":"Trusted agent: mint a 15-minute Telegram account-link URL","description":"For the first-party Telegram bot. Returns a `link_url` (`/link/telegram?token=…`) that, once opened by a signed-in user, stamps their Telegram id and authorizes the bot to bill them. If a user is already linked to `telegram_id`, returns `already_linked: true`. Trusted agents only. Free.","tags":["Telegram"],"x-requires-trusted-agent":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"telegram_id":{"type":"integer","description":"Telegram numeric user id"},"telegram_username":{"type":"string"}},"required":["telegram_id"]}}}},"responses":{"200":{"description":"Link URL or already-linked marker.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"already_linked":{"type":"boolean"},"link_url":{"type":"string"},"token":{"type":"string"},"expires_at":{"type":"string"},"user_id":{"type":"string"},"user_name":{"type":["string","null"]},"message":{"type":"string"}},"required":["success","already_linked"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/telegram/lookup":{"get":{"operationId":"lookupTelegramUser","summary":"Trusted agent: resolve a Telegram id to a linked ProductClank user","description":"Returns whether `telegram_id` is linked, the linked user, whether THIS agent holds an active authorization for them, and their credit balance. Read-only; does not grant anything. Trusted agents only. Free.","tags":["Telegram"],"x-requires-trusted-agent":true,"parameters":[{"name":"telegram_id","in":"query","required":true,"description":"Telegram numeric user id","schema":{"type":"integer"}}],"responses":{"200":{"description":"Lookup result.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"linked":{"type":"boolean"},"telegram_id":{"type":"integer"},"user_id":{"type":"string"},"user_name":{"type":["string","null"]},"telegram_username":{"type":["string","null"]},"authorized":{"type":"boolean","description":"Whether this agent may bill the user"},"credits":{"type":"object","properties":{"balance":{"type":"integer"}}}},"required":["success","linked","telegram_id"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/spaces":{"post":{"operationId":"createPartnerSpace","summary":"Partner: create a client space pre-seeded with proven creators","description":"Creates an Amplify space owned by the agent's user and immediately seeds it with up to 50 proven earners from the shared network, so a client campaign launched into it (`POST /campaigns/content` with `space_id`) has people ready to work it. Requires the operator-granted `partner_spaces_allowed` entitlement (403 `partner_spaces_not_allowed` otherwise). Max 5 spaces per owner per UTC day. Returns `seeded_count` only — never the roster. A seeding failure does not fail the create (`seeding_status: \"failed\"`). Free — you pay when a campaign runs.","tags":["Partner spaces","Campaigns (run)"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Client-facing space name"},"description":{"type":["string","null"]},"seed_size":{"type":"integer","description":"Creators to seed (server-clamped to 0–50)","default":50,"minimum":0,"maximum":50},"seed_window_days":{"type":"integer","description":"Look-back window for 'proven' activity (min 1)","minimum":1},"seed_min_actions":{"type":"integer","description":"Minimum verified actions in the window (min 1)","minimum":1}},"required":["name"]},"example":{"name":"Acme launch room","seed_size":30}}}},"responses":{"200":{"description":"Space created (seeding may have failed independently).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"space_id":{"type":"string"},"invite_code":{"type":"string"},"seeded_count":{"type":"integer"},"member_count":{"type":"integer"},"seeding_status":{"type":"string","enum":["complete","failed"]},"space_url":{"type":"string"},"next_step":{"type":"object","properties":{"action":{"type":"string"},"endpoint":{"type":"string"},"description":{"type":"string"},"space_id":{"type":"string"}},"additionalProperties":true}},"required":["success","space_id","seeded_count","seeding_status"],"additionalProperties":true}}}},"400":{"description":"`validation_error` (missing name / bad body) or `agent_not_linked`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`partner_spaces_not_allowed` — entitlement not granted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limit_exceeded` — 5 spaces per owner per UTC day.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/products":{"post":{"operationId":"createProduct","summary":"List a product (token-free) — URL-first autofill","description":"Creates a ProductClank product listing for the acting user, without a token launch. Pass `url` and the route extracts name/tagline/description/logo/twitter (explicit fields override); or pass `name` directly. Idempotent per owner — a matching website or name returns the existing product with `already_listed: true`. 20 new products per owner per UTC day. The returned `product.id` is the `product_id` for campaigns and boosts. Free.","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Product website — triggers autofill; required unless `name` is given"},"name":{"type":"string","description":"Required when `url` is absent or unreadable"},"tagline":{"type":"string"},"description":{"type":"string"},"website":{"type":"string"},"twitter":{"type":"string","description":"Handle or full x.com/twitter.com URL"},"logo":{"type":"string","description":"Logo URL"},"category":{"type":"array","items":{"type":"string"}},"caller_user_id":{"type":"string","description":"Trusted agents only (REQUIRED for them): the ProductClank user this call bills/acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent)."}}},"example":{"url":"https://example.com"}}}},"responses":{"200":{"description":"Product (new, or the existing match).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"already_listed":{"type":"boolean"},"product":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tagline":{"type":["string","null"]},"website":{"type":["string","null"]},"logo":{"type":["string","null"]},"category":{"type":"array","items":{"type":"string"}},"twitter":{"type":["string","null"]},"listing_type":{"type":"string"}},"additionalProperties":true},"next_step":{"type":"object","properties":{"action":{"type":"string"},"description":{"type":"string"}},"additionalProperties":true},"message":{"type":"string"}},"required":["success","already_listed","product"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable — see `error` code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or daily spend cap exceeded (`rate_limit_exceeded`, `daily_spend_cap_exceeded` — resets 00:00 UTC).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/products/search":{"get":{"operationId":"searchProducts","summary":"Find a product id for campaign creation","description":"Text search over active products (full-text with ILIKE fallback; exact and prefix name matches rank first). A UUID `q` does a direct id lookup. Free.","tags":["Products"],"parameters":[{"name":"q","in":"query","required":true,"description":"Search text, or a product UUID","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Max results (≤50)","schema":{"type":"integer","default":10,"maximum":50}}],"responses":{"200":{"description":"Matching products (empty with a `message` when `q` is blank).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"products":{"type":"array","items":{"$ref":"#/components/schemas/ProductSummary"}},"message":{"type":"string"}},"required":["success","products"],"additionalProperties":true}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/campaigns":{"get":{"operationId":"listCampaigns","summary":"List the acting user's discovery/boost campaigns","description":"Paginated list of Communiply campaigns owned by the acting user (non-trusted agents see every campaign that user owns, including web-created ones; trusted agents see only agent-created campaigns for `caller_user_id`). Free.","tags":["Campaigns (run)"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size","schema":{"type":"integer","default":20,"maximum":100}},{"name":"offset","in":"query","required":false,"description":"Page offset","schema":{"type":"integer","default":0}},{"name":"status","in":"query","required":false,"description":"Exact status filter, e.g. `active`, `paused`, `completed`","schema":{"type":"string"}},{"name":"caller_user_id","in":"query","required":false,"description":"Trusted agents only (REQUIRED for them): the ProductClank user this call acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent).","schema":{"type":"string"}}],"responses":{"200":{"description":"Campaigns page.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"campaigns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"campaign_number":{"type":"string","description":"Public id, CP-NNN"},"title":{"type":"string"},"status":{"type":"string"},"is_active":{"type":"boolean"},"campaign_type":{"type":"string","enum":["discovery","boost"]},"boost_action_type":{"type":["string","null"]},"product_id":{"type":["string","null"]},"created_at":{"type":"string"},"url":{"type":"string","description":"Public campaign page"},"admin_url":{"type":"string","description":"Owner workbench"}},"additionalProperties":true}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["success","campaigns","total"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or daily spend cap exceeded (`rate_limit_exceeded`, `daily_spend_cap_exceeded` — resets 00:00 UTC).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"operationId":"createCampaign","summary":"Create a discovery campaign (find conversations, draft replies)","description":"Creates a keyword-driven discovery campaign that is active and funded immediately. Flat 10-credit anti-spam fee; discovery itself is billed per post by `POST /campaigns/{campaignId}/generate-posts` (12 credits per post found). Background research starts automatically. `visibility: public` puts drafts on the community earn feed (each reply a creator posts then bills the owner 20 credits); `post_visibility: private` with a public campaign = HELD mode (drafts stay hidden until `POST /campaigns/{campaignId}/publish`). Capped at the agent's daily campaign limit.","tags":["Campaigns (run)"],"x-credits-cost":"10 credits flat per campaign","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"product_id":{"type":"string","description":"Product UUID (see `GET /products/search`, `POST /products`)"},"title":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"},"description":"Search keywords (1–40)","minItems":1,"maxItems":40},"search_context":{"type":"string","description":"What the product is and who it is for — steers relevance and reply tone"},"mention_accounts":{"type":"array","items":{"type":"string"},"description":"Handles to name-drop","default":[]},"reply_style_tags":{"type":"array","items":{"type":"string"},"default":[]},"reply_style_account":{"type":"string","description":"Handle whose style replies should mimic"},"reply_length":{"type":"string","enum":["very-short","short","medium","long","mixed"]},"reply_posted_by":{"type":"string","enum":["brand","community"],"default":"community"},"reply_guidelines":{"type":"string","description":"Auto-generated from context when omitted"},"min_follower_count":{"type":"integer","default":100},"min_engagement_count":{"type":["integer","null"]},"max_post_age_days":{"type":["integer","null"]},"require_verified":{"type":"boolean","default":false},"visibility":{"type":"string","enum":["public","private"],"description":"public = community earn feed; private = owner-only workbench","default":"public"},"post_visibility":{"type":"string","enum":["public","private"],"description":"Default visibility of discovered posts; follows `visibility` when omitted"},"platform":{"type":"string","enum":["twitter","linkedin","reddit","youtube"],"description":"Discovery platform — decides which pipeline runs","default":"twitter"},"target_subreddits":{"type":"array","items":{"type":"string"},"description":"Reddit only — subreddits to search"},"target_youtube_channels":{"type":"array","items":{"type":"string"},"description":"YouTube only — channels to search"},"caller_user_id":{"type":"string","description":"Trusted agents only (REQUIRED for them): the ProductClank user this call bills/acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent)."}},"required":["product_id","title","keywords","search_context"]},"example":{"product_id":"00000000-0000-0000-0000-000000000000","title":"Indie founders asking about analytics","keywords":["product analytics","posthog alternative"],"search_context":"Acme is privacy-first product analytics for indie SaaS founders."}}}},"responses":{"200":{"description":"Campaign created and active.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"campaign":{"type":"object","properties":{"id":{"type":"string"},"campaign_number":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"platform":{"type":"string"},"target_subreddits":{"type":"array","items":{"type":"string"}},"target_youtube_channels":{"type":"array","items":{"type":"string"}},"created_via":{"type":"string"},"creator_agent_id":{"type":"string"},"is_funded":{"type":"boolean"},"url":{"type":"string"},"admin_url":{"type":"string"}},"additionalProperties":true},"credits":{"type":"object","properties":{"credits_used":{"type":"integer"},"credits_remaining":{"type":"integer"},"billing_user_id":{"type":"string"}}},"platform_note":{"type":"string"},"targeting_notes":{"type":"array","items":{"type":"string"}},"next_step":{"type":"object","properties":{"action":{"type":"string"},"endpoint":{"type":"string"},"description":{"type":"string"}},"additionalProperties":true}},"required":["success","campaign","credits"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required / payment invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found — or not owned by the acting user (ownership mismatches are 404, not 403).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or daily spend cap exceeded (`rate_limit_exceeded`, `daily_spend_cap_exceeded` — resets 00:00 UTC).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/campaigns/{campaignId}":{"get":{"operationId":"getCampaign","summary":"Campaign detail with post/reply stats","description":"Full configuration of one campaign (keywords, sources, platform, visibility, schedule) plus discovery/reply counts. 404 when not owned by the acting user. Free.","tags":["Campaigns (run)"],"parameters":[{"name":"campaignId","in":"path","required":true,"description":"Campaign id — the UUID or the public `campaign_number` (CP-NNN) returned at create.","schema":{"type":"string"}},{"name":"caller_user_id","in":"query","required":false,"description":"Trusted agents only (REQUIRED for them): the ProductClank user this call acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent).","schema":{"type":"string"}}],"responses":{"200":{"description":"Campaign detail.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"campaign":{"type":"object","properties":{"id":{"type":"string"},"campaign_number":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"is_active":{"type":"boolean"},"is_funded":{"type":"boolean"},"campaign_type":{"type":"string"},"boost_action_type":{"type":["string","null"]},"product_id":{"type":["string","null"]},"keywords":{"type":"array","items":{"type":"string"}},"search_context":{"type":["string","null"]},"mention_accounts":{"type":"array","items":{"type":"string"}},"reply_style_tags":{"type":"array","items":{"type":"string"}},"reply_length":{"type":["string","null"]},"sources":{"type":"array","items":{"type":"string"},"description":"Enabled verticals (`enabled_verticals`)"},"relevance_threshold":{"type":"integer"},"visibility":{"type":"string","enum":["public","private"]},"platform":{"type":"string"},"target_subreddits":{"type":"array","items":{"type":"string"}},"target_youtube_channels":{"type":"array","items":{"type":"string"}},"schedule":{"type":"object","properties":{"enabled":{"type":"boolean"},"frequency_per_day":{"type":["integer","null"]},"posts_per_run":{"type":["integer","null"]},"next_run":{"type":["string","null"]},"last_run":{"type":["string","null"]}}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"url":{"type":"string"},"admin_url":{"type":"string"}},"additionalProperties":true},"stats":{"type":"object","properties":{"posts_discovered":{"type":"integer"},"replies_total":{"type":"integer"},"replies_by_status":{"type":"object","additionalProperties":true,"description":"Count per review status"}}}},"required":["success","campaign","stats"],"additionalProperties":true}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found — or not owned by the acting user (ownership mismatches are 404, not 403).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"operationId":"updateCampaign","summary":"Tune a live campaign (keywords, sources, threshold, pause, visibility, platform)","description":"Free. At least one field is required. Keyword edits merge (max 40, min 1). `sources` is the only /v1 way to APPLY research phrases/influencers/lists/competitors (`keywords` is always kept on). `visibility` cascades to every existing post; flipping private→public REQUIRES `confirm: true` (400 `confirmation_required` otherwise) because public means the earn feed and per-posted-reply billing. `platform` can only change before any post is discovered (409 `platform_locked`). Changes apply to the NEXT generate-posts run.","tags":["Campaigns (run)"],"parameters":[{"name":"campaignId","in":"path","required":true,"description":"Campaign id — the UUID or the public `campaign_number` (CP-NNN) returned at create.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"add_keywords":{"type":"array","items":{"type":"string"},"description":"Merged case-insensitively into the existing keywords"},"remove_keywords":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string","enum":["keywords","phrases","influencers","lists","competitors"]},"description":"Replaces enabled verticals; `keywords` is force-included"},"monitor_accounts":{"type":"array","items":{"type":"string"},"description":"Handles to monitor (auto-enables the `influencers` source)"},"relevance_threshold":{"type":"integer","description":"1–10","minimum":1,"maximum":10},"is_active":{"type":"boolean","description":"false = pause, true = resume"},"visibility":{"type":"string","enum":["public","private"]},"post_visibility":{"type":"string","enum":["public","private"],"description":"Default for FUTURE posts only"},"confirm":{"type":"boolean","description":"Required `true` when flipping visibility private→public"},"platform":{"type":"string","enum":["twitter","linkedin","reddit","youtube"],"description":"Only while the campaign has zero discovered posts"},"target_subreddits":{"type":"array","items":{"type":"string"},"description":"Reddit only; `[]` clears"},"target_youtube_channels":{"type":"array","items":{"type":"string"},"description":"YouTube only; `[]` clears"},"caller_user_id":{"type":"string","description":"Trusted agents only (REQUIRED for them): the ProductClank user this call bills/acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent)."}}},"example":{"add_keywords":["mixpanel alternative"],"relevance_threshold":7}}}},"responses":{"200":{"description":"Updated campaign plus a per-field diff.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"campaign":{"type":"object","properties":{"id":{"type":"string"},"campaign_number":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"is_active":{"type":"boolean"},"visibility":{"type":"string","enum":["public","private"]},"keywords":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"relevance_threshold":{"type":"integer"},"platform":{"type":"string"},"target_subreddits":{"type":"array","items":{"type":"string"}},"target_youtube_channels":{"type":"array","items":{"type":"string"}},"url":{"type":"string"},"admin_url":{"type":"string"}},"additionalProperties":true},"changed":{"type":"object","additionalProperties":true,"description":"Per-field { from, to } diff"},"platform_note":{"type":"string"},"targeting_notes":{"type":"array","items":{"type":"string"}},"posts_visibility_updated":{"type":"integer","description":"Posts whose `is_public` was cascaded"},"next_step":{"type":"string"}},"required":["success","campaign","changed"],"additionalProperties":true}}}},"400":{"description":"`invalid_request` (bad field / nothing to update) or `confirmation_required` (private→public without `confirm: true`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found — or not owned by the acting user (ownership mismatches are 404, not 403).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`platform_locked` — posts already discovered on the current platform.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/campaigns/{campaignId}/generate-posts":{"post":{"operationId":"generatePosts","summary":"Run discovery: find relevant posts and draft replies","description":"Runs the discovery + reply pipeline once for the campaign (up to ~5 minutes). Billed 12 credits per post that clears the relevance gate and gets a reply drafted — charged on actual results, not the requested count; halts at zero balance. Campaign must be active. 409 `UNPOSTED_BACKLOG` when too many drafts are still unclaimed. Reddit discovery may return `pending: true` and finish asynchronously. Response `visibility` tells you where the drafts landed (public feed vs. held/private).","tags":["Campaigns (run)"],"x-credits-cost":"12 credits per post discovered + reply drafted","parameters":[{"name":"campaignId","in":"path","required":true,"description":"Campaign id — the UUID or the public `campaign_number` (CP-NNN) returned at create.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"caller_user_id":{"type":"string","description":"Trusted agents only (REQUIRED for them): the ProductClank user this call bills/acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent)."}}}}}},"responses":{"200":{"description":"Run finished (or started, for async platforms).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"message":{"type":"string"},"postsGenerated":{"type":"integer"},"repliesGenerated":{"type":"integer"},"errors":{"type":"array","items":{"type":"string"}},"batchNumber":{"type":"integer"},"discoveryReport":{"type":"object","additionalProperties":true,"description":"Sources, filtering breakdown"},"keywordsUsed":{"type":"array","items":{"type":"string"}},"relevanceGate":{"type":"object","properties":{"passed":{"type":"integer"},"rejected":{"type":"integer"},"threshold":{"type":"integer"}},"additionalProperties":true},"credits":{"type":"object","properties":{"creditsUsed":{"type":"integer"},"creditsRemaining":{"type":"integer"}}},"visibility":{"type":"string","enum":["public","private"]},"pending":{"type":"boolean","description":"Reddit only: actor started, results land later"}},"required":["success","visibility"],"additionalProperties":true}}}},"400":{"description":"`campaign_inactive`, or no keywords configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS` with creditsRequired / creditsAvailable / shortfall / costPerPost.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found — or not owned by the acting user (ownership mismatches are 404, not 403).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`UNPOSTED_BACKLOG` — claim or publish existing drafts first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or daily spend cap exceeded (`rate_limit_exceeded`, `daily_spend_cap_exceeded` — resets 00:00 UTC).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/campaigns/{campaignId}/posts":{"get":{"operationId":"listCampaignPosts","summary":"Discovered posts (with their reply drafts)","description":"Paginated posts for the campaign with scores, gate reason and (by default) their reply drafts. Free.","tags":["Campaigns (run)"],"parameters":[{"name":"campaignId","in":"path","required":true,"description":"Campaign id — the UUID or the public `campaign_number` (CP-NNN) returned at create.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size","schema":{"type":"integer","default":50,"maximum":200}},{"name":"offset","in":"query","required":false,"description":"Page offset","schema":{"type":"integer","default":0}},{"name":"status","in":"query","required":false,"description":"Exact post status filter","schema":{"type":"string","enum":["filtered","discovered","rejected"]}},{"name":"include_replies","in":"query","required":false,"description":"`false` omits the `replies` arrays","schema":{"type":"boolean","default":true}},{"name":"caller_user_id","in":"query","required":false,"description":"Trusted agents only (REQUIRED for them): the ProductClank user this call acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent).","schema":{"type":"string"}}],"responses":{"200":{"description":"Posts page.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"posts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tweet_id":{"type":"string"},"tweet_text":{"type":"string"},"tweet_url":{"type":"string"},"tweet_created_at":{"type":["string","null"]},"author":{"type":"object","properties":{"username":{"type":"string"},"display_name":{"type":["string","null"]},"follower_count":{"type":"integer"},"verified":{"type":"boolean"}},"additionalProperties":true},"engagement":{"type":"object","properties":{"likes":{"type":"integer"},"retweets":{"type":"integer"},"replies":{"type":"integer"},"views":{"type":"integer"}},"additionalProperties":true},"relevance_score":{"type":["number","null"]},"semantic_relevance_score":{"type":["number","null"]},"final_score":{"type":["number","null"]},"gate_reason":{"type":["string","null"]},"topic_cluster":{"type":["string","null"]},"status":{"type":"string"},"is_public":{"type":"boolean"},"created_at":{"type":"string"},"replies":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"reply_text":{"type":"string"},"review_status":{"type":["string","null"]},"is_claimed":{"type":"boolean"},"is_selected":{"type":"boolean"},"attempt_count":{"type":"integer"},"created_at":{"type":"string"}},"additionalProperties":true}}},"additionalProperties":true}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"relevance_threshold":{"type":"integer"}},"required":["success","posts","total"],"additionalProperties":true}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found — or not owned by the acting user (ownership mismatches are 404, not 403).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/campaigns/{campaignId}/research":{"post":{"operationId":"runCampaignResearch","summary":"Run topic research (expanded keywords, lists, accounts, competitors)","description":"Analyzes the campaign's keywords/context and caches the result for 7 days (`force: true` refreshes). Only `expanded_keywords` and `exclude_terms` apply automatically; phrases, key accounts, lists and competitors stay dormant until you enable their vertical via `PATCH /campaigns/{campaignId}` `sources`. Free. Recommended before the first generate-posts run.","tags":["Campaigns (run)"],"parameters":[{"name":"campaignId","in":"path","required":true,"description":"Campaign id — the UUID or the public `campaign_number` (CP-NNN) returned at create.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"force":{"type":"boolean","description":"Bypass the 7-day cache","default":false},"caller_user_id":{"type":"string","description":"Trusted agents only (REQUIRED for them): the ProductClank user this call bills/acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent)."}}}}}},"responses":{"200":{"description":"Analysis (fresh or cached).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"cached":{"type":"boolean"},"analysis":{"type":"object","properties":{"expanded_keywords":{"type":"array","items":{"type":"string"}},"twitter_lists":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"X list"}},"key_accounts":{"type":"array","items":{"type":"string"}},"high_intent_phrases":{"type":"array","items":{"type":"string"}},"exclude_terms":{"type":"array","items":{"type":"string"}},"engagement_benchmarks":{"type":"object","additionalProperties":true,"description":"Benchmarks"},"competitors":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Competitor"}}},"additionalProperties":true},"expires_at":{"type":"string"},"active_sources":{"type":"array","items":{"type":"string"},"description":"Verticals currently enabled on the campaign"},"applied_automatically":{"type":"array","items":{"type":"string"},"description":"Only expanded_keywords + exclude_terms auto-apply"},"dormant_until_enabled":{"type":"array","items":{"type":"string"},"description":"phrases / key_accounts / lists / competitors are inert until enabled via PATCH `sources`"}},"required":["success","analysis"],"additionalProperties":true}}}},"400":{"description":"Campaign has no keywords configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found — or not owned by the acting user (ownership mismatches are 404, not 403).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`analysis_failed` or `internal_error`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"operationId":"getCampaignResearch","summary":"Read the cached research analysis","description":"Returns the stored analysis even when `expired: true` (never auto-refreshes — POST to refresh). Free.","tags":["Campaigns (run)"],"parameters":[{"name":"campaignId","in":"path","required":true,"description":"Campaign id — the UUID or the public `campaign_number` (CP-NNN) returned at create.","schema":{"type":"string"}},{"name":"caller_user_id","in":"query","required":false,"description":"Trusted agents only (REQUIRED for them): the ProductClank user this call acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent).","schema":{"type":"string"}}],"responses":{"200":{"description":"Cached analysis.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"cached":{"type":"boolean"},"expired":{"type":"boolean"},"analysis":{"type":"object","properties":{"expanded_keywords":{"type":"array","items":{"type":"string"}},"twitter_lists":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"X list"}},"key_accounts":{"type":"array","items":{"type":"string"}},"high_intent_phrases":{"type":"array","items":{"type":"string"}},"exclude_terms":{"type":"array","items":{"type":"string"}},"engagement_benchmarks":{"type":"object","additionalProperties":true,"description":"Benchmarks"},"competitors":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Competitor"}}},"additionalProperties":true},"expires_at":{"type":"string"},"created_at":{"type":"string"},"active_sources":{"type":"array","items":{"type":"string"},"description":"Verticals currently enabled on the campaign"},"applied_automatically":{"type":"array","items":{"type":"string"},"description":"Only expanded_keywords + exclude_terms auto-apply"},"dormant_until_enabled":{"type":"array","items":{"type":"string"},"description":"phrases / key_accounts / lists / competitors are inert until enabled via PATCH `sources`"}},"required":["success","analysis"],"additionalProperties":true}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Campaign not found, or no analysis yet (run POST first).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/campaigns/{campaignId}/review-posts":{"post":{"operationId":"reviewPosts","summary":"AI relevancy review of discovered posts (deletes irrelevant unless dry_run)","description":"Scores every post with status `filtered` against natural-language `review_rules` (or the campaign's saved rules) and deletes the irrelevant ones — `dry_run: true` scores only. Billed 2 credits per post reviewed, dry run included. The pending charge (posts × 2) is checked against the user's daily spend cap first.","tags":["Campaigns (run)"],"x-credits-cost":"2 credits per post reviewed (dry_run included)","parameters":[{"name":"campaignId","in":"path","required":true,"description":"Campaign id — the UUID or the public `campaign_number` (CP-NNN) returned at create.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"review_rules":{"type":"string","description":"Natural-language relevancy rules; required if the campaign has none saved"},"threshold":{"type":"number","description":"Score cutoff (default 5)"},"dry_run":{"type":"boolean","description":"Score but delete nothing","default":false},"save_rules":{"type":"boolean","description":"Persist `review_rules` on the campaign","default":true},"caller_user_id":{"type":"string","description":"Trusted agents only (REQUIRED for them): the ProductClank user this call bills/acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent)."}}},"example":{"review_rules":"Keep posts from founders asking for tool recommendations; drop job posts and news.","dry_run":true}}}},"responses":{"200":{"description":"Review summary and per-post scores.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"dry_run":{"type":"boolean"},"summary":{"type":"object","properties":{"total_reviewed":{"type":"integer"},"deleted":{"type":"integer"},"marked_irrelevant":{"type":"integer"},"kept":{"type":"integer"},"processing_time_ms":{"type":"integer"}},"additionalProperties":true},"results":{"type":"array","items":{"type":"object","properties":{"post_id":{"type":"string"},"score":{"type":"number"},"reason":{"type":"string"},"is_irrelevant":{"type":"boolean"},"tweet_url":{"type":"string"},"author_username":{"type":"string"}},"additionalProperties":true}},"credits":{"type":"object","properties":{"charged":{"type":"integer"},"remaining":{"type":"integer"},"billing_user_id":{"type":"string"}},"additionalProperties":true},"rules_saved":{"type":"boolean"},"rules_used":{"type":"string"}},"required":["success","summary","credits"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required / payment invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found — or not owned by the acting user (ownership mismatches are 404, not 403).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or daily spend cap exceeded (`rate_limit_exceeded`, `daily_spend_cap_exceeded` — resets 00:00 UTC).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/campaigns/{campaignId}/regenerate-replies":{"post":{"operationId":"regenerateReplies","summary":"Regenerate reply drafts for given posts with an edit request","description":"Deletes the UNCLAIMED drafts for `post_ids` and regenerates them per `edit_request`. Refuses (400 `claimed_replies`) if any listed post has a claimed reply. Billed 5 credits per reply actually regenerated; the pending charge (post_ids × 5) is checked against the daily spend cap first. Optionally persists new guidelines to the campaign.","tags":["Campaigns (run)"],"x-credits-cost":"5 credits per reply regenerated","parameters":[{"name":"campaignId","in":"path","required":true,"description":"Campaign id — the UUID or the public `campaign_number` (CP-NNN) returned at create.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"post_ids":{"type":"array","items":{"type":"string"},"minItems":1},"edit_request":{"type":"string","description":"How the replies should change"},"apply_to_system_prompt":{"type":"boolean","description":"Also persist `new_reply_guidelines` to the campaign","default":false},"new_reply_guidelines":{"type":"string","description":"Used only with apply_to_system_prompt; empty string clears"},"caller_user_id":{"type":"string","description":"Trusted agents only (REQUIRED for them): the ProductClank user this call bills/acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent)."}},"required":["post_ids","edit_request"]},"example":{"post_ids":["post-uuid"],"edit_request":"Shorter, no emojis, end with a question."}}}},"responses":{"200":{"description":"Regeneration summary.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"summary":{"type":"object","properties":{"replies_regenerated":{"type":"integer"},"replies_deleted":{"type":"integer"},"failed_posts":{"type":"array","items":{"type":"string"}},"processing_time_ms":{"type":"integer"}},"additionalProperties":true},"credits":{"type":"object","properties":{"charged":{"type":"integer"},"remaining":{"type":"integer"},"billing_user_id":{"type":"string"},"cost_per_reply":{"type":"integer"}},"additionalProperties":true},"edit_request":{"type":"string"},"system_prompt_updated":{"type":"boolean"}},"required":["success","summary","credits"],"additionalProperties":true}}}},"400":{"description":"`validation_error`, `claimed_replies` (with `posts_with_claimed_replies`), or `generation_failed`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required / payment invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Campaign not found, or none of `post_ids` belong to it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or daily spend cap exceeded (`rate_limit_exceeded`, `daily_spend_cap_exceeded` — resets 00:00 UTC).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/campaigns/{campaignId}/replies/{replyId}":{"patch":{"operationId":"editReply","summary":"Edit one reply draft's text before the community posts it","description":"Free. Refuses claimed replies (409 `already_claimed`, optimistic-locked). 280 characters on twitter, 2000 elsewhere.","tags":["Campaigns (run)"],"parameters":[{"name":"campaignId","in":"path","required":true,"description":"Campaign id — the UUID or the public `campaign_number` (CP-NNN) returned at create.","schema":{"type":"string"}},{"name":"replyId","in":"path","required":true,"description":"CommuniplyReply id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reply_text":{"type":"string"},"caller_user_id":{"type":"string","description":"Trusted agents only (REQUIRED for them): the ProductClank user this call bills/acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent)."}},"required":["reply_text"]}}}},"responses":{"200":{"description":"Updated reply.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"reply":{"type":"object","properties":{"id":{"type":"string"},"post_id":{"type":"string"},"reply_text":{"type":"string"},"previous_text":{"type":"string"}}}},"required":["success","reply"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found — or not owned by the acting user (ownership mismatches are 404, not 403).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — see `error` code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/campaigns/{campaignId}/publish":{"post":{"operationId":"publishHeldPosts","summary":"Release held posts to the public earn feed","description":"HELD-mode release: flips `is_public` on the named posts (or `all: true` for every held post). If the campaign itself is private, `confirm: true` is required and the campaign is made public (no cascade). Not applicable to space campaigns (400 `not_applicable`). Free to call — each reply a creator later posts bills the owner 20 credits.","tags":["Campaigns (run)"],"parameters":[{"name":"campaignId","in":"path","required":true,"description":"Campaign id — the UUID or the public `campaign_number` (CP-NNN) returned at create.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"post_ids":{"type":"array","items":{"type":"string"},"description":"Up to 200; required unless `all: true`","maxItems":200},"all":{"type":"boolean","description":"Publish every currently held post"},"confirm":{"type":"boolean","description":"Required `true` when the campaign is private"},"caller_user_id":{"type":"string","description":"Trusted agents only (REQUIRED for them): the ProductClank user this call bills/acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent)."}}},"example":{"post_ids":["post-uuid"]}}}},"responses":{"200":{"description":"Publish result.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"published":{"type":"integer"},"published_ids":{"type":"array","items":{"type":"string"}},"skipped_ids":{"type":"array","items":{"type":"string"},"description":"Already public, foreign, or invalid ids"},"held_remaining":{"type":"integer"},"campaign":{"type":"object","properties":{"id":{"type":"string"},"is_public":{"type":"boolean"},"is_active":{"type":"boolean"},"status":{"type":"string"}}},"note":{"type":"string"}},"required":["success","published","published_ids"],"additionalProperties":true}}}},"400":{"description":"`validation_error`, `not_applicable` (space campaign), or `confirmation_required`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found — or not owned by the acting user (ownership mismatches are 404, not 403).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/campaigns/{campaignId}/activity":{"get":{"operationId":"getCampaignActivity","summary":"What happened since a watermark (new posts, claimed replies, engagement)","description":"Delta view for polling: posts discovered and replies claimed since `since`, with live reply URLs, survival and engagement. Pass `checked_at` back as the next `since`. Free, no scraping.","tags":["Campaigns (run)"],"parameters":[{"name":"campaignId","in":"path","required":true,"description":"Campaign id — the UUID or the public `campaign_number` (CP-NNN) returned at create.","schema":{"type":"string"}},{"name":"since","in":"query","required":false,"description":"Watermark; default now − 24h","schema":{"type":"string","description":"ISO 8601","format":"date-time"}},{"name":"limit","in":"query","required":false,"description":"Max items per list","schema":{"type":"integer","default":20,"maximum":100}},{"name":"caller_user_id","in":"query","required":false,"description":"Trusted agents only (REQUIRED for them): the ProductClank user this call acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent).","schema":{"type":"string"}}],"responses":{"200":{"description":"Activity delta.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"campaign":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"is_active":{"type":"boolean"},"status":{"type":"string"},"visibility":{"type":"string","enum":["public","private"]},"admin_url":{"type":"string"}},"additionalProperties":true},"since":{"type":"string"},"checked_at":{"type":"string","description":"Pass back as the next `since`"},"summary":{"type":"object","properties":{"new_posts":{"type":"integer"},"replies_claimed":{"type":"integer"},"replies_posted":{"type":"integer"},"engagement_drawn":{"type":"object","properties":{"likes":{"type":"integer"},"replies":{"type":"integer"}}},"quiet":{"type":"boolean"}},"additionalProperties":true},"new_posts":{"type":"array","items":{"type":"object","properties":{"post_id":{"type":"string"},"url":{"type":"string"},"text":{"type":"string"},"author":{"type":"string"},"platform":{"type":"string"},"discovered_at":{"type":"string"},"semantic_relevance_score":{"type":["number","null"]},"final_score":{"type":["number","null"]}},"additionalProperties":true}},"claimed_replies":{"type":"array","items":{"type":"object","properties":{"reply_id":{"type":"string"},"post_id":{"type":"string"},"reply_text":{"type":"string"},"posted_url":{"type":["string","null"]},"network":{"type":"string"},"claimed_at":{"type":"string"},"url_verified":{"type":"boolean"},"review_status":{"type":["string","null"]},"survival_status":{"type":["string","null"]},"engagement":{"type":"object","properties":{"likes":{"type":"integer"},"replies":{"type":"integer"}}}},"additionalProperties":true}},"lists_truncated_at":{"type":"integer"}},"required":["success","checked_at","summary"],"additionalProperties":true}}}},"400":{"description":"`invalid_since`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found — or not owned by the acting user (ownership mismatches are 404, not 403).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/campaigns/{campaignId}/results":{"get":{"operationId":"getCampaignResults","summary":"Spend vs. outcomes: funnel, rates, survival, engagement, credits per usable reply","description":"Read-only report from stored data (never scrapes, never spends). Funnel discovered→kept→drafted→claimed→posted→approved; `survival_rate` is null under the volume floor. Free.","tags":["Campaigns (run)"],"parameters":[{"name":"campaignId","in":"path","required":true,"description":"Campaign id — the UUID or the public `campaign_number` (CP-NNN) returned at create.","schema":{"type":"string"}},{"name":"caller_user_id","in":"query","required":false,"description":"Trusted agents only (REQUIRED for them): the ProductClank user this call acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent).","schema":{"type":"string"}}],"responses":{"200":{"description":"Results report.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"campaign":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"created_at":{"type":"string"},"status":{"type":"string"},"is_active":{"type":"boolean"},"visibility":{"type":"string","enum":["public","private"]},"relevance_threshold":{"type":"integer"},"admin_url":{"type":"string"}},"additionalProperties":true},"funnel":{"type":"object","properties":{"posts_discovered":{"type":"integer"},"posts_kept":{"type":"integer"},"posts_rejected":{"type":"integer"},"replies_drafted":{"type":"integer"},"replies_claimed":{"type":"integer"},"replies_posted":{"type":"integer"},"replies_approved":{"type":"integer"},"replies_rejected":{"type":"integer"}},"additionalProperties":true},"rates":{"type":"object","properties":{"keep_rate":{"type":["number","null"]},"claim_rate":{"type":["number","null"]},"posted_rate":{"type":["number","null"]},"approval_rate":{"type":["number","null"]},"approval_sample":{"type":"integer"}},"additionalProperties":true},"survival":{"type":"object","properties":{"checked":{"type":"integer"},"alive":{"type":"integer"},"gone":{"type":"integer"},"survival_rate":{"type":["number","null"]},"volume_floor":{"type":"integer"},"note":{"type":"string"}},"additionalProperties":true},"engagement":{"type":"object","properties":{"measured_replies":{"type":"integer"},"likes_drawn":{"type":"integer"},"replies_drawn":{"type":"integer"},"note":{"type":"string"}},"additionalProperties":true},"spend":{"type":"object","properties":{"credits_spent":{"type":"integer"},"by_operation":{"type":"object","additionalProperties":true,"description":"credits per operation_type"},"usable_replies":{"type":"integer"},"credits_per_usable_reply":{"type":["number","null"]},"credits_per_post_discovered":{"type":["number","null"]},"note":{"type":"string"}},"additionalProperties":true},"counts_truncated_at":{"type":"integer"},"generated_at":{"type":"string"}},"required":["success","funnel","spend"],"additionalProperties":true}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found — or not owned by the acting user (ownership mismatches are 404, not 403).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or daily spend cap exceeded (`rate_limit_exceeded`, `daily_spend_cap_exceeded` — resets 00:00 UTC).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/campaigns/{campaignId}/schedule":{"get":{"operationId":"getCampaignSchedule","summary":"Standing-discovery schedule, cost projection and blockers","description":"Current schedule config, projected daily credits, balance, the user's daily spend cap, hard limits, and `blockers` (reasons an enabled schedule would not fire). Free.","tags":["Campaigns (run)"],"parameters":[{"name":"campaignId","in":"path","required":true,"description":"Campaign id — the UUID or the public `campaign_number` (CP-NNN) returned at create.","schema":{"type":"string"}},{"name":"caller_user_id","in":"query","required":false,"description":"Trusted agents only (REQUIRED for them): the ProductClank user this call acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent).","schema":{"type":"string"}}],"responses":{"200":{"description":"Schedule state.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"campaign":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"platform":{"type":"string"},"is_active":{"type":"boolean"}},"additionalProperties":true},"schedule":{"type":"object","properties":{"enabled":{"type":"boolean"},"frequency_per_day":{"type":["integer","null"]},"posts_per_run":{"type":["integer","null"]},"next_run":{"type":["string","null"]},"last_run":{"type":["string","null"]}}},"projection":{"type":"object","additionalProperties":true,"description":"Projected credits per run / per day and affordability"},"credit_balance":{"type":"integer"},"daily_spend_limit_credits":{"type":["integer","null"]},"limits":{"type":"object","properties":{"max_frequency_per_day":{"type":"integer"},"max_posts_per_run":{"type":"integer"},"max_projected_daily_credits":{"type":"integer"},"note":{"type":"string"}},"additionalProperties":true},"blockers":{"type":"array","items":{"type":"string"}}},"required":["success","schedule","blockers"],"additionalProperties":true}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found — or not owned by the acting user (ownership mismatches are 404, not 403).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or daily spend cap exceeded (`rate_limit_exceeded`, `daily_spend_cap_exceeded` — resets 00:00 UTC).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"operationId":"setCampaignSchedule","summary":"Turn standing discovery on or off (authorizes unattended spend)","description":"Free to call, but enabling AUTHORIZES LATER SPEND: the hourly cron bills the owner 12 credits per post found with no human in the loop. Enabling therefore requires `confirm: true` — without it you get 400 `confirmation_required` carrying the projection to show the human. The projected daily cost is capped by the user's per-app daily spend limit (429 `daily_spend_cap_exceeded`) and by hard limits (1–4 runs/day, 1–20 posts/run). Disabling never needs confirmation.","tags":["Campaigns (run)"],"x-credits-cost":"12 credits per post found by each scheduled run (billed later by the cron)","parameters":[{"name":"campaignId","in":"path","required":true,"description":"Campaign id — the UUID or the public `campaign_number` (CP-NNN) returned at create.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"frequency_per_day":{"type":"integer","description":"Runs per day (1–4); enabling only","minimum":1,"maximum":4},"posts_per_run":{"type":"integer","description":"Posts per run (1–20); enabling only","minimum":1,"maximum":20},"confirm":{"type":"boolean","description":"Must be `true` to enable"},"caller_user_id":{"type":"string","description":"Trusted agents only (REQUIRED for them): the ProductClank user this call bills/acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent)."}},"required":["enabled"]},"example":{"enabled":true,"frequency_per_day":2,"posts_per_run":5,"confirm":true}}}},"responses":{"200":{"description":"Schedule updated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"schedule":{"type":"object","properties":{"enabled":{"type":"boolean"},"frequency_per_day":{"type":["integer","null"]},"posts_per_run":{"type":["integer","null"]},"next_run":{"type":["string","null"]},"last_run":{"type":["string","null"]}}},"projection":{"type":"object","additionalProperties":true,"description":"Present when enabling"},"credit_balance":{"type":"integer"},"daily_spend_limit_credits":{"type":["integer","null"]},"changed":{"type":"object","additionalProperties":true,"description":"Per-field { from, to }"},"blockers":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}},"required":["success","schedule"],"additionalProperties":true}}}},"400":{"description":"`invalid_request` (missing `enabled`, limits exceeded) or `confirmation_required` (enabling without `confirm: true`; carries `projection`, `credit_balance`, `limits`, `blockers`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found — or not owned by the acting user (ownership mismatches are 404, not 403).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`daily_spend_cap_exceeded` — projected daily credits exceed the user's per-app cap.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/campaigns/{campaignId}/delegates":{"post":{"operationId":"addCampaignDelegate","summary":"Give a ProductClank user web-app access to an agent-created campaign","description":"Adds `user_id` as a delegator so the campaign appears in their My Campaigns. Only for campaigns created by THIS agent (403 otherwise — this route pushes access outward). Idempotent. Free.","tags":["Campaigns (run)","Delegation"],"parameters":[{"name":"campaignId","in":"path","required":true,"description":"Campaign id — the UUID or the public `campaign_number` (CP-NNN) returned at create.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string","description":"ProductClank User.id"},"caller_user_id":{"type":"string","description":"Trusted agents only (REQUIRED for them): the ProductClank user this call bills/acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent)."}},"required":["user_id"]}}}},"responses":{"200":{"description":"Delegate added (or already present).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"message":{"type":"string"},"delegator":{"type":"object","properties":{"user_id":{"type":"string"},"campaign_id":{"type":"string"}}},"already_delegator":{"type":"boolean"}},"required":["success"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found — or not owned by the acting user (ownership mismatches are 404, not 403).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/campaigns/boost":{"post":{"operationId":"boostPost","summary":"Boost one social post with real community engagement","description":"Creates a boost campaign for a single post URL on X/Twitter, Instagram, TikTok, LinkedIn, Reddit, Farcaster or YouTube (GitHub is rejected). `replies` (200 credits, 10 AI-drafted replies posted by real people) and `quote` (200 credits, 10 quote posts, X only) generate text; `likes` (300 credits, 30) and `repost` (300 credits, 10) create task slots. Every call creates its OWN campaign. Charged flat after creation succeeds; `item_count` can request fewer items but does not lower the price. `defer_generation: true` returns immediately with `generation: \"processing\"` and drafts in the background (optional `callback_url` is POSTed the result). Capped at the agent's daily campaign limit.","tags":["Campaigns (run)"],"x-credits-cost":"200 (replies / quote) or 300 (likes / repost) credits flat per boost","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"post_url":{"type":"string","description":"URL of the post to boost (required unless the deprecated `tweet_url` is sent)"},"action_type":{"type":"string","enum":["replies","likes","repost","quote"],"description":"Unsupported on the platform → falls back to `replies`","default":"replies"},"product_id":{"type":"string","description":"Optional product — steers the AI voice and links the product"},"reply_guidelines":{"type":"string","description":"Overrides the auto-built guidelines (replies / quote)"},"post_text":{"type":"string","description":"Skip the server-side fetch and use this text"},"post_author":{"type":"string","description":"Author handle when `post_text` is given"},"defer_generation":{"type":"boolean","description":"replies / quote only: return before drafting","default":false},"callback_url":{"type":"string","description":"HTTPS URL POSTed once deferred generation completes (one best-effort attempt)"},"item_count":{"type":"integer","description":"Request fewer items than the action default (price unchanged)","minimum":1},"caller_user_id":{"type":"string","description":"Trusted agents only (REQUIRED for them): the ProductClank user this call bills/acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent)."},"tweet_url":{"type":"string","description":"Deprecated alias of `post_url`","deprecated":true},"tweet_text":{"type":"string","description":"Deprecated alias of `post_text`","deprecated":true},"tweet_author":{"type":"string","description":"Deprecated alias of `post_author`","deprecated":true}},"required":["post_url"]},"example":{"post_url":"https://x.com/acme/status/1234567890","action_type":"replies","reply_guidelines":"Congratulate the launch and ask one real question."}}}},"responses":{"200":{"description":"Boost created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"campaign":{"type":"object","properties":{"id":{"type":"string"},"campaign_number":{"type":"string"},"platform":{"type":"string"},"action_type":{"type":"string"},"is_reboost":{"type":"boolean"},"url":{"type":"string"},"admin_url":{"type":"string"}},"additionalProperties":true},"post":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"text":{"type":"string","description":"First 100 chars"},"author":{"type":["string","null"]},"platform":{"type":"string"}},"additionalProperties":true},"tweet":{"type":"object","additionalProperties":true,"description":"Deprecated duplicate of `post`"},"items_generated":{"type":"integer"},"items_expected":{"type":"integer"},"generation":{"type":"string","enum":["complete","processing"]},"credits":{"type":"object","properties":{"credits_used":{"type":"integer"},"credits_remaining":{"type":"integer"},"billing_user_id":{"type":"string"}}}},"required":["success","campaign","post","generation","credits"],"additionalProperties":true}}}},"400":{"description":"`validation_error` — missing post_url, unsupported platform URL, GitHub URL, or unparseable post id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`insufficient_credits` with credits_required / credits_available / shortfall / topup_options.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_id` not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or daily spend cap exceeded (`rate_limit_exceeded`, `daily_spend_cap_exceeded` — resets 00:00 UTC).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`creation_failed` or `internal_error`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`post_fetch_failed` — could not read the post text; send `post_text`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/campaigns/content":{"post":{"operationId":"createContentCampaign","summary":"Launch a content campaign (real creators produce original content)","description":"Creates a community content campaign for a product: creators produce posts/videos about it, the owner reviews submissions in the web app, and rewards ship on approval. 1000 credits flat, charged after creation. `dry_run: true` returns a free AI-composed proposal (title, description, CTA) with affordability — no row, no charge. `space_id` runs it INSIDE a community space you own or may create campaigns in (auto-lists the product there); omitting it means PUBLIC reach — the response echoes `reach` so you can assert. Capped at the agent's daily campaign limit.","tags":["Campaigns (run)"],"x-credits-cost":"1000 credits flat per campaign (dry_run is free)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"product_id":{"type":"string"},"campaign_message":{"type":"string","description":"The brief — what creators should make and why"},"campaign_goals":{"type":"array","items":{"type":"string"}},"target_audience":{"type":["string","null"]},"preferred_platform":{"type":["string","null"]},"additional_guidelines":{"type":["string","null"]},"references":{"type":["string","null"],"description":"Example posts / links"},"dry_run":{"type":"boolean","description":"Preview only, free","default":false},"space_id":{"type":["string","null"],"description":"Run inside this community space instead of the public network"},"caller_user_id":{"type":"string","description":"Trusted agents only (REQUIRED for them): the ProductClank user this call bills/acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent)."}},"required":["product_id","campaign_message"]},"example":{"product_id":"00000000-0000-0000-0000-000000000000","campaign_message":"Show how you use Acme to ship faster. Short video or thread.","dry_run":true}}}},"responses":{"200":{"description":"Either a dry-run proposal or the created campaign.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"success":{"type":"boolean","const":true},"dry_run":{"type":"boolean","const":true},"proposal":{"type":"object","additionalProperties":true,"description":"AI-composed title / description / CTA"},"product":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"credits_required":{"type":"integer"},"credits_available":{"type":"integer"},"can_afford":{"type":"boolean"},"next_step":{"type":"object","properties":{"action":{"type":"string"},"endpoint":{"type":"string"},"description":{"type":"string"}},"additionalProperties":true}},"required":["success","dry_run","proposal"],"additionalProperties":true},{"type":"object","properties":{"success":{"type":"boolean","const":true},"campaign":{"type":"object","properties":{"id":{"type":"string"},"campaign_number":{"type":"integer"},"title":{"type":"string"},"product_id":{"type":"string"},"campaign_type":{"type":"string"},"status":{"type":"string","description":"`processing` — the brief generates and auto-activates in ~2–5 min"},"public_url":{"type":"string"},"admin_url":{"type":"string"},"reach":{"type":"string","enum":["community","public"]},"space_id":{"type":["string","null"]}},"additionalProperties":true},"credits":{"type":"object","properties":{"credits_used":{"type":"integer"},"credits_remaining":{"type":"integer"},"billing_user_id":{"type":"string"}}},"next_step":{"type":"object","properties":{"action":{"type":"string"},"endpoint":{"type":"string"},"description":{"type":"string"}},"additionalProperties":true}},"required":["success","campaign","credits"],"additionalProperties":true}]}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required / payment invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found — or not owned by the acting user (ownership mismatches are 404, not 403).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or daily spend cap exceeded (`rate_limit_exceeded`, `daily_spend_cap_exceeded` — resets 00:00 UTC).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/campaigns/content/{campaignId}":{"get":{"operationId":"getContentCampaignResults","summary":"Content-campaign results: lifecycle state, submissions, winners","description":"Derived lifecycle state, submission counts by status, the submissions themselves (proof URL, creator, review state, points) and winners. Accepts a UUID or a numeric campaign number. Owned = created by this agent or by the acting user. Free, paginated.","tags":["Campaigns (run)"],"parameters":[{"name":"campaignId","in":"path","required":true,"description":"Campaign UUID or numeric `campaign_number`","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter submissions","schema":{"type":"string","enum":["pending","approved","rejected"]}},{"name":"limit","in":"query","required":false,"description":"Page size","schema":{"type":"integer","default":50,"maximum":100}},{"name":"offset","in":"query","required":false,"description":"Page offset","schema":{"type":"integer","default":0}},{"name":"caller_user_id","in":"query","required":false,"description":"Trusted agents only (REQUIRED for them): the ProductClank user this call acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent).","schema":{"type":"string"}}],"responses":{"200":{"description":"Results.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"campaign":{"type":"object","properties":{"id":{"type":"string"},"campaign_number":{"type":"integer"},"title":{"type":"string"},"description":{"type":["string","null"]},"product_id":{"type":["string","null"]},"state":{"type":"string","description":"Derived lifecycle state"},"state_label":{"type":"string"},"is_accepting_submissions":{"type":"boolean"},"raw_status":{"type":"string"},"start_date":{"type":["string","null"]},"end_date":{"type":["string","null"]},"created_at":{"type":"string"},"reward_type":{"type":["string","null"]},"winners_count":{"type":"integer"},"participants_count":{"type":"integer"},"visibility":{"type":"string"},"space_id":{"type":["string","null"]},"public_url":{"type":"string"}},"additionalProperties":true},"counts":{"type":"object","properties":{"total":{"type":"integer"},"pending":{"type":"integer"},"approved":{"type":"integer"},"rejected":{"type":"integer"}}},"submissions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"post_url":{"type":["string","null"]},"image_url":{"type":["string","null"]},"description":{"type":["string","null"]},"submission_type":{"type":"string"},"status":{"type":"string"},"review_notes":{"type":["string","null"]},"reviewed_at":{"type":["string","null"]},"points_allocated":{"type":["integer","null"]},"points_awarded_at":{"type":["string","null"]},"created_at":{"type":"string"},"creator":{"type":"object","properties":{"user_id":{"type":"string"},"name":{"type":["string","null"]},"avatar":{"type":["string","null"]},"x_username":{"type":["string","null"]}},"additionalProperties":true}},"additionalProperties":true}},"winners":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"user_id":{"type":"string"},"submission_id":{"type":["string","null"]},"winner_type":{"type":"string"},"reward_amount":{"type":["number","null"]},"tx_hash":{"type":["string","null"]},"distributed_at":{"type":["string","null"]}},"additionalProperties":true}},"pagination":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"returned":{"type":"integer"},"total_matching":{"type":"integer"},"has_more":{"type":"boolean"}}}},"required":["success","campaign","counts","submissions"],"additionalProperties":true}}}},"400":{"description":"`campaignId` is neither a UUID nor a campaign number.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Campaign belongs to neither this agent nor the acting user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found — or not owned by the acting user (ownership mismatches are 404, not 403).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/content/spaces":{"get":{"operationId":"listContentSpaces","summary":"Content-enabled spaces the acting user may write into","description":"Spaces the user owns, delegates for, or manages campaigns in that have a Content workspace. Free.","tags":["Content Studio"],"parameters":[{"name":"caller_user_id","in":"query","required":false,"description":"Trusted agents only (REQUIRED for them): the ProductClank user this call acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent).","schema":{"type":"string"}}],"responses":{"200":{"description":"Spaces.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"spaces":{"type":"array","items":{"type":"object","properties":{"space_id":{"type":"string"},"name":{"type":"string"}}}}},"required":["success","spaces"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or daily spend cap exceeded (`rate_limit_exceeded`, `daily_spend_cap_exceeded` — resets 00:00 UTC).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/content/workspace":{"get":{"operationId":"getContentWorkspace","summary":"The brand's full calibration (voice, platforms, topics, style guides)","description":"Returns the workspace, topic inventory and per-channel style guides. When the space has no workspace yet, returns `enabled: false` plus a `setup_hint` instead of 404. Free.","tags":["Content Studio"],"parameters":[{"name":"space_id","in":"query","required":true,"description":"Content space id (see `GET /content/spaces`)","schema":{"type":"string"}},{"name":"caller_user_id","in":"query","required":false,"description":"Trusted agents only (REQUIRED for them): the ProductClank user this call acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent).","schema":{"type":"string"}}],"responses":{"200":{"description":"Workspace (or `enabled: false`).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"space_id":{"type":"string"},"space_name":{"type":"string"},"enabled":{"type":"boolean"},"workspace":{"oneOf":[{"type":"object","properties":{"brand_name":{"type":["string","null"]},"platforms":{"type":"array","items":{"type":"string"}},"voice":{"type":["string","null"]},"post_types":{"type":["string","null"]},"platform_playbook":{"type":["string","null"]},"review_threshold":{"type":"integer"},"automation_paused":{"type":"boolean"},"trending_source_handles":{"type":"array","items":{"type":"string"}},"onboarding_completed_at":{"type":["string","null"]}},"additionalProperties":true},{"type":"null"}]},"topics":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"search_context":{"type":["string","null"]},"source_handles":{"type":"array","items":{"type":"string"}},"seed_urls":{"type":"array","items":{"type":"string"}},"is_active":{"type":"boolean"},"last_run_at":{"type":["string","null"]}},"additionalProperties":true}},"style_guides":{"type":"array","items":{"type":"object","properties":{"channel":{"type":"string"},"voice_summary":{"type":["string","null"]},"tone_attributes":{"type":"array","items":{"type":"string"}},"dos":{"type":"array","items":{"type":"string"}},"donts":{"type":"array","items":{"type":"string"}},"structure":{"type":["string","null"]},"lexicon":{"type":["string","null"]},"example_openers":{"type":"array","items":{"type":"string"}},"updated_at":{"type":["string","null"]}},"additionalProperties":true}},"review_url":{"type":"string"},"setup_hint":{"type":"string"}},"required":["success","space_id","enabled"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`not_found` (space not accessible) or `content_not_enabled` (no workspace yet — set one up via `POST /content/workspace`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"operationId":"setupContentWorkspace","summary":"Set up or update the content engine for a space","description":"Creates or updates the ContentWorkspace from an onboarding conversation. Target an existing `space_id` OR `new_space: { name }` (creates a solo space owned by the caller; idempotent on name). Structured fields are free; `brand_doc` (≥40 chars of pasted brand material) is structured by AI into voice/KB/platforms and seeds topics for 5 credits. First-time setup requires `voice` (or a brand_doc); `platforms` defaults to [\"X\"]. Up to 12 topics per call. Nothing is published.","tags":["Content Studio"],"x-credits-cost":"5 credits only when `brand_doc` is provided","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"space_id":{"type":"string","description":"Existing space — required unless `new_space` is given"},"new_space":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"}},"required":["name"]},"brand_name":{"type":"string"},"platforms":{"type":"array","items":{"type":"string"},"description":"e.g. [\"X\", \"LinkedIn\"]"},"voice":{"type":"string","description":"Voice / humanizer guidance — required on first setup unless brand_doc"},"post_types":{"type":"string","description":"Post templates guidance"},"platform_playbook":{"type":"string"},"brand_doc":{"type":"string","description":"Free-form brand material (≥40 chars) — billed"},"review_threshold":{"type":"integer","description":"0–100","minimum":0,"maximum":100},"trending_source_handles":{"type":"array","items":{"type":"string"},"description":"X handles to watch for trends"},"topics":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"},"description":"Auto-suggested when omitted"},"search_context":{"type":"string"},"source_handles":{"type":"array","items":{"type":"string"},"description":"Pinned X accounts (else auto-extracted from search_context)"},"seed_urls":{"type":"array","items":{"type":"string"},"description":"Anchor posts / articles (else auto-extracted)"}},"required":["label"]},"description":"Up to 12 per call","maxItems":12},"caller_user_id":{"type":"string","description":"Trusted agents only (REQUIRED for them): the ProductClank user this call bills/acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent)."}}},"example":{"new_space":{"name":"Acme"},"brand_name":"Acme","platforms":["X"],"voice":"Plain, direct, first person. No hype.","topics":[{"label":"Shipping analytics for indie SaaS"}]}}}},"responses":{"200":{"description":"Workspace ready.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"created_space":{"type":"boolean"},"created_workspace":{"type":"boolean"},"topics_created":{"type":"integer"},"space_id":{"type":"string"},"space_name":{"type":"string"},"enabled":{"type":"boolean"},"workspace":{"type":"object","properties":{"brand_name":{"type":["string","null"]},"platforms":{"type":"array","items":{"type":"string"}},"voice":{"type":["string","null"]},"post_types":{"type":["string","null"]},"platform_playbook":{"type":["string","null"]},"review_threshold":{"type":"integer"},"automation_paused":{"type":"boolean"},"trending_source_handles":{"type":"array","items":{"type":"string"}},"onboarding_completed_at":{"type":["string","null"]}},"additionalProperties":true},"topics":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"search_context":{"type":["string","null"]},"source_handles":{"type":"array","items":{"type":"string"}},"seed_urls":{"type":"array","items":{"type":"string"}},"is_active":{"type":"boolean"},"last_run_at":{"type":["string","null"]}},"additionalProperties":true}},"style_guides":{"type":"array","items":{"type":"object","properties":{"channel":{"type":"string"},"voice_summary":{"type":["string","null"]},"tone_attributes":{"type":"array","items":{"type":"string"}},"dos":{"type":"array","items":{"type":"string"}},"donts":{"type":"array","items":{"type":"string"}},"structure":{"type":["string","null"]},"lexicon":{"type":["string","null"]},"example_openers":{"type":"array","items":{"type":"string"}},"updated_at":{"type":["string","null"]}},"additionalProperties":true}},"review_url":{"type":"string"},"next_step":{"type":"string"}},"required":["success","space_id","workspace"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required / payment invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`not_found` (space not accessible) or `content_not_enabled` (no workspace yet — set one up via `POST /content/workspace`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/content/candidates":{"post":{"operationId":"writeContentCandidates","summary":"Write 1–25 draft candidates into a space (free, auto-reviewed, never published)","description":"Inserts drafts exactly like the human paste door, then scores them in the background when auto-review is on. `platform` must be one of the workspace's platforms (case-insensitive; omitted → the first one; unknown → 400 `unknown_platform` listing the valid ones). Free.","tags":["Content Studio"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"space_id":{"type":"string","description":"Content space id"},"candidates":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"title":{"type":"string","description":"Stored as the topic label"},"platform":{"type":"string"},"template":{"type":"string","default":"Build-in-Public"}},"required":["text"]},"description":"1–25 candidates","minItems":1,"maxItems":25},"caller_user_id":{"type":"string","description":"Trusted agents only (REQUIRED for them): the ProductClank user this call bills/acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent)."}},"required":["space_id","candidates"]},"example":{"space_id":"space-uuid","candidates":[{"text":"We cut our onboarding from 9 steps to 3. Here is what we removed.","platform":"X"}]}}}},"responses":{"200":{"description":"Drafts created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"created":{"type":"integer"},"draft_ids":{"type":"array","items":{"type":"string"}},"space_id":{"type":"string"},"review_url":{"type":"string"},"auto_review":{"type":"boolean"},"next_step":{"type":"string"}},"required":["success","created","draft_ids"],"additionalProperties":true}}}},"400":{"description":"`validation_error`, `too_many_candidates` (>25), or `unknown_platform` (carries `platforms`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Space not accessible, or Content not enabled for it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/content/queue":{"get":{"operationId":"getContentQueue","summary":"The space's drafts with review score, verdict and fix suggestion","description":"`status=active` (default) = draft + reviewed + staged; `pending` = unscored drafts; `staged` = user-approved awaiting publish (publishing is not exposed to agents). Free.","tags":["Content Studio"],"parameters":[{"name":"space_id","in":"query","required":true,"description":"Content space id (see `GET /content/spaces`)","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Queue view","schema":{"type":"string","enum":["active","pending","reviewed","staged","discarded"],"default":"active"}},{"name":"limit","in":"query","required":false,"description":"Max drafts","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"caller_user_id","in":"query","required":false,"description":"Trusted agents only (REQUIRED for them): the ProductClank user this call acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent).","schema":{"type":"string"}}],"responses":{"200":{"description":"Queue.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"space_id":{"type":"string"},"status":{"type":"string"},"review_threshold":{"type":"integer"},"counts":{"type":"object","properties":{"pending":{"type":"integer"},"reviewed":{"type":"integer"},"staged":{"type":"integer"},"discarded":{"type":"integer"}}},"drafts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":["string","null"]},"platform":{"type":"string"},"template":{"type":["string","null"]},"text":{"type":"string"},"status":{"type":"string","enum":["draft","reviewed","staged","discarded"]},"source":{"type":"string"},"review":{"type":"object","properties":{"score":{"type":["number","null"]},"verdict":{"type":["string","null"]},"summary":{"type":["string","null"]},"notes":{"type":["string","null"]}}},"starred":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string"}},"planned_at":{"type":["string","null"]},"created_at":{"type":"string"}},"additionalProperties":true}},"review_url":{"type":"string"},"note":{"type":"string"}},"required":["success","drafts","counts"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`not_found` (space not accessible) or `content_not_enabled` (no workspace yet — set one up via `POST /content/workspace`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/content/drafts":{"patch":{"operationId":"updateContentDraft","summary":"Act on one draft: edit, revise, fix, humanize, review, stage, discard, plan","description":"One action per call. `edit` (free, needs `text`), `revise` (2 credits; `preset` and/or `instruction`), `fix` (2), `humanize` (2), `review` (2 — re-scores against the brand KB), `stage` (free, marks approved), `discard` (free), `plan` (free; `planned_at` ISO date or null — a calendar plan, not a schedule). Any text-changing action clears the previous score; re-run `review` to re-score. Never publishes.","tags":["Content Studio"],"x-credits-cost":"2 credits for revise / fix / humanize; 2 for review; edit / stage / discard / plan are free","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"space_id":{"type":"string","description":"Content space id"},"draft_id":{"type":"string"},"action":{"type":"string","enum":["edit","revise","fix","humanize","review","stage","discard","plan"]},"text":{"type":"string","description":"Required for `edit`"},"instruction":{"type":"string","description":"Optional steer for revise / fix / humanize"},"preset":{"type":"string","enum":["shorter","longer","punchier","deeper","simpler","more_specific","less_salesy","more_casual","more_formal"],"description":"`revise` preset (combine with `instruction` or use alone)"},"planned_at":{"type":["string","null"],"description":"`plan` only: ISO date/datetime, or null to unplan"},"caller_user_id":{"type":"string","description":"Trusted agents only (REQUIRED for them): the ProductClank user this call bills/acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent)."}},"required":["space_id","draft_id","action"]},"example":{"space_id":"space-uuid","draft_id":"draft-uuid","action":"revise","preset":"punchier"}}}},"responses":{"200":{"description":"Updated draft.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"action":{"type":"string"},"credits_charged":{"type":"integer"},"draft":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":["string","null"]},"platform":{"type":"string"},"template":{"type":["string","null"]},"text":{"type":"string"},"status":{"type":"string","enum":["draft","reviewed","staged","discarded"]},"source":{"type":"string"},"review":{"type":"object","properties":{"score":{"type":["number","null"]},"verdict":{"type":["string","null"]},"summary":{"type":["string","null"]},"notes":{"type":["string","null"]}}},"starred":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string"}},"planned_at":{"type":["string","null"]},"created_at":{"type":"string"}},"additionalProperties":true},"review_url":{"type":"string"},"note":{"type":"string"}},"required":["success","action","credits_charged","draft"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required / payment invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`not_found` (space not accessible) or `content_not_enabled` (no workspace yet — set one up via `POST /content/workspace`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/content/topics":{"get":{"operationId":"listContentTopics","summary":"Topic inventory for a space","description":"Free.","tags":["Content Studio"],"parameters":[{"name":"space_id","in":"query","required":true,"description":"Content space id (see `GET /content/spaces`)","schema":{"type":"string"}},{"name":"caller_user_id","in":"query","required":false,"description":"Trusted agents only (REQUIRED for them): the ProductClank user this call acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent).","schema":{"type":"string"}}],"responses":{"200":{"description":"Topics.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"space_id":{"type":"string"},"topics":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"search_context":{"type":["string","null"]},"source_handles":{"type":"array","items":{"type":"string"}},"seed_urls":{"type":"array","items":{"type":"string"}},"is_active":{"type":"boolean"},"last_run_at":{"type":["string","null"]}},"additionalProperties":true}}},"required":["success","topics"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`not_found` (space not accessible) or `content_not_enabled` (no workspace yet — set one up via `POST /content/workspace`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"operationId":"createContentTopics","summary":"Add up to 12 topics (keywords auto-suggested when omitted)","description":"New topics default to manual cadence and active. Handles and URLs in `search_context` are auto-extracted unless `source_handles` / `seed_urls` are given explicitly. Free.","tags":["Content Studio"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"space_id":{"type":"string","description":"Content space id"},"topics":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"},"description":"Auto-suggested when omitted"},"search_context":{"type":"string"},"source_handles":{"type":"array","items":{"type":"string"},"description":"Pinned X accounts (else auto-extracted from search_context)"},"seed_urls":{"type":"array","items":{"type":"string"},"description":"Anchor posts / articles (else auto-extracted)"}},"required":["label"]},"description":"1–12 topics","minItems":1,"maxItems":12},"caller_user_id":{"type":"string","description":"Trusted agents only (REQUIRED for them): the ProductClank user this call bills/acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent)."}},"required":["space_id","topics"]},"example":{"space_id":"space-uuid","topics":[{"label":"Pricing experiments","keywords":["saas pricing","usage-based"]}]}}}},"responses":{"200":{"description":"Created topics.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"space_id":{"type":"string"},"created":{"type":"integer"},"topics":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"search_context":{"type":["string","null"]},"source_handles":{"type":"array","items":{"type":"string"}},"seed_urls":{"type":"array","items":{"type":"string"}},"is_active":{"type":"boolean"},"last_run_at":{"type":["string","null"]}},"additionalProperties":true}}},"required":["success","created","topics"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`not_found` (space not accessible) or `content_not_enabled` (no workspace yet — set one up via `POST /content/workspace`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"operationId":"updateContentTopic","summary":"Update one topic","description":"Explicit `source_handles` / `seed_urls` win; when only `search_context` changes, sources are re-extracted from it. Free.","tags":["Content Studio"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"space_id":{"type":"string","description":"Content space id"},"topic_id":{"type":"string"},"label":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"search_context":{"type":"string"},"is_active":{"type":"boolean"},"source_handles":{"type":"array","items":{"type":"string"}},"seed_urls":{"type":"array","items":{"type":"string"}},"caller_user_id":{"type":"string","description":"Trusted agents only (REQUIRED for them): the ProductClank user this call bills/acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent)."}},"required":["space_id","topic_id"]}}}},"responses":{"200":{"description":"Updated topic.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"topic":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"search_context":{"type":["string","null"]},"source_handles":{"type":"array","items":{"type":"string"}},"seed_urls":{"type":"array","items":{"type":"string"}},"is_active":{"type":"boolean"},"last_run_at":{"type":["string","null"]}},"additionalProperties":true}},"required":["success","topic"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`not_found` (space not accessible) or `content_not_enabled` (no workspace yet — set one up via `POST /content/workspace`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"operationId":"deleteContentTopic","summary":"Delete a topic (its past drafts are kept)","description":"Free.","tags":["Content Studio"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"space_id":{"type":"string","description":"Content space id"},"topic_id":{"type":"string"},"caller_user_id":{"type":"string","description":"Trusted agents only (REQUIRED for them): the ProductClank user this call bills/acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent)."}},"required":["space_id","topic_id"]}}}},"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"deleted":{"type":"string","description":"The topic id"}},"required":["success","deleted"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`not_found` (space not accessible) or `content_not_enabled` (no workspace yet — set one up via `POST /content/workspace`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/content/topics/suggest":{"post":{"operationId":"suggestContentTopics","summary":"KB-grounded topic ideas that avoid existing topics","description":"Brainstorms new topics from the brand KB; add the ones you want via `POST /content/topics`. Free.","tags":["Content Studio"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"space_id":{"type":"string","description":"Content space id"},"caller_user_id":{"type":"string","description":"Trusted agents only (REQUIRED for them): the ProductClank user this call bills/acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent)."}},"required":["space_id"]}}}},"responses":{"200":{"description":"Suggestions.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"space_id":{"type":"string"},"suggestions":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"title / angle / why"}},"next_step":{"type":"string"}},"required":["success","suggestions"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`not_found` (space not accessible) or `content_not_enabled` (no workspace yet — set one up via `POST /content/workspace`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/content/feedback":{"post":{"operationId":"submitContentFeedback","summary":"Turn feedback into a durable brand-KB rule","description":"Proposes a KB rule from `feedback` (optionally grounded in `draft_id`) for 1 credit; with `apply: true` (default) the rule is applied immediately to all future drafts and reviews, otherwise it waits for approval in web Settings. This is the learning door — `PATCH /content/drafts` `revise` only changes one draft.","tags":["Content Studio"],"x-credits-cost":"1 credits per call","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"space_id":{"type":"string","description":"Content space id"},"feedback":{"type":"string","description":"The reaction or rule to learn"},"draft_id":{"type":"string","description":"Grounds the rule in an example draft"},"apply":{"type":"boolean","default":true},"caller_user_id":{"type":"string","description":"Trusted agents only (REQUIRED for them): the ProductClank user this call bills/acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent)."}},"required":["space_id","feedback"]},"example":{"space_id":"space-uuid","feedback":"Never open with a rhetorical question.","apply":true}}}},"responses":{"200":{"description":"Rule proposed (and applied when `applied: true`).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"applied":{"type":"boolean"},"rule":{"type":"object","properties":{"id":{"type":"string"},"section":{"type":"string"},"markdown":{"type":"string"},"rationale":{"type":"string"},"status":{"type":"string"}},"additionalProperties":true},"next_step":{"type":"string"}},"required":["success","applied","rule"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required / payment invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`not_found` (space not accessible) or `content_not_enabled` (no workspace yet — set one up via `POST /content/workspace`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/participate/feed":{"get":{"operationId":"getParticipationFeed","summary":"Unclaimed reply/quote drafts you can post from your own account","description":"Public-network posts with at least one unclaimed draft the agent can complete — only `reply` and `quote` (likes/reposts need a screenshot, which agents cannot upload; `actionType=like|repost` → 400 `action_type_unavailable`). `total` counts posts with any unclaimed draft; `matching` is the count after the action filter. Free.","tags":["Participation (earn)"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size","schema":{"type":"integer","default":25,"maximum":100}},{"name":"offset","in":"query","required":false,"description":"Page offset","schema":{"type":"integer","default":0}},{"name":"campaignId","in":"query","required":false,"description":"Restrict to one campaign","schema":{"type":"string"}},{"name":"actionType","in":"query","required":false,"description":"Draft type","schema":{"type":"string","enum":["reply","quote"]}}],"responses":{"200":{"description":"Feed page (camelCase item fields).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"posts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"campaignId":{"type":"string"},"campaign":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"campaignNumber":{"type":"string"},"title":{"type":"string"},"productId":{"type":["string","null"]}},"additionalProperties":true},{"type":"null"}]},"platform":{"type":"string"},"tweetId":{"type":"string"},"tweetUrl":{"type":"string"},"tweetText":{"type":"string"},"tweetCreatedAt":{"type":["string","null"]},"author":{"type":"object","properties":{"username":{"type":"string"},"displayName":{"type":["string","null"]},"followerCount":{"type":"integer"},"verified":{"type":"boolean"}},"additionalProperties":true},"unclaimedReplies":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Pass as `replyId` to /participate/submit"},"replyText":{"type":"string"},"actionType":{"type":"string","enum":["reply","quote"]}}}}},"additionalProperties":true}},"matching":{"type":"integer"},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"completable_action_types":{"type":"array","items":{"type":"string"}}},"required":["success","posts","total"],"additionalProperties":true}}}},"400":{"description":"`action_type_unavailable`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/participate/submit":{"post":{"operationId":"submitParticipation","summary":"Claim a draft and submit the URL of your posted reply/quote","description":"Same core as the human submit flow: claims `replyId` and records `replyUrl` (X, Reddit, YouTube, LinkedIn). The earning user needs a linked handle on that network (`x_handle_required` etc.); X replies are author-matched, quotes are verified to quote the source. Awards 20 points on public campaigns (plus campaign credits when configured). $PRO is claimed separately via `claim-signature`. Capped at the agent's daily submission limit. Free.","tags":["Participation (earn)"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"replyId":{"type":"string","description":"Draft id from the feed"},"replyUrl":{"type":"string","description":"URL of the reply/quote you posted"},"screenshotHash":{"type":["string","null"],"description":"Optional proof hash"},"caller_user_id":{"type":"string","description":"Trusted agents only (REQUIRED for them): the ProductClank user this call bills/acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent)."}},"required":["replyId","replyUrl"]},"example":{"replyId":"reply-uuid","replyUrl":"https://x.com/me/status/1234567890"}}}},"responses":{"200":{"description":"Submitted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"message":{"type":"string"},"replyId":{"type":"string"},"pointsAwarded":{"type":"integer"},"creditsAwarded":{"type":"integer"},"billing_user_id":{"type":"string"},"next_step":{"type":"object","properties":{"action":{"type":"string"},"endpoint":{"type":"string"},"description":{"type":"string"}},"additionalProperties":true}},"required":["success","replyId","pointsAwarded"],"additionalProperties":true}}}},"400":{"description":"`validation_error`, `already_claimed`, `claim_limit`, `duplicate_proof`, `action_type_unavailable`, `<network>_handle_required`, `tweet_unreachable`, `tweet_author_mismatch`, `quote_*` verification codes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Private post/campaign you are not a member of, or delegation not authorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Reply not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`reserved_by_other`, `campaign_paused`, `task_paused`, `subreddit_daily_cap`, or a claim race.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or daily spend cap exceeded (`rate_limit_exceeded`, `daily_spend_cap_exceeded` — resets 00:00 UTC).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/participate/earnings":{"get":{"operationId":"getEarnings","summary":"Points, credits, reply counts, strikes and $PRO claim status","description":"For the acting user. Free.","tags":["Participation (earn)"],"parameters":[{"name":"caller_user_id","in":"query","required":false,"description":"Trusted agents only (REQUIRED for them): the ProductClank user this call acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent).","schema":{"type":"string"}}],"responses":{"200":{"description":"Earnings.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"userId":{"type":"string"},"points":{"type":"integer"},"credits":{"type":"integer"},"replies":{"type":"object","properties":{"submitted":{"type":"integer"},"approved":{"type":"integer"},"rejected":{"type":"integer"},"strikes":{"type":"integer","description":"3 strikes = blocked"}}},"proClaim":{"type":"object","properties":{"enabled":{"type":"boolean"},"amountPerClaim":{"type":["number","null"]},"maxClaimsPerDay":{"type":"integer"},"walletConnected":{"type":"boolean"},"claimedCount":{"type":"integer"},"claimableCount":{"type":"integer"},"totalClaimed":{"type":"number"}},"additionalProperties":true}},"required":["success","points","replies"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/participate/claim-signature":{"post":{"operationId":"getProClaimSignature","summary":"EIP-712 signature to claim $PRO on-chain for one accepted reply","description":"Pays the AGENT's own registered `wallet_address` (not a delegated user). Requires an `erc8004_agent_id`, rewards enabled, allowlist (unless open claims), an unclaimed accepted reply submitted by this agent, and the daily claim cap. Submit the returned data to the claim contract on Base, then call `record-claim`.","tags":["Participation (earn)"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"replyId":{"type":"string"}},"required":["replyId"]}}}},"responses":{"200":{"description":"Signed claim.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"replyId":{"type":"string"},"signature":{"type":"string"},"claimData":{"type":"object","additionalProperties":true,"description":"Typed claim payload for the contract call"},"contractAddress":{"type":"string"},"chainId":{"type":"integer"},"network":{"type":"string"},"tokenDecimals":{"type":"integer"},"amountInWei":{"type":"string"},"recipient":{"type":"string"},"expiresAt":{"type":"string"},"next_step":{"type":"object","properties":{"action":{"type":"string"},"endpoint":{"type":"string"},"description":{"type":"string"}},"additionalProperties":true}},"required":["success","signature","claimData","contractAddress"],"additionalProperties":true}}}},"400":{"description":"`rewards_disabled`, `not_eligible` (reply not claimed / rejected), `not_verified`, missing wallet, or `validation_error`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`not_eligible` (no erc8004_agent_id) or `not_allowlisted`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Reply not found for this agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`already_claimed` (DB or on-chain).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`daily_cap_reached`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/participate/record-claim":{"post":{"operationId":"recordProClaim","summary":"Record the on-chain $PRO claim transaction (idempotent)","description":"Bookkeeping only — marks the reply's reward as claimed with `txHash`. Safe to retry. Does not verify the transaction on-chain.","tags":["Participation (earn)"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"replyId":{"type":"string"},"txHash":{"type":"string","description":"0x + 64 hex","pattern":"^0x[0-9a-fA-F]{64}$"}},"required":["replyId","txHash"]}}}},"responses":{"200":{"description":"Recorded (or already recorded).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"message":{"type":"string"},"replyId":{"type":"string"},"txHash":{"type":"string"}},"required":["success","replyId","txHash"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Reply not found for this agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/participate/campaigns":{"get":{"operationId":"listParticipationCampaigns","summary":"Joinable content / take-action campaigns","description":"Active public campaigns plus community campaigns from spaces the acting user belongs to, filtered to those accepting submissions. Free.","tags":["Participation (earn)"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Max campaigns","schema":{"type":"integer","default":25,"maximum":100}},{"name":"kind","in":"query","required":false,"description":"Filter by kind","schema":{"type":"string","enum":["content","take_action"]}},{"name":"caller_user_id","in":"query","required":false,"description":"Trusted agents only (REQUIRED for them): the ProductClank user this call acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent).","schema":{"type":"string"}}],"responses":{"200":{"description":"Campaigns.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"campaigns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["content","take_action"]},"is_community":{"type":"boolean"},"space_id":{"type":["string","null"]},"reward_type":{"type":["string","null"]},"reward_amount":{"type":["number","null"]},"end_date":{"type":["string","null"]},"participants_count":{"type":"integer"},"max_participants":{"type":["integer","null"]},"action_message":{"type":["string","null"]},"description":{"type":["string","null"]},"url":{"type":"string"}},"additionalProperties":true}},"total":{"type":"integer"}},"required":["success","campaigns","total"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/participate/campaigns/{campaignId}":{"get":{"operationId":"getParticipationBrief","summary":"Full participation brief for a campaign","description":"The ask, criteria, rewards, whether it is accepting submissions, and how many submissions the acting user has left. Free.","tags":["Participation (earn)"],"parameters":[{"name":"campaignId","in":"path","required":true,"description":"Campaign UUID","schema":{"type":"string"}},{"name":"caller_user_id","in":"query","required":false,"description":"Trusted agents only (REQUIRED for them): the ProductClank user this call acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent).","schema":{"type":"string"}}],"responses":{"200":{"description":"Brief.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"campaign":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["content","take_action"]},"is_community":{"type":"boolean"},"space_id":{"type":["string","null"]},"description":{"type":["string","null"]},"action_message":{"type":["string","null"]},"action_cta":{"type":["string","null"]},"action_url":{"type":["string","null"]},"content_types":{"type":"array","items":{"type":"string"}},"brief_context":{"type":["string","null"]},"brief_sections":{"type":"object","additionalProperties":true,"description":"Structured brief"},"eligibility_criteria":{"type":["string","null"]},"selection_criteria":{"type":["string","null"]},"rewards":{"type":"object","properties":{"reward_type":{"type":["string","null"]},"reward_amount":{"type":["number","null"]},"reward_token":{"type":["string","null"]},"eligible_submission_reward":{"type":["number","null"]},"top_winner_reward":{"type":["number","null"]},"top_winners_count":{"type":["integer","null"]},"reward_explanation":{"type":["string","null"]}},"additionalProperties":true},"start_date":{"type":["string","null"]},"end_date":{"type":["string","null"]},"status":{"type":"string"},"accepting_submissions":{"type":"boolean"},"participants_count":{"type":"integer"},"max_participants":{"type":["integer","null"]},"url":{"type":"string"}},"additionalProperties":true},"my_participation":{"type":"object","properties":{"submissions_used":{"type":"integer"},"submissions_allowed":{"type":"integer"}}},"next_step":{"type":"object","properties":{"action":{"type":"string"},"endpoint":{"type":"string"},"description":{"type":"string"}},"additionalProperties":true}},"required":["success","campaign","my_participation"],"additionalProperties":true}}}},"400":{"description":"`not_participatable` — not a community content / take-action campaign.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Private community campaign and the acting user is not a member.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found — or not owned by the acting user (ownership mismatches are 404, not 403).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/participate/campaigns/{campaignId}/submissions":{"post":{"operationId":"submitCampaignProof","summary":"Submit proof for a content / take-action campaign (pending owner review)","description":"Inserts a PENDING submission — rewards ship only when the campaign owner approves in the web app. At least one of `cast_url` / `description` (a `media_url` alone is promoted into `cast_url`). Links only, no uploads. X-post proofs are author-matched against the acting user's linked handle; the same `cast_url` twice on a campaign → 409 `duplicate_proof`. Per-user submission caps come from the campaign; per-agent daily cap from `rate_limit_daily`. Free.","tags":["Participation (earn)"],"parameters":[{"name":"campaignId","in":"path","required":true,"description":"Campaign UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"cast_url":{"type":"string","description":"URL of the post / content"},"media_url":{"type":"string","description":"Hosted image or video URL (rendered inline for the reviewer when it is a direct image)"},"description":{"type":"string","description":"Up to 2000 chars","maxLength":2000},"caller_user_id":{"type":"string","description":"Trusted agents only (REQUIRED for them): the ProductClank user this call bills/acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent)."}}},"example":{"cast_url":"https://x.com/me/status/1234567890","description":"Thread on how I use Acme."}}}},"responses":{"201":{"description":"Submission created (this route wraps its payload in `data`).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"submission":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"cast_url":{"type":["string","null"]},"image_url":{"type":["string","null"]},"description":{"type":["string","null"]},"created_at":{"type":"string"}},"additionalProperties":true},"message":{"type":"string"},"campaign_url":{"type":"string"},"profile_url":{"type":"string"},"next_step":{"type":"object","properties":{"action":{"type":"string"},"endpoint":{"type":"string"},"description":{"type":"string"}},"additionalProperties":true}}}},"required":["success","data"],"additionalProperties":true}}}},"400":{"description":"`validation_error`, `not_participatable`, `campaign_closed`, `campaign_full`, `x_handle_required`, `tweet_unreachable`, `post_author_mismatch`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Private community campaign and the acting user is not a member.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found — or not owned by the acting user (ownership mismatches are 404, not 403).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`duplicate_proof`, `submission_cap_reached`, or `submission_exists`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or daily spend cap exceeded (`rate_limit_exceeded`, `daily_spend_cap_exceeded` — resets 00:00 UTC).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/participate/campaigns/{campaignId}/my-submissions":{"get":{"operationId":"listMySubmissions","summary":"The acting user's submissions on a campaign","description":"Status (pending / approved / rejected) and review notes. Point allocations are withheld until rewards ship. Free.","tags":["Participation (earn)"],"parameters":[{"name":"campaignId","in":"path","required":true,"description":"Campaign UUID","schema":{"type":"string"}},{"name":"caller_user_id","in":"query","required":false,"description":"Trusted agents only (REQUIRED for them): the ProductClank user this call acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent).","schema":{"type":"string"}}],"responses":{"200":{"description":"Submissions.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"submissions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"campaign_id":{"type":"string"},"submission_type":{"type":"string"},"image_url":{"type":["string","null"]},"description":{"type":["string","null"]},"cast_url":{"type":["string","null"]},"status":{"type":"string","enum":["pending","approved","rejected"]},"reviewed_at":{"type":["string","null"]},"review_notes":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"additionalProperties":true}},"total":{"type":"integer"},"campaign_url":{"type":"string"},"profile_url":{"type":"string"}},"required":["success","submissions","total"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/credits/balance":{"get":{"operationId":"getCreditBalance","summary":"Credit balance of the agent's own account","description":"Always the agent's linked user — no `caller_user_id` support here (trusted agents use `/participate/earnings` or `/credits/history` for a delegated user). Free.","tags":["Credits"],"responses":{"200":{"description":"Balance.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"balance":{"type":"integer"},"plan":{"type":"string"},"lifetime_purchased":{"type":"integer"},"lifetime_used":{"type":"integer"},"lifetime_bonus":{"type":"integer"}},"required":["success","balance","plan"],"additionalProperties":true}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/credits/history":{"get":{"operationId":"getCreditHistory","summary":"Credit transactions of the acting user","description":"Paginated ledger. Free.","tags":["Credits"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size","schema":{"type":"integer","default":20,"maximum":100}},{"name":"offset","in":"query","required":false,"description":"Page offset","schema":{"type":"integer","default":0}},{"name":"caller_user_id","in":"query","required":false,"description":"Trusted agents only (REQUIRED for them): the ProductClank user this call acts for — must hold an active authorization for this agent. Non-trusted agents must omit it (403 if sent).","schema":{"type":"string"}}],"responses":{"200":{"description":"Transactions page.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"transactions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"amount":{"type":"integer","description":"Negative = spend"},"balance_after":{"type":"integer"},"operation_type":{"type":["string","null"]},"description":{"type":["string","null"]},"created_at":{"type":"string"}},"additionalProperties":true}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["success","transactions","total"],"additionalProperties":true}}}},"400":{"description":"Validation error — see `error` (e.g. `validation_error`) and `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (`internal_error`, or `configuration_error` when the agent has no linked user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/credits/topup":{"post":{"operationId":"topUpCredits","summary":"Buy a credit bundle (card, USDC transfer, or x402)","description":"Credits land on the agent's own account. Bundles: nano 40 ($2), micro 200 ($10), small 550 ($25), medium 1200 ($50), large 2600 ($100), enterprise 14000 ($500). Three ways to pay: `payment_method: \"card\"` returns a Stripe `checkout_url` for the human (credits arrive via webhook after payment, `status: awaiting_payment`); `payment_tx_hash` of a completed USDC transfer on Base is verified and credited (replay-guarded); or call with no payment and receive HTTP 402 with x402 v2 instructions (`PAYMENT-REQUIRED` header + `payment_methods` body) — re-send with the signed payment header and credits are added in the same call. Trusted agents are credited without payment.","tags":["Credits"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bundle":{"type":"string","enum":["nano","micro","small","medium","large","enterprise"]},"payment_method":{"type":"string","enum":["card","crypto"],"description":"`card` = Stripe Checkout link; omitted/`crypto` = USDC tx hash or x402"},"payment_tx_hash":{"type":"string","description":"Completed USDC transfer tx hash on Base (direct-transfer path)"},"return_to":{"type":"string","description":"Card only: same-origin relative path to return to after Stripe (must start with `/`)","maxLength":200}},"required":["bundle"]},"example":{"bundle":"micro","payment_method":"card"}}}},"responses":{"200":{"description":"Credits added (crypto / x402 / trusted), or a card checkout to hand to the human.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"success":{"type":"boolean","const":true},"credits_added":{"type":"integer"},"new_balance":{"type":"integer"},"bundle":{"type":"string"},"amount_usdc":{"type":"number","description":"0 for trusted agents"},"payment_method":{"type":"string","enum":["trusted","direct_transfer","x402"]}},"required":["success","credits_added","new_balance","payment_method"],"additionalProperties":true},{"type":"object","properties":{"success":{"type":"boolean","const":true},"payment_method":{"type":"string","enum":["card"]},"status":{"type":"string","enum":["awaiting_payment"]},"checkout_url":{"type":"string"},"checkout_id":{"type":"string"},"bundle":{"type":"string"},"credits":{"type":"integer"},"price_usd":{"type":"number"},"next_step":{"type":"object","properties":{"action":{"type":"string"},"description":{"type":"string"}},"additionalProperties":true}},"required":["success","payment_method","status","checkout_url"],"additionalProperties":true}]}}}},"400":{"description":"`validation_error` — unknown bundle (carries `available_bundles`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid `Authorization: Bearer pck_live_…` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`payment_required` (x402 challenge: `bundle`, `credits`, `amount_usdc`, `payment_methods.{x402,direct_transfer}`, plus a base64 `PAYMENT-REQUIRED` header), `payment_invalid` (bad/duplicate tx hash or bad payment header), or `payment_error`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — agent deactivated, not trusted, or `caller_user_id` delegation not authorized (`unauthorized_delegation`, `authorization_revoked`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`no_linked_user` (card path).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`server_error`, `credit_error`, or `internal_error`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Stripe returned no checkout URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}