Product Documentation
Start typing to search…
  1. API Reference

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 (34)"] --> B["Subcategories (469)"]
    B --> C["Topics (19,579)"]

    A --> A1["Technology"]
    A --> A2["Business"]
    A --> A3["Healthcare"]
    A1 --> B1["Cloud Infrastructure"]
    A1 --> B2["Cybersecurity"]
    B1 --> C1["AWS (B2B)"]
    B1 --> C2["Azure (B2B)"]
    B2 --> C3["Zero Trust (B2B)"]

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

Each topic is classified as B2B or B2C and contains a name, description, and keywords used for intent scoring.

Prerequisites: You need either a JWT token (Authentication) or an API key (Authentication Step 3).

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

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

Authentication

The Taxonomy API accepts two authentication methods:

Option 1: Bearer Token

-H "Authorization: Bearer YOUR_JWT_TOKEN"

Option 2: API Key

-H "X-API-Key: YOUR_API_KEY"

Categories

List Categories

curl "https://apiv2.delivr.ai/taxonomy/categories?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

Response (200 OK)

{
  "response": {
    "categories": [
      {
        "category_id": "cff96418-d30f-4ec1-...",
        "name": "Animal Lovers",
        "status": "active",
        "created_at": "2025-10-19T10:49:38.189079Z",
        "updated_at": null
      }
    ]
  }
}

Get Category by ID

Returns the same fields plus description.

curl "https://apiv2.delivr.ai/taxonomy/categories/YOUR_CATEGORY_ID" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "response": {
    "category_id": "cff96418-d30f-4ec1-...",
    "name": "Animal Lovers",
    "description": "",
    "status": "active",
    "created_at": "2025-10-19T10:49:38.189079Z",
    "updated_at": null
  }
}

Count Categories

curl "https://apiv2.delivr.ai/taxonomy/categories/count" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "response": {
    "count": 34
  }
}

Subcategories

List Subcategories

curl "https://apiv2.delivr.ai/taxonomy/subcategories?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

Query Parameters

ParameterDescription
limitMax results to return
offsetSkip this many results
category_idFilter by parent category

Response (200 OK)

{
  "response": {
    "subcategories": [
      {
        "category_id": "9e93a1bc-db56-483e-...",
        "name": "Accounting",
        "parent_category_id": "ec857c28-e4f4-442a-...",
        "parent_category_name": "Business",
        "status": "active",
        "created_at": "2025-10-19T10:29:22.487497Z",
        "updated_at": null
      }
    ]
  }
}

Get Subcategory by ID

Returns the same fields plus description.

curl "https://apiv2.delivr.ai/taxonomy/subcategories/YOUR_SUBCATEGORY_ID" \
  -H "X-API-Key: YOUR_API_KEY"

Count Subcategories

curl "https://apiv2.delivr.ai/taxonomy/subcategories/count" \
  -H "X-API-Key: YOUR_API_KEY"

Topics

List Topics

curl "https://apiv2.delivr.ai/taxonomy/topics?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

Query Parameters

ParameterDescription
limitMax results to return
offsetSkip this many results
category_idFilter by category
subcategory_idFilter by subcategory
topic_typeFilter by type: B2B or B2C
statusFilter by status: active
searchSearch topics by name

Response (200 OK)

{
  "response": {
    "topics": [
      {
        "topic_id": "4eyes_110486",
        "name": "15Five",
        "category_id": "ec857c28-e4f4-442a-...",
        "category_name": "Business",
        "subcategory_id": "2b9e9070-98f6-446e-...",
        "subcategory_name": "Brands",
        "status": "active",
        "topic_type": "B2B",
        "created_at": "2025-05-16T16:26:56.402159Z",
        "updated_at": "2025-05-16T16:26:56.402159Z"
      }
    ]
  }
}

Get Topic by ID

Returns additional fields: parent, description, and keywords.

curl "https://apiv2.delivr.ai/taxonomy/topics/4eyes_110486" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "response": {
    "topic_id": "4eyes_110486",
    "parent": "Intent",
    "name": "15Five",
    "description": "The audience for the topic of 15Five primarily includes HR professionals, team leaders, and organizational development specialists...",
    "keywords": "15Five performance management employee engagement employee feedback...",
    "category_id": "ec857c28-e4f4-442a-...",
    "category_name": "Business",
    "subcategory_id": "2b9e9070-98f6-446e-...",
    "subcategory_name": "Brands",
    "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://apiv2.delivr.ai/taxonomy/topics/count?search=marketing" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "response": {
    "count": 2369
  }
}

Search Topics

Use the search parameter to find topics by name:

curl "https://apiv2.delivr.ai/taxonomy/topics?search=cloud+computing&limit=5" \
  -H "X-API-Key: YOUR_API_KEY"

Results are returned in relevance order.

Topic Requests

Request new topics to be added to the taxonomy. Processing is manual and may take some time.

List Topic Requests

curl "https://apiv2.delivr.ai/taxonomy/topic-requests?limit=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

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://apiv2.delivr.ai/taxonomy/topic-requests" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -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 or B2C).

Count Topic Requests

curl "https://apiv2.delivr.ai/taxonomy/topic-requests/count" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Endpoint Reference

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

Next Steps

Updated 1 day ago