Skip to main content
POST
/
v1
/
tag
Tag
curl --request POST \
  --url https://api.classer.ai/v1/tag \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "text": "<string>",
  "image": [
    {}
  ],
  "file": "<string>",
  "labels": [
    "<string>"
  ],
  "classifier": "<string>",
  "descriptions": {},
  "examples": {},
  "text_type": "<string>",
  "threshold": 123,
  "priority": "<string>",
  "cache": true
}
'
{
  "labels": [
    {"label": "technology", "confidence": 0.95},
    {"label": "finance", "confidence": 0.82}
  ],
  "tokens": 198,
  "latency_ms": 112,
  "cached": false
}

​
Request

​
text
string
The text to tag (max 1M tokens). Required unless an image or file is provided.
​
image
string or string[]
Image(s) to tag — URL (https://...) or base64-encoded string. Images above 4MP (2048×2048) are resized. Max 20 images.
​
file
string
PDF or DOCX file — URL or base64-encoded string. Text is extracted and each page is converted to an image for visual analysis. Max 20 pages.
​
labels
string[]
List of possible labels (1–200, max 100 characters each). Required unless classifier is provided.
​
classifier
string
Saved classifier name (e.g. "support-tickets") or a pinned version ("support-tickets@v2"). Alternative to providing labels inline.
​
descriptions
object
Optional descriptions for each label to improve accuracy. Keys are label names, values are description strings.
​
examples
object
Optional per-label example texts to improve accuracy. Keys are label names, values are arrays of example strings.
​
text_type
string
Optional context for prompt tuning (e.g. "app review", "support ticket")
​
threshold
number
default:"0.5"
Confidence threshold (0–1). Only labels above this threshold are returned.
​
priority
string
default:"standard"
Priority level: standard (<1s, 0.20/1M tokens) or `fast` (&lt;200ms, 0.60/1M tokens)
​
cache
boolean
default:"true"
Set to false to bypass cache and force a fresh classification

​
Response

​
labels
array
Labels above the threshold, each with label (string) and confidence (number, rounded to 4 decimal places)
​
tokens
number
Total tokens used
​
latency_ms
number
Processing time in milliseconds
​
cached
boolean
Whether the response was served from cache

​
Examples

​
Basic tagging

import classer

result = classer.tag(
    text="Breaking: Tech stocks surge amid AI boom",
    labels=["politics", "technology", "finance", "sports"],
    threshold=0.5
)

for t in result.labels:
    print(f"{t.label}: {t.confidence}")
# technology: 0.92
# finance: 0.78

​
With descriptions

result = classer.tag(
    text="New iPhone announced with AI features and lower price",
    labels=["technology", "business", "consumer", "ai"],
    descriptions={
        "technology": "Hardware, software, gadgets",
        "business": "Corporate news, earnings, strategy",
        "consumer": "Product launches, pricing, reviews",
        "ai": "Artificial intelligence, machine learning"
    },
    threshold=0.4
)

for t in result.labels:
    print(f"{t.label}: {t.confidence}")

{
  "labels": [
    {"label": "technology", "confidence": 0.95},
    {"label": "finance", "confidence": 0.82}
  ],
  "tokens": 198,
  "latency_ms": 112,
  "cached": false
}