---
title: "Create a brief"
method: POST
path: "/briefs"
tags: ["Briefs"]
---

# Create a brief

`POST /briefs`

## Request

- Base URL: `https://viral.app/api/v1`
- URL: `https://viral.app/api/v1/briefs`
- Auth: API key in header `x-api-key`

Creates a brief (version 1) from content written as markdown (contentMarkdown) or TipTap JSON (content), with ordered sample videos from your tracked accounts and an optional audience: campaigns to link (campaignIds), creators to send it to directly (creatorIds), or everyone at the organization (allCreators). Viral-library videos are attached afterwards with POST /briefs/{id}/samples. With notify=true, every creator it reaches is notified. A brief nobody reads yet is a draft.

## Request body

- object: Request to create a brief
  - `name` string, required: Brief name (unique per organization)
  - `content` object: The brief as TipTap JSON (the editor's document). Send this or contentMarkdown.
    - `type` 'doc', required
    - `content` object[]
      - `type` string, required
  - `contentMarkdown` string: The brief as markdown. Send this or content.
  - `sampleVideos` object[]
    - `orgAccountId` string, required: Organization account ID with orgacc_ prefix. Not the same as platform account ID.
    - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat)
    - `platformVideoId` string, required
    - `url` string, uri, required
    - `label` string, nullable: Optional caption creators see above the video, after its number in the list
  - `campaignIds` string[]
  - `creatorIds` string[]: Creators (org creator ids, from list_creators) who read the brief directly, outside any campaign. Not-joined creators are allowed: they read it once they join.
  - `allCreators` boolean: true = every creator at the organization reads the brief, including creators who join later. Such a brief has no campaign or creator links of its own: send campaignIds: [] and creatorIds: [] in the same call to clear existing ones.
  - `notify` boolean, required

## Response `200`

OK

- object
  - `id` string, required: Campaign brief ID with orgbrief_ prefix
  - `version` integer, required

## Other responses

- `400`: 400
- `401`: 401
- `402`: 402
- `404`: 404
- `408`: 408
- `409`: 409
- `429`: 429
- `500`: 500

---

[API](https://skmtc.dev/viral/apis/viral-app-api.md) · [All operations](https://skmtc.dev/viral/apis/viral-app-api/llms.txt) · [OpenAPI document](https://skmtc.dev/viral/apis/viral-app-api/revisions/31e97fa79ef1?raw)