Quickstart

Five steps, using the real Gateway contract.

1. Obtain an API key

Keys are issued by an AIality operator today (no self-service issuance yet). Once you have one, export it:

export AIALITY_API_KEY="gwk_..."

2. Resolve Reality

Use the entity's stable public identity directly — no internal id lookup, no database access, no operator round-trip:

curl -s "https://<your-aiality-gateway-host>/v1/reality?entity=anthropic&factTopicSlug=data-retention&scope=%7B%7D" \
  -H "Authorization: Bearer $AIALITY_API_KEY"

Replace https://<your-aiality-gateway-host> with your configured Gateway host — this deployment doesn't assert a live branded API domain (see Security).

Returns a ResolvedRealityV1 pointing at the current exact FactStateVersion. Not sure what entities or topics exist? See Entities and Topics.

3. Fetch the exact state

curl -s "https://<your-aiality-gateway-host>/v1/states/{factStateVersionId}" \
  -H "Authorization: Bearer $AIALITY_API_KEY"

This route is immutable and cacheable — the same id always returns the same body.

4. Check freshness and authority

curl -s "https://<your-aiality-gateway-host>/v1/states/{factStateVersionId}/freshness" \
  -H "Authorization: Bearer $AIALITY_API_KEY"

Returns a FreshnessVerdictV1 (FRESH / STALE / UNKNOWN). Authority is included on the resolved/exact-state response.

5. (Optional) Create a Reality Lock

curl -s -X POST "https://<your-aiality-gateway-host>/v1/locks" \
  -H "Authorization: Bearer $AIALITY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"factStateVersionIds": ["..."]}'

Locks are immutable once created — the same Idempotency-Key retried never creates a second lock.