Procedure 01 / Quickstart

First calls.

Four operations in order: admit a node, admit a relation, read a traversal, and request a derivation. The commands below use the temporary hosted address and a provisioned token.

1. 01

   Set the host

   The hosted address is temporary. Replace it when a stable domain is issued.

   export GNOMON_API_URL="https://api.gnomon.one"

2. 02

   Hold the token

   Keep the token in an environment variable or secret manager. Do not commit it, put it in a URL, or paste it into logs.

   export GNOMON_TOKEN="gnm1.<claims>.<signature>"

3. 03

   Check liveness

   /health is the only open route. It does not prove the engine is loaded.

   curl -sS "$GNOMON_API_URL/v1/health"

   {"status":"ok"}

4. 04

   Observe one text

   The text is encoded as UTF-8, admitted as a node, and reduced to a 16-character invariant. The same text and configuration produce the same hash.

   curl -sS "$GNOMON_API_URL/v1/observe" -H "Authorization: Bearer $GNOMON_TOKEN" -H "Content-Type: application/json" --data '{"text":"the sky is blue"}'

   {"node":"<16-hex-invariant>"}

5. 05

   Admit a relation

   A sequence writes directed transitions between consecutive nodes. A single observation has no relation to traverse.

   curl -sS "$GNOMON_API_URL/v1/observe-seq" -H "Authorization: Bearer $GNOMON_TOKEN" -H "Content-Type: application/json" --data '{"epithets":["sky","blue"]}'

   {"nodes":["<hash>","<hash>"]}

6. 06

   Query

   /query accepts text or an existing hash. If the text is not yet a node, it is admitted first. The response is the text projection.

   curl -sS "$GNOMON_API_URL/v1/query" -H "Authorization: Bearer $GNOMON_TOKEN" -H "Content-Type: application/json" --data '{"query":"sky","payload_kind":"text"}'

   {"emitted_text":"..."}

7. 07

   Emit from an anchor

   /emit does not admit anything. If the anchor is absent, the result is UNKNOWN_SEAM.

   curl -sS "$GNOMON_API_URL/v1/emit" -H "Authorization: Bearer $GNOMON_TOKEN" -H "Content-Type: application/json" --data '{"node":"<node-hash>","mode":"nlc_v2","max_steps":15}'

   {"verdict":"...","emitted_text":"..."}

8. 08

   Derive

   /derive reconstructs a justification between two nodes. The HTTP route reports promotion only; the sealed proof is exposed through the Python engine, not this route.

   curl -sS "$GNOMON_API_URL/v1/derive" -H "Authorization: Bearer $GNOMON_TOKEN" -H "Content-Type: application/json" --data '{"query":"sky","target":"blue","payload_kind":"proof","learn":false}'

   {"promoted":false}

What the outputs mean

A node hash is identity, not a label. The readable text is an epithet attached to that identity. Two different texts can share an invariant if they share the same block structure; the hash is the address, not a semantic summary.

UNKNOWN_SEAM is a real answer: the requested relation is not present. It is not a prompt to invent one and it is not an HTTP 404.

Do not expect a reset

If a call fails

Failures are JSON objects with a stable error string. Authentication failures are 401 or 403; malformed requests and engine exceptions are 400. See Errors & limits.