feeldb
← Integrations overview

FeelDB Emotions API / v1.1.0

API reference

This technical reference is generated from the OpenAPI contract. Start with public lookup; use a server-side key for more volume and batching. Field names and examples below are in English.

OpenAPI 3.1 JSON ↓

Authentication

Browser widget routes use a publishable key in ?pk= and a matching Origin. Arcs accept either a publishable key or a secret bearer. The public title alias has a legacy transition mode described by x-keyless-sunset. After configured retirement, requests without pk return uniform 401 key_required for existing, unknown, hidden and malformed IDs, with no-store. Taxonomy, icons and this contract stay keyless. No keyless arc or batch exists. Secret keys are for server-to-server calls only. Send Authorization: Bearer <your-key> over HTTPS. Never expose a secret in browser code, a query string or logs. Publishable-key routes allow browser CORS. Secret-bearer routes are server-only. A key grants volume, never access to non-public titles.

Keyless title lookup is retired on this deployment: requests without pk return uniform 401 key_required, with no-store. Our previews use an origin-bound house pk.

Request an API key →

Rate limits & quota

  • Keyless: 60 requests per minute per IP.
  • Default per key: 120 requests per minute and 50,000 lookups per UTC day.
  • Batch: at most 100 IMDb IDs and a 16 KiB JSON body.

Limits can be configured per partner. A batch spends lookup quota for valid unique IDs, including IDs that are not found. Requests and lookups are separate units. Secret-key routes expose rate headers; publishable routes do not expose X-RateLimit-*. For secret-key calls, read X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. On 429, wait for Retry-After; do not retry in a tight loop. Authenticated conditional requests still count toward request limits.

Caching & ETag

Publishable widget responses and the pk title alias: public, max-age=120, s-maxage=120. Secret-bearer title responses: private, max-age=300. Legacy keyless title responses only while the flag is enabled: public, max-age=600, s-maxage=3600. All errors are no-store. Follow each endpoint’s Cache-Control, as catalog, icons and contract freshness differ. Never share secret-bearer responses through a public cache. Publishable compact responses contain no partner account data.

Retain the ETag and send it as If-None-Match. A matching validator returns 304 without a body; reuse your stored response. Cache by API origin, key, IMDb ID and language. API-served 304 responses still spend a unit; local browser cache hits do not reach the API. Use the returned URLs for attribution and icons so a domain move does not break your integration.

Errors

Errors use { "error": { "code", "message", "docs" } }. Handle the stable code, rather than parsing a message. Unknown, malformed, hidden and pending single-title IDs share a uniform 404 not_found response. A published title with no qualifying emotions is a 200 response with compact s: insufficient_data (or verbose status for server calls), not a 404.

Error codes from the OpenAPI contract
CodeMeaning
not_foundNo published title has this IMDb id.
invalid_imdb_idIMDb ids look like tt0111161.
unauthorizedMissing or invalid API key.
key_revokedSee the response descriptions below each operation.
partner_suspendedThis partner account is suspended.
rate_limitedToo many requests.
quota_exceededDaily quota exceeded.
batch_too_largeAt most 100 ids per batch.
payload_too_largeSee the response descriptions below each operation.
method_not_allowedSee the response descriptions below each operation.
server_errorSee the response descriptions below each operation.
service_unavailableTemporarily unavailable, retry later.
validation_errorInvalid request body.
key_requiredA publishable key is required: add ?pk=… (see docs)
balance_exhaustedPrepaid balance exhausted
origin_not_allowedThis key is not allowed from this origin
addon_requiredThis add-on is not enabled for your key

Keep X-Request-Id when reporting an issue. Never include your secret key.

Versioning & changelog

API paths and SDK downloads are versioned. Current contract: 1.1.0. Store stable emotion key values; translated labels and response URLs may change.

1.1.0

  • Origin-bound publishable widget lookup and entitled compact arcs.
  • Stateless widget failure report beacon.
  • Secret-key account billing; configurable keyless lookup sunset (SEC-18).

1.0.0

  • Initial versioned partner emotions API with public and keyed title lookup, batch lookup, taxonomy, SVG icons and account usage.
  • Shared JavaScript and PHP SDK fixtures; documented AI provenance, attribution and canonical URLs.

SDKs

JavaScript / TypeScript: zero dependencies, ESM and CommonJS, Node ≥18 and modern browsers. PHP ≥8.1: framework-free client, retries, ETag revalidation and Badge::html() for a server-rendered attribution link. The web component uses the origin-bound publishable API, lazy-loads when visible and reserves layout space. The compact schema carries t, s, e, u, x; arcs carry v, b, d, i, t. Failure reporting is a best-effort text/plain beacon, not a secret-bearing request.

npm and Packagist publication is pending. Download the versioned archives below and install them locally. Keep secret-key SDK calls on your server. Browser SDK calls use publishableKey and a registered Origin. Quickstart examples →

Downloads: widget.js17.9 KiBfeeldb-js-1.1.0.tgz7.4 KiBfeeldb-php-1.1.0.zip19.2 KiBSHA256SUMS670 B

Titles

GET/api/public/v1/titles/{imdb_id}/emotionsPublishable key in ?pk= · browser · keyless retired

Get dominant emotions by IMDb id

Legacy keyless lookup only while partners.keyless_lookup is true. With pk this is the widget alias, using compact payload and publishable headers. No cookies. See x-keyless-sunset for both flag states.

Parameters

Parameters for getPublicTitleEmotions
Name / locationTypeRequiredDescription
imdb_id / pathstringYesIMDb title id. Malformed, unknown, hidden and pending ids receive the same 404 envelope.
lang / querystring (ka, en)NoLabel and title language; defaults to ka. Unsupported values normalize to en; all labels retain both languages.
If-None-Match / headerstringNoPreviously received ETag; a match returns 304 without a body.
pk / querystringNo

Responses

200 Successful response.

application/json

