API Reference

Error Codes

Request Contract — One Interpretation

Every JSON endpoint enforces a single canonical interpretation of the request before authentication, validation, analysis, idempotency, or billing see it. A request the proxy, the parser, and the analyzer could read differently is rejected outright — it can never authorize under one reading and execute or bill under another. Rules applied to every request body:

• •Content type. JSON endpoints accept application/json only, UTF-8 encoded. Form submissions, text/plain, or a non-UTF-8 charset declaration return 415 unsupported_media_type.
• •Body shape. Exactly one JSON object per request — maximum 1 MiB and 64 levels of nesting, nothing before or after it. A repeated property name is a 400 duplicate_field error at any depth: parsers disagree about which occurrence wins, so the request is ambiguous by definition.
• •Unicode. The body must be valid UTF-8, and \uXXXX escapes must encode real code points — a lone surrogate half is invalid_unicode, never silently replaced.
• •Unknown fields. Fields outside the endpoint's schema are 400 unknown_parameter errors — including unsupported configuration selectors and any field attempting to set tenant, account, actor, or key identity. Identity comes only from the Bearer credential; a body field can never change who is authorized or billed.
• •Query vs. body. Endpoints whose contract is body-only reject query parameters, and GET detection endpoints (query-only) reject request bodies — both as ambiguous_request. Parameters never silently compete or get dropped.

A rejected request executes nothing, reserves nothing, and bills nothing — the check runs before entitlement and usage accounting. The same parsed request then drives authorization, configuration selection, analysis, the idempotency request hash, and usage settlement end to end.

Text Limits

text accepts at most 4,096 Unicode code points counted on the submitted UTF-8 string after stripping leading and trailing whitespace. A code point is one Unicode character - a combining accent counts separately (e.g. e + ◌́ = 2), and an emoji outside the Basic Multilingual Plane counts as 1 (not the 2 UTF-16 units a JavaScript .length reports). Input is validated as submitted - no Unicode normalization is applied and input is never truncated. Oversized input is rejected with 400 input_too_long.

Longer material is chunked in your environment, before submission: each chunk is analyzed as an independent snippet, and every successfully analyzed chunk consumes analyzer runs from your quota - a 3-chunk document analyzed by 2 analyzers consumes 6 runs. Chunk-level signals describe the submitted snippet only; a signature or receipt verifies what was sent in that request, not your source document, and any document-level conclusion is a customer-side aggregation. How you extract, normalize, split, and combine is outside Sentiqra's reproducibility guarantee unless you record it - the input-preparation contract (sentiqra/prepare/v1) does that: deterministic sentence-atomic chunking that preserves speaker turns and quoted material, explicit NFC normalization, marked overlap, per-chunk language assignment, and a customer-held manifest binding each request and returned receipt back to source offsets.

Language & Input Handling

language is a declaration, not a detection result. Sentiqra analyzes text under the language you declare; omitting it applies the documented English default and reports language_source: "default" (vs. "declared") at the top level. The API does not detect or split languages:

• •Mixed-language text is analyzed under the single declared language. Signal quality on the non-declared portions is unspecified - split mixed-language input upstream when it matters.
• •Incorrect declarations produce a valid result computed against the wrong language's coverage - the API cannot detect a wrong declaration. Declare accurately.
• •Language fallback. When the declared language is supported by the analyzer but is not a dedicated coverage language, analysis runs under English coverage and reports applicability: "language_fallback" plus effective_language. When the analyzer has no coverage at all, it reports status: "not_applicable" + applicability: "unsupported_language" (unbilled; 400 when no requested analyzer covers the code).
• •No analyzable content (emoji-only, numeric-only, punctuation-only, symbol-only): single-analyzer endpoints return 422 insufficient_content; /v1/analyze marks each requested analyzer not_applicable. Nothing executes and nothing is billed.
• •Fragments and short inputs execute normally - weak evidence resolves to no_signals or abstained, never a forced guess.
• •Encoded content (base64, hex, quoted-printable) is analyzed literally as submitted. Decode upstream when the encoded payload is what you want analyzed.

Coverage is per-analyzer - the supported-language set differs across analyzers. Check the analyzer's language matrix before declaring a code. See the conditions table for how to route each outcome.

Score Semantics & Output Profiles

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.

Scores are not comparable across labels or analyzers unless validated on your own labeled traffic. Two versioned output profiles intentionally expose different score precision - a profile's field set and semantics never change in place; a different shape ships as a new profile name and version. The response example above shows profile full.v1; see Understanding signals for the field-level reference.

Under reduced.v1, confidence names the band and score carries that band's representative value:

Interfaces

Sentiqra exposes the same analyzers through three interfaces with deliberately different capabilities. REST is the request/response interface; MCP is the agent interface; the playground is an anonymous demo. The matrix below is the published contract - it is generated from the same registry as the rest of this page.

Configuration Pinning (detection_config)

Send detection_config to pin the configuration a request runs against. The value is an opaque sqcfg_* identifier copied from verification.configuration in a previous response, or from GET /v1/status for the current configuration of each analyzer.

A configuration ID is scoped to an analyzer set: a single analyzer slug, or the canonical sorted set a multi-analyzer request produced (the composite scope in its receipt). A pin is valid only for the exact analyzer set in the request - submitting a single-analyzer ID for a two-analyzer request, or a different analyzer's ID, is a scope mismatch. Output profile (full/reduced) and language do not change the configuration.

