Catalog API

The Catalog API provides access to AudienceGPT's global topic catalog -- a shared repository of pre-classified audience segments. Organizations can browse, search, and filter the catalog, then selectively add topics to their own library. Topics added from the catalog are linked (not copied), so they benefit from global updates like engine version upgrades and taxonomy improvements.

Browse the Global Catalog

Retrieve a paginated, filtered list of global topics with an inLibrary flag indicating whether each topic is already in your organization's library.

GET /api/topics/catalog

Auth: API key with topics:read scope, or Clerk session

Query Parameters

Parameter	Type	Default	Description
`page`	number	1	Page number
`pageSize`	number	25	Items per page (max 100)
`sortBy`	string	`created_at`	Sort column: `topic_name`, `parent_category`, `segment_type`, `taxonomy_type`, `audience_type`, `created_at`
`sortOrder`	string	`desc`	`asc` or `desc`
`search`	string	--	Free-text search across topic names, taxonomy paths, and keywords. Multi-word queries use AND matching (all words must appear).
`parentCategory`	string	--	Filter by parent category (41 types, e.g., "Auto", "Insurance")
`taxonomyType`	string	--	Filter by taxonomy type group (13 groups)
`segmentType`	string	--	`B2B`, `B2C`, `B2B2C`, `B2E`, `B2G`
`audienceType`	string	--	Filter by audience type (14 types)
`subcategory`	string	--	Filter by subcategory (L0 tree node)
`subcategoryL1`	string	--	Filter by subcategory L1 level
`subcategoryL2`	string	--	Filter by subcategory L2 level
`subcategoryL3`	string	--	Filter by subcategory L3 level
`subcategoryL4`	string	--	Filter by subcategory L4 level
`hasExternalId`	boolean	--	Filter to topics with external IDs (imported/synced topics)
`inLibrary`	boolean	--	`true` for topics already in your library, `false` for topics not yet added

Response (200)

{
  "data": [
    {
      "id": "tp_01hy...",
      "topicName": "Tesla Model 3 Buyers",
      "parentCategory": "Auto",
      "taxonomyType": "Automotive & Vehicles",
      "subcategory": "Electric Vehicles",
      "segmentType": "B2C",
      "audienceType": "In-Market Buyers",
      "iabCode": "IAB2",
      "engineVersion": "2.5",
      "createdAt": "2026-02-01T10:00:00.000Z",
      "inLibrary": false
    },
    {
      "id": "tp_02ab...",
      "topicName": "BMW X5 Shoppers",
      "parentCategory": "Auto",
      "taxonomyType": "Automotive & Vehicles",
      "subcategory": "Luxury Vehicles",
      "segmentType": "B2C",
      "audienceType": "In-Market Buyers",
      "iabCode": "IAB2",
      "engineVersion": "2.5",
      "createdAt": "2026-01-15T08:00:00.000Z",
      "inLibrary": true
    }
  ],
  "total": 2,
  "page": 1,
  "pageSize": 25,
  "totalPages": 1
}

curl Example

# Search for automotive topics not yet in your library
curl "https://app.audiencegpt.com/api/topics/catalog?search=electric+vehicle&parentCategory=Auto&inLibrary=false" \
  -H "Authorization: Bearer txadv_your_api_key"

TypeScript Example

async function searchCatalog(query: string, filters: Record<string, string> = {}) {
  const params = new URLSearchParams({
    search: query,
    pageSize: "50",
    ...filters,
  });

  const response = await fetch(
    `https://app.audiencegpt.com/api/topics/catalog?${params}`,
    { headers: { "Authorization": `Bearer ${API_KEY}` } }
  );

  return response.json();
}

// Search for B2B technology topics not in library
const results = await searchCatalog("cloud computing", {
  segmentType: "B2B",
  inLibrary: "false",
});

Get distinct filter values available in the global catalog for building filter UIs.

GET /api/topics/catalog/facets

Auth: API key with topics:read scope, or Clerk session

Response (200)

