LIFELINE engine

The right help, for this moment.

Sign in to try it

Runs cost credits. Ask us for credits.

Example results

What LIFELINE returns

Real results, not mock-ups.

Sent

“something for when I'm scared at night and can't sleep”

How LIFELINE read it

Something encouraging to help when I'm scared at night and can't sleep (comfort for anxiety and nighttime fear).

looked forSong · support (light)track: fear doubtanxietysleepfeartone: comforting

Interpreted by the classifierRanked by the model

Why these: This person is scared at night and needs something calming to help them sleep. Ref 99 (Weightless) is an evidence-based ambient instrumental designed to lower physiological arousal and encourage sleep — the best immediate fit. Next are gentle, faith-centered calming options: 36 (Still Waters — Psalm 23) anchors anxiety in Scripture and peaceful imagery, 131 (Just Be Held) invites surrender and rest in God’s presence, and 22 (The Lord Is With Me) offers steady reassurance of God’s nearness in trials. Ref 54 (Right On Time) is a short, conversational faith reassurance about laying down worries — a simple, comforting closer if they want something brief and devotional.

#1Song · support (light)fear doubt

fit: track:fear_doubt · signal:calming · topic:sleep · topic:fear · tone:comforting · score 40

YouTube · 8:09

#2Song · worshipdespairfear doubtfaith foundation

fit: track:fear_doubt · signal:calming · topic:anxiety · topic:fear · tone:comforting · score 40

YouTube · 4:10

#3Song · Christiandespairfear doubtfaith foundation

fit: track:fear_doubt · topic:anxiety · topic:fear · tone:comforting · score 34

YouTube · 3:43

Raw JSON

