Campaigns

A campaign is a budgeted creator program with payout rules and platform targeting. Org-scoped: the URL identifies the brand.

Resource shape

{
  "id": 4,
  "name": "Summer UGC Campaign",
  "status": "draft",
  "currency": "usd",
  "countries": ["US", "GB"],
  "website": "https://example.com/product",
  "content_type": "ugc",
  "category": "product",
  "platform_ids": ["youtube", "tiktok"],
  "tiktok_music_id": "7038475063498387456",
  "cpm_amount": 500,
  "min_payout_amount": 1000,
  "max_payout_amount": 10000,
  "base_reward_amount": 0,
  "total_budget_amount": 0,
  "used_amount": 0,
  "unused_amount": 0,
  "view_count": 0,
  "submissions_count": 0,
  "published_at": null,
  "paused_at": null,
  "created_at": "2026-05-01T10:00:00Z",
  "updated_at": "2026-05-06T10:00:00Z",
  "url": "https://hypemarket.ai/organizations/3/campaigns/4.json",
  "banner_image_url": "https://hypemarket.ai/rails/active_storage/...",
  "brief": "<p>Create a product demo in your own style...</p>"
}

status is one of draft, active, paused, finished. brief is included on show only and is rendered HTML (rich text).

List

GET /organizations/:organization_id/campaigns.json

Returns the brand’s campaigns (subject to your role’s policy scope). Paginated.

Show

GET /organizations/:organization_id/campaigns/:id.json

Returns one campaign including the rendered brief HTML. Sets an ETag.

Create

POST /organizations/:organization_id/campaigns.json

{
  "campaign": {
    "name": "Summer UGC Campaign",
    "website": "https://example.com/product",
    "content_type": "ugc",
    "category": "product",
    "currency": "usd",
    "cpm_amount": 500,
    "min_payout_amount": 1000,
    "max_payout_amount": 10000,
    "base_reward_amount": 0,
    "platform_ids": ["youtube", "tiktok"],
    "countries": ["US", "GB"],
    "brief": "<p>Create a product demo in your own style...</p>"
  }
}

Creates a draft campaign. Requires a write-scoped token and an admin role on the brand. Returns 201 Created with the new campaign.

If you omit optional fields, the server fills them from the campaign form defaults where possible. Budget totals always start at zero on create; funding happens separately.

Update

PATCH /organizations/:organization_id/campaigns/:id.json

{
  "campaign": {
    "name": "Updated campaign name",
    "cpm_amount": 650
  }
}

Returns 200 OK with the updated campaign.

Once a campaign has been published, only the same fields allowed in the web UI remain writable; financial fields are no longer accepted.

Delete

DELETE /organizations/:organization_id/campaigns/:id.json

Returns 204 No Content. Fails if the campaign is no longer a draft or already has fundings.

State transitions (not yet exposed via JSON)

POST .../publish, .../pause, and .../resume still redirect today. JSON support is not rolled out for those actions yet.

Errors

Code	When
`401`	Missing token, or read token attempting a write
`403`	You’re authenticated but your role can’t perform this action
`404`	Campaign or org does not exist for you
`422`	Validation failed