Emotion Analysis API
Detect 20 distinct emotions in text.
The Emotion Analysis API classifies submitted text against 20 emotions in 16 supported languages with a flat taxonomy.
The API returns the top-3 emotions with signal-match scores. Use the results to enrich customer feedback analysis, social media monitoring, support prioritization, content recommendation, and wellness screening workflows.
POST /v1/analyze · REST · JSON · Bearer authentication
Scope
Sentiqra analyzes emotion signals contained in the text you submit. It does not diagnose mental health conditions, determine psychological states, or replace clinical or professional review.
Make your first request
curl -X POST https://sentiqra.tech/v1/analyze \
-H "Authorization: Bearer $SENTIQRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "I have been waiting three weeks for a response and nobody seems to care about my issue.",
"language": "en",
"analyzers": [
"emotions"
]
}'
Example response:
{
"language": "en",
"language_source": "declared",
"signals": [
{
"analyzer": "emotions",
"code": "negative_emotion",
"label": "Negative Emotion",
"score": 0.95,
"level": "category"
},
{
"analyzer": "emotions",
"code": "frustration",
"label": "Frustration",
"score": 0.93,
"level": "label",
"parent": "negative_emotion"
},
{
"analyzer": "emotions",
"code": "disappointment",
"label": "Disappointment",
"score": 0.87,
"level": "label",
"parent": "negative_emotion"
}
],
"meta": {
"analyzers": [
{
"name": "emotions",
"status": "completed",
"applicability": "analyzable",
"assessment": "signals_detected",
"signal_count": 3,
"billed": true
}
]
},
"usage": {
"analyzer_runs": 1
},
"verification": {
"configuration": "sqcfg_3WTVYJV6",
"fingerprint": "fp_8a72...19f",
"input_commitment": "ic_31bd...a42",
"signature": "sig_ed25519_4c1f...e2a",
"key_id": "edk_af4f218e"
}
}
Don't have an API key? Generate one from the API Keys page in your dashboard.
Endpoint
/v1/analyze
Classifies emotion signals in submitted text and returns the top-3 emotions with signal-match scores.
Request
{
"text": "I have been waiting three weeks for a response and nobody seems to care about my issue.",
"language": "en",
"analyzers": [
"emotions"
]
}
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| text | string | Yes | - | Text to analyze |
| language | string | No | "en" | Supported language code |
Advanced parameters →
Related endpoints
GET /v1/meta/domains/emotions
Identifier, availability, and endpoint for this analyzer. Send a Bearer API key for taxonomy summary and supported languages.
GET /v1/meta/domains
Lists all analyzers with identifiers, status, and endpoints - no authentication required. Send a Bearer API key for taxonomy size and language counts.
What the API can classify from text
Sentiqra can identify language associated with 20 distinct emotions:
Can classify from text
- • Joy and excitement
- • Sadness and loneliness
- • Anger and contempt
- • Fear and anxiety
- • Surprise and confusion
- • Love and gratitude
20 emotions in total - the complete list is available to customers after request access .
Requires external evidence
- • Clinical mental health diagnosis
- • Psychological state assessment
- • Emotional intent vs. impact
- • Longitudinal emotional patterns
- • Contextual and situational factors
- • Speaker's actual emotional state
- • Sarcasm and irony disambiguation
- • Cultural emotion expression norms
These are classification signals, not psychological assessments. For cases requiring external evidence, Sentiqra can provide one textual evidence layer for your broader analysis.
What requires additional evidence
Some emotion conclusions cannot be established from an isolated text item.
Clinical diagnosis
Determining mental health conditions requires assessment by qualified clinical personnel.
Actual emotional state
Text may not reflect the speaker's true emotional state - people may mask, exaggerate, or perform emotions.
Sarcasm and irony
Distinguishing genuine emotions from sarcastic or ironic expression may require contextual and conversational evidence.
Cultural context
Emotion expression norms vary by culture. Sentiqra does not apply culture-specific interpretation rules.
Longitudinal patterns
Establishing emotional trends over time requires multiple data points and temporal analysis.
Classification is not assessment
A typical emotion analysis workflow looks like:
Content
↓
Sentiqra emotion signals
↓
Context / policy / business logic / cultural factors
↓
Human or professional review
↓
Customer-defined decision
Sentiqra supplies structured classification evidence. Your organization determines whether further analysis, labeling, escalation, action, or no action is appropriate.
An empty result is not a verdict
When no emotion is detected above threshold, the API returns an empty signal set - not a low-confidence guess. This lets your workflow distinguish "no emotion detected" from "low-confidence emotion detected" without a fallback label to filter out.
An empty signals array alone does not establish that the content is neutral or benign. Check meta.analyzers[].status and assessment:
- •
completed / no_signals- the analyzer ran and nothing crossed threshold. Not proof of neutral content; genuinely flat text and borderline cases both land here. - •
completed / abstained- a validated rejection rule found the input off-domain (e.g. too fragmentary to classify meaningfully). The analyzer declined to report - also not a neutral verdict. - •
not_applicable- nothing ran: the declared language isn't covered (unsupported_language) or the text has no analyzable letters (insufficient_content). Route these separately - they are non-results.
Queue-routing rule: treat no_signals as "no actionable emotion signal", not as a finding that the text is emotionally neutral. See the production guide for the full conditions table.
Response structure
groups
Emotion categories, ranked by score (level: "category").
{
"analyzer": "emotions",
"code": "negative_emotion",
"label": "Negative Emotion",
"score": 0.95,
"level": "category"
}
signals
Stable machine identifier for the signal. Use code when storing or cross-referencing signals (level: "label").
{
"analyzer": "emotions",
"code": "frustration",
"label": "Frustration",
"score": 0.93,
"level": "label",
"parent": "negative_emotion"
}
parent
Category slug this label-level signal belongs to. Dotted form is group.label - e.g. negative_emotion.frustration means frustration sits under negative_emotion.
| Field | Type | Description |
|---|---|---|
| code | string | Stable machine identifier |
| label | string | Human-readable display name |
| parent | string | Parent category code (label-level only) |
| score | float | Signal-match strength (0.0–1.0) |
Signal scores
A score expresses signal-match strength under a particular analyzer configuration. It is not a probability that the signal or a downstream action is correct. Validate action thresholds on representative labeled data.
Paid API keys receive the continuous score (profile full.v1); anonymous, playground, demo, and free-tier responses return banded scores with a confidence band (profile reduced.v1). See Understanding signals for the profile and band table.
It does not represent:
- • Probability that the speaker actually felt the emotion
- • Clinical or psychological assessment
- • Emotional intensity or severity
- • Sarcasm or irony disambiguation
- • Justification for an automated action
Confidence should determine evidence strength - not workflow policy. Configure review thresholds according to emotion type, context, and your own labeled evaluation data.
Your application decides what happens next.
20 emotions in a flat taxonomy
The taxonomy uses a flat structure with 20 distinct emotions. Representative emotions are shown publicly - the complete list is available to customers after request access .
Deterministic classification
For the same normalized input evaluated against the same supported pinned configuration and output profile, Sentiqra returns the same canonical signals.
Version changes are explicit so historical and current analyzer behavior can be distinguished.
Supported languages
Emotion Analysis currently supports 16 languages.
| Code | Language | Status |
|---|---|---|
| en | English | Production |
| fr | French | Production |
| es | Spanish | Production |
| de | German | Production |
| it | Italian | Production |
| nl | Dutch | Production |
| no | Norwegian | Production |
| pl | Polish | Production |
| uk | Ukrainian | Production |
| ru | Russian | Production |
| sv | Swedish | Production |
| fi | Finnish | Production |
| lv | Latvian | Production |
| lt | Lithuanian | Production |
| pt | Portuguese | Production |
| tr | Turkish | Production |
All languages this detector supports are enabled on every plan. Custom or restricted arrangements may scope language access - check the dashboard or GET /v1/account/entitlements for account-specific availability.
Detector does not support language → 400 unsupported_language
Detector supports language but the account is not entitled (restricted/custom arrangements only - GA plans include all supported languages) → 403 language_not_in_plan
Performance
Built for real-time emotion analysis pipelines.
Published latency targets, not measured guarantees - measured snapshot figures are on the performance dashboard. Actual latency depends on network conditions, payload size, and load.
Errors, limits, and rate controls
The Emotions API uses standard HTTP response codes:
| Code | Description |
|---|---|
| 400 | Invalid request |
| 401 | Authentication error |
| 403 | Access unavailable |
| 413 | Input too large |
| 429 | Rate or quota exceeded |
| 500 | Internal error |
| 503 | Temporary unavailability |
For retryable responses, follow documented backoff and Retry-After behavior.
| Header | Description |
|---|---|
| X-RateLimit-Limit | Max requests per second |
| X-RateLimit-Remaining | Remaining requests in current window |
| X-RateLimit-Reset | Unix timestamp when window resets |
Data handling
Sentiqra documents separately what crosses and remains within the service boundary:
Raw request content
Submitted text is processed in memory and not retained. No model training on your data.
Signal metadata
Individual signal results are not stored. Only aggregate counters are derived from them before the response is sent, apart from the bounded idempotency replay copy and webhook delivery payloads described in the retention schedule.
Operational metadata
Request status, key identifiers, latency, and billing information are logged for operational purposes.
Code examples
All examples use environment variables for API keys - do not hard-code keys in source.
curl -X POST https://sentiqra.tech/v1/analyze \
-H "Authorization: Bearer $SENTIQRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "I have been waiting three weeks for a response and nobody seems to care about my issue.",
"language": "en",
"analyzers": [
"emotions"
]
}'
Reading Emotion Analysis output
What you can safely infer from a result - and what you must not.
Intended task
Rank which of the 20 documented emotions a piece of text expresses - the emotional register of the writing.
Input requirements
text- the only field analyzed; up to 4,096 Unicode code points. Over the limit is rejected withinput_too_long, never truncated.language- must be a language this analyzer supports. Unsupported codes are rejected with400 unsupported_language, never analyzed as a different language.analyzers- include"emotions"; up to 2 analyzers per request, one billed run each.- No context beyond
text- no user IDs, history, profiles, or attachments are read or inferred. - Short text works, but single words and fragments carry little signal - very thin input can return an empty result.
Ordinary positive
“I was dreading this release all week, but seeing it finally live - I am honestly so proud of the team.”
Safe inference: The text expresses pride and relief with an excitement undertone - a ranked mix, not a single verdict.
Confusing negative · Reported speech
“The customer sounded angry. You must be furious about the delay.”
What happens: Anger signals can fire - the text describes and attributes emotion rather than expressing it. Signals reflect the emotional language in the text, which may belong to a described third party rather than the author.
Why it's tricky: Secondhand emotion, quoted feelings, and hypothetical phrasing ("you must be furious") share vocabulary with felt emotion. Read emotion signals as the register of the text, not a measurement of any person's actual state.
What you can safely infer
- The emotional register of the text as written, ranked across the documented emotion set.
- That mixed emotions are a normal result - consume the ranked list, not just the top label.
What you must not infer
- ✕The author's actual mental or emotional state - text is evidence of language, not feeling.
- ✕That a described emotion belongs to the author rather than someone they describe.
- ✕That a flat or empty result means the author feels nothing - thin text is thin evidence.
Boundary: Emotion signals describe the emotional language in a text. They are not a mental-health assessment and say nothing about any person's actual state.