Brand key required
Briefs
A brief is a document you send to creators: what to film, what to say, what to avoid. Create it as a draft or create-and-send in one call, then mint public submission links for drafts to come back through.
List briefs
GET/v1/briefs
request
curl "https://api.ugcroster.com/v1/briefs" \
-H "Authorization: Bearer rsk_brand_key"response 200
{
"data": [
{
"id": "brief_001",
"title": "Summer Skincare Reel Brief",
"body": "<p>Show your morning skincare routine…</p>",
"is_html": true,
"form_id": "form_xyz789",
"attachments": [ { "name": "moodboard.pdf", "url": "https://…", "size": 182044 } ],
"sent_to": ["emma@example.com"],
"creator_recipients": [ { "email": "emma@example.com" } ],
"created_at": "2026-06-10T10:00:00Z"
}
],
"pagination": { "page": 1, "limit": 20, "total": 15, "has_more": false }
}Create a brief
POST/v1/briefs
| Field | Type | Description |
|---|---|---|
| title | string | Required. |
| body | string | Brief content: plain text or HTML (auto-detected, or set is_html). When omitted, the structured fields below are composed into a body for you. |
| instructions | string | Structured alternative to body: main instructions text. |
| talking_points | string[] | Rendered as a "Talking points" list. |
| do_not | string[] | Rendered as a "Please avoid" list. |
| due_date | string | ISO date; rendered into the body and stored on the brief. |
| recipients | array | [{ "email": … }]. Providing recipients (or creator_email) creates AND sends. Omit both to keep a draft. |
| creator_email | string | Shorthand for a single recipient. |
| attachments | array | [{ name, url, size }] file references. |
| campaign_id / content_type / platform | string | Optional linkage and labels. |
request: create and send
curl -X POST "https://api.ugcroster.com/v1/briefs" \
-H "Authorization: Bearer rsk_brand_key" \
-H "Content-Type: application/json" \
-d '{
"title": "Fall Collection Unboxing",
"campaign_id": "form_new456",
"creator_email": "emma@example.com",
"instructions": "Film an authentic unboxing of the fall collection.",
"talking_points": ["Highlight the packaging", "Show texture close-ups"],
"do_not": ["Mention competitors", "Use filters"],
"due_date": "2026-09-15"
}'response 200
{
"data": {
"id": "brief_new001",
"title": "Fall Collection Unboxing",
"sent_to": ["emma@example.com"],
"status": "created"
}
}With no recipients (or an explicit "status": "draft") the brief is saved as a draft and status comes back draft.
Get and update a brief
GET/v1/briefs/{id}
Returns the same shape as a list item.
PATCH/v1/briefs/{id}
| Field | Type | Description |
|---|---|---|
| title | string | New title (non-empty). |
| body | string | New content. is_html is re-detected unless you set it explicitly. |
| attachments | array | Replaces the attachment list. |
| is_html | boolean | Force HTML or plain-text rendering. |
request
curl -X PATCH "https://api.ugcroster.com/v1/briefs/brief_001" \
-H "Authorization: Bearer rsk_brand_key" \
-H "Content-Type: application/json" \
-d '{ "title": "Summer Skincare Reel Brief v2" }'Send a brief
POST/v1/briefs/{id}
Sending is a POST to the brief itself with an action field: there is no /send sub-route. New recipients are merged with anyone the brief was already sent to.
request
curl -X POST "https://api.ugcroster.com/v1/briefs/brief_001" \
-H "Authorization: Bearer rsk_brand_key" \
-H "Content-Type: application/json" \
-d '{ "action": "send", "recipients": [{ "email": "emma@example.com" }] }'response 200
{ "data": { "id": "brief_001", "sent_to": ["emma@example.com"], "status": "sent" } }Submission links
POST/v1/briefs/{id}/submission-links
Mints public draft-submission links. Each link opens an upload page where the creator submits draft files or links for review (no Roster account required). Pass creators (max 100), or creator_emails, or an empty body to mint for every existing recipient of the brief. Minting again for the same creator returns their existing link.
request
curl -X POST "https://api.ugcroster.com/v1/briefs/brief_001/submission-links" \
-H "Authorization: Bearer rsk_brand_key" \
-H "Content-Type: application/json" \
-d '{ "creators": [{ "email": "emma@example.com", "name": "Emma Chen" }] }'response 200
{
"data": {
"brief_id": "brief_001",
"links": [
{
"email": "emma@example.com",
"name": "Emma Chen",
"token": "3f6c1f95ce9e03af2b61f95ce9e03af1",
"url": "https://www.ugcroster.com/submit/3f6c1f95ce9e03af2b61f95ce9e03af1"
}
]
}
}GET/v1/briefs/{id}/submission-links
Lists existing active links for the brief without minting new ones (each item also carries a deliverable_id when a submission has been linked).