Product Documentation
  1. Build Audiences

Taxonomy API

Overview

The Taxonomy API gives you read-only access to Delivr.ai's intent topic catalog. Use it to browse categories, subcategories, and topics, or to request new topics.

The taxonomy is organized as a three-level hierarchy:

Taxonomy hierarchy: 26 categories contain 298 subcategories, which contain 50,000+ topics. For example, the category Computers and Electronics, beside Business and Industrial and Health, has the subcategory Computer Security, with the topics Zero Trust (B2B) and AWS Security (B2B), and the subcategory Enterprise Technology, with the topic AWS Data Exchange (B2B).

Each topic has a type (B2B, B2C, B2B2C, B2G or B2E) and contains a name, description, and keywords used for intent scoring.

Prerequisites: An organization API key + secret pair. Create one in the dashboard at https://app.delivr.ai/{org_id}/settings/api-keys (see Authentication).

Base URL: https://api.delivr.ai

The Taxonomy API is only available on api.delivr.ai.

Authentication

The Taxonomy API authenticates with an organization API key. Send both headers on every request:

-H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET"

Create the key + secret in the dashboard at https://app.delivr.ai/{org_id}/settings/api-keys.

Categories

List Categories

curl "https://api.delivr.ai/api/v1/taxonomy/categories?limit=10" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET"

Response (200 OK)

{
  "response": {
    "categories": [
      {
        "category_id": "698289da-287c-5d77-...",
        "name": "Pets & Animals",
        "status": "active",
        "created_at": "2026-10-15T07:34:34.723134Z",
        "updated_at": "2026-10-15T07:34:34.723134Z"
      }
    ]
  }
}

Get Category by ID

Returns the same fields plus description.

curl "https://api.delivr.ai/api/v1/taxonomy/categories/YOUR_CATEGORY_ID" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET"

Response

{
  "response": {
    "category_id": "698289da-287c-5d77-...",
    "name": "Pets & Animals",
    "description": "Animals, living pets and their care. Robotic, electronic and simulated toy pets belong to Shopping & Retailers / Toys.",
    "status": "active",
    "created_at": "2026-10-15T07:34:34.723134Z",
    "updated_at": "2026-10-15T07:34:34.723134Z"
  }
}

Count Categories

curl "https://api.delivr.ai/api/v1/taxonomy/categories/count" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET"

Response

{
  "response": {
    "count": 26
  }
}

Subcategories

List Subcategories

curl "https://api.delivr.ai/api/v1/taxonomy/subcategories?limit=10" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET"

Query Parameters

ParameterDescription
limitMax results to return, up to 100. A larger value is reduced to 100 rather than refused. Omit it and every matching row is returned, which for topics is the whole catalog.
offsetSkip this many results
category_idFilter by parent category

Response (200 OK)

{
  "response": {
    "subcategories": [
      {
        "category_id": "841019ca-5689-5a22-...",
        "name": "Business Operations",
        "parent_category_id": "6d080b12-409b-5874-...",
        "parent_category_name": "Business & Industrial",
        "status": "active",
        "created_at": "2026-10-15T07:34:34.723134Z",
        "updated_at": "2026-10-15T07:34:34.723134Z"
      }
    ]
  }
}

Get Subcategory by ID

Returns the same fields plus description.

curl "https://api.delivr.ai/api/v1/taxonomy/subcategories/YOUR_SUBCATEGORY_ID" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET"

Count Subcategories

curl "https://api.delivr.ai/api/v1/taxonomy/subcategories/count" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET"

Topics

List Topics

curl "https://api.delivr.ai/api/v1/taxonomy/topics?limit=10" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET"

Query Parameters

ParameterDescription
limitMax results to return, up to 100. A larger value is reduced to 100 rather than refused. Omit it and every matching row is returned, which for topics is the whole catalog.
offsetSkip this many results
category_idFilter by category
subcategory_idFilter by subcategory
topic_typeFilter by type: B2B, B2C, B2B2C, B2G or B2E
statusHas no effect for API keys: only active topics are ever returned
searchSearch topics by name

Response (200 OK)

{
  "response": {
    "topics": [
      {
        "topic_id": "4eyes_110486",
        "name": "15Five",
        "category_id": "6d080b12-409b-5874-...",
        "category_name": "Business & Industrial",
        "subcategory_id": "841019ca-5689-5a22-...",
        "subcategory_name": "Business Operations",
        "status": "active",
        "topic_type": "B2B",
        "created_at": "2025-05-16T16:26:56.402159Z",
        "updated_at": "2026-10-16T06:56:09.160075Z"
      }
    ]
  }
}

Get Topic by ID

Returns additional fields: parent, description, and keywords.

curl "https://api.delivr.ai/api/v1/taxonomy/topics/4eyes_110486" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET"

Response

{
  "response": {
    "topic_id": "4eyes_110486",
    "parent": "Intent",
    "name": "15Five",
    "description": "15Five is a performance management and employee engagement platform. It offers weekly check-ins, performance reviews, OKR tracking...",
    "keywords": "15five, 15five performance management, 15five check ins, 15five engagement surveys, ...",
    "category_id": "6d080b12-409b-5874-...",
    "category_name": "Business & Industrial",
    "subcategory_id": "841019ca-5689-5a22-...",
    "subcategory_name": "Business Operations",
    "status": "active",
    "topic_type": "B2B",
    "created_at": "2025-05-16T16:26:56.402159Z"
  }
}

Count Topics

Supports the same filters as list. Use search to count matching topics.

curl "https://api.delivr.ai/api/v1/taxonomy/topics/count?search=marketing" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET"

Response

{
  "response": {
    "count": 2251
  }
}

Search Topics

Use the search parameter to find topics by name:

curl "https://api.delivr.ai/api/v1/taxonomy/topics?search=cloud+computing&limit=5" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET"

Results are returned in relevance order.

Topic Requests

Request new topics to be added to the taxonomy. Requests are reviewed and published automatically, usually within an hour. A request whose place in the catalog is unclear is held for review by our team, and some requests are declined. Check a request's status with List Topic Requests below.

A new topic collects intent from the day it is published. Research before that day is not added afterwards, so request a topic as soon as you know you need it.

List Topic Requests

curl "https://api.delivr.ai/api/v1/taxonomy/topic-requests?limit=10" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET"

Response (200 OK)

{
  "response": {
    "requests": [
      {
        "topic_id": "4eyes_502110",
        "name": "Public Relations & Brand Reputation Management",
        "status": "approved",
        "segment_type": "B2B",
        "category": "Business Services",
        "category_id": "27fab684-1e8e-4622-...",
        "subcategory": "Marketing",
        "subcategory_id": "71770c39-d0e2-468d-...",
        "keyword_set": "Public Relations, Brand Reputation, ...",
        "suggested_topic_name": "Corporate Communications & Brand Management",
        "suggested_topic_names": "Corporate Communications & Brand Management, ...",
        "suggested_description": "This topic focuses on...",
        "created_at": "2025-12-02T16:21:50.628641Z"
      }
    ]
  }
}

Create Topic Request

curl -X POST "https://api.delivr.ai/api/v1/taxonomy/topic-requests" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Your Topic Name",
    "description": "Description of the topic and target audience.",
    "type": "B2B"
  }'

Required fields: name, description, type (B2B, B2C, B2B2C, B2G or B2E). email is optional. Submitting a name that already has a request returns 200 with the existing request instead of creating a duplicate.

Count Topic Requests

curl "https://api.delivr.ai/api/v1/taxonomy/topic-requests/count" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET"

Endpoint Reference

MethodEndpointDescription
GET/api/v1/taxonomy/categoriesList categories
GET/api/v1/taxonomy/categories/{id}Get category by ID
GET/api/v1/taxonomy/categories/countCount categories
GET/api/v1/taxonomy/subcategoriesList subcategories
GET/api/v1/taxonomy/subcategories/{id}Get subcategory by ID
GET/api/v1/taxonomy/subcategories/countCount subcategories
GET/api/v1/taxonomy/topicsList topics
GET/api/v1/taxonomy/topics/{id}Get topic by ID
GET/api/v1/taxonomy/topics/countCount topics
GET/api/v1/taxonomy/topic-requestsList topic requests
POST/api/v1/taxonomy/topic-requestsCreate topic request
GET/api/v1/taxonomy/topic-requests/countCount topic requests

Next Steps

Updated 11 days ago

Did this page help you?