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:

flowchart TD
    A["Categories (26)"] --> B["Subcategories (298)"]
    B --> C["Topics (50,000+)"]

    A --> A1["Computers & Electronics"]
    A --> A2["Business & Industrial"]
    A --> A3["Health"]
    A1 --> B1["Computer Security"]
    A1 --> B2["Enterprise Technology"]
    B1 --> C1["Zero Trust (B2B)"]
    B1 --> C2["AWS Security (B2B)"]
    B2 --> C3["AWS Data Exchange (B2B)"]

    style A fill:#3b82f6,color:#fff
    style B fill:#6366f1,color:#fff
    style C fill:#8b5cf6,color:#fff

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 5 days ago

Did this page help you?