When detection_config is omitted the request runs the current configuration for the requested analyzer set. Omission never selects a historical configuration and never carries a previous request's pin forward.

Configuration lifecycle

The current configuration is immutable while it is current. Configurations that rotate out remain supported historical for the window published in the changelog entry that introduced their successor; on Enterprise agreements the support window is a contractual commitment for the life of the contract - subject to the security-suspension rule below, which can pause execution (never verification) of any configuration while it applies.

Replay an analysis using its original input and supported configuration ID. Configuration availability follows the published support policy or your contract.

Security suspension

A configuration pins LOGICAL behavior, not a permanently running build. When a dependency, runtime, or deployment component serving a configuration becomes unsafe, a confirmed security_vulnerability incident may suspend execution of the affected scope: pinned and unpinned requests that would execute it fail with configuration_suspended; nothing is substituted and no different detector answers in its place. Execution resumes only after the patched build passes the compatibility attestation path (reproducibility report proving the configuration's promised behavior is unchanged), or the configuration is retired through the documented lifecycle with notice. Where neither is immediately possible, a narrowly-scoped replay arrangement - an isolated deployment approved per engagement - may serve historical replay while the suspended build stays out of the general path. Receipt verification is independent of execution: a suspended or retired configuration's receipts still verify against the published key set - /v1/verify performs cryptographic verification, never re-execution, so availability of one never depends on the other.

Pinning errors

A rejected pin fails the request before any analyzer run executes and is never billed. The current configuration is never silently substituted.

Replaying an analysis

1. Run an analysis. The receipt names the configuration that produced it in verification.configuration.
2. Replay the same input with that ID in detection_config.
3. Compare the canonical result: identical language, identical signals (order, codes, scores), and identical verification.configuration.

curl -s https://sentiqra.tech/v1/analyze \
  -H "Authorization: Bearer $SENTIQRA_API_KEY" -H "Content-Type: application/json" \
  -d '{"text": "you are a worthless idiot", "language": "en", "analyzers": ["trust-safety"]}'

# → "verification": { "configuration": "sqcfg_ZZW77NM9", "fingerprint": "fp2_…", … }

curl -s https://sentiqra.tech/v1/analyze \
  -H "Authorization: Bearer $SENTIQRA_API_KEY" -H "Content-Type: application/json" \
  -d '{"text": "you are a worthless idiot", "language": "en", "analyzers": ["trust-safety"], "detection_config": "sqcfg_ZZW77NM9"}'

# → same signals and the same verification.configuration.

Replay is guaranteed while the configuration remains current or supported historical under the published support policy or your contract — not indefinitely, and subject to the security-suspension rule: an unsafe execution environment pauses execution (never receipt verification) until a patched build passes compatibility attestation.

Rate Limits

Rate limits vary by plan. Exceeding the limit returns 429 rate_limit_exceeded - check X-RateLimit-Reset for the retry time.

Monthly quota works differently per plan. Free is a hard cap: quota exhaustion returns 429 monthly_quota_exceeded until the next billing cycle or an upgrade. Paid plans continue past quota into automatic overage billing at the plan's per-1K rate; you get 429 overage_cap_reached or 429 spend_cap_reached only at the plan's overage ceiling or your configured cap.

Plan prices and quotas are also shown on the pricing page - both read the same source.

Idempotency & partial results

Send an Idempotency-Key header on POST /v1/analyze to make retries safe. Re-submitting the same key with the same canonical request replays the recorded response — marked by X-Sentiqra-Idempotent-Replay: true — with no additional charge. The request identity covers the request fields (including detection_config); the same key with a different body returns 409 idempotency_conflict. Idempotency records hold the key, a hash of the request fields, per-analyzer outcomes, and the response for 24 hours — your submitted text is never persisted. A fresh key is a new logical operation and bills normally.

When one of two requested analyzers fails, the response still returns the completed analyzer's signals. Check each entry in meta.analyzers[] — status is completed, failed, overloaded, or not_applicable, and billed shows whether the run counted against your quota. A failed analyzer is never reported as a successful empty result — meta.partial marks the response incomplete.

Three separate fields describe what happened per analyzer: status (did it execute), applicability (analyzable, language_fallback, insufficient_content, or unsupported_language), and assessment for completed runs (signals_detected, no_signals, abstained). An empty signals array alone is never a verdict — no_signals means nothing crossed threshold (not proof of safety), abstained means a validated rule declined to report, and not_applicable means nothing ran at all. See the Production Guide conditions table for routing.

A plain replay returns the recorded outcome verbatim — it never silently retries failed analyzers. To retry them, resubmit the same key and body with X-Retry-Failed: true: this explicit child operation re-executes only the failed analyzers, merges their results into the recorded response, and bills only newly-completed runs (usage.billed_runs shows this request's charge). A second child with nothing left to retry returns 409 no_failed_analyzers. See the Production Guide for the full failure-mode matrix.

Versioning & Changelog

The current API version is v1. We use URL-based versioning (/v1/analyze). Breaking changes require a new version number and are announced at least 90 days before the old version is retired; non-breaking changes (new endpoints, new optional parameters, new response fields) are added to the current version.