OpenEmotions™

API guide

Local base URL: http://localhost:8000 for Python, or http://localhost:8080 for Compose. Planned production base URL: https://api.open-emotions.com. Public deployment must be configured before using that address.

API version: /v1/. No account, API key, or authentication is required for v0.1 reads. Contributions use GitHub pull requests; canonical POST, PUT, PATCH and DELETE routes do not exist.

Quick start

curl http://localhost:8000/v1/emotions/anger
curl 'http://localhost:8000/v1/emotions?valence=negative&sort=name&page=1&page_size=10'
curl 'http://localhost:8000/v1/transitions?from=frustration&to=anger&trigger=goal-obstruction'

import json
from urllib.request import urlopen
with urlopen('http://localhost:8000/v1/emotions/anger', timeout=10) as response:
    emotion = json.load(response)
print(emotion['data']['short_definition'])

const response = await fetch('http://localhost:8000/v1/emotions/anger');
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const { data, meta } = await response.json();
console.log(data.name, meta.dataset_version);

Routes

GET /health checks database connectivity and the configured dataset import. GET /v1/meta returns release identity and available collections.

The following collections each have GET /v1/<collection> and GET /v1/<collection>/{slug}:

  • emotions
  • triggers
  • appraisals
  • responses
  • modifiers
  • transitions
  • intensity_descriptors
  • sources
  • evidence
  • contributors
  • reviews

Emotion relationship lists are available at /v1/emotions/{slug}/triggers, /appraisals, /responses, /transitions, and /evidence. The transitions endpoint includes incoming and outgoing shifts. Evidence lists the claims whose subject is that emotion; follow individual claim details for sources and incoming reviews.

Query behavior

search performs a case-insensitive literal substring search on name and description, up to 200 characters. % and _ are literal characters, not wildcard operators. valence, evidence_status and family match exact values. Transition filters from, to, and trigger take exact slugs. Filters intended for a different entity type return no matching records where applicable.

sort accepts name, slug, evidence_status, or their - prefixed descending equivalents. Stable IDs break ties. Pagination uses page (one-based) and page_size (1–100, default 24). An out-of-range page returns an empty list. Every collection and relationship response includes page, page_size, total, and pages. With zero matches, pages is 0. Relationship endpoints use a stable name/ID order.

Envelopes

Abbreviated response:

{
  "data": [{"slug": "anger", "evidence_status": "editorial_seed"}],
  "meta": {
    "api_version": "v1", "software_version": "0.1.0",
    "dataset_version": "0.1.0", "schema_version": "0.1.0",
    "source_git_commit": "unknown", "dataset_digest": "sha256 content digest"
  },
  "pagination": {"page": 1, "page_size": 24, "total": 24, "pages": 1}
}

Single-record responses use an object in data and a null pagination field. Record data includes stable namespaced IDs, versions, dates, and evidence status. Source Git commit is unknown in a checkout with no commit. Dataset digest remains a reproducible content identity.

Errors and limits

{"error":{"code":"entity_not_found","message":"Emotion 'xyz' was not found.","request_id":"request UUID"}}
  • 400: malformed request where applicable.
  • 404: unknown record, collection, document, or export format.
  • 405: unsupported method, including canonical writes.
  • 422: invalid pagination, sort, or other typed request input.
  • 429: per-process anonymous request limit reached; honor Retry-After.
  • 500: unexpected failure; public output contains no traceback.
  • 503: database or configured dataset is not ready.

X-Request-ID correlates a response with server logs. Do not send credentials in search fields. The default anonymous budget is 120 requests per minute per client connection address, per process, configurable by the operator. Other page requests also contribute to the local counter. This is a basic safeguard, not a distributed quota. Production should enforce fair-use limits at the trusted ingress and restrict forwarded headers to that ingress.

Evidence and graphs

Editorial seeds are not scientific findings. Unknown values stay null. Evidence claims, source links and reviews explain the scope of individual assertions. IDs such as openemotions:emotion:anger are the same in the database and graph. Graph edges describe possible relations, never deterministic predictions.

Download snapshots at /downloads/json, /downloads/yaml, /downloads/csv. CSV contains a complete payload_json alongside display columns; display strings are spreadsheet-formula neutralized. Release exports include dataset/schema version, date, commit, and attribution. Canonical YAML remains authoritative.

Interactive definitions: Swagger UI, ReDoc, OpenAPI JSON. Python and JavaScript examples are included in the repository. v0.x may evolve; retain stable IDs and pin dataset versions for reproducible research.