Activities#

Work with creator content activities using the Brandwave TypeScript SDK.

Authentication required

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

GET /v1/activities#

Retrieve a paginated list of activities for an organization.

bash

GET /v1/activities?page_index=0&page_size=25&organization_id=org_123
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
pageIndex	`integer`	Required	Zero-based page index for pagination.
pageSize	`integer`	Required	Number of items per page (1-100).
organizationId	`string (UUID)`	Required	Organization identifier.
searchTerm	`string`	—	Free-text search term to filter results (max 200 characters).
sortBy	`string`	—	Column name to sort by.
sortDirection	`'asc' \| 'desc'`	—	Sort direction: ascending or descending.
channel	`'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit'`	—	Filter by social media platform.
creatorId	`string (UUID)`	—	Filter by creator identifier.
campaignId	`string (UUID)`	—	Filter by campaign identifier.

Response#

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

Underlying SDK method: bw.activities.list(params)

GET /v1/activities/count#

Get the total number of activities matching the given filters.

bash

GET /v1/activities/count?organization_id=org_123
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization identifier.
channel	`'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit'`	—	Filter by social media platform.
creatorId	`string (UUID)`	—	Filter by creator identifier.
campaignId	`string (UUID)`	—	Filter by campaign identifier.

Response#

Returns { count } with the total number of matching records.

Underlying SDK method: bw.activities.count(params)

GET /v1/activities/stats#

Aggregate statistics for activities matching the given filters.

bash

GET /v1/activities/stats?organization_id=org_123
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization identifier.
channel	`'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit'`	—	Filter by social media platform.
creatorId	`string (UUID)`	—	Filter by creator identifier.
campaignId	`string (UUID)`	—	Filter by campaign identifier.
searchTerm	`string`	—	Free-text search term to filter results (max 200 characters).

Response#

Returns { data } with the result.

Underlying SDK method: bw.activities.stats(params)

POST /v1/activities#

Create a new activity with optional creator auto-linking.

bash

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

{
  "organization_id": "org_123",
  "channel": "instagram",
  "activity": "...",
  "name": "My Campaign"
}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization identifier.
channel	`'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit'`	Required	Social media platform for this activity.
activity	`'instagram_story' \| 'instagram_post' \| 'instagram_reel' \| 'youtube_video' \| 'youtube_short' \| 'tiktok_video' \| 'twitter_post' \| 'linkedin_post' \| 'reddit_post'`	Required	Specific content type within a platform.
name	`string`	Required	Activity name or title (max 500 characters).
startAt	`string (ISO 8601) \| null`	—	When the activity was published or started.
endAt	`string (ISO 8601) \| null`	—	When the activity ended (e.g., story expiry).
creatorId	`string (UUID)`	—	Creator to auto-link to this activity.

Response#

Returns { data } with the result.

Underlying SDK method: bw.activities.create(params)

PATCH /v1/activities/:id#

Update an activity's details, social media channel, content link, or metrics.

bash

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

{
  "name": "My Campaign"
}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Activity identifier to update.
channel	`'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit'`	—	Updated social media platform.
activity	`'instagram_story' \| 'instagram_post' \| 'instagram_reel' \| 'youtube_video' \| 'youtube_short' \| 'tiktok_video' \| 'twitter_post' \| 'linkedin_post' \| 'reddit_post'`	—	Updated content type.
name	`string`	Required	Updated activity name (max 500 characters).
startAt	`string (ISO 8601) \| null`	—	Updated start date.
endAt	`string (ISO 8601) \| null`	—	Updated end date.
contentHref	`string (URL) \| null`	—	URL to the original content (max 2,048 characters).
viewsCount	`integer \| null`	—	Manual view count override (non-negative integer).
likeCount	`integer \| null`	—	Manual like count override (non-negative integer).
replyCount	`integer \| null`	—	Manual reply count override (non-negative integer).

Response#

Returns { data } with the result.

Underlying SDK method: bw.activities.update(params)

Content link changes reset metrics

Changing the contentLink triggers a metric refresh. Previous metric snapshots are preserved but the latest values will update.

DELETE /v1/activities/:id#

Permanently delete an activity and its associated records.

bash

DELETE /v1/activities/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Activity identifier to delete.

Response#

Returns { data } with the result.

Underlying SDK method: bw.activities.delete(params)

Destructive action

Deleting an activity permanently removes all linked metrics, costs, creator associations, and notes. This action cannot be undone.

POST /v1/activities/content-link/connect#

Connect a social media post URL to an activity for automatic metric tracking.

bash

POST /v1/activities/content-link/connect
Authorization: Bearer {token}
Content-Type: application/json

{
  "activity_id": "act_abc123",
  "platform": "instagram",
  "content_url": "..."
}

Parameters#

Name	Type	Required	Description
activityId	`string (UUID)`	Required	Activity identifier to connect the content link to.
platform	`'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit'`	Required	Social media platform for this content.
contentUrl	`string`	Required	URL to the social media content (max 2,048 characters).

Response#

Returns { data } with the result.

Underlying SDK method: bw.activities.contentLink.connect(params)

Metric refresh

Connecting a content link triggers an immediate metric fetch for the linked post.

POST /v1/activities/content-link/disconnect#

Disconnect a content link from an activity, stopping automatic metric tracking.

bash

POST /v1/activities/content-link/disconnect
Authorization: Bearer {token}
Content-Type: application/json

{
  "activity_id": "act_abc123"
}

Parameters#

Name	Type	Required	Description
activityId	`string (UUID)`	Required	Activity identifier to disconnect the content link from.

Response#

Returns { data } with the result.

Underlying SDK method: bw.activities.contentLink.disconnect(params)

GET /v1/activities/creators#

List creators linked to an activity with pagination.

bash

GET /v1/activities/creators?page_index=0&page_size=25&organization_id=org_123&activity_id=act_abc123
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
pageIndex	`integer`	Required	Zero-based page index for pagination.
pageSize	`integer`	Required	Number of items per page (1-100).
organizationId	`string (UUID)`	Required	Organization identifier.
activityId	`string (UUID)`	Required	Activity identifier to list creators for.

Response#

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

Underlying SDK method: bw.activities.creators.list(params)

GET /v1/activities/creators/count#

Count the number of creators linked to an activity.

bash

GET /v1/activities/creators/count?organization_id=org_123&activity_id=act_abc123
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization identifier.
activityId	`string (UUID)`	Required	Activity identifier to count creators for.

Response#

Returns { count } with the total number of matching records.

Underlying SDK method: bw.activities.creators.count(params)

POST /v1/activities/:id/creators#

Associate a creator with an activity.

bash

POST /v1/activities/:id/creators
Authorization: Bearer {token}
Content-Type: application/json

{
  "activity_id": "act_abc123",
  "creator_id": "con_abc123"
}

Parameters#

Name	Type	Required	Description
activityId	`string (UUID)`	Required	Activity identifier to link.
creatorId	`string (UUID)`	Required	Creator identifier to link.

Response#

Returns { data } with the result.

Underlying SDK method: bw.activities.creators.link(params)

DELETE /v1/activities/:id/creators/:creatorId#

Remove a creator association from an activity.

bash

DELETE /v1/activities/:id/creators/:creatorId
Authorization: Bearer {token}
Content-Type: application/json

{
  "activity_id": "act_abc123"
}

Parameters#

Name	Type	Required	Description
activityId	`string (UUID)`	Required	Activity identifier to unlink from.
creatorId	`string (UUID)`	Required	Creator identifier to unlink.

Response#

Returns { data } with the result.

Underlying SDK method: bw.activities.creators.unlink(params)

Cascading deletion

Unlinking a creator removes all cost records associated with that creator on this activity.

POST /v1/activities/costs#

Add a cost line item to an activity with amount and currency code.

bash

POST /v1/activities/costs
Authorization: Bearer {token}
Content-Type: application/json

{
  "activity_id": "act_abc123",
  "amount": "150.00",
  "type": "instagram_post",
  "currency": "..."
}

Parameters#

Name	Type	Required	Description
activityId	`string (UUID)`	Required	Activity identifier to add the cost to.
amount	`number`	Required	Cost amount (must be greater than zero, max 100M).
type	`string`	Required	Cost type label, e.g. "creator_fee", "production" (max 100 characters).
currency	`string`	Required	ISO 4217 currency code, e.g. "USD", "NZD" (exactly 3 characters).
description	`string \| null`	—	Optional description of this cost line item (max 1,000 characters).
creatorId	`string (UUID) \| null`	—	Creator this cost is attributed to.

Response#

Returns { data } with the result.

Underlying SDK method: bw.activities.costs.create(params)

Auto-linking

If the activity has exactly one linked creator, the cost is automatically attributed to that creator.

PATCH /v1/activities/costs/:id#

Update a cost line item on an activity, including creator attribution.

bash

PATCH /v1/activities/costs/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Cost record identifier to update.
amount	`number`	—	Updated cost amount (must be greater than zero, max 100M).
type	`string`	—	Updated cost type label (max 100 characters).
description	`string \| null`	—	Updated description (max 1,000 characters).
creatorId	`string (UUID) \| null`	—	Updated creator attribution.

Response#

Returns { data } with the result.

Underlying SDK method: bw.activities.costs.update(params)

DELETE /v1/activities/costs/:id#

Remove a cost line item from an activity.

bash

DELETE /v1/activities/costs/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Cost record identifier to delete.

Response#

Returns { data } with the result.

Underlying SDK method: bw.activities.costs.delete(params)

GET /v1/activities/metrics/confidence#

Assess the statistical confidence of an activity's metrics.

bash

GET /v1/activities/metrics/confidence?organization_id=org_123
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization identifier.
startDate	`string \| null`	—	Start date for confidence calculation window.
endDate	`string \| null`	—	End date for confidence calculation window.

Response#

Returns { data } with the result.

Underlying SDK method: bw.activities.metrics.confidence(params)

GET /v1/activities/sparklines#

Fetch sparkline chart data for one or more activities.

bash

GET /v1/activities/sparklines?activity_ids=...
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
activityIds	`Array<string (UUID)>`	Required	Array of activity identifiers to fetch sparkline data for.

Response#

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

Underlying SDK method: bw.activities.sparklines.list(params)

GET /v1/activities/:id#

Retrieve a single activity by ID with full details.

bash

GET /v1/activities/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Activity identifier.

Response#

Returns { data } with the result.

Underlying SDK method: bw.activities({ id })