Collabs

A collab is a brand’s brief that creators can apply to. Org-scoped: the URL identifies the brand.

Resource shape

{
  "id": 9,
  "name": "Spring Lipstick Drop",
  "state": "published",
  "currency": "usd",
  "countries": ["US", "CA"],
  "website": "https://example.com/lipstick",
  "require_spark_ads": true,
  "requires_product_shipment": false,
  "submissions_count": 24,
  "completed_count": 6,
  "published_at": "2026-04-15T10:00:00Z",
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": "2026-05-01T10:00:00Z",
  "url": "https://hypemarket.ai/organizations/3/collabs/9.json",
  "banner_image_url": "https://hypemarket.ai/rails/active_storage/...",
  "brief": "<p>Show the lipstick in a get-ready-with-me video...</p>"
}

state is one of draft, submitted_for_review, published, paused. brief is included on show only and is rendered HTML (rich text).

List

GET /organizations/:organization_id/collabs.json

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

Show

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

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

Create

POST /organizations/:organization_id/collabs.json

{
  "collab": {
    "name": "Spring lipsticks",
    "website": "https://example.com/lipstick",
    "currency": "eur",
    "countries": ["FR", "DE"],
    "require_spark_ads": true,
    "requires_product_shipment": false,
    "brief": "<p>Show the lipstick in a get-ready-with-me video...</p>"
  }
}

Creates a draft collab. Requires a write-scoped token and an admin role on the brand.

You can send a collab payload to override the brand defaults. Any omitted fields fall back to the brand’s defaults (for example default countries and brief template).

If you omit collab entirely, the server still creates a draft from defaults only.

To pre-fill from a product page, pass a top-level website query param such as ?website=https://.... That prefill flow is primarily intended for the web UI and may replace generated fields such as name, brief, countries, website, and banner_image.

Update

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

{
  "collab": {
    "name": "Updated name",
    "currency": "eur",
    "countries": ["FR", "DE"],
    "brief": "<p>New brief…</p>"
  }
}

Returns 200 OK with the updated collab. To remove an existing banner, pass purge_banner_image: "1".

Delete

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

Returns 204 No Content. Fails if the collab has approved submissions.

State transitions (not yet exposed via JSON)

POST .../submit, .../pause, .../unpause redirect today. JSON support is on the rollout list.

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	Collab or org does not exist for you
422	Validation failed