Skip to Content
Skip to Content
Starcovery

Campaigns

By Starcovery. Updated .

Create a campaign, generate matches, add or remove creators, and export the shortlist.

This page covers how to create a campaign, generate and edit its matches, request a send or funding, and control who reads it.

A campaign stores a goal, generated creator matches, and the shortlist you edit. Campaign endpoints work from the web app, Model Context Protocol (MCP), the REST API, and the CLI.

All campaign endpoints require a credential: a Settings API key, an OAuth access token, or a browser session. Send a Settings API key as x-api-key or Authorization: Bearer, and an OAuth access token as Authorization: Bearer. See Authentication.

Set the contract, creator posting date, campaign details declassifying date, and disclosure, then request a Send Proposal. The Starcovery team sends the proposals from its staff queue and handles funding, as described in Send and funding requests.

Create and manage a campaign

Create with a goal

curl -X POST "https://www.starcovery.com/api/campaigns" \
  -H "x-api-key: <access_token>" \
  -H "content-type: application/json" \
  -d '{
    "name": "Coffee",
    "goal": "quiet morning coffee creators who film at home"
  }'

You can include contract, embargoUntil (campaign details declassifying date), disclosure, and marketInformation on create. contract takes compensationCents, deliverable, platforms, the platforms one payment covers (["ig"], ["tt"], or ["ig", "tt"]), and the optional creator posting date in creatorPostingDate; a hired creator posts on each platform they run. embargoUntil needs contract in the same body, or the create returns 400 invalid_campaign_terms with the reason in message.

marketInformation is {"releaseDelayMonths": <n>}, the answer that decides when the campaign's name and pay per creator join the going rate, the list of campaigns and the typical pay other organizations and creators see. The going rate shows nothing about the organization that ran the campaign, and a campaign joins it no earlier than its declassifying date. Omit marketInformation to leave the question unanswered; on create, "marketInformation": null returns 400 invalid_body. Funding requires an answer. releaseDelayMonths takes one of these values:

  • 0 adds them once funding is requested.
  • 1 to 18 holds them back that many months after the funding cycle's first funding request. A funding cycle starts at the first funding request open since the campaign last held no funds, so a full refund restarts the hold.
  • null keeps them out.

To retry a create safely, send the same idempotencyKey (1 to 128 characters) and a complete, valid body on each attempt. A repeat with a key your organization already used returns the campaign the first request created, even when the rest of the body differs, and charges nothing.

On create and update, a contract or date that fails the terms check returns 400 invalid_campaign_terms with the reason in message.

Generate matches

curl -X POST "https://www.starcovery.com/api/campaigns/{campaignId}/generate" \
  -H "x-api-key: <access_token>" \
  -H "content-type: application/json" \
  -d '{}'

Generation runs one creator search against the campaign goal, billed like GET /api/search, and stores the ranked creators on the campaign.

Add or remove matches

Add or remove individual matches with POST /api/campaigns/{campaignId}/matches and DELETE /api/campaigns/{campaignId}/matches/{matchId}. The add body carries the creator's profileId and fitScore only; the platform, handle, name, picture, and follower count of the match come from the catalog profile, and a body with any other key answers 400 invalid_body naming the key. Removing a match that already has a proposal delivery returns 409 campaign_match_delivered.

Read, update, or export

Read the campaign with matches (GET /api/campaigns/{campaignId}), update it (PATCH /api/campaigns/{campaignId}), or export the shortlist as CSV (GET /api/campaigns/{campaignId}/export).

List the campaigns of the organization with GET /api/campaigns, newest update first. ?status=draft, ?status=active, or ?status=archived lists only the campaigns in that status, and another value answers 400 invalid_query.

GET /api/campaigns and GET /api/campaigns/{campaignId} carry nextStep, the step the web app shows next on the campaign:

{
  "id": "fund",
  "label": "Fund the creators who accepted",
  "actor": "you",
  "line": "2 creators accepted. Fund $600 to lock them in."
}

For members of the organization, GET /api/campaigns/{campaignId} also carries people, each person on the campaign with their answer, funding, and signed hire. A hire lists posts, each live post Starcovery recorded, one per platform, with its url, viewCount, engagementCount (likes plus comments), and recordedAt.

id is one of pick, proposal, send, answers, fund, post, and payout, in campaign order. actor names who takes the step: you for your organization, starcovery, creators, or {"creator": "<name>"} when one funded creator has yet to post. nextStep is null once no step is left, because the campaign is done or archived or no creator was reached or accepted, and on a campaign another organization owns.

