Files

Store briefs, plans, reports, and notes against a campaign, activity, or creator, and read them back.

Authentication required

All endpoints require a Bearer token in the Authorization header. See the Authentication guide for setup instructions.

GET /v1/files

List the files attached to one campaign, activity, or creator, including who added each file and whether a person uploaded it or an AI assistant wrote it.

bash
GET /v1/files?owner_type=...&owner_id=...
Authorization: Bearer {token}

Parameters

NameTypeRequiredDescription
ownerType'campaign' | 'activity' | 'creator'RequiredWhich kind of record this file belongs to: campaign, activity, or creator.
ownerIdstring (UUID)RequiredIdentifier of the campaign, activity, or creator.
workspaceIdstring (UUID)—Workspace identifier.

Response

Returns { items, totalCount, facets, _meta } with paginated results.

POST /v1/files

Create a text, markdown, or CSV file on a campaign, activity, or creator by supplying its content directly. Use this to save a written report, summary, plan, or notes. To keep a file someone shared with you, import it instead.

bash
POST /v1/files
Authorization: Bearer {token}
Content-Type: application/json

{
  "owner_type": "...",
  "owner_id": "...",
  "file_name": "...",
  "content_type": "...",
  "content": "Note content here."
}

Parameters

NameTypeRequiredDescription
ownerType'campaign' | 'activity' | 'creator'RequiredWhich kind of record this file belongs to: campaign, activity, or creator.
ownerIdstring (UUID)RequiredIdentifier of the campaign, activity, or creator.
workspaceIdstring (UUID)—Workspace identifier.
fileNamestringRequiredFile name including its extension, for example "wrap-report.md".
contentType'text/markdown' | 'text/plain' | 'text/csv'RequiredMedia type of the supplied content.
contentstringRequiredThe complete text content to store.
descriptionstring | null—Short note about what this file contains and why it was attached.

Response

Returns { data, _meta } with the result.

POST /v1/files/import

Add the original of a file someone shared, such as a spreadsheet, PDF, slide deck, document or screenshot, to a campaign, activity, or creator. Brandwave downloads the file from its link and stores a private copy.

bash
POST /v1/files/import
Authorization: Bearer {token}
Content-Type: application/json

{
  "owner_type": "...",
  "owner_id": "...",
  "file": "..."
}

Parameters

NameTypeRequiredDescription
ownerType'campaign' | 'activity' | 'creator'RequiredWhich kind of record this file belongs to: campaign, activity, or creator.
ownerIdstring (UUID)RequiredIdentifier of the campaign, activity, or creator.
workspaceIdstring (UUID)—Workspace identifier.
fileobjectRequiredThe file to copy into Brandwave.
fileNamestring—A clearer name to store the file under, including its extension. Defaults to the original name.
descriptionstring | null—Short note about what this file contains and why it was attached.

Response

Returns { data, _meta } with the result.

GET /v1/files/:id/download

Get a short-lived authorized URL for reading one private file, so it can be opened or fetched and analyzed.

bash
GET /v1/files/:id/download
Authorization: Bearer {token}

Parameters

NameTypeRequiredDescription
idstring (UUID)RequiredUnique identifier (UUID v4).

Response

Returns { data, _meta } with the result.

PATCH /v1/files/:id

Update the name of a file attached to a campaign, activity, or creator so it says what the document actually is.

bash
PATCH /v1/files/:id
Authorization: Bearer {token}
Content-Type: application/json

{
  "file_name": "..."
}

Parameters

NameTypeRequiredDescription
idstring (UUID)RequiredUnique identifier (UUID v4).
fileNamestringRequiredA clearer name for this file, including its extension.

Response

Returns { data, _meta } with the result.

DELETE /v1/files/:id

Remove a file from the campaign, activity, or creator it is attached to.

bash
DELETE /v1/files/:id
Authorization: Bearer {token}

Parameters

NameTypeRequiredDescription
idstring (UUID)RequiredUnique identifier (UUID v4).

Response

Returns { data, _meta } with the result.