---
updatedAt: 2026-06-25T05:56:48.000Z
agentTools:
  projectIndex: https://docs.delivr.ai/llms.txt
---

# List categories

Returns the top-level intent taxonomy categories.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Intent Audiences",
    "description": "Build and export person-level intent audiences end to end. Browse the topic **taxonomy** to find what your buyers research, discover the **fields** you can filter on, then create, manage, sample, and download **audiences**.\n\n**Authentication:** organization API key (`X-Api-Key` + `X-Api-Secret`). Audiences are project-scoped: name the project with the `X-Project-Id` header or a `?project_id=` query parameter (equivalent). (Legacy JWT bearer auth still works but is deprecated.)\n\n**Base URL:** `https://api.delivr.ai`\n",
    "version": "1.0",
    "contact": {
      "name": "Delivr.ai Support",
      "url": "https://delivr.ai"
    }
  },
  "servers": [
    {
      "url": "https://api.delivr.ai",
      "description": "Production"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": [],
      "ApiSecretAuth": []
    }
  ],
  "tags": [
    {
      "name": "Taxonomy",
      "description": "Browse the intent topic catalog: categories, subcategories, topics, and topic requests."
    }
  ],
  "paths": {
    "/api/v1/taxonomy/categories": {
      "get": {
        "tags": [
          "Taxonomy"
        ],
        "summary": "List categories",
        "operationId": "listCategories",
        "description": "Returns the top-level intent taxonomy categories.",
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "description": "Category name prefix filter.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Category status filter.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "date_from",
            "in": "query",
            "description": "Filter by updated_at >= this date (YYYY-MM-DD, UTC).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "date_to",
            "in": "query",
            "description": "Filter by updated_at <= this date (YYYY-MM-DD, UTC).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of records to return.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 20,
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Offset for result pagination (>= 0).",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 0,
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CategoriesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key",
        "description": "Organization API key (`dlvr_` prefixed), created in the dashboard at `https://app.delivr.ai/{org_id}/settings/api-keys`. Must be paired with the `X-Api-Secret` header."
      },
      "ApiSecretAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Secret",
        "description": "Secret half of the organization API key, paired with `X-Api-Key`. Both headers are required on every request."
      }
    },
    "schemas": {
      "CategoryListItem": {
        "type": "object",
        "required": [
          "category_id",
          "name",
          "status"
        ],
        "properties": {
          "category_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "CategoriesPayload": {
        "type": "object",
        "properties": {
          "categories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CategoryListItem"
            }
          }
        }
      },
      "CategoriesResponse": {
        "type": "object",
        "properties": {
          "response": {
            "$ref": "#/components/schemas/CategoriesPayload"
          }
        }
      }
    }
  }
}
```