Response 200 fields for getPublicTitleEmotions
FieldTypeRequiredDescription
dataobjectYesPublished title emotion data.
data.imdb_idstringYesIMDb identifier of the published title. pattern: ^tt[0-9]{7,10}$
data.typestring (movie, series)YesMovie or series; animation is a separate flag.
data.yearinteger | nullYesRelease year, or null when unknown.
data.titleobjectYesOriginal and translated title names.
data.title.originalstringYesOriginal title, falling back to English.
data.title.enstringYesEnglish title.
data.title.kastring | nullYesGeorgian title, or null if unavailable.
data.namestringYesTitle in requested language, falling back to English.
data.animationbooleanYesWhether the title is animated.
data.statusstring (ok, insufficient_data)Yesok when at least one emotion qualifies; insufficient_data when none reach the configured minimum share (default 5%). This is a 200 response with an empty emotions array.
data.emotionsarray<object>YesTop up to three emotions with share at least the configured minimum (default 5%), using the same ordering as the title page. maxItems: 3
data.emotions[].rankintegerYesOne-based rank among the returned dominant emotions. minimum: 1; maximum: 3
data.emotions[].keystringYesStable emotion slug.
data.emotions[].labelstringYesEmotion label in requested language.
data.emotions[].labelsobjectYesLabels in both supported languages.
data.emotions[].labels.kastringYesGeorgian label.
data.emotions[].labels.enstringYesEnglish label.
data.emotions[].familystringYesEmotion family grouping in the FeelDB taxonomy.
data.emotions[].colorstringYesFamily display colour as a hexadecimal RGB value. pattern: ^#[0-9A-Fa-f]{6}$
data.emotions[].iconstringYesAbsolute SVG icon URL; use the returned URL rather than constructing one.
data.emotions[].sharenumberYesShare of the title's emotional signal in percent, not % of people; rounded to one decimal. The returned top emotions need not sum to 100. minimum: 0; maximum: 100
data.tied_with_nextbooleanYesWhether rank 3 has the same share as rank 4, signalling a tie at the display cutoff.
data.sourceobjectYesEvidence origin, viewer count and confidence.
data.source.kindstring (ai, blended, viewers, none)Yesai = AI estimate only; blended = AI estimate plus viewer ballots; viewers = viewer ballots only; none = no emotion evidence.
data.source.viewersintegerYesDistinct viewers who submitted ballots; never a synthetic vote count. minimum: 0
data.source.confidencestring (high, medium, low)YesHigh when viewers >= 10; medium when an AI estimate is present or viewers are 3–9; low otherwise. Confidence describes evidence, not a probability.
data.urlstringYesCanonical title page URL in the requested language.
data.urlsobjectYesCanonical title page URLs in both languages.
data.urls.kastringYesCanonical Georgian title page URL.
data.urls.enstringYesCanonical English title page URL.
data.attributionobjectYesRequired display attribution and backlink.
data.attribution.textstring (Emotion data: FeelDB, ემოციების მონაცემები: FeelDB)YesLocalized attribution text.
data.attribution.urlstringYesFeelDB title page backlink; use this returned URL.
data.attribution.termsstringYesURL of attribution terms; use this returned URL.
data.updated_atstringYesUTC ISO-8601 timestamp of the latest AI estimate or viewer ballot, falling back to title updated_at.
tstringYes pattern: ^tt[0-9]{7,10}$
sstring (ok, insufficient_data)Yes
earray<tuple<integer, integer>>Yes maxItems: 3
ustringYes pattern: ^/
xintegerYes minimum: 1
sany (ok)No
sany (insufficient_data)No
eanyNo maxItems: 0
title-ok
{
    "data": {
        "imdb_id": "tt0092929",
        "type": "movie",
        "year": 1988,
        "title": {
            "original": "Drowning by Numbers",
            "en": "Drowning by Numbers",
            "ka": null
        },
        "status": "ok",
        "emotions": [
            {
                "rank": 1,
                "key": "confusion",
                "label": "Confusion",
                "labels": {
                    "ka": "დაბნეულობა",
                    "en": "Confusion"
                },
                "share": 18,
                "family": "play",
                "color": "#B8E04A",
                "icon": "https://feeldb.resoftware.ai/api/public/v1/icons/confusion.svg"
            },
            {
                "rank": 2,
                "key": "humor",
                "label": "Humor",
                "labels": {
                    "ka": "იუმორი",
                    "en": "Humor"
                },
                "share": 15,
                "family": "play",
                "color": "#B8E04A",
                "icon": "https://feeldb.resoftware.ai/api/public/v1/icons/humor.svg"
            },
            {
                "rank": 3,
                "key": "joy",
                "label": "Joy",
                "labels": {
                    "ka": "სიხარული",
                    "en": "Joy"
                },
                "share": 13.3,
                "family": "joy",
                "color": "#FFC53D",
                "icon": "https://feeldb.resoftware.ai/api/public/v1/icons/joy.svg"
            }
        ],
        "source": {
            "kind": "blended",
            "viewers": 2,
            "confidence": "medium"
        },
        "url": "https://feeldb.resoftware.ai/movies/10000-drowning-by-numbers-1988",
        "urls": {
            "ka": "https://feeldb.resoftware.ai/ka/movies/10000-drowning-by-numbers-1988",
            "en": "https://feeldb.resoftware.ai/movies/10000-drowning-by-numbers-1988"
        },
        "attribution": {
            "text": "Emotion data: FeelDB",
            "url": "https://feeldb.resoftware.ai/movies/10000-drowning-by-numbers-1988",
            "terms": "https://feeldb.resoftware.ai/integrations#attribution"
        },
        "updated_at": "2026-10-12T00:25:17Z",
        "name": "Drowning by Numbers",
        "animation": false,
        "tied_with_next": true
    }
}
title-insufficient
{
    "data": {
        "imdb_id": "tt0000001",
        "type": "series",
        "year": 2024,
        "title": {
            "original": "Example",
            "en": "Example",
            "ka": null
        },
        "status": "insufficient_data",
        "emotions": [],
        "source": {
            "kind": "none",
            "viewers": 0,
            "confidence": "low"
        },
        "url": "https://feeldb.resoftware.ai/series/1-example-2024",
        "urls": {
            "ka": "https://feeldb.resoftware.ai/ka/series/1-example-2024",
            "en": "https://feeldb.resoftware.ai/series/1-example-2024"
        },
        "attribution": {
            "text": "Emotion data: FeelDB",
            "url": "https://feeldb.resoftware.ai/series/1-example-2024",
            "terms": "https://feeldb.resoftware.ai/integrations#attribution"
        },
        "updated_at": "2026-10-12T00:00:00Z",
        "name": "Example",
        "animation": false,
        "tied_with_next": false
    }
}
widget
{
    "t": "tt1375666",
    "s": "ok",
    "e": [
        [
            7,
            42
        ],
        [
            12,
            31
        ],
        [
            3,
            18
        ]
    ],
    "u": "/movies/18213-inception-2010",
    "x": 2
}
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
Without pk and flag true: public, max-age=600, s-maxage=3600, stale-while-revalidate=86400. With pk: public, max-age=120, s-maxage=120.
X-Request-Id
Request identifier for diagnostics.
Vary
Accept-Encoding on the pk alias.
Access-Control-Allow-Origin
Wildcard public CORS without credentials.
304 Not modified; no response body. Reuse the cached representation.
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
Without pk and flag true: public, max-age=600, s-maxage=3600, stale-while-revalidate=86400. With pk: public, max-age=120, s-maxage=120.
X-Request-Id
Request identifier for diagnostics.
Vary
Accept-Encoding on the pk alias.
Access-Control-Allow-Origin
Wildcard public CORS without credentials.

