TRUTH engine

Is it actually true? Let's check.

Submit a claim, then poll for the result.

Submit a claim (async, real engine)

Funded account · browser session only20 submissions / hour per account202 in <1s; the assessment finishes in ~2–10 minutes (deep: longer)

Queues an assessment and returns a job id; poll /status. Resubmitting the same claim joins the same job.

Request body

FieldTypeMeaning
contentrequiredstring (1–2000)The claim, lyric, line from a sermon, or saying to test. Words that could ask 2–3 different claims are run as every claim they ask; words asking more than 3 run once, as typed.
claimsstring[] (1–3)Instead of content: the exact claims to test, each run as written.
contextstring (≤2000)Where it was said / who said it.
reasoning_profilestandard | deepdeep is slower and costs more.

Response

FieldTypeMeaning
jobId / statusuuid / queued | processingThe first claim's job handle to poll.
claims[]{claim, question, jobId, status} | {claim, question, error}Every claim run, each its own job with its own result on /status.

Try it

Sign in with a funded account to send.

POST /api/public/truth/submit
Response
// the response will appear here

Call it from your code

from the reader's browser (session cookie)
curl -sS -X POST 'https://<your-shepherd-host>/api/public/truth/submit' \
  -H "Cookie: <session cookie of the signed-in reader; browser only, no service bearer>" \
  -H 'content-type: application/json' \
  --data-binary @- <<'JSON'
{
  "content": "God won't give you more than you can handle.",
  "context": "Said to comfort a friend whose dad just died."
}
JSON

Browser only, with credentials: "same-origin". A service bearer gets 403 browser_session_required.

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

FieldTypeMeaning
X-API-Versionrequiredv<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-Versionrequired<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-VersionsrequiredJSON objectThe 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.