{
  "need": "something for when I'm scared at night and can't sleep",
  "routing": {
    "kind": "resource",
    "fromClassifier": true,
    "signals": [],
    "childSafetyAlerts": 0,
    "submission": null,
    "message": null
  },
  "interpretation": {
    "source": "classifier",
    "model": "gpt-5-mini",
    "query": {
      "category": "support_song",
      "tracks": [
        "fear_doubt"
      ],
      "topics": [
        "anxiety",
        "sleep",
        "fear"
      ],
      "tone": "comforting",
      "title": null,
      "creator": null
    },
    "proposed": {
      "category": "support_song",
      "tracks": [
        "fear_doubt"
      ],
      "topics": [
        "anxiety",
        "sleep",
        "fear"
      ],
      "tone": "comforting",
      "requestedTitleName": null,
      "requestedCreatorName": null,
      "needSummary": "Something encouraging to help when I'm scared at night and can't sleep (comfort for anxiety and nighttime fear)."
    },
    "engine": {
      "category": "support_song",
      "tone": "comforting",
      "tracks": [
        "fear_doubt"
      ],
      "topics": [
        "anxiety",
        "sleep",
        "fear"
      ],
      "signals": [
        "calming"
      ],
      "requestedResourceKeys": [],
      "requestedCreatorKeys": [],
      "requestedTitleKeys": []
    }
  },
  "resources": [
    {
      "resourceKey": "submitted:youtube:www-youtube-com-watch-f2eb3a16aa",
      "canonicalKey": "marconi union|weightless",
      "category": "support_song",
      "provider": "YouTube",
      "title": "Weightless",
      "creator": "Marconi Union",
      "blurb": "Play this when your head won’t stop racing and you just need something calm to float on.",
      "sourceUrl": "https://www.youtube.com/watch?v=UfcAVejslrU",
      "embedUrl": "https://www.youtube.com/embed/UfcAVejslrU?feature=oembed",
      "thumbnailUrl": "https://i.ytimg.com/vi/UfcAVejslrU/hqdefault.jpg",
      "durationSeconds": 489,
      "topics": [
        "relaxation",
        "calm",
        "sleep"
      ],
      "journeyTracks": [
        "fear_doubt"
      ],
      "deliveryVisibility": "public",
      "spiritualDepth": 0,
      "placementSafety": {
        "spiritualDepth": 0,
        "placementFitStored": true,
        "legacySafety": {
          "introOutreachSafe": false,
          "initialOutreachSafe": false,
          "supportEnrichmentSafe": false,
          "practicalEnrichmentSafe": false
        }
      },
      "rank": 1,
      "score": 40,
      "matchReasons": [
        "track:fear_doubt",
        "signal:calming",
        "topic:sleep",
        "topic:fear",
        "tone:comforting"
      ]
    },
    {
      "resourceKey": "submitted:youtube:www-youtube-com-watch-200023f0f7",
      "canonicalKey": "leanna crawford|still waters psalm 23",
      "category": "worship_song",
      "provider": "YouTube",
      "title": "Still Waters (Psalm 23)",
      "creator": "Leanna Crawford",
      "blurb": "Play \"Still Waters\" when you need something gentle to help you breathe and feel steady again.",
      "sourceUrl": "https://www.youtube.com/watch?v=WW0VJxPqeRc",
      "embedUrl": "https://www.youtube.com/embed/WW0VJxPqeRc?feature=oembed",
      "thumbnailUrl": "https://i.ytimg.com/vi/WW0VJxPqeRc/hqdefault.jpg",
      "durationSeconds": 250,
      "topics": [
        "psalm_23",
        "trust",
        "anxiety"
      ],
      "journeyTracks": [
        "despair",
        "fear_doubt",
        "faith_foundation",
        "gospel_response"
      ],
      "deliveryVisibility": "public",
      "spiritualDepth": 0.9,
      "placementSafety": {
        "spiritualDepth": 0.9,
        "placementFitStored": true,
        "legacySafety": {
          "introOutreachSafe": false,
          "initialOutreachSafe": false,
          "supportEnrichmentSafe": false,
          "practicalEnrichmentSafe": false
        }
      },
      "rank": 2,
      "score": 40,
      "matchReasons": [
        "track:fear_doubt",
        "signal:calming",
        "topic:anxiety",
        "topic:fear",
        "tone:comforting"
      ]
    },
    {
      "resourceKey": "submitted:youtube:www-youtube-com-watch-4e500a6e59",
      "canonicalKey": "casting crowns|just be held",
      "category": "christian_song",
      "provider": "YouTube",
      "title": "Just Be Held",
      "creator": "Casting Crowns",
      "blurb": "Play this when you're exhausted and need a calm reminder it's okay to stop fighting and just be held.",
      "sourceUrl": "https://www.youtube.com/watch?v=tIZitK6_IMQ",
      "embedUrl": "https://www.youtube.com/embed/tIZitK6_IMQ?feature=oembed",
      "thumbnailUrl": "https://i.ytimg.com/vi/tIZitK6_IMQ/hqdefault.jpg",
      "durationSeconds": 223,
      "topics": [
        "surrender",
        "trust",
        "comfort",
        "hope"
      ],
      "journeyTracks": [
        "despair",
        "fear_doubt",
        "faith_foundation",
        "gospel_response"
      ],
      "deliveryVisibility": "public",
      "spiritualDepth": 0.9,
      "placementSafety": {
        "spiritualDepth": 0.9,
        "placementFitStored": true,
        "legacySafety": {
          "introOutreachSafe": false,
          "initialOutreachSafe": false,
          "supportEnrichmentSafe": false,
          "practicalEnrichmentSafe": false
        }
      },
      "rank": 3,
      "score": 34,
      "matchReasons": [
        "track:fear_doubt",
        "topic:anxiety",
        "topic:fear",
        "tone:comforting"
      ]
    }
  ],
  "rankedBy": "llm_rerank",
  "whyThese": "This person is scared at night and needs something calming to help them sleep. Ref 99 (Weightless) is an evidence-based ambient instrumental designed to lower physiological arousal and encourage sleep — the best immediate fit. Next are gentle, faith-centered calming options: 36 (Still Waters — Psalm 23) anchors anxiety in Scripture and peaceful imagery, 131 (Just Be Held) invites surrender and rest in God’s presence, and 22 (The Lord Is With Me) offers steady reassurance of God’s nearness in trials. Ref 54 (Right On Time) is a short, conversational faith reassurance about laying down worries — a simple, comforting closer if they want something brief and devotional.",
  "retryKind": "exact",
  "relaxedMatch": false,
  "tryDifferent": {
    "excludeResourceKeys": [
      "submitted:youtube:www-youtube-com-watch-f2eb3a16aa",
      "submitted:youtube:www-youtube-com-watch-200023f0f7",
      "submitted:youtube:www-youtube-com-watch-4e500a6e59"
    ]
  },
  "queue": [
    "submitted:youtube:www-youtube-com-watch-09db574b72",
    "submitted:youtube:www-youtube-com-watch-8936c4cca5"
  ],
  "usage": null,
  "spend": [
    {
      "step": "flare_pass_1",
      "model": "gpt-5-mini",
      "inputTokens": 20528,
      "outputTokens": 2023
    },
    {
      "step": "catalog_rerank",
      "model": "gpt-5-mini",
      "inputTokens": 8000,
      "outputTokens": 2000
    }
  ],
  "versions": {
    "api": "v1",
    "engine": "lifeline-engine/match-v1",
    "engines": {
      "flare": "flare-engine/classify-v1"
    }
  }
}

Returned by LIFELINE v1 · API v1.

Matches a need to reviewed resources: songs, verses, prayers, devotionals, teaching and stories.

Match a need to resources