GET /api/campaigns/{campaignId} also carries currentSteps, every step under way in campaign order, in the same shape. A step before nextStep can still wait: while Starcovery has not sent every proposal and a later step waits too, nextStep names the later step and currentSteps lists the send step before it. currentSteps is empty once no step is left and null on a campaign another organization owns.

Update name, goal, visibility, status, contract, campaign details declassifying date (embargoUntil), creator posting date (contract.creatorPostingDate), disclosure, or marketInformation (null clears it). contract replaces the stored contract: send compensationCents, deliverable, and platforms with it, and send creatorPostingDate again to keep the posting date. Status takes draft, archived, or active; Starcovery sets active when the team sends the proposals, and active reopens an archived campaign whose proposals were sent. A campaign that is active or holds a proposal delivery cannot return to draft, a campaign with a send or funding request open with the Starcovery team cannot be archived, and a campaign that is not archived or was never sent cannot be set active; each patch returns 409 campaign_status_locked with reason sent, request_open, or not_sent. The contract and the disclosure lock when the team sends the proposals: while the campaign is active or holds a proposal delivery, a patch that changes or clears contract, or changes disclosure, returns 409 contract_locked.

curl -X PATCH "https://www.starcovery.com/api/campaigns/{campaignId}" \
  -H "x-api-key: <access_token>" \
  -H "content-type: application/json" \
  -d '{
    "goal": "quiet morning coffee creators who film at home"
  }'

Omit a top-level field you do not want to change.

Every endpoint is in the API reference with an interactive playground.

Send and funding requests

Sending proposals and funding a campaign are staff actions. Any surface can record the request.

POST /api/campaigns/{campaignId}/send-request records one open Send Proposal request and notifies the Starcovery team, who send the proposals from the staff queue. The campaign needs draft status, a contract whose creator posting date, when set, is today or a later day in UTC, a disclosure, and at least one match with 1,000 or more followers.

POST /api/campaigns/{campaignId}/funding-request records one open funding request for the accepted creators not yet funded, per person, at the compensation per creator times those people, plus the campaign price of $99, $499, or $999 by company size on the campaign's first funding request only. Starcovery keeps the campaign price, which is not creator pay and is never refunded. The caller needs an owner or admin role in the organization, and the campaign needs a contract, market information, and at least one creator who accepted and is not yet funded (reason no_accepted otherwise). An archived campaign returns reason archived; reopen it with {"status":"active"} first.

Both return 201 with the request row in request. A campaign with an open request, or one that fails a gate, returns 409 campaign_request_denied with the reason in reason. The reason creators_changed means a creator accepted while the funding request was prepared, and the same call is safe to repeat. A funding request from a member who is not an owner or admin returns 403 organization_funding_forbidden.

The market information answer locks while a funding request is open or the campaign holds funds. Then a PATCH /api/campaigns/{campaignId} that changes or clears marketInformation returns 409 market_information_locked.

curl -X POST "https://www.starcovery.com/api/campaigns/{campaignId}/send-request" \
  -H "x-api-key: <access_token>"

The Starcovery team sends the proposals, invoices the organization, and pays creators. Prepaid credit packs are a different money domain and stay available.

Visibility and cost

  • New campaigns are public by default. Ordinary public campaign bodies are free to read for any identified caller.
  • A credential bound to the organization that owns the campaign, or a browser session of one of its members, reads campaign detail at any time, including contract metadata.
  • A stored campaign details declassifying date (embargoUntil) returns 404 to identified callers outside the owning organization until that instant.
  • A private campaign returns 404 to identified callers outside the owning organization. Unsigned callers get 401 on every campaign endpoint.
  • Making a campaign private costs 1 credit: at creation, or when you change a public campaign to private. Updates to an already-private campaign do not charge again.
  • Generating matches runs one search, which spends the daily grant or 1 credit like GET /api/search. A repeat of a search the organization already ran is free while that search is still in its search history (Pay for API calls without a subscription).

CLI equivalents

starcovery campaigns listCampaigns
starcovery campaigns createCampaign --name "Coffee" --goal "quiet morning coffee creators"
starcovery campaigns updateCampaign --campaignId <CAMPAIGN> --goal "quiet morning coffee creators who film at home"
starcovery campaigns updateCampaign --campaignId <CAMPAIGN> --marketInformation 0
starcovery campaigns generateCampaignMatches --campaignId <CAMPAIGN>
starcovery campaigns openCampaign --campaignId <CAMPAIGN>
starcovery campaigns addCampaignMatch --campaignId <CAMPAIGN> --profileId <CREATOR> --fitScore 0.8
starcovery campaigns exportCampaign --campaignId <CAMPAIGN> > out.csv