zelf.developers

Brands

The brands (workspaces) an API key can access. Most content endpoints accept a brand_id from here to unlock brand-specific signals like ownership, tagging, and NPS. brands.catalog adds the brands Zelf curates for competitive benchmarking, which every key can read content for.

Create Sub-brand

POST/api/v1/brands/sub_brands.create

Creates a sub-brand under the workspace brand. A sub-brand tracks a competitor (COMPETITIVE) or a content theme (THEME) separately.

A brand may have at most 64 sub-brands; requests beyond this limit are rejected. The new brand's id is the value to supply as brand_id elsewhere.

Request body

search_termsType: string[]

Plain keywords the brand monitors across platforms, matched as-is (case-insensitive, no operators).

inclusion_termsType: string[]

Terms that must be present for content to match.

exclusion_termsType: string[]

Terms that disqualify content from matching.

compound_inclusion_termsType: string[]

Secondary inclusion terms layered on top of inclusion_terms.

influencer_termsType: string[]

Terms that mark matched content as influencer content.

allowed_languagesType: string[]

ISO 639-1 codes to track, or the single value all. An empty array means all languages are tracked. A code outside ISO 639-1 is rejected, because a brand tracking it would match no content.

boolean_queryType: stringor null

Full-text search across the caption, transcript, summary, and hashtags.

Syntax

  • Multiple words are combined with AND: nike running matches content containing both nike and running.
  • OR (case-insensitive) matches either side: nike OR adidas.
  • NOT (case-insensitive) excludes a term: running NOT marathon matches running but not marathon.
  • Wrap a phrase in double quotes to match the words in order: "summer collection".
  • Negate a phrase with NOT: NOT "out of stock".
  • Group with parentheses to combine operators: (nike OR adidas) running.
  • ONEAR/n (case-insensitive) matches terms within n words of each other, in order: apple ONEAR/2 watch matches apple watch and apple smart watch, but not watch ... apple. It binds more tightly than AND and OR, so apple ONEAR/2 watch AND cheap is interpreted as (apple near watch) AND cheap.

Examples

  • nike running - contains both terms.
  • nike OR adidas - contains either brand.
  • "summer sale" NOT clearance - the exact phrase, without clearance.
  • (running OR cycling) NOT "beginner guide" - either sport, excluding the phrase.
  • apple ONEAR/2 watch - apple within two words before watch.

Content matching this query is connected to (associated with) this brand.

titleType: stringRequiredmin length 1

Display name of the new sub-brand.

min length
1
sub_brand_typeType: enumRequired

Type of sub-brand: COMPETITIVE or THEME.

Show values
COMPETITIVETHEME

Returns Brand

idType: stringread-only

Unique identifier for the brand. Supply it wherever a brand_id accepts a brand id.

titleType: string

Display name of the brand.

is_primaryType: boolean

true for the brand this access belongs to, and false for every other brand the request can access.

sub_brand_typeType: stringor nullread-only

COMPETITIVE or THEME for a sub-brand; null for a top-level brand.

parent_brand_idType: stringor nullread-only

Id of the parent brand for a sub-brand; null for a top-level brand.

keywordsType: BrandKeywords

The terms this brand uses to monitor social platforms. All arrays are always present, though they may be empty, and are never null.

Show child attributes
keywords.search_termsType: string[]read-only

Plain keywords the brand monitors across platforms, matched as-is (case-insensitive, no operators).

keywords.inclusion_termsType: string[]read-only

Terms that must be present for content to match.

keywords.exclusion_termsType: string[]read-only

Terms that disqualify content from matching, even when other criteria are met.

keywords.compound_inclusion_termsType: string[]read-only

Secondary inclusion terms layered on top of inclusion_terms. A match requires at least one term from inclusion_terms and at least one from compound_inclusion_terms.

keywords.influencer_termsType: string[]read-only

Terms that mark matched content as influencer content (for example, sponsored, ad, or gifted).

keywords.allowed_languagesType: string[]read-only

ISO 639-1 codes for the languages the brand tracks. An empty array indicates that all languages are tracked.

keywords.boolean_queryType: stringor nullread-only

Full-text search across the caption, transcript, summary, and hashtags.

Syntax

  • Multiple words are combined with AND: nike running matches content containing both nike and running.
  • OR (case-insensitive) matches either side: nike OR adidas.
  • NOT (case-insensitive) excludes a term: running NOT marathon matches running but not marathon.
  • Wrap a phrase in double quotes to match the words in order: "summer collection".
  • Negate a phrase with NOT: NOT "out of stock".
  • Group with parentheses to combine operators: (nike OR adidas) running.
  • ONEAR/n (case-insensitive) matches terms within n words of each other, in order: apple ONEAR/2 watch matches apple watch and apple smart watch, but not watch ... apple. It binds more tightly than AND and OR, so apple ONEAR/2 watch AND cheap is interpreted as (apple near watch) AND cheap.

