Classify API

The Classify API is the core endpoint for AudienceGPT's AI-powered audience taxonomy classification. It accepts a topic description and returns a structured 7-layer classification including taxonomy placement, segment type, intent signals, and DSP-ready naming. The endpoint uses Claude Sonnet 4.6 with web search capabilities to verify unfamiliar brands and products before classifying.

POST /api/classify

Classify a topic through the full 7-layer classification pipeline powered by Claude Sonnet 4.6.

Auth: API key with classify scope, or Clerk session

POST /api/classify

Request Body

Field	Type	Required	Description
messages	array	Yes	Anthropic message format array (max 50 messages)

Each message in the array follows the Anthropic Messages API format:

{
  "messages": [
    {
      "role": "user",
      "content": "Classify: Tesla Model 3 electric vehicle buyers in California"
    }
  ]
}

Response (200)

The response contains a text field with the classification result as a JSON string. Parse this string to get the structured classification object.

{
  "text": "{\"topic_name\":\"Tesla Model 3 Buyers - California\",\"parent_category\":\"Auto\",\"taxonomy_type\":\"Automotive & Vehicles\",\"subcategory\":\"Electric Vehicles\",\"segment_type\":\"B2C\",\"audience_type\":\"In-Market Buyers\",\"keywords\":[\"tesla\",\"model 3\",\"electric vehicle\",\"EV\",\"california\"],\"segment_desc_liveramp\":\"In-market consumers researching or actively purchasing Tesla Model 3 electric vehicles in California\",\"segment_desc_tradedesk\":\"Tesla Model 3 EV buyers in CA\",\"internal_description\":\"Audience segment targeting consumers showing purchase intent for Tesla Model 3 electric vehicles within the California market\"}"
}

Parsed classification fields:

Field	Type	Description
topic_name	string	Normalized, DSP-friendly topic name
parent_category	string	One of 41 parent categories (e.g., "Auto", "Insurance", "Business Technology")
taxonomy_type	string	One of 13 taxonomy type groups (e.g., "Automotive & Vehicles", "Technology & Telecom")
subcategory	string	Specific subcategory within the parent category
segment_type	string	B2B, B2C, B2B2C, B2E, or B2G
audience_type	string	One of 14 audience types (e.g., "In-Market Buyers", "Business Decision Makers")
keywords	string[]	Relevant keywords for the topic
segment_desc_liveramp	string	LiveRamp-formatted segment description
segment_desc_tradedesk	string	Trade Desk-formatted segment description (character-limited)
internal_description	string	Detailed internal description

curl Example

curl -X POST https://app.audiencegpt.com/api/classify \
  -H "Authorization: Bearer txadv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Classify: Enterprise SaaS decision makers evaluating CRM platforms"
      }
    ]
  }'

TypeScript Example

async function classify(topicDescription: string): Promise<ClassificationResult> {
  const response = await fetch("https://app.audiencegpt.com/api/classify", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.AUDIENCEGPT_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      messages: [
        { role: "user", content: `Classify: ${topicDescription}` },
      ],
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error);
  }

  const { text } = await response.json();
  return JSON.parse(text);
}

Multi-turn Classification

The Classify API supports multi-turn conversations for gathering additional context before classification. Include previous messages for context:

{
  "messages": [
    { "role": "user", "content": "I need to target people interested in luxury watches" },
    { "role": "assistant", "content": "I can help classify that. Could you tell me more about the specific brand or price range?" },
    { "role": "user", "content": "Rolex and Omega, $5000+ range, targeting affluent professionals" }
  ]
}

tip

Multi-turn classification provides more accurate results because the model has additional context about the marketing objective, target audience, and campaign goals.

Web Search

The classification model has access to a web search tool (up to 3 searches per request) that it uses to verify unfamiliar brands, products, or companies before classifying. This prevents misidentification -- for example, an activewear brand being classified as B2B SaaS.

Web search results are used internally by the model; citation markup is stripped from the response before it is returned.

Model Configuration

Setting	Value
Model	Claude Sonnet 4.6 (claude-sonnet-4-6)
Max output tokens	4,096
Web search uses	Up to 3 per request
Output format	Structured JSON (guaranteed valid via output_config)

info

The classification model can be overridden via the CLASSIFICATION_MODEL environment variable. Available options are claude-sonnet-4-6 (default, best accuracy) and claude-haiku-4-5 (3x cheaper, faster).

Error Responses

400 Bad Request

{
  "error": "messages array is required"
}

{
  "error": "messages array exceeds maximum of 50"
}

401 Unauthorized

{
  "error": "Unauthorized"
}

429 Quota Exceeded

{
  "error": "Monthly classifications quota exceeded (10000 limit)"
}

500 Internal Server Error

{
  "error": "Classification failed"
}

Usage Tracking

Every classification request is tracked for billing and analytics:

• Input and output token counts
• Web search invocation count
• Request duration
• Authentication method used

View usage statistics in the admin dashboard or via the usage API.

Next Steps

• Topics API -- Save classified topics to your library
• Campaign Brief API -- Upload documents for bulk topic extraction
• Matrix Generation -- Generate combinatorial topics
• SDK Integration -- Client-side classification via POST /api/sdk/classify