Funded account or a bound service bearer120 calls / hour per accountusually 10–40s for a free-text need; ~1s for structured fields only; hard budget 270s (a slow upstream returns a retryable 504)

A need in plain words or structured fields → ranked resources.

· A need that reads as a crisis, abuse or something for an admin comes back in `routing` with no resources; an ask to add a resource comes back as resource_submission.
· A request with free-text language returns a retryable 503 when it can't be read right now; enum-only fields (category / tracks / tone) still work.
· deliveryVisibility private: don't tie it to the person in a public room.
· A named title that isn't in the catalog returns an empty list.

Request body

Field	Type	Meaning
`need`	`string (3–500)`	The need in the person's words. Required unless you give structured fields.
`category`	`string \| null`	worship_song · christian_song · support_song · scripture_verse · guided_prayer · journal_prompt · bible_study_plan · teaching_video · testimony_video. null = any medium. Overrides the interpreter.
`tracks`	`string[]`	Struggle roots: anger · despair · fear_doubt · harmful_habit · sexual_habit · friend_support · faith_foundation.
`topics`	`string[]`	Short topic words (anxiety, grief, birthday…).
`tone`	`energizing \| comforting \| reverent \| null`	Song tone. Overrides the interpreter.
`title / creator`	`string`	A named ask ("play X by Y"). Exact-identity lookups never fall back to a generic pick.
`surface`	`web \| discord_public \| discord_dm \| partner`	Where it will be shown. On Discord, a row blocked for embedding comes back as a plain link (direct ask) or is excluded (inline). Default web.
`context`	`direct_request \| inline_placement`	direct_request: a person asked — the LLM reranker judges fit. inline_placement: auto-embedding inside a support flow — deterministic and narrow (never a worship song in the practical lane). Default direct_request.
`limit`	`1–8`	How many picks to return. Default 3.
`excludeResourceKeys / tryDifferent`	`string[] / boolean`	"Show me another": pass the previous tryDifferent.excludeResourceKeys back and set tryDifferent true.

Response

Field	Type	Meaning
`routing`	`{ kind, fromClassifier, signals[], childSafetyAlerts, submission, message }`	How the safety classifier routed a free-text need: resource (served); support / admin_review / child_safety (NOT served — the message says what Shepherd would do instead; resources is empty); resource_submission (an ask to ADD a resource — not served either; submission carries the named title / creator / url for the submission workflow). not_checked for an enum-only request (no caller language).
`resources[]`	`Resource[]`	Ranked picks: resourceKey, category, title, creator, blurb (user-facing), sourceUrl, embedUrl, thumbnailUrl, durationSeconds, topics, journeyTracks, deliveryVisibility (public / private — private means the bot DMs it rather than posting in a channel), spiritualDepth (reviewed 0 secular · ~0.5 approachable christian · ~0.9 worship, null when unreviewed), placementSafety (the served row's placement-safety facts verbatim — spiritualDepth, placementFitStored, legacySafety{introOutreachSafe, initialOutreachSafe, supportEnrichmentSafe, practicalEnrichmentSafe} — or null when the catalog service does not report them; a lane-aware consumer applies the bot's export predicate itself), rank, score, matchReasons, verse (verses only: the card Shepherd renders — reference, line (our SHEP translation, else the public-domain WEB text), fullText (WEB), attribution, sourceLabel, art{url, alt} (clean VerseArt, or null while pending), readUrl (our /verse reader); null when the row has no reference).
`interpretation`	`object`	source (classifier / llm / caller), model, query (the fields the serve ran with), proposed (what the interpreter suggested before your overrides), engine (what the engine itself understood).
`rankedBy / whyThese`	`"llm_rerank" \| "deterministic" \| null / string \| null`	llm_rerank with the reranker's one-paragraph reasoning, or deterministic (identity lookups, inline placement, or a reranker outage). BOTH are null on a routing-only response (a need the safety classifier routed away is never ranked, because it is never served).
`retryKind / relaxedMatch`	`exact \| same_artist \| wandered_fresh \| recycled / boolean`	How a "show me another" was satisfied and whether the requested identity was relaxed.
`tryDifferent.excludeResourceKeys / queue`	`string[] / string[]`	What to exclude on the next ask, and the reranker's ranked tail below the shown picks.
`dedupe`	`"fresh" \| "in_flight" \| "cached" \| "undeduped"`	Which dedupe path this call took (identical requests from YOUR account share one run, so a double-tap or retry is not charged twice): 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/lifeline/match

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/lifeline/match' \
  -H 'Authorization: Bearer $SHEPHERD_API_KEY' \
  -H 'content-type: application/json' \
  --data-binary @- <<'JSON'
{
  "need": "something for when I'm scared at night and can't sleep",
  "surface": "web"
}
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.