FLARE engine

Notice the moment before anyone asks.

Sign in to try it

Example results

What FLARE returns

Real results, not mock-ups.

Sent

3 messages in a public channel — Banter that reads as "kys", aimed at a teammate who then goes quiet. FLARE raises one signal about the person who said it and one about the person it hit.

Public channelkai, ren

kai

my bad on that last round guys

ren

bro you threw the whole game, kys honestly lmao

kai

...ok. i'm just gonna log off

Returned by FLARE v0 · API v1.

FLARE raises structured signals that someone can act on; it does not act on anyone.

Classify a conversation window

Funded account or a bound service bearer40 calls / hour per accountusually 5–25s; up to ~60s more when the model asks for a second, deeper pass; hard budget 270s (the second pass is skipped rather than overrun it)

Classifies the messages you send. Nothing is delivered. An identical resubmit within 10 minutes is not charged twice (see `dedupe`).

· A quiet window returns an empty signals array.

Request body

Field	Type	Meaning
`messages`required	`Message[] (1–40)`	The window, oldest first. Each message: author (any stable label), text (≤1200 chars), optional at (ISO time), mentionsShepherd (true when the message @-mentions Shepherd), mentions (author labels this message @-mentions).
`surface`	`"discord_public" \| "discord_dm"`	Where the window came from. DMs are treated as already directed at Shepherd. Default discord_public.
`channelName`	`string`	Optional channel name — context for the model (e.g. "lobby", "prayer-requests").
`escalate`	`boolean`	Allow the second, stronger pass when the first pass self-flags the window as ambiguous. Default true (production behavior).
`botCapabilities`	`{ resourceSubmissions?, clarificationResourceSubmissions? }`	What the delivering bot can render. Production drops a resource_submission for a bot without the submission capability (and a needs_clarification one without its own), so readiness reflects the same filter. Default: both true (the current bot).

Response

Field	Type	Meaning
`signals[]`	`Signal[]`	Each signal FLARE raises: actionType (who and what it is about — support_author: the person who wrote it; support_target: the person it was aimed at; support_friend: someone worried about a friend; admin_review: something for a moderator to look at; resource_request: someone asking for a resource; resource_submission: someone suggesting a resource to add), recommendation, forAuthor, targetAuthor, instigatorAuthors, supportTrack {key,label,module} (the kind of moment), urgency (low / medium / high / urgent), confidence (0–1), evidenceMessageIndexes (0-based into your messages), evidenceSummary, uncertainty, rationale, concernCategory, resource (the structured ask for a resource_request). Urgency and confidence are FLARE's read of the signal. Each signal also carries readiness (ready / accumulating / suppressed / expired), which is NOT part of FLARE's read: it is Shepherd's own delivery decision — whether Shepherd's bot, applying its own thresholds on top of the signal, would deliver it now (expired is the model retiring a signal it had raised). Apply your own thresholds to urgency and confidence if you act on signals yourself.
`childSafetyAlerts[]`	`Alert[]`	Admin-facing child-safety alerts, separate from signals: concern, severity (watch / review / urgent_review / emergency), confidence (0–1), suspected minor / counterparty authors, evidence and the recommended admin action.
`truthRequests[]`	`TruthRequest[]`	Material faith claims the window asserts as fact — the hand-off signal to the TRUTH engine (author, claimText, speakerCertainty, materialityHint).
`escalate / escalateReason / escalated`	`boolean / string \| null / boolean`	Pass 1 asked for a deeper look, why, and whether pass 2 actually ran. escalateReason is null whenever there is no reason to give (including every unescalated window).
`passes[]`	`Pass[]`	Model, reasoning effort and token usage per pass.
`contract`	`{ promptVersion, contractVersion }`	The classifier prompt + output-contract versions that produced this result.
`supportTracks[]`	`Track[]`	The support-track catalog the classifier routes into (key, label, module, trackId).
`dedupe`	`"fresh" \| "in_flight" \| "cached" \| "undeduped"`	Which dedupe path this call took (identical submissions from YOUR account share one run): fresh ran it, in_flight joined one already running, cached got a recent result back, undeduped means the dedupe layer was degraded and this call ran on its own. Nothing is ever shared across accounts.

Try it

POST /api/public/flare/classify

Response

// the response will appear here

Call it from your code

server-to-server (service bearer)

curl -sS -X POST 'https://<your-shepherd-host>/api/public/flare/classify' \
  -H 'Authorization: Bearer $SHEPHERD_API_KEY' \
  -H 'content-type: application/json' \
  --data-binary @- <<'JSON'
{
  "surface": "discord_public",
  "messages": [
    {
      "author": "kai",
      "text": "my bad on that last round guys"
    },
    {
      "author": "ren",
      "text": "bro you threw the whole game, kys honestly lmao"
    },
    {
      "author": "kai",
      "text": "...ok. i'm just gonna log off"
    }
  ]
}
JSON

Never ship the service key to a browser.

Versions

Every response from every Shepherd engine — a result, an estimate, a refusal or an error — says which versions produced it, under the same three headers on every engine. A JSON object body carries the same three as `versions: { api, engine, engines }`.

Response headers

Field	Type	Meaning
`X-API-Version`required	`v<N>`	The API version: the request/response contract, the same for every engine ("v1"). It changes only for a breaking change to that contract.
`X-Engine-Version`required	`<engine>-engine/<line>-v<N>`	The responding engine's version ("truth-engine/research-v32", "verse-engine/card-v1"). The number goes up whenever the engine's behaviour changes: its prompts, its models, its retrieval or its rules.
`X-Engine-Versions`required	`JSON object`	The versions of the engines this response's own work called, by engine name ({"lifeline": "lifeline-engine/match-v1", "truth": "truth-engine/research-v32"} from a FORMATION study; {} when it called none — a refusal before any work, or a result served from a recent identical run).

· Read as a label, a version is the engine's name, its number and the API's: "VERSE v3 · API v1". The example results on every engine page are labelled this way, with the versions each was captured under.
· A result stored for later (a TRUTH read, a FORMATION study's reviews) keeps the version that produced it; the headers name the versions answering now.
· TRUTH's assessment endpoints return the frozen assessment contract, which carries its own provenance.truth_engine_version, so there the versions are in the headers only. The open contract endpoint runs the deterministic stub and answers as truth-engine/stub-v0.