What it does
The/classify endpoint takes a piece of text and a set of labels you define, then returns a probability score for each label indicating how well the text fits. Scores are softmax-normalised across all labels so they sum to 1.0, and the highest-scoring label is returned as top_label.
Each label is scored by running the text against a rubric — a yes/no question you write that describes what the label means. The model judges how strongly the text “answers yes” to each question, then normalises the results into a probability distribution.
When to use it
You need to route incoming content. Support tickets, user messages, or documents need to reach the right handler. Classify lets you define your own categories without training a model — just write rubrics that describe each category. You’re building a moderation layer. A two-label setup (spam / not spam, safe / unsafe) gives you a confidence score you can threshold however your policy requires.
You need intent detection. Identify whether an incoming message is a question, complaint, feedback, or cancellation request — and act on it accordingly.
You want domain tagging at scale. Tag documents as medical, legal, financial, or any domain relevant to your pipeline, without fine-tuning or labelling training data.
Common use cases
| Use case | How classify helps |
|---|---|
| Support ticket triage | Route tickets to billing, technical, or account teams automatically |
| Content moderation | Score content against a rubric for spam, toxicity, or policy violations |
| Intent detection | Identify question / complaint / feedback / cancellation intent |
| Domain tagging | Label documents by topic for downstream routing or filtering |
| Lead qualification | Score inbound inquiries against criteria like urgency or deal size |
| Email categorisation | Sort inbound email into categories without a rules engine |
How it fits into your workflow
Classify sits between your input source and your routing or handling logic. You pass in the raw text — a ticket, a message, a document — and use the scores to decide what to do next.top_label for simple routing and the full scores map if you need finer-grained control (e.g. only act if the top score exceeds a threshold).
Writing good rubrics
The rubric is the most important part of a classify request. Poor rubrics produce noisy, unreliable scores; well-written rubrics are specific, direct, and independent. Rules of thumb:- Be specific. Vague rubrics produce low-confidence scores.
- Frame as a yes/no question. “Does this text describe X?” outperforms “X content”.
- Avoid negations. “Is this NOT about finance?” will confuse the model. Use a positive label instead.
- Keep rubrics independent. Overlapping rubrics (e.g. “Is this medical?” and “Is this about health?”) split probability mass unpredictably.
| Label | Poor rubric | Good rubric |
|---|---|---|
medical | medical content | Does this text describe a medical condition, symptom, treatment, or health topic? |
urgent | urgent or important | Does this text indicate that the sender needs an immediate response or is describing a time-sensitive situation? |
complaint | negative feedback | Is this text expressing dissatisfaction, frustration, or a formal complaint about a product or service? |