No JSON response body.

404 Uniform not_found for unknown, malformed, hidden and pending titles, or missing resources.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 404 fields for getPublicTitleEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-not_found
{
    "error": {
        "code": "not_found",
        "message": "No published title has this IMDb id.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
405 HTTP method not supported.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 405 fields for getPublicTitleEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
422 Invalid request structure or more than 100 batch ids.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 422 fields for getPublicTitleEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-invalid_imdb_id
{
    "error": {
        "code": "invalid_imdb_id",
        "message": "IMDb ids look like tt0111161.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
error-batch_too_large
{
    "error": {
        "code": "batch_too_large",
        "message": "At most 100 ids per batch.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
429 Rate limit or daily lookup quota exceeded; obey Retry-After.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 429 fields for getPublicTitleEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-rate_limited
{
    "error": {
        "code": "rate_limited",
        "message": "Too many requests.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
error-quota_exceeded
{
    "error": {
        "code": "quota_exceeded",
        "message": "Daily quota exceeded.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
Retry-After
Seconds until a retry is permitted; quota errors wait until next UTC midnight.
500 Internal server error without stack traces.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 500 fields for getPublicTitleEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
503 Temporarily unavailable; keyed endpoints fail closed when Redis or DB is unavailable.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 503 fields for getPublicTitleEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-service_unavailable
{
    "error": {
        "code": "service_unavailable",
        "message": "Temporarily unavailable, retry later.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
401 Missing, invalid or revoked publishable key.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 401 fields for getPublicTitleEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-key_required
{
    "error": {
        "code": "key_required",
        "message": "A publishable key is required: add ?pk=… (see docs)",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
Cache-Control
no-store, private
402 Prepaid balance exhausted.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 402 fields for getPublicTitleEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-balance_exhausted
{
    "error": {
        "code": "balance_exhausted",
        "message": "Prepaid balance exhausted",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
Cache-Control
no-store, private
403 Origin not allowed or partner suspended.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 403 fields for getPublicTitleEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-origin_not_allowed
{
    "error": {
        "code": "origin_not_allowed",
        "message": "This key is not allowed from this origin",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
Cache-Control
no-store, private
GET/api/v1/titles/{imdb_id}/emotionsSecret bearer · server

Get dominant emotions by IMDb id

Server-to-server bearer authentication; no browser CORS and no cookies. Cache-Control: private, max-age=300.

Parameters

Parameters for getTitleEmotions
Name / locationTypeRequiredDescription
imdb_id / pathstringYesIMDb title id. Malformed, unknown, hidden and pending ids receive the same 404 envelope.
lang / querystring (ka, en)NoLabel and title language; defaults to ka. Unsupported values normalize to en; all labels retain both languages.
If-None-Match / headerstringNoPreviously received ETag; a match returns 304 without a body.

Responses

200 Successful response.

application/json

Single-title response envelope.

Response 200 fields for getTitleEmotions
FieldTypeRequiredDescription
dataobjectYesPublished title emotion data.
data.imdb_idstringYesIMDb identifier of the published title. pattern: ^tt[0-9]{7,10}$
data.typestring (movie, series)YesMovie or series; animation is a separate flag.
data.yearinteger | nullYesRelease year, or null when unknown.
data.titleobjectYesOriginal and translated title names.
data.title.originalstringYesOriginal title, falling back to English.
data.title.enstringYesEnglish title.
data.title.kastring | nullYesGeorgian title, or null if unavailable.
data.namestringYesTitle in requested language, falling back to English.
data.animationbooleanYesWhether the title is animated.
data.statusstring (ok, insufficient_data)Yesok when at least one emotion qualifies; insufficient_data when none reach the configured minimum share (default 5%). This is a 200 response with an empty emotions array.
data.emotionsarray<object>YesTop up to three emotions with share at least the configured minimum (default 5%), using the same ordering as the title page. maxItems: 3
data.emotions[].rankintegerYesOne-based rank among the returned dominant emotions. minimum: 1; maximum: 3
data.emotions[].keystringYesStable emotion slug.
data.emotions[].labelstringYesEmotion label in requested language.
data.emotions[].labelsobjectYesLabels in both supported languages.
data.emotions[].labels.kastringYesGeorgian label.
data.emotions[].labels.enstringYesEnglish label.
data.emotions[].familystringYesEmotion family grouping in the FeelDB taxonomy.
data.emotions[].colorstringYesFamily display colour as a hexadecimal RGB value. pattern: ^#[0-9A-Fa-f]{6}$
data.emotions[].iconstringYesAbsolute SVG icon URL; use the returned URL rather than constructing one.
data.emotions[].sharenumberYesShare of the title's emotional signal in percent, not % of people; rounded to one decimal. The returned top emotions need not sum to 100. minimum: 0; maximum: 100
data.tied_with_nextbooleanYesWhether rank 3 has the same share as rank 4, signalling a tie at the display cutoff.
data.sourceobjectYesEvidence origin, viewer count and confidence.
data.source.kindstring (ai, blended, viewers, none)Yesai = AI estimate only; blended = AI estimate plus viewer ballots; viewers = viewer ballots only; none = no emotion evidence.
data.source.viewersintegerYesDistinct viewers who submitted ballots; never a synthetic vote count. minimum: 0
data.source.confidencestring (high, medium, low)YesHigh when viewers >= 10; medium when an AI estimate is present or viewers are 3–9; low otherwise. Confidence describes evidence, not a probability.
data.urlstringYesCanonical title page URL in the requested language.
data.urlsobjectYesCanonical title page URLs in both languages.
data.urls.kastringYesCanonical Georgian title page URL.
data.urls.enstringYesCanonical English title page URL.
data.attributionobjectYesRequired display attribution and backlink.
data.attribution.textstring (Emotion data: FeelDB, ემოციების მონაცემები: FeelDB)YesLocalized attribution text.
data.attribution.urlstringYesFeelDB title page backlink; use this returned URL.
data.attribution.termsstringYesURL of attribution terms; use this returned URL.
data.updated_atstringYesUTC ISO-8601 timestamp of the latest AI estimate or viewer ballot, falling back to title updated_at.
title-ok
{
    "data": {
        "imdb_id": "tt0092929",
        "type": "movie",
        "year": 1988,
        "title": {
            "original": "Drowning by Numbers",
            "en": "Drowning by Numbers",
            "ka": null
        },
        "status": "ok",
        "emotions": [
            {
                "rank": 1,
                "key": "confusion",
                "label": "Confusion",
                "labels": {
                    "ka": "დაბნეულობა",
                    "en": "Confusion"
                },
                "share": 18,
                "family": "play",
                "color": "#B8E04A",
                "icon": "https://feeldb.resoftware.ai/api/public/v1/icons/confusion.svg"
            },
            {
                "rank": 2,
                "key": "humor",
                "label": "Humor",
                "labels": {
                    "ka": "იუმორი",
                    "en": "Humor"
                },
                "share": 15,
                "family": "play",
                "color": "#B8E04A",
                "icon": "https://feeldb.resoftware.ai/api/public/v1/icons/humor.svg"
            },
            {
                "rank": 3,
                "key": "joy",
                "label": "Joy",
                "labels": {
                    "ka": "სიხარული",
                    "en": "Joy"
                },
                "share": 13.3,
                "family": "joy",
                "color": "#FFC53D",
                "icon": "https://feeldb.resoftware.ai/api/public/v1/icons/joy.svg"
            }
        ],
        "source": {
            "kind": "blended",
            "viewers": 2,
            "confidence": "medium"
        },
        "url": "https://feeldb.resoftware.ai/movies/10000-drowning-by-numbers-1988",
        "urls": {
            "ka": "https://feeldb.resoftware.ai/ka/movies/10000-drowning-by-numbers-1988",
            "en": "https://feeldb.resoftware.ai/movies/10000-drowning-by-numbers-1988"
        },
        "attribution": {
            "text": "Emotion data: FeelDB",
            "url": "https://feeldb.resoftware.ai/movies/10000-drowning-by-numbers-1988",
            "terms": "https://feeldb.resoftware.ai/integrations#attribution"
        },
        "updated_at": "2026-10-12T00:25:17Z",
        "name": "Drowning by Numbers",
        "animation": false,
        "tied_with_next": true
    }
}
title-insufficient
{
    "data": {
        "imdb_id": "tt0000001",
        "type": "series",
        "year": 2024,
        "title": {
            "original": "Example",
            "en": "Example",
            "ka": null
        },
        "status": "insufficient_data",
        "emotions": [],
        "source": {
            "kind": "none",
            "viewers": 0,
            "confidence": "low"
        },
        "url": "https://feeldb.resoftware.ai/series/1-example-2024",
        "urls": {
            "ka": "https://feeldb.resoftware.ai/ka/series/1-example-2024",
            "en": "https://feeldb.resoftware.ai/series/1-example-2024"
        },
        "attribution": {
            "text": "Emotion data: FeelDB",
            "url": "https://feeldb.resoftware.ai/series/1-example-2024",
            "terms": "https://feeldb.resoftware.ai/integrations#attribution"
        },
        "updated_at": "2026-10-12T00:00:00Z",
        "name": "Example",
        "animation": false,
        "tied_with_next": false
    }
}
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
304 Not modified; no response body. Reuse the cached representation.
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.

No JSON response body.

404 Uniform not_found for unknown, malformed, hidden and pending titles, or missing resources.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 404 fields for getTitleEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-not_found
{
    "error": {
        "code": "not_found",
        "message": "No published title has this IMDb id.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
405 HTTP method not supported.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 405 fields for getTitleEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
422 Invalid request structure or more than 100 batch ids.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 422 fields for getTitleEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-invalid_imdb_id
{
    "error": {
        "code": "invalid_imdb_id",
        "message": "IMDb ids look like tt0111161.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
error-batch_too_large
{
    "error": {
        "code": "batch_too_large",
        "message": "At most 100 ids per batch.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
429 Rate limit or daily lookup quota exceeded; obey Retry-After.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 429 fields for getTitleEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-rate_limited
{
    "error": {
        "code": "rate_limited",
        "message": "Too many requests.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
error-quota_exceeded
{
    "error": {
        "code": "quota_exceeded",
        "message": "Daily quota exceeded.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
Retry-After
Seconds until a retry is permitted; quota errors wait until next UTC midnight.
500 Internal server error without stack traces.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 500 fields for getTitleEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
503 Temporarily unavailable; keyed endpoints fail closed when Redis or DB is unavailable.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 503 fields for getTitleEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-service_unavailable
{
    "error": {
        "code": "service_unavailable",
        "message": "Temporarily unavailable, retry later.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
401 Missing, invalid or revoked bearer key.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 401 fields for getTitleEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-unauthorized
{
    "error": {
        "code": "unauthorized",
        "message": "Missing or invalid API key.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
403 Partner account suspended.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 403 fields for getTitleEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-partner_suspended
{
    "error": {
        "code": "partner_suspended",
        "message": "This partner account is suspended.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
402 balance_exhausted: prepaid balance exhausted.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 402 fields for getTitleEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
Cache-Control
no-store, private
GET/api/v1/widget/{imdb_id}Publishable key in ?pk= · browser

Get compact emotions with a publishable key

Requires a matching Origin. No cookies or X-RateLimit-* headers. Ranked emotion tuples contain at most three entries; insufficient_data has an empty e. Canonical u has no host. 200 and 304 consume quota and a metered lookup.

Parameters

Parameters for getWidgetEmotions
Name / locationTypeRequiredDescription
imdb_id / pathstringYesIMDb title id. Malformed, unknown, hidden and pending ids receive the same 404 envelope.
pk / querystringYes
lang / querystring (ka, en)No

Responses

200 Compact public emotion payload.

application/json

Response 200 fields for getWidgetEmotions
FieldTypeRequiredDescription
tstringYes pattern: ^tt[0-9]{7,10}$
sstring (ok, insufficient_data)Yes
earray<tuple<integer, integer>>Yes maxItems: 3
ustringYes pattern: ^/
xintegerYes minimum: 1
sany (ok)No
sany (insufficient_data)No
eanyNo maxItems: 0
Example
{
    "t": "tt1375666",
    "s": "ok",
    "e": [
        [
            7,
            42
        ],
        [
            12,
            31
        ],
        [
            3,
            18
        ]
    ],
    "u": "/movies/18213-inception-2010",
    "x": 2
}
Response headers
Cache-Control
public, max-age=120, s-maxage=120
ETag
Weak payload validator; 304 still consumes a metered lookup.
Access-Control-Allow-Origin
*
Vary
Accept-Encoding
304 Not modified; no response body.
Response headers
Cache-Control
public, max-age=120, s-maxage=120
ETag
Weak payload validator; 304 still consumes a metered lookup.
Access-Control-Allow-Origin
*
Vary
Accept-Encoding

No JSON response body.

401 Missing, invalid or revoked publishable key.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 401 fields for getWidgetEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-key_required
{
    "error": {
        "code": "key_required",
        "message": "A publishable key is required: add ?pk=… (see docs)",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
Cache-Control
no-store, private
402 Prepaid balance exhausted.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 402 fields for getWidgetEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-balance_exhausted
{
    "error": {
        "code": "balance_exhausted",
        "message": "Prepaid balance exhausted",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
Cache-Control
no-store, private
403 Origin not allowed or partner suspended.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 403 fields for getWidgetEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-origin_not_allowed
{
    "error": {
        "code": "origin_not_allowed",
        "message": "This key is not allowed from this origin",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
Cache-Control
no-store, private
404 Title not found.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 404 fields for getWidgetEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
Cache-Control
no-store, private
429 Quota or rate limit exceeded.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 429 fields for getWidgetEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
Cache-Control
no-store, private
503 Billing service unavailable.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 503 fields for getWidgetEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
Cache-Control
no-store, private
500 Unexpected server error.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 500 fields for getWidgetEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
Cache-Control
no-store, private
GET/api/v1/titles/{imdb_id}/arcPublishable key in ?pk= · browser OR Secret bearer · server

Get an entitled compact emotion arc

Requires the arcs add-on before billing. Use pk query with matching Origin or secret bearer. Unsupported bins encode null in d and i. Unknown, hidden, pending and ineligible titles share a 404. Warm eligible payloads may remain cached for up to 600 seconds. Every 200/304 is metered, including immediate revocation checks. Publishable responses use C-6 headers and no cookies or X-RateLimit-*; secret responses use private, max-age=300 and no CORS.

Parameters

Parameters for getTitleArc
Name / locationTypeRequiredDescription
imdb_id / pathstringYesIMDb title id. Malformed, unknown, hidden and pending ids receive the same 404 envelope.
pk / querystringNo

Responses

200 Compact public emotion payload.

application/json

Response 200 fields for getTitleArc
FieldTypeRequiredDescription
vinteger (1)Yes
binteger (20)Yes
darray<integer | null>YesTaxonomy emotion ids; unsupported bins are null. minItems: 20; maxItems: 20
iarray<integer | null>YesRound-half-up integer percent; unsupported bins are null at the same positions as d. minItems: 20; maxItems: 20
tarray<tuple<string (peak, valley, rise, fall), integer>>Yes maxItems: 3
Example
{
    "v": 1,
    "b": 20,
    "d": [
        7,
        29,
        29,
        29,
        29,
        29,
        29,
        29,
        29,
        29,
        29,
        29,
        29,
        29,
        29,
        29,
        29,
        29,
        29,
        29
    ],
    "i": [
        20,
        23,
        25,
        28,
        30,
        33,
        35,
        38,
        40,
        43,
        45,
        48,
        50,
        53,
        55,
        58,
        60,
        63,
        65,
        68
    ],
    "t": [
        [
            "peak",
            7
        ],
        [
            "valley",
            13
        ]
    ]
}
Response headers
Cache-Control
Publishable: public, max-age=120, s-maxage=120. Secret: private, max-age=300.
ETag
Weak payload validator; 304 still consumes a metered lookup.
Access-Control-Allow-Origin
Present only for publishable-key requests.
Vary
Accept-Encoding
304 Not modified; no response body.
Response headers
Cache-Control
Publishable: public, max-age=120, s-maxage=120. Secret: private, max-age=300.
ETag
Weak payload validator; 304 still consumes a metered lookup.
Access-Control-Allow-Origin
Present only for publishable-key requests.
Vary
Accept-Encoding

No JSON response body.

401 Missing, invalid or revoked publishable key.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 401 fields for getTitleArc
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-key_required
{
    "error": {
        "code": "key_required",
        "message": "A publishable key is required: add ?pk=… (see docs)",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
Cache-Control
no-store, private
402 Prepaid balance exhausted.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 402 fields for getTitleArc
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-balance_exhausted
{
    "error": {
        "code": "balance_exhausted",
        "message": "Prepaid balance exhausted",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
Cache-Control
no-store, private
403 addon_required, origin_not_allowed or partner_suspended.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 403 fields for getTitleArc
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-addon_required
{
    "error": {
        "code": "addon_required",
        "message": "This add-on is not enabled for your key",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
Cache-Control
no-store, private
404 Title not found.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 404 fields for getTitleArc
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
Cache-Control
no-store, private
429 Quota or rate limit exceeded.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 429 fields for getTitleArc
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
Cache-Control
no-store, private
503 Billing service unavailable.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 503 fields for getTitleArc
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
Cache-Control
no-store, private
500 Unexpected server error.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 500 fields for getTitleArc
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
Cache-Control
no-store, private

Batch

POST/api/v1/emotions/batchSecret bearer · server

Look up up to 100 IMDb ids

Keyed only; no keyless batch endpoint. Deduplicates ids case-insensitively and preserves request order. Default quota 50,000 lookups per UTC day; default keyed rate 120 requests/minute. No browser CORS.

Request body

JSON batch body, at most 16 KiB.

application/json

At most 100 identifiers and optional language; the whole body must be at most 16 KiB.

Request body fields for batchTitleEmotions
FieldTypeRequiredDescription
imdb_idsarray<string>YesIMDb identifiers; malformed strings are reported in invalid, valid ids use ^tt[0-9]{7,10}$. maxItems: 100
langstring (ka, en)NoRequested language; defaults to ka.
Example
{
    "imdb_ids": [
        "tt0092929",
        "tt9999999",
        "abc"
    ],
    "lang": "en"
}

Responses

200 Successful response.

application/json

Batch results in request order, deduplicated case-insensitively. Malformed ids are listed, not rejected individually.

Response 200 fields for batchTitleEmotions
FieldTypeRequiredDescription
dataarray<object>YesFound published titles in request order. maxItems: 100
data[].imdb_idstringYesIMDb identifier of the published title. pattern: ^tt[0-9]{7,10}$
data[].typestring (movie, series)YesMovie or series; animation is a separate flag.
data[].yearinteger | nullYesRelease year, or null when unknown.
data[].titleobjectYesOriginal and translated title names.
data[].title.originalstringYesOriginal title, falling back to English.
data[].title.enstringYesEnglish title.
data[].title.kastring | nullYesGeorgian title, or null if unavailable.
data[].namestringYesTitle in requested language, falling back to English.
data[].animationbooleanYesWhether the title is animated.
data[].statusstring (ok, insufficient_data)Yesok when at least one emotion qualifies; insufficient_data when none reach the configured minimum share (default 5%). This is a 200 response with an empty emotions array.
data[].emotionsarray<object>YesTop up to three emotions with share at least the configured minimum (default 5%), using the same ordering as the title page. maxItems: 3
data[].emotions[].rankintegerYesOne-based rank among the returned dominant emotions. minimum: 1; maximum: 3
data[].emotions[].keystringYesStable emotion slug.
data[].emotions[].labelstringYesEmotion label in requested language.
data[].emotions[].labelsobjectYesLabels in both supported languages.
data[].emotions[].labels.kastringYesGeorgian label.
data[].emotions[].labels.enstringYesEnglish label.
data[].emotions[].familystringYesEmotion family grouping in the FeelDB taxonomy.
data[].emotions[].colorstringYesFamily display colour as a hexadecimal RGB value. pattern: ^#[0-9A-Fa-f]{6}$
data[].emotions[].iconstringYesAbsolute SVG icon URL; use the returned URL rather than constructing one.
data[].emotions[].sharenumberYesShare of the title's emotional signal in percent, not % of people; rounded to one decimal. The returned top emotions need not sum to 100. minimum: 0; maximum: 100
data[].tied_with_nextbooleanYesWhether rank 3 has the same share as rank 4, signalling a tie at the display cutoff.
data[].sourceobjectYesEvidence origin, viewer count and confidence.
data[].source.kindstring (ai, blended, viewers, none)Yesai = AI estimate only; blended = AI estimate plus viewer ballots; viewers = viewer ballots only; none = no emotion evidence.
data[].source.viewersintegerYesDistinct viewers who submitted ballots; never a synthetic vote count. minimum: 0
data[].source.confidencestring (high, medium, low)YesHigh when viewers >= 10; medium when an AI estimate is present or viewers are 3–9; low otherwise. Confidence describes evidence, not a probability.
data[].urlstringYesCanonical title page URL in the requested language.
data[].urlsobjectYesCanonical title page URLs in both languages.
data[].urls.kastringYesCanonical Georgian title page URL.
data[].urls.enstringYesCanonical English title page URL.
data[].attributionobjectYesRequired display attribution and backlink.
data[].attribution.textstring (Emotion data: FeelDB, ემოციების მონაცემები: FeelDB)YesLocalized attribution text.
data[].attribution.urlstringYesFeelDB title page backlink; use this returned URL.
data[].attribution.termsstringYesURL of attribution terms; use this returned URL.
data[].updated_atstringYesUTC ISO-8601 timestamp of the latest AI estimate or viewer ballot, falling back to title updated_at.
not_foundarray<string>YesUnknown, hidden or pending IMDb ids, without distinguishing those cases. maxItems: 100
invalidarray<string>YesMalformed input ids in request order. maxItems: 100
batch
{
    "data": [
        {
            "imdb_id": "tt0092929",
            "type": "movie",
            "year": 1988,
            "title": {
                "original": "Drowning by Numbers",
                "en": "Drowning by Numbers",
                "ka": null
            },
            "status": "ok",
            "emotions": [
                {
                    "rank": 1,
                    "key": "confusion",
                    "label": "Confusion",
                    "labels": {
                        "ka": "დაბნეულობა",
                        "en": "Confusion"
                    },
                    "share": 18,
                    "family": "play",
                    "color": "#B8E04A",
                    "icon": "https://feeldb.resoftware.ai/api/public/v1/icons/confusion.svg"
                },
                {
                    "rank": 2,
                    "key": "humor",
                    "label": "Humor",
                    "labels": {
                        "ka": "იუმორი",
                        "en": "Humor"
                    },
                    "share": 15,
                    "family": "play",
                    "color": "#B8E04A",
                    "icon": "https://feeldb.resoftware.ai/api/public/v1/icons/humor.svg"
                },
                {
                    "rank": 3,
                    "key": "joy",
                    "label": "Joy",
                    "labels": {
                        "ka": "სიხარული",
                        "en": "Joy"
                    },
                    "share": 13.3,
                    "family": "joy",
                    "color": "#FFC53D",
                    "icon": "https://feeldb.resoftware.ai/api/public/v1/icons/joy.svg"
                }
            ],
            "source": {
                "kind": "blended",
                "viewers": 2,
                "confidence": "medium"
            },
            "url": "https://feeldb.resoftware.ai/movies/10000-drowning-by-numbers-1988",
            "urls": {
                "ka": "https://feeldb.resoftware.ai/ka/movies/10000-drowning-by-numbers-1988",
                "en": "https://feeldb.resoftware.ai/movies/10000-drowning-by-numbers-1988"
            },
            "attribution": {
                "text": "Emotion data: FeelDB",
                "url": "https://feeldb.resoftware.ai/movies/10000-drowning-by-numbers-1988",
                "terms": "https://feeldb.resoftware.ai/integrations#attribution"
            },
            "updated_at": "2026-10-12T00:25:17Z",
            "name": "Drowning by Numbers",
            "animation": false,
            "tied_with_next": true
        }
    ],
    "not_found": [
        "tt9999999"
    ],
    "invalid": [
        "abc"
    ]
}
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
401 Missing, invalid or revoked bearer key.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 401 fields for batchTitleEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-unauthorized
{
    "error": {
        "code": "unauthorized",
        "message": "Missing or invalid API key.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
403 Partner account suspended.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 403 fields for batchTitleEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-partner_suspended
{
    "error": {
        "code": "partner_suspended",
        "message": "This partner account is suspended.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
405 HTTP method not supported.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 405 fields for batchTitleEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
413 Payload exceeds the 16 KiB body limit.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 413 fields for batchTitleEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
422 Invalid request structure or more than 100 batch ids.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 422 fields for batchTitleEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-batch_too_large
{
    "error": {
        "code": "batch_too_large",
        "message": "At most 100 ids per batch.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
error-validation_error
{
    "error": {
        "code": "validation_error",
        "message": "Invalid request body.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
429 Rate limit or daily lookup quota exceeded; obey Retry-After.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 429 fields for batchTitleEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-rate_limited
{
    "error": {
        "code": "rate_limited",
        "message": "Too many requests.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
error-quota_exceeded
{
    "error": {
        "code": "quota_exceeded",
        "message": "Daily quota exceeded.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
Retry-After
Seconds until a retry is permitted; quota errors wait until next UTC midnight.
500 Internal server error without stack traces.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 500 fields for batchTitleEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
503 Temporarily unavailable; keyed endpoints fail closed when Redis or DB is unavailable.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 503 fields for batchTitleEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-service_unavailable
{
    "error": {
        "code": "service_unavailable",
        "message": "Temporarily unavailable, retry later.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
402 balance_exhausted: prepaid balance exhausted.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 402 fields for batchTitleEmotions
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
Cache-Control
no-store, private

Catalog

GET/api/v1/emotionsKeyless · public

Get the emotion taxonomy

Keyless, CORS * without credentials, public cache for one day; no cookies. Taxonomy version 2 has 28 entries.

Parameters

Parameters for getEmotionCatalog
Name / locationTypeRequiredDescription
lang / querystring (ka, en)NoLabel and title language; defaults to ka. Unsupported values normalize to en; all labels retain both languages.
If-None-Match / headerstringNoPreviously received ETag; a match returns 304 without a body.

Responses

200 Successful response.

application/json

Emotion taxonomy ordered by catalog position.

Response 200 fields for getEmotionCatalog
FieldTypeRequiredDescription
dataarray<object>YesCurrent taxonomy entries (28 in version 2).
data[].keystringYesStable emotion slug.
data[].labelstringYesEmotion label in requested language.
data[].labelsobjectYesLabels in both supported languages.
data[].labels.kastringYesGeorgian label.
data[].labels.enstringYesEnglish label.
data[].familystringYesEmotion family grouping in the FeelDB taxonomy.
data[].colorstringYesFamily display colour as a hexadecimal RGB value. pattern: ^#[0-9A-Fa-f]{6}$
data[].iconstringYesAbsolute SVG icon URL; use the returned URL rather than constructing one.
taxonomy_versionintegerYesVersion of the taxonomy used by these entries. minimum: 1
catalog
{
    "data": [
        {
            "key": "joy",
            "labels": {
                "ka": "სიხარული",
                "en": "Joy"
            },
            "label": "Joy",
            "family": "joy",
            "color": "#FFC53D",
            "icon": "https://feeldb.resoftware.ai/api/public/v1/icons/joy.svg"
        }
    ],
    "taxonomy_version": 2
}
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
304 Not modified; no response body. Reuse the cached representation.
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.

No JSON response body.

405 HTTP method not supported.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 405 fields for getEmotionCatalog
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
429 Rate limit or daily lookup quota exceeded; obey Retry-After.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 429 fields for getEmotionCatalog
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-rate_limited
{
    "error": {
        "code": "rate_limited",
        "message": "Too many requests.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
error-quota_exceeded
{
    "error": {
        "code": "quota_exceeded",
        "message": "Daily quota exceeded.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
Retry-After
Seconds until a retry is permitted; quota errors wait until next UTC midnight.
500 Internal server error without stack traces.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 500 fields for getEmotionCatalog
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
503 Temporarily unavailable; keyed endpoints fail closed when Redis or DB is unavailable.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 503 fields for getEmotionCatalog
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-service_unavailable
{
    "error": {
        "code": "service_unavailable",
        "message": "Temporarily unavailable, retry later.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
GET/api/public/v1/icons/{slug}.svgKeyless · public

Get an emotion SVG icon

Keyless whitelisted icon; no raw input path joins. Cache-Control: public, max-age=31536000, immutable; X-Content-Type-Options: nosniff.

Parameters

Parameters for getEmotionIcon
Name / locationTypeRequiredDescription
slug / pathstringYesWhitelisted catalog emotion slug. Unknown slugs return 404.

Responses

200 Successful response.

image/svg+xml

SVG markup.

Type: string

Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
X-Content-Type-Options
Prevents MIME sniffing.
404 Uniform not_found for unknown, malformed, hidden and pending titles, or missing resources.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 404 fields for getEmotionIcon
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-not_found
{
    "error": {
        "code": "not_found",
        "message": "No published title has this IMDb id.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
405 HTTP method not supported.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 405 fields for getEmotionIcon
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
500 Internal server error without stack traces.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 500 fields for getEmotionIcon
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
GET/api/v1/openapi.jsonKeyless · public

Get the OpenAPI 3.1 contract

Single source of the API contract and changelog; keyless, CORS *, public cache for one hour.

Responses

200 Successful response.

application/json

OpenAPI 3.1 document, including info, paths and components.

Type: object

Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
404 Uniform not_found for unknown, malformed, hidden and pending titles, or missing resources.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 404 fields for getOpenApiDocument
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-not_found
{
    "error": {
        "code": "not_found",
        "message": "No published title has this IMDb id.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
405 HTTP method not supported.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 405 fields for getOpenApiDocument
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
500 Internal server error without stack traces.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 500 fields for getOpenApiDocument
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.

Account

GET/api/v1/meSecret bearer · server

Get current partner limits and usage

Secret bearer only. Query pk and bearer publishable keys are refused without billing data. Integer money is in currency minor units; two current tariffs with UTC effective timestamps. No internal statement pending/state fields are exposed.

Responses

200 Successful response.

application/json

Partner account and current UTC-day usage, visible only with a secret key.

Response 200 fields for getPartnerAccount
FieldTypeRequiredDescription
clientobjectYesPartner account identity.
client.namestringYesPartner organisation name.
keyobjectYesSafe key metadata; no secret is returned.
key.prefixstringYesIdentifiable public key prefix.
key.created_atstringYesUTC ISO-8601 key issuance timestamp.
limitsobjectYesLimits configured for this partner.
limits.per_minuteintegerYesRequest limit per minute. minimum: 1
limits.daily_quotaintegerYesIMDb lookup quota per UTC day. minimum: 1
usageobjectYesBuffered usage counters for today.
usage.today_requestsintegerYesRequests recorded today. minimum: 0
usage.today_idsintegerYesIMDb lookups consumed today. minimum: 0
usage.remaining_idsintegerYesLookups remaining in the daily quota. minimum: 0
billingobjectYes
billing.balanceintegerYesInteger currency minor units (e.g. tetri). minimum: 0
billing.allowance_remainingintegerYesRemaining free emotion lookup units; arcs do not consume this allowance. minimum: 0
billing.currencystringYes
billing.tariffstuple<object, object>YesCurrent emotions then arcs tariffs; effective_from is UTC ISO-8601. minItems: 2; maxItems: 2
billing.tariffs[0].productstring (emotions)Yes
billing.tariffs[0].price_per_1000integerYesInteger currency minor units per 1000 lookups. minimum: 0
billing.tariffs[0].currencystringYes
billing.tariffs[0].effective_fromstringYes format: date-time
billing.tariffs[1].productstring (arcs)Yes
billing.tariffs[1].price_per_1000integerYesInteger currency minor units per 1000 lookups. minimum: 0
billing.tariffs[1].currencystringYes
billing.tariffs[1].effective_fromstringYes format: date-time
billing.addonsarray<string>Yes
Response headers
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
401 Missing, invalid or revoked bearer key.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 401 fields for getPartnerAccount
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-unauthorized
{
    "error": {
        "code": "unauthorized",
        "message": "Missing or invalid API key.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
403 Partner account suspended.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 403 fields for getPartnerAccount
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-partner_suspended
{
    "error": {
        "code": "partner_suspended",
        "message": "This partner account is suspended.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
405 HTTP method not supported.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 405 fields for getPartnerAccount
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
429 Rate limit or daily lookup quota exceeded; obey Retry-After.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 429 fields for getPartnerAccount
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-rate_limited
{
    "error": {
        "code": "rate_limited",
        "message": "Too many requests.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
error-quota_exceeded
{
    "error": {
        "code": "quota_exceeded",
        "message": "Daily quota exceeded.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
Retry-After
Seconds until a retry is permitted; quota errors wait until next UTC midnight.
500 Internal server error without stack traces.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 500 fields for getPartnerAccount
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.
503 Temporarily unavailable; keyed endpoints fail closed when Redis or DB is unavailable.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 503 fields for getPartnerAccount
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
error-service_unavailable
{
    "error": {
        "code": "service_unavailable",
        "message": "Temporarily unavailable, retry later.",
        "docs": "https://feeldb.resoftware.ai/integrations/docs#errors"
    }
}
Response headers
ETag
Payload validator; send it as If-None-Match for a bodyless 304.
Cache-Control
HTTP caching policy; public surfaces are edge-cacheable, keyed responses are private.
X-RateLimit-Limit
Requests allowed per minute.
X-RateLimit-Remaining
Requests remaining in the minute window.
X-RateLimit-Reset
Unix timestamp at which the rate-limit window resets.
X-Request-Id
Request identifier for diagnostics.

Widget

POST/api/public/v1/widget/reportKeyless · public

Report a widget failure

Stateless aggregate beacon, no authentication or billing. Only text/plain bodies at most 512 bytes matching the grammar are recorded. Accepted and invalid reports return 204; limiter rejects with 429 without storage (10/min/IP, 600/min/pk). At most 50 domain|code fields per key/day; no raw title id, IP, URL or token is stored. No cookies.

Request body

text/plain

ASCII grammar; byte limit 512. Invalid bodies are silently discarded.

Type: string

Example
"fdb_pk_abcdefghijkl_ABCDEFGHIJKLMNOPQRSTUVWX network tt1375666"

Responses

204 Accepted or silently discarded invalid report. No body.
Response headers
Cache-Control
no-store, private
Access-Control-Allow-Origin
*

No JSON response body.

429 rate_limited: report rejected by limiter; nothing recorded.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 429 fields for reportWidgetFailure
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
Cache-Control
no-store, private
500 Unexpected server error.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 500 fields for reportWidgetFailure
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
Cache-Control
no-store, private
503 Service unavailable.

application/json

Uniform JSON error envelope. Never includes stack traces or private title information.

Response 503 fields for reportWidgetFailure
FieldTypeRequiredDescription
errorobjectYesStable machine-readable error and human help.
error.codestring (not_found, invalid_imdb_id, unauthorized, key_revoked, partner_suspended, rate_limited, quota_exceeded, batch_too_large, payload_too_large, method_not_allowed, server_error, service_unavailable, validation_error, key_required, balance_exhausted, origin_not_allowed, addon_required)YesStable error code. not_found covers absent routes and malformed, unknown, hidden or pending single-title ids. validation_error covers malformed batch bodies.
error.messagestringYesHuman-readable explanation; do not parse this for control flow.
error.docsstringYesAbsolute English error documentation URL.
Response headers
Cache-Control
no-store, private