Collabs

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

Operations

Operation	Method + path	Token scope	Role	Notes
List collabs	GET /organizations/:organization_id/collabs.json	read or write	Organization member	Paginated
Show collab	GET /organizations/:organization_id/collabs/:id.json	read or write	Organization member	ETag on show
Create collab	POST /organizations/:organization_id/collabs.json	write	Organization admin	Creates a draft
Update collab	PATCH /organizations/:organization_id/collabs/:id.json	write	Organization admin	purge_banner_image removes banner
Delete collab	DELETE /organizations/:organization_id/collabs/:id.json	write	Organization admin	Only draft collabs without submissions can be deleted

Not exposed in JSON

State transitions such as submit, pause, and unpause still redirect through HTML endpoints today.

Resource shape

{
  "id": "qZmRpL",
  "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/gKpMxN/collabs/qZmRpL.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 organization’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 organization.

You can send a collab payload to override the server-created draft defaults. Any omitted fields keep the generated defaults (for example the default name, default countries, default brief template, and the database default currency).

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, include "purge_banner_image": "1" inside the collab payload.

Delete

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

Returns 204 No Content only for draft collabs with no submissions. Fails with 403 if the collab is no longer a draft, and 422 if any submissions exist.

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