Support AI Agent

Classify support tickets using AI. Supports multiple LLM providers. Returns structured intent classification with confidence scores.

Authentication

All API requests require a Bearer token in the Authorization header. If API_SECRET_KEY is not set, auth is skipped (dev mode).

Authorization: Bearer <API_SECRET_KEY>

POST /api/classify

Classify a single support ticket. Returns intent, confidence, reasoning, and detected language.

Request body

Field	Type	Required	Description
`subject`	string	required	Ticket subject line
`description`	string	optional	Ticket body text
`provider`	string	optional	`openai` \| `anthropic` \| `vertex`. Default: `openai`
`systemPrompt`	string	optional	Custom system prompt override

Example request

curl

curl -X POST https://your-domain.com/api/classify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-key" \
  -d '{
    "subject": "Cancel my subscription",
    "description": "I would like to cancel my subscription please.",
    "provider": "openai"
  }'

Response

200 OK

{
  "intent": "cancel_request",
  "confidence": 0.95,
  "reasoning": "User explicitly requests subscription cancellation.",
  "detectedLanguage": "en"
}

Errors

401 Unauthorized

{ "error": "Unauthorized" }

400 Bad Request

{ "error": "subject is required" }

500 Internal Server Error

{ "error": "Classification failed" }

POST /api/test-prompts

Batch test classification against existing Zendesk tickets. Fetches tickets by tag and classifies each one. Used by the Playground UI.

Request body

{
  "tag": "canc_queue",       // Zendesk tag to search, default: "canc_queue"
  "limit": 10,              // Max tickets to fetch, default: 10
  "provider": "openai",     // AI provider, default: "openai"
  "systemPrompt": "..."     // Optional custom prompt
}

Response

200 OK

{
  "results": [
    {
      "ticketId": 165779,
      "subject": "Cancel my subscription",
      "description": "...",
      "tags": ["canc_queue", "10_plan_offered"],
      "status": "open",
      "classification": {
        "intent": "cancel_request",
        "confidence": 0.95,
        "reasoning": "...",
        "detectedLanguage": "en"
      },
      "error": null
    }
  ],
  "total": 10,
  "provider": "openai",
  "testedAt": "2026-05-05T12:00:00.000Z"
}

Models

Provider	Model	Value
OpenAI	GPT-4o	`openai`
Anthropic	Claude Sonnet 4	`anthropic`
Google	Gemini 2.0 Flash	`vertex`

Types

ClassificationResult

{
  "intent": "cancel_request" | "cancel_escalate" | "cancel_info" | "pause_active" | "not_cancel",
  "confidence": 0.0 - 1.0,
  "reasoning": "string",
  "detectedLanguage": "en" | "es" | "fr" | "de" | "it" | "pt"  // optional
}

Intent types

Intent	Description
`cancel_request`	Simple cancellation request, no financial disputes
`cancel_escalate`	Cancel + refund/dispute/chargeback — route to human agent
`cancel_info`	User asking about cancellation policies or process
`pause_active`	User has a paused subscription
`not_cancel`	Not related to cancellation

Support AI Agent API