API guide

Base URL: https://www.open-emotions.com/v1. JSON over HTTPS. The API version is in the path (/v1); changes within it are additions only.

Authentication

Send Authorization: Bearer oe_live_… on POST /v1/classify. GET /v1/meta and GET /v1/health are public.

Keys are issued by the project, one for each app that connects. A key has its own rate limit and can be revoked. To run without a key, download the weights: see Models.

Quick start

curl https://www.open-emotions.com/v1/meta

curl https://www.open-emotions.com/v1/classify \
  -H "Authorization: Bearer oe_live_…" \
  -H "Content-Type: application/json" \
  -d '{"blocks":[{"id":"a","text":"Thank you so much!"}]}'

const response = await fetch("https://www.open-emotions.com/v1/classify", {
  method: "POST",
  headers: { authorization: "Bearer oe_live_…", "content-type": "application/json" },
  body: JSON.stringify({ blocks: [{ id: "a", text: "Thank you so much!" }] }),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const { results, labels, provenance } = await response.json();
console.log(results[0].scores, provenance.model);

Routes

• GET /v1/meta returns everything a client needs to attach the observer: its identity, the 28 labels in order with their groups and meanings, how scores are to be read, the model and revision, and the limits.
• POST /v1/classify scores blocks of text. One result per block, in request order.
• GET /v1/health reports whether the observer is up and whether the model is warm.

Classify

Request

{
  "blocks": [
    { "id": "a", "text": "Thank you so much!", "before": "…", "after": "…" }
  ],
  "client": { "name": "my-app" }
}

• blocks: 1 to 32 blocks. Each has text (up to 4,000 characters) and an optional id that is echoed back.
• before and after: optional context, up to 600 characters each. It is accepted but not scored.
• client.name: optional, to identify your app in our logs.

Response

{
  "results": [
    { "id": "a", "scores": [0.02, 0.01, …] }
  ],
  "labels": "goemotions@1",
  "provenance": {
    "observer": { "id": "open-emotions", "version": "0.2.0" },
    "implementation": "…",
    "model": { "id": "…", "revision": "…" },
    "requestId": "req_…",
    "at": "2026-01-01T00:00:00.000Z",
    "durationMs": 120
  },
  "usage": { "blocks": 1, "scored": 1, "chars": 18 }
}

• scores holds 28 numbers from 0 to 1, in the label order that /v1/meta returns.
• A block that couldn't be scored has "scores": null with a reason and retryable. A blank block has the reason empty.
• provenance names the model and revision that produced the scores. Store it with them.

Reading the scores

Each score is the classifier's confidence that the emotion is expressed in the text. The labels are independent, so several can be high at once. A score is not an intensity, and not evidence of what anyone feels. See Limitations.

Errors

Every error has the same shape. retryable says whether the same request can succeed later.

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests for this key. Try again in 12 seconds.",
    "retryable": true,
    "retryAfterSeconds": 12,
    "requestId": "req_…"
  }
}

Limits

• 60 requests per minute for each key.
• 32 blocks per request, 4,000 characters per block, 256 KB per request body.

Browsers

The API answers cross-origin requests from any origin and never uses cookies. A key in browser code is visible to anyone, so call the API from your server.