Examples

  • nike running - contains both terms.
  • nike OR adidas - contains either brand.
  • "summer sale" NOT clearance - the exact phrase, without clearance.
  • (running OR cycling) NOT "beginner guide" - either sport, excluding the phrase.
  • apple ONEAR/2 watch - apple within two words before watch.

Content matching this query is connected to (associated with) this brand.

Responses

Brand

idType: stringread-only

Unique identifier for the brand. Supply it wherever a brand_id accepts a brand id.

titleType: string

Display name of the brand.

is_primaryType: boolean

true for the brand this access belongs to, and false for every other brand the request can access.

sub_brand_typeType: stringor nullread-only

COMPETITIVE or THEME for a sub-brand; null for a top-level brand.

parent_brand_idType: stringor nullread-only

Id of the parent brand for a sub-brand; null for a top-level brand.

keywordsType: BrandKeywords

The terms this brand uses to monitor social platforms. All arrays are always present, though they may be empty, and are never null.

Show child attributes
keywords.search_termsType: string[]read-only

Plain keywords the brand monitors across platforms, matched as-is (case-insensitive, no operators).

keywords.inclusion_termsType: string[]read-only

Terms that must be present for content to match.

keywords.exclusion_termsType: string[]read-only

Terms that disqualify content from matching, even when other criteria are met.

keywords.compound_inclusion_termsType: string[]read-only

Secondary inclusion terms layered on top of inclusion_terms. A match requires at least one term from inclusion_terms and at least one from compound_inclusion_terms.

keywords.influencer_termsType: string[]read-only

Terms that mark matched content as influencer content (for example, sponsored, ad, or gifted).

keywords.allowed_languagesType: string[]read-only

ISO 639-1 codes for the languages the brand tracks. An empty array indicates that all languages are tracked.

keywords.boolean_queryType: stringor nullread-only

Full-text search across the caption, transcript, summary, and hashtags.

Syntax

  • Multiple words are combined with AND: nike running matches content containing both nike and running.
  • OR (case-insensitive) matches either side: nike OR adidas.
  • NOT (case-insensitive) excludes a term: running NOT marathon matches running but not marathon.
  • Wrap a phrase in double quotes to match the words in order: "summer collection".
  • Negate a phrase with NOT: NOT "out of stock".
  • Group with parentheses to combine operators: (nike OR adidas) running.
  • ONEAR/n (case-insensitive) matches terms within n words of each other, in order: apple ONEAR/2 watch matches apple watch and apple smart watch, but not watch ... apple. It binds more tightly than AND and OR, so apple ONEAR/2 watch AND cheap is interpreted as (apple near watch) AND cheap.

Examples

  • nike running - contains both terms.
  • nike OR adidas - contains either brand.
  • "summer sale" NOT clearance - the exact phrase, without clearance.
  • (running OR cycling) NOT "beginner guide" - either sport, excluding the phrase.
  • apple ONEAR/2 watch - apple within two words before watch.

Content matching this query is connected to (associated with) this brand.

Request

string[]
string[]
string[]
from zelf import ZelfAPIClient

client = ZelfAPIClient(api_key="<your-api-key>")

result = client.sub_brands.create(
    search_terms=["zelf", "zelfai"],
    inclusion_terms=["creator", "influencer"],
    exclusion_terms=["giveaway"],
    compound_inclusion_terms=["marketing"],
    influencer_terms=["sponsored", "ad", "gifted"],
    allowed_languages=["en"],
    boolean_query="python",
    title="Zelf",
    sub_brand_type="COMPETITIVE",
)
print(result)
Response
{
  "log_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "timestamp": "2026-01-01T00:00:00Z",
  "results": [
    {
      "id": "brd_Lw6ZZmNYhW0P9k0x",
      "title": "Zelf",
      "is_primary": true,
      "sub_brand_type": null,
      "parent_brand_id": null,
      "keywords": {
        "search_terms": [
          "zelf",
          "zelfai"
        ],
        "inclusion_terms": [
          "creator",
          "influencer"
        ],
        "exclusion_terms": [
          "giveaway"
        ],
        "compound_inclusion_terms": [
          "marketing"
        ],
        "influencer_terms": [
          "sponsored",
          "ad",
          "gifted"
        ],
        "allowed_languages": [
          "en"
        ],
        "boolean_query": "python"
      }
    }
  ],
  "item_count": 1,
  "page": 1,
  "next": null,
  "previous": null
}

List Brands

GET/api/v1/brands/brands.list

Returns every brand this key can reach: the workspace brand, every brand linked to it, and the sub-brands of each. Start here when building a new integration, to find out which brand ids are available.

Each row's id is the value to supply as brand_id wherever a brand is named. is_primary identifies the workspace brand, and parent_brand_id links a sub-brand to its parent.

Returns Brand

idType: stringread-only

Unique identifier for the brand. Supply it wherever a brand_id accepts a brand id.

titleType: string