{
  "parentCategories": ["Auto", "Business Technology", "Insurance", "Real Estate"],
  "taxonomyTypes": ["Automotive & Vehicles", "Technology & Telecom", "Financial Services"],
  "subcategories": ["Electric Vehicles", "Cloud Computing", "Cybersecurity"],
  "subcategoryL1s": ["Battery Technology", "SaaS Platforms"],
  "subcategoryL2s": [],
  "subcategoryL3s": [],
  "subcategoryL4s": [],
  "audienceTypes": ["In-Market Buyers", "Business Decision Makers", "Technology Infrastructure Buyers"],
  "segmentTypes": ["B2B", "B2C", "B2B2C"]
}

info

Subcategory facets in the catalog are sourced from the taxonomy tree (Level 0 nodes) rather than raw topic values, ensuring a clean and consistent filter list.

Add Topics to Library

Add global catalog topics to your organization's library. Supports two modes: ID-based (specific topics) and filter-based (bulk add all matching topics).

POST /api/topics/catalog

Auth: API key with topics:write scope, or Clerk session

Option 1: Add by Topic IDs

{
  "topicIds": ["tp_01hy...", "tp_02ab...", "tp_03cd..."]
}

Field	Type	Required	Description
`topicIds`	string[]	Yes	Global topic IDs to add (max 500 per request)

Response (200)

{
  "added": 3
}

Option 2: Add by Filters (Bulk)

Add all topics matching the specified filters at once.

{
  "filters": {
    "search": "electric vehicle",
    "parentCategory": "Auto",
    "segmentType": "B2C"
  }
}

Field	Type	Required	Description
`filters.search`	string	No	Free-text search filter
`filters.parentCategory`	string	No	Parent category filter (41 types)
`filters.taxonomyType`	string	No	Taxonomy type filter (13 groups)
`filters.subcategory`	string	No	Subcategory filter (L0 tree node)
`filters.segmentType`	string	No	Segment type filter
`filters.audienceType`	string	No	Audience type filter

Response (200)

{
  "added": 47
}

tip

Filter-based bulk add uses an efficient single-query INSERT...SELECT that skips topics already in your library. This is much faster than adding topics one by one for large catalog selections.

curl Example

# Add specific topics by ID
curl -X POST https://app.audiencegpt.com/api/topics/catalog \
  -H "Authorization: Bearer txadv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"topicIds": ["tp_01hy...", "tp_02ab..."]}'

# Bulk add all automotive B2C topics
curl -X POST https://app.audiencegpt.com/api/topics/catalog \
  -H "Authorization: Bearer txadv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"filters": {"parentCategory": "Auto", "segmentType": "B2C"}}'

TypeScript Example

// Add specific topics from catalog
async function addFromCatalog(topicIds: string[]) {
  const response = await fetch("https://app.audiencegpt.com/api/topics/catalog", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ topicIds }),
  });

  const { added } = await response.json();
  console.log(`Added ${added} topics to library`);
  return added;
}

// Bulk add all matching topics
async function bulkAddFromCatalog(filters: Record<string, string>) {
  const response = await fetch("https://app.audiencegpt.com/api/topics/catalog", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ filters }),
  });

  const { added } = await response.json();
  console.log(`Bulk added ${added} topics to library`);
  return added;
}

Error Responses

Status	Body	Description
400	`{"error": "topicIds array or filters object required"}`	Missing both topicIds and filters
401	`{"error": "Unauthorized"}`	Invalid credentials
500	`{"error": "Failed to list catalog topics"}`	Server error
500	`{"error": "Failed to add topics to library"}`	Insert error

Next Steps

Topics API -- Manage topics after adding from catalog
Classify API -- Classify custom topics not in the catalog
Import API -- Bulk import from external CSV files
Activations API -- Push catalog topics to DSP platforms

Browse the Global Catalog​

Query Parameters​

Response (200)​

curl Example​

TypeScript Example​

Catalog Facets​

Response (200)​

Add Topics to Library​

Option 1: Add by Topic IDs​

Response (200)​

Option 2: Add by Filters (Bulk)​

Response (200)​

curl Example​

TypeScript Example​

Error Responses​

Next Steps​

Browse the Global Catalog

Query Parameters

Response (200)

curl Example

TypeScript Example

Catalog Facets

Response (200)

Add Topics to Library

Option 1: Add by Topic IDs

Response (200)

Option 2: Add by Filters (Bulk)

Response (200)

curl Example

TypeScript Example

Error Responses

Next Steps