NETWORK engine

Not just somewhere to go. Someone expecting you.

Match a person to verified hosts ready to receive them, then carry the introduction until they arrive.

Bind a new person before their first match (service callers)

Funded account or a bound service bearer30 binds / hour per seekerRef~100ms

Service callers: bind a new person's seekerRef before their first /match. Returns the seekerToken once. Free. A ref already bound answers 409 seeker_already_bound; a signed-in account answers 400 service_callers_only.

Request body

FieldTypeMeaning
seekerRefrequiredstring (1–120)The partner-scoped ref for the person (stored as service:<partner>:<ref>).

Response

FieldTypeMeaning
seekerTokenstring (hex)The ref token for this partner + seekerRef — required on /match (x-shepherd-ref-token header) and on every later introduction call under this seekerRef. Returned once; Shepherd stores only its hash.

Try it

Sign in with a funded account to send.

POST /api/public/network/seekers
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/network/seekers' \
  -H 'Authorization: Bearer $SHEPHERD_API_KEY' \
  -H 'content-type: application/json' \
  --data-binary @- <<'JSON'
{
  "seekerRef": "player-123"
}
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

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.