Display name of the brand.

is_primaryType: boolean

true for the brand this access belongs to, and false for every other brand the request can access.

sub_brand_typeType: stringor nullread-only

COMPETITIVE or THEME for a sub-brand; null for a top-level brand.

parent_brand_idType: stringor nullread-only

Id of the parent brand for a sub-brand; null for a top-level brand.

keywordsType: BrandKeywords

The terms this brand uses to monitor social platforms. All arrays are always present, though they may be empty, and are never null.

Show child attributes
keywords.search_termsType: string[]read-only

Plain keywords the brand monitors across platforms, matched as-is (case-insensitive, no operators).

keywords.inclusion_termsType: string[]read-only

Terms that must be present for content to match.

keywords.exclusion_termsType: string[]read-only

Terms that disqualify content from matching, even when other criteria are met.

keywords.compound_inclusion_termsType: string[]read-only

Secondary inclusion terms layered on top of inclusion_terms. A match requires at least one term from inclusion_terms and at least one from compound_inclusion_terms.

keywords.influencer_termsType: string[]read-only

Terms that mark matched content as influencer content (for example, sponsored, ad, or gifted).

keywords.allowed_languagesType: string[]read-only

ISO 639-1 codes for the languages the brand tracks. An empty array indicates that all languages are tracked.

keywords.boolean_queryType: stringor nullread-only

Full-text search across the caption, transcript, summary, and hashtags.

Syntax

  • Multiple words are combined with AND: nike running matches content containing both nike and running.
  • OR (case-insensitive) matches either side: nike OR adidas.
  • NOT (case-insensitive) excludes a term: running NOT marathon matches running but not marathon.
  • Wrap a phrase in double quotes to match the words in order: "summer collection".
  • Negate a phrase with NOT: NOT "out of stock".
  • Group with parentheses to combine operators: (nike OR adidas) running.
  • ONEAR/n (case-insensitive) matches terms within n words of each other, in order: apple ONEAR/2 watch matches apple watch and apple smart watch, but not watch ... apple. It binds more tightly than AND and OR, so apple ONEAR/2 watch AND cheap is interpreted as (apple near watch) AND cheap.

Examples

  • nike running - contains both terms.
  • nike OR adidas - contains either brand.
  • "summer sale" NOT clearance - the exact phrase, without clearance.
  • (running OR cycling) NOT "beginner guide" - either sport, excluding the phrase.
  • apple ONEAR/2 watch - apple within two words before watch.

Content matching this query is connected to (associated with) this brand.

Responses

Brand

idType: stringread-only

Unique identifier for the brand. Supply it wherever a brand_id accepts a brand id.

titleType: string

Display name of the brand.

is_primaryType: boolean

true for the brand this access belongs to, and false for every other brand the request can access.

sub_brand_typeType: stringor nullread-only

COMPETITIVE or THEME for a sub-brand; null for a top-level brand.

parent_brand_idType: stringor nullread-only

Id of the parent brand for a sub-brand; null for a top-level brand.

keywordsType: BrandKeywords

The terms this brand uses to monitor social platforms. All arrays are always present, though they may be empty, and are never null.

Show child attributes
keywords.search_termsType: string[]read-only

Plain keywords the brand monitors across platforms, matched as-is (case-insensitive, no operators).

keywords.inclusion_termsType: string[]read-only

Terms that must be present for content to match.

keywords.exclusion_termsType: string[]read-only

Terms that disqualify content from matching, even when other criteria are met.

keywords.compound_inclusion_termsType: string[]read-only

Secondary inclusion terms layered on top of inclusion_terms. A match requires at least one term from inclusion_terms and at least one from compound_inclusion_terms.

keywords.influencer_termsType: string[]read-only

Terms that mark matched content as influencer content (for example, sponsored, ad, or gifted).

keywords.allowed_languagesType: string[]read-only

ISO 639-1 codes for the languages the brand tracks. An empty array indicates that all languages are tracked.

keywords.boolean_queryType: stringor nullread-only

Full-text search across the caption, transcript, summary, and hashtags.

Syntax

  • Multiple words are combined with AND: nike running matches content containing both nike and running.
  • OR (case-insensitive) matches either side: nike OR adidas.
  • NOT (case-insensitive) excludes a term: running NOT marathon matches running but not marathon.
  • Wrap a phrase in double quotes to match the words in order: "summer collection".
  • Negate a phrase with NOT: NOT "out of stock".
  • Group with parentheses to combine operators: (nike OR adidas) running.
  • ONEAR/n (case-insensitive) matches terms within n words of each other, in order: apple ONEAR/2 watch matches apple watch and apple smart watch, but not watch ... apple. It binds more tightly than AND and OR, so apple ONEAR/2 watch AND cheap is interpreted as (apple near watch) AND cheap.

Examples

  • nike running - contains both terms.
  • nike OR adidas - contains either brand.
  • "summer sale" NOT clearance - the exact phrase, without clearance.
  • (running OR cycling) NOT "beginner guide" - either sport, excluding the phrase.
  • apple ONEAR/2 watch - apple within two words before watch.

Content matching this query is connected to (associated with) this brand.

from zelf import ZelfAPIClient

client = ZelfAPIClient(api_key="<your-api-key>")

result = client.brands.list()
print(result)
Response
{
  "log_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "timestamp": "2026-01-01T00:00:00Z",
  "results": [
    {
      "id": "brd_Lw6ZZmNYhW0P9k0x",
      "title": "Zelf",
      "is_primary": true,
      "sub_brand_type": null,
      "parent_brand_id": null,
      "keywords": {
        "search_terms": [
          "zelf",
          "zelfai"
        ],
        "inclusion_terms": [
          "creator",
          "influencer"
        ],
        "exclusion_terms": [
          "giveaway"
        ],
        "compound_inclusion_terms": [
          "marketing"
        ],
        "influencer_terms": [
          "sponsored",
          "ad",
          "gifted"
        ],
        "allowed_languages": [
          "en"
        ],
        "boolean_query": "python"
      }
    }
  ],
  "item_count": 1,
  "page": 1,
  "next": null,
  "previous": null
}

Update Brand

PATCH/api/v1/brands/brands.update

Partially updates a brand's monitoring keywords. Only the supplied fields are modified.

Targets the brand the key acts on unless brand_id is provided in the request body.

Any brand listed by brands.list is a valid target. That list holds every brand linked to the key, each linked brand's sub-brands, and the key's own brand. A single key therefore reaches whole brand families, often dozens of brands, and this endpoint writes to all of them. Returns the updated brand.

Request body

search_termsType: string[]

Plain keywords the brand monitors across platforms, matched as-is (case-insensitive, no operators).

inclusion_termsType: string[]

Terms that must be present for content to match.

exclusion_termsType: string[]

Terms that disqualify content from matching.

compound_inclusion_termsType: string[]

Secondary inclusion terms layered on top of inclusion_terms.

influencer_termsType: string[]

Terms that mark matched content as influencer content.

allowed_languagesType: string[]

ISO 639-1 codes to track, or the single value all. An empty array means all languages are tracked. A code outside ISO 639-1 is rejected, because a brand tracking it would match no content.

boolean_queryType: stringor null

Full-text search across the caption, transcript, summary, and hashtags.

Syntax

  • Multiple words are combined with AND: nike running matches content containing both nike and running.
  • OR (case-insensitive) matches either side: nike OR adidas.
  • NOT (case-insensitive) excludes a term: running NOT marathon matches running but not marathon.
  • Wrap a phrase in double quotes to match the words in order: "summer collection".
  • Negate a phrase with NOT: NOT "out of stock".
  • Group with parentheses to combine operators: (nike OR adidas) running.
  • ONEAR/n (case-insensitive) matches terms within n words of each other, in order: apple ONEAR/2 watch matches apple watch and apple smart watch, but not watch ... apple. It binds more tightly than AND and OR, so apple ONEAR/2 watch AND cheap is interpreted as (apple near watch) AND cheap.

Examples

  • nike running - contains both terms.
  • nike OR adidas - contains either brand.
  • "summer sale" NOT clearance - the exact phrase, without clearance.
  • (running OR cycling) NOT "beginner guide" - either sport, excluding the phrase.
  • apple ONEAR/2 watch - apple within two words before watch.

Content matching this query is connected to (associated with) this brand.

brand_idType: stringmin length 1

Brand to update, specified as an id from brands.list. Omit to update the workspace brand.

min length
1

Returns Brand

idType: stringread-only

Unique identifier for the brand. Supply it wherever a brand_id accepts a brand id.

titleType: string

Display name of the brand.

is_primaryType: boolean

true for the brand this access belongs to, and false for every other brand the request can access.

sub_brand_typeType: stringor nullread-only

COMPETITIVE or THEME for a sub-brand; null for a top-level brand.

parent_brand_idType: stringor nullread-only

Id of the parent brand for a sub-brand; null for a top-level brand.

keywordsType: BrandKeywords

The terms this brand uses to monitor social platforms. All arrays are always present, though they may be empty, and are never null.

Show child attributes
keywords.search_termsType: string[]read-only

Plain keywords the brand monitors across platforms, matched as-is (case-insensitive, no operators).

keywords.inclusion_termsType: string[]read-only

Terms that must be present for content to match.

keywords.exclusion_termsType: string[]read-only

Terms that disqualify content from matching, even when other criteria are met.

keywords.compound_inclusion_termsType: string[]read-only

Secondary inclusion terms layered on top of inclusion_terms. A match requires at least one term from inclusion_terms and at least one from compound_inclusion_terms.

keywords.influencer_termsType: string[]read-only

Terms that mark matched content as influencer content (for example, sponsored, ad, or gifted).

keywords.allowed_languagesType: string[]read-only

ISO 639-1 codes for the languages the brand tracks. An empty array indicates that all languages are tracked.

keywords.boolean_queryType: stringor nullread-only

Full-text search across the caption, transcript, summary, and hashtags.

Syntax

  • Multiple words are combined with AND: nike running matches content containing both nike and running.
  • OR (case-insensitive) matches either side: nike OR adidas.
  • NOT (case-insensitive) excludes a term: running NOT marathon matches running but not marathon.
  • Wrap a phrase in double quotes to match the words in order: "summer collection".
  • Negate a phrase with NOT: NOT "out of stock".
  • Group with parentheses to combine operators: (nike OR adidas) running.
  • ONEAR/n (case-insensitive) matches terms within n words of each other, in order: apple ONEAR/2 watch matches apple watch and apple smart watch, but not watch ... apple. It binds more tightly than AND and OR, so apple ONEAR/2 watch AND cheap is interpreted as (apple near watch) AND cheap.

Examples

  • nike running - contains both terms.
  • nike OR adidas - contains either brand.
  • "summer sale" NOT clearance - the exact phrase, without clearance.
  • (running OR cycling) NOT "beginner guide" - either sport, excluding the phrase.
  • apple ONEAR/2 watch - apple within two words before watch.

Content matching this query is connected to (associated with) this brand.

Responses

Brand

idType: stringread-only

Unique identifier for the brand. Supply it wherever a brand_id accepts a brand id.

titleType: string

Display name of the brand.

is_primaryType: boolean

true for the brand this access belongs to, and false for every other brand the request can access.

sub_brand_typeType: stringor nullread-only

COMPETITIVE or THEME for a sub-brand; null for a top-level brand.

parent_brand_idType: stringor nullread-only

Id of the parent brand for a sub-brand; null for a top-level brand.

keywordsType: BrandKeywords

The terms this brand uses to monitor social platforms. All arrays are always present, though they may be empty, and are never null.

Show child attributes
keywords.search_termsType: string[]read-only

Plain keywords the brand monitors across platforms, matched as-is (case-insensitive, no operators).

keywords.inclusion_termsType: string[]read-only

Terms that must be present for content to match.

keywords.exclusion_termsType: string[]read-only

Terms that disqualify content from matching, even when other criteria are met.

keywords.compound_inclusion_termsType: string[]read-only

Secondary inclusion terms layered on top of inclusion_terms. A match requires at least one term from inclusion_terms and at least one from compound_inclusion_terms.

keywords.influencer_termsType: string[]read-only

Terms that mark matched content as influencer content (for example, sponsored, ad, or gifted).

keywords.allowed_languagesType: string[]read-only

ISO 639-1 codes for the languages the brand tracks. An empty array indicates that all languages are tracked.

keywords.boolean_queryType: stringor nullread-only

Full-text search across the caption, transcript, summary, and hashtags.

Syntax

  • Multiple words are combined with AND: nike running matches content containing both nike and running.
  • OR (case-insensitive) matches either side: nike OR adidas.
  • NOT (case-insensitive) excludes a term: running NOT marathon matches running but not marathon.
  • Wrap a phrase in double quotes to match the words in order: "summer collection".
  • Negate a phrase with NOT: NOT "out of stock".
  • Group with parentheses to combine operators: (nike OR adidas) running.
  • ONEAR/n (case-insensitive) matches terms within n words of each other, in order: apple ONEAR/2 watch matches apple watch and apple smart watch, but not watch ... apple. It binds more tightly than AND and OR, so apple ONEAR/2 watch AND cheap is interpreted as (apple near watch) AND cheap.

Examples

  • nike running - contains both terms.
  • nike OR adidas - contains either brand.
  • "summer sale" NOT clearance - the exact phrase, without clearance.
  • (running OR cycling) NOT "beginner guide" - either sport, excluding the phrase.
  • apple ONEAR/2 watch - apple within two words before watch.

Content matching this query is connected to (associated with) this brand.

Request

string[]
string[]
string[]
from zelf import ZelfAPIClient

client = ZelfAPIClient(api_key="<your-api-key>")

result = client.brands.update(
    search_terms=["zelf", "zelfai"],
    inclusion_terms=["creator", "influencer"],
    exclusion_terms=["giveaway"],
    compound_inclusion_terms=["marketing"],
    influencer_terms=["sponsored", "ad", "gifted"],
    allowed_languages=["en"],
    boolean_query="python",
    brand_id="brd_Lw6ZZmNYhW0P9k0x",
)
print(result)
Response
{
  "log_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "timestamp": "2026-01-01T00:00:00Z",
  "results": [
    {
      "id": "brd_Lw6ZZmNYhW0P9k0x",
      "title": "Zelf",
      "is_primary": true,
      "sub_brand_type": null,
      "parent_brand_id": null,
      "keywords": {
        "search_terms": [
          "zelf",
          "zelfai"
        ],
        "inclusion_terms": [
          "creator",
          "influencer"
        ],
        "exclusion_terms": [
          "giveaway"
        ],
        "compound_inclusion_terms": [
          "marketing"
        ],
        "influencer_terms": [
          "sponsored",
          "ad",
          "gifted"
        ],
        "allowed_languages": [
          "en"
        ],
        "boolean_query": "python"
      }
    }
  ],
  "item_count": 1,
  "page": 1,
  "next": null,
  "previous": null
}

Add Brand Accounts

POST/api/v1/brands/accounts/brand_accounts.add

Adds profiles to a brand's tracked, influencer or owned list. Use owned for the brand's own profiles.

Each profile_url is matched and deduplicated by (platform, username), so re-adding an existing account has no effect. URLs that cannot be parsed fail validation on profile_urls.

Supply brand_id in the request body to target another brand; otherwise the brand the key acts on is used. Any brand listed by brands.list is a valid target, which includes linked top-level brands and their sub-brands.

Request body

brand_idType: stringmin length 1

Brand to modify, specified as an id from brands.list. Omit to modify the workspace brand.

min length
1
account_typeType: enumRequired

The list to modify: tracked, influencer, or owned for the brand's own profiles.

Show values
trackedinfluencerowned
profile_urlsType: string(uri)[]Required

Profile URLs on a supported platform (instagram, tiktok or youtube).

Returns BrandAccountGroups

trackedType: BrandAccount[]

Accounts the brand monitors.

Show child attributes
tracked[].usernameType: string

The account's handle.

tracked[].platformType: string

instagram, tiktok or youtube.

tracked[].external_urlType: stringor null

The account's profile URL, when available.

influencerType: BrandAccount[]

Accounts the brand treats as partnership candidates.

Show child attributes
influencer[].usernameType: string

The account's handle.

influencer[].platformType: string

instagram, tiktok or youtube.

influencer[].external_urlType: stringor null

The account's profile URL, when available.

ownedType: BrandAccount[]

Profiles the brand operates itself.

Show child attributes
owned[].usernameType: string

The account's handle.

owned[].platformType: string

instagram, tiktok or youtube.

owned[].external_urlType: stringor null

The account's profile URL, when available.

Responses

BrandAccountGroups

trackedType: BrandAccount[]

Accounts the brand monitors.

Show child attributes
tracked[].usernameType: string

The account's handle.

tracked[].platformType: string

instagram, tiktok or youtube.

tracked[].external_urlType: stringor null

The account's profile URL, when available.

influencerType: BrandAccount[]

Accounts the brand treats as partnership candidates.

Show child attributes
influencer[].usernameType: string

The account's handle.

influencer[].platformType: string

instagram, tiktok or youtube.

influencer[].external_urlType: stringor null

The account's profile URL, when available.

ownedType: BrandAccount[]

Profiles the brand operates itself.

Show child attributes
owned[].usernameType: string

The account's handle.

owned[].platformType: string

instagram, tiktok or youtube.

owned[].external_urlType: stringor null

The account's profile URL, when available.

Request

string
enumRequired
string(uri)[]Required
from zelf import ZelfAPIClient

client = ZelfAPIClient(api_key="<your-api-key>")

result = client.brand_accounts.add(
    brand_id="brd_Lw6ZZmNYhW0P9k0x",
    account_type="tracked",
    profile_urls=["https://www.instagram.com/zelfai"],
)
print(result)
Response
{
  "log_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "timestamp": "2026-01-01T00:00:00Z",
  "results": [
    {
      "tracked": [
        {
          "username": "zelfai",
          "platform": "instagram",
          "external_url": "https://www.instagram.com/zelfai"
        }
      ],
      "influencer": [
        {
          "username": "zelfai",
          "platform": "instagram",
          "external_url": "https://www.instagram.com/zelfai"
        }
      ],
      "owned": [
        {
          "username": "zelfai",
          "platform": "instagram",
          "external_url": "https://www.instagram.com/zelfai"
        }
      ]
    }
  ],
  "item_count": 1,
  "page": 1,
  "next": null,
  "previous": null
}

List Brand Accounts

GET/api/v1/brands/accounts/brand_accounts.list

Returns a brand's tracked and influencer creator accounts, plus the owned accounts the brand operates itself.

Defaults to the brand the key acts on. Supply brand_id to target another brand listed by brands.list, which includes linked top-level brands and their sub-brands. Restrict the response to a single list with the account_type parameter (tracked, influencer or owned).

Parameters

brand_idType: string

Identifies the brand to operate on. Defaults to the brand the key acts on when brand_id is omitted. Every id returned by brands.list is accepted. That set includes linked top-level brands and their sub-brands, not only sub-brands. Returns INVALID_ID if the value is malformed, and 403 for a brand outside the key's reach.

account_typeType: enum

Restricts the response to a single list (tracked, influencer or owned).

Show values
influencerownedtracked

Returns BrandAccountGroups

trackedType: BrandAccount[]

Accounts the brand monitors.

Show child attributes
tracked[].usernameType: string

The account's handle.

tracked[].platformType: string

instagram, tiktok or youtube.

tracked[].external_urlType: stringor null

The account's profile URL, when available.

influencerType: BrandAccount[]

Accounts the brand treats as partnership candidates.

Show child attributes
influencer[].usernameType: string

The account's handle.

influencer[].platformType: string

instagram, tiktok or youtube.

influencer[].external_urlType: stringor null

The account's profile URL, when available.

ownedType: BrandAccount[]

Profiles the brand operates itself.

Show child attributes
owned[].usernameType: string

The account's handle.

owned[].platformType: string

instagram, tiktok or youtube.

owned[].external_urlType: stringor null

The account's profile URL, when available.

Responses

BrandAccountGroups

trackedType: BrandAccount[]

Accounts the brand monitors.

Show child attributes
tracked[].usernameType: string

The account's handle.

tracked[].platformType: string

instagram, tiktok or youtube.

tracked[].external_urlType: stringor null

The account's profile URL, when available.

influencerType: BrandAccount[]

Accounts the brand treats as partnership candidates.

Show child attributes
influencer[].usernameType: string

The account's handle.

influencer[].platformType: string

instagram, tiktok or youtube.

influencer[].external_urlType: stringor null

The account's profile URL, when available.

ownedType: BrandAccount[]

Profiles the brand operates itself.

Show child attributes
owned[].usernameType: string

The account's handle.

owned[].platformType: string

instagram, tiktok or youtube.

owned[].external_urlType: stringor null

The account's profile URL, when available.

Request

string
enum
from zelf import ZelfAPIClient

client = ZelfAPIClient(api_key="<your-api-key>")

result = client.brand_accounts.list()
print(result)
Response
{
  "log_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "timestamp": "2026-01-01T00:00:00Z",
  "results": [
    {
      "tracked": [
        {
          "username": "zelfai",
          "platform": "instagram",
          "external_url": "https://www.instagram.com/zelfai"
        }
      ],
      "influencer": [
        {
          "username": "zelfai",
          "platform": "instagram",
          "external_url": "https://www.instagram.com/zelfai"
        }
      ],
      "owned": [
        {
          "username": "zelfai",
          "platform": "instagram",
          "external_url": "https://www.instagram.com/zelfai"
        }
      ]
    }
  ],
  "item_count": 1,
  "page": 1,
  "next": null,
  "previous": null
}

Remove Brand Accounts

DELETE/api/v1/brands/accounts/brand_accounts.remove

Removes profiles from a brand's tracked, influencer or owned list. This operation is destructive; call it only when the intent is to stop following these accounts.

Profiles are matched by (platform, username) parsed from each profile_url. Returns the updated list.

Supply brand_id in the request body to target another brand; otherwise the brand the key acts on is used. Any brand listed by brands.list is a valid target, which includes linked top-level brands and their sub-brands.

Request body

brand_idType: stringmin length 1

Brand to modify, specified as an id from brands.list. Omit to modify the workspace brand.

min length
1
account_typeType: enumRequired

The list to modify: tracked, influencer, or owned for the brand's own profiles.

Show values
trackedinfluencerowned
profile_urlsType: string(uri)[]Required

Profile URLs on a supported platform (instagram, tiktok or youtube).

Returns BrandAccountGroups

trackedType: BrandAccount[]

Accounts the brand monitors.

Show child attributes
tracked[].usernameType: string

The account's handle.

tracked[].platformType: string

instagram, tiktok or youtube.

tracked[].external_urlType: stringor null

The account's profile URL, when available.

influencerType: BrandAccount[]

Accounts the brand treats as partnership candidates.

Show child attributes
influencer[].usernameType: string

The account's handle.

influencer[].platformType: string

instagram, tiktok or youtube.

influencer[].external_urlType: stringor null

The account's profile URL, when available.

ownedType: BrandAccount[]

Profiles the brand operates itself.

Show child attributes
owned[].usernameType: string

The account's handle.

owned[].platformType: string

instagram, tiktok or youtube.

owned[].external_urlType: stringor null

The account's profile URL, when available.

Responses

BrandAccountGroups

trackedType: BrandAccount[]

Accounts the brand monitors.

Show child attributes
tracked[].usernameType: string

The account's handle.

tracked[].platformType: string

instagram, tiktok or youtube.

tracked[].external_urlType: stringor null

The account's profile URL, when available.

influencerType: BrandAccount[]

Accounts the brand treats as partnership candidates.

Show child attributes
influencer[].usernameType: string

The account's handle.

influencer[].platformType: string

instagram, tiktok or youtube.

influencer[].external_urlType: stringor null

The account's profile URL, when available.

ownedType: BrandAccount[]

Profiles the brand operates itself.

Show child attributes
owned[].usernameType: string

The account's handle.

owned[].platformType: string

instagram, tiktok or youtube.

owned[].external_urlType: stringor null

The account's profile URL, when available.

Request

string
enumRequired
string(uri)[]Required
from zelf import ZelfAPIClient

client = ZelfAPIClient(api_key="<your-api-key>")

result = client.brand_accounts.remove(
    brand_id="brd_Lw6ZZmNYhW0P9k0x",
    account_type="tracked",
    profile_urls=["https://www.instagram.com/zelfai"],
)
print(result)
Response
{
  "log_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "timestamp": "2026-01-01T00:00:00Z",
  "results": [
    {
      "tracked": [
        {
          "username": "zelfai",
          "platform": "instagram",
          "external_url": "https://www.instagram.com/zelfai"
        }
      ],
      "influencer": [
        {
          "username": "zelfai",
          "platform": "instagram",
          "external_url": "https://www.instagram.com/zelfai"
        }
      ],
      "owned": [
        {
          "username": "zelfai",
          "platform": "instagram",
          "external_url": "https://www.instagram.com/zelfai"
        }
      ]
    }
  ],
  "item_count": 1,
  "page": 1,
  "next": null,
  "previous": null
}

Search Brand Catalog

GET/api/v1/brands/catalog/brands.catalog

Returns the brands Zelf curates for competitive benchmarking. Every api key can read content for these brands, whether or not they are linked to yours, so this is where to look for a competitor that is not one of your own sub-brands.

Each row's id is the value to supply as brand_id on the content and AI analysis endpoints; the brand write endpoints do not accept it. Narrow the list with search (title substring), industry_id, or category_id; the id values for the last two come from brands.catalog_categories.

Parameters

order_byType: enum[]unique items true

Sort direction is inverted: order_by=field sorts descending and order_by=-field sorts ascending. Comma-separate to sort by multiple fields.

Show values
unique items
true
title-title
category_idType: string

Category id from brands.catalog_categories. Case is ignored.

industry_idType: string

Industry id from brands.catalog_categories. Case is ignored.

Returns BrandCatalog

idType: stringread-only

Unique identifier for the brand. Supply it as brand_id on the content and AI analysis endpoints to read this brand's content.

titleType: string

Display name of the brand.

industry_idType: stringor null

Identifier of the brand's industry.

industry_nameType: stringor null

Name of the brand's industry.

category_idType: stringor null

Identifier of the brand's category.

category_nameType: stringor null

Name of the brand's category.

Responses

BrandCatalog

idType: stringread-only

Unique identifier for the brand. Supply it as brand_id on the content and AI analysis endpoints to read this brand's content.

titleType: string

Display name of the brand.

industry_idType: stringor null

Identifier of the brand's industry.

industry_nameType: stringor null

Name of the brand's industry.

category_idType: stringor null

Identifier of the brand's category.

category_nameType: stringor null

Name of the brand's category.

Request

string
order_byenum[]
string
from zelf import ZelfAPIClient

client = ZelfAPIClient(api_key="<your-api-key>")

result = client.brands.catalog()
print(result)
Response
{
  "log_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "timestamp": "2026-01-01T00:00:00Z",
  "results": [
    {
      "id": "brd_Lw6ZZmNYhW0P9k0x",
      "title": "Zelf",
      "brand_logo": "https://cdn.hellozelf.com/logos/zelfai.png",
      "industry_id": "C05",
      "industry_name": "Apparel and Fashion",
      "category_id": "C05S04",
      "category_name": "Casual/Everyday Wear"
    }
  ],
  "item_count": 1,
  "page": 1,
  "next": null,
  "previous": null
}

List Brand Catalog Categories

GET/api/v1/brands/catalog/categories/brands.catalog_categories

Returns every industry and the categories under it, as one flat list. An industry has level: industry and a null parent_id; a category has level: category and the parent_id of its industry.

Each id is the value to supply as industry_id or category_id to brands.catalog.

Returns BrandCatalogItem

idType: string

Identifier to pass as industry_id or category_id to brands.catalog.

nameType: string

Display name of the industry or category.

levelType: string

industry or category.

parent_idType: stringor null

Industry id a category belongs to; null for an industry.

Responses

BrandCatalogItem

idType: string

Identifier to pass as industry_id or category_id to brands.catalog.

nameType: string

Display name of the industry or category.

levelType: string

industry or category.

parent_idType: stringor null

Industry id a category belongs to; null for an industry.

from zelf import ZelfAPIClient

client = ZelfAPIClient(api_key="<your-api-key>")

result = client.brands.catalog_categories()
print(result)
Response
{
  "log_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "timestamp": "2026-01-01T00:00:00Z",
  "results": [
    {
      "id": "C05S04",
      "name": "Casual/Everyday Wear",
      "level": "category",
      "parent_id": "C05"
    }
  ],
  "item_count": 1,
  "page": 1,
  "next": null,
  "previous": null
}