intent classification api

Intent classification you can route on

Intent detection is a choice among labels you define, not a summary of the message. Ask for the choice and you get the distribution you need to decide what happens next.

Intent is a choice, not a summary

Most intent pipelines ask a chat model to name the intent in prose, then spend the next hundred lines parsing and retrying. The task itself is a closed-set classification: one message in, one label out, with a number that says how sure the model was.

This API takes the second view. You declare the intents that exist for your product, and the model returns a probability for each of them in one pass — including the low ones, which are what lets you escalate instead of guessing.

The request and what comes back

The free endpoint takes a state and a list of questions, each with a prompt and the options you allow. The keyed endpoint takes the same state with typed questions carrying instructions and criteria, which is where per-label guidance belongs.

The response mirrors your ids: an option, a confidence, and a probabilities object keyed by the labels you sent. Ask for one intent or eight; each is answered over its own closed set.

A message with no matching intent is a normal outcome. Declare an other label and route on its probability like any other.

Route on the score, not just the winner

The winner alone throws away the information that makes routing safe. A 0.41 top label and a 0.95 top label both name an intent, but only one of them belongs in an automated queue.

Threshold the distribution: route above it, hold and escalate below it, and log the whole vector for review. The API does not decide your threshold; it gives you the number to threshold on.

  • Automate the high-confidence majority into the right queue.
  • Send the ambiguous middle to a human instead of a wrong queue.
  • Keep the distribution as evidence when somebody asks why a ticket went where it went.

Several questions, one request

Intent is rarely the only thing a router needs. Urgency, sentiment and whether the customer wants to cancel are separate bounded questions about the same message, and they can be sent together — one state, several typed questions, one answer set.

That keeps the questions from disagreeing about what the message said, and it keeps one round trip in the path between the customer and the queue.

Limits worth knowing

The label set is closed, so an intent you forgot to declare can only come back as whichever declared label fits best — or as other, if you gave it one. Overlapping labels split the probability between them, which shows up as low confidence rather than an error.

For products with per-tenant intents, use a label set per request or normalise tenant-specific labels into a shared taxonomy first. The model reads the state and the options; it has no memory of your taxonomy between calls.

Frequently asked questions

How many intent labels can one question have?

Two to twelve per choice question, and up to eight questions per request on the free tier and on paid plans. A taxonomy wider than twelve intents is usually several questions — a domain first, then the intent inside it.

Does it work in languages other than English?

Label names and instructions can be written in the language of your messages. Measure agreement on your own sample before relying on it: intent labels are product-specific, and published benchmarks do not cover your taxonomy.

Can I classify a whole ticket thread at once?

The state is text or JSON, so a thread can be sent as text or as a JSON array of turns. The free tier caps the state at 8,000 characters; the paid tier accepts 200,000 and the model refuses anything past its own window instead of truncating it.

Is intent classification free to try?

Yes. The browser playground and the keyless endpoint run on a daily allowance with no account, and a paid key raises the limit and adds vision states.

Keep reading

Model notes

One short email when a new decision model lands or a benchmark changes. No spam, unsubscribe in one click.