API Reference

The VerifiedState API is a REST API served over HTTPS. All requests and responses use JSON. Base URL: https://api.verifiedstate.ai

Authentication

Every request must include a Bearer token in the Authorization header. Get your key at verifiedstate.ai/keys.

curl https://api.verifiedstate.ai/health/YOUR_NAMESPACE_ID   -H "Authorization: Bearer vs_live_YOUR_KEY"

Quickstart — first verified memory in 5 minutes

curl -X POST https://api.verifiedstate.ai/ingest   -H "Authorization: Bearer vs_live_YOUR_KEY"   -H "Content-Type: application/json"   -d '{"namespace_id":"YOUR_NS","content":"Alice prefers dark mode.","source_type":"user_input"}'
# → {"artifact_id":"…","span_count":1,"r2_stored":false}

curl -X POST https://api.verifiedstate.ai/extract   -H "Authorization: Bearer vs_live_YOUR_KEY"   -H "Content-Type: application/json"   -d '{"namespace_id":"YOUR_NS","artifact_id":"ARTIFACT_ID"}'
# → {"assertions_created":2,"assertion_ids":["…","…"]}

curl -X POST https://api.verifiedstate.ai/verify   -H "Authorization: Bearer vs_live_YOUR_KEY"   -H "Content-Type: application/json"   -d '{"namespace_id":"YOUR_NS","assertion_id":"ASSERTION_ID"}'
# → {"receipt_id":"…","status":"verified","final_confidence":0.5,"conflicts_found":false}

curl -X POST https://api.verifiedstate.ai/query   -H "Authorization: Bearer vs_live_YOUR_KEY"   -H "Content-Type: application/json"   -d '{"namespace_id":"YOUR_NS","query_text":"what display theme does Alice prefer?"}'
# → {"assertions":[…],"receipts":{…},"total":1}

Error codes

POST /ingest

Accepts raw text content (conversation turn, document excerpt, tool output, etc.), stores it as an artifact with evidence spans, and optionally offloads large payloads to R2 object storage. Returns an artifact_id to use with /extract.

Request body

Response

curl example

curl -X POST https://api.verifiedstate.ai/ingest   -H "Authorization: Bearer vs_live_YOUR_KEY"   -H "Content-Type: application/json"   -d '{
    "namespace_id": "YOUR_NAMESPACE_ID",
    "content": "Alice confirmed her Postgres cluster is on version 16.",
    "source_type": "conversation",
    "source_id": "msg_abc123"
  }'

POST /extract

Calls an LLM (Llama 3.3 70B via OpenRouter) to extract subject-predicate-object assertions from the spans of an artifact. Each assertion is stored with status proposed and an embedding for semantic retrieval. Generates embeddings immediately using text-embedding-3-small.

Request body

Response

curl example

curl -X POST https://api.verifiedstate.ai/extract   -H "Authorization: Bearer vs_live_YOUR_KEY"   -H "Content-Type: application/json"   -d '{"namespace_id":"YOUR_NAMESPACE_ID","artifact_id":"ARTIFACT_ID"}'

POST /verify

Runs the 3-tier verification ladder (structural → span grounding → state consistency) on an assertion. Produces a signed Ed25519 receipt and updates the assertion status. Use /receipt/:id to retrieve the full receipt.

Formula: confidence = support_score × source_trust_score × corroboration_factor. Thresholds: ≥ 0.80 → verified, 0.65–0.79 → provisionally_verified, < 0.65 → unverified.

Request body

Response

curl example

curl -X POST https://api.verifiedstate.ai/verify   -H "Authorization: Bearer vs_live_YOUR_KEY"   -H "Content-Type: application/json"   -d '{"namespace_id":"YOUR_NAMESPACE_ID","assertion_id":"ASSERTION_ID"}'

POST /query

Hybrid retrieval: pgvector cosine similarity (1024-dim embeddings via text-embedding-3-small) plus exact slot_key match when query_text contains pipe separators. Returns assertions ranked by relevance with their active receipts attached.

Request body

Response

curl example

curl -X POST https://api.verifiedstate.ai/query   -H "Authorization: Bearer vs_live_YOUR_KEY"   -H "Content-Type: application/json"   -d '{
    "namespace_id": "YOUR_NAMESPACE_ID",
    "query_text": "what database does Alice use?",
    "limit": 5,
    "filters": {"valid_only": true, "status": "verified"}
  }'

GET /receipt/:id

Returns the full verification receipt for a given receipt ID. The receipt includes the Ed25519 signature, evidence refs, method stack, confidence scores, and verifier identity.

Path parameter

curl example

curl https://api.verifiedstate.ai/receipt/RECEIPT_ID   -H "Authorization: Bearer vs_live_YOUR_KEY"

GET /chain/:writer

Returns the current Merkle chain head for a writer principal. Each assertion stores assertion_hash and prev_hash, forming a tamper-evident chain. Replay the chain client-side to verify integrity.

Path parameter

curl example

curl "https://api.verifiedstate.ai/chain/system%3Aextract"   -H "Authorization: Bearer vs_live_YOUR_KEY"

POST /compress

Encodes an artifact into the IR1 (Intermediate Representation) format optimised for LLM consumption, and writes the literal sidecar to R2 for lossless recovery. Typical compression ratio: 0.35–0.55× (IR is 2–3× smaller than original in token count).

Request body

Response

curl example

curl -X POST https://api.verifiedstate.ai/compress   -H "Authorization: Bearer vs_live_YOUR_KEY"   -H "Content-Type: application/json"   -d '{"namespace_id":"YOUR_NAMESPACE_ID","artifact_id":"ARTIFACT_ID"}'

POST /decompress

Fetches the literal sidecar from R2, reconstructs the original content, and verifies its SHA-256 hash. Returns the exact original bytes — guaranteed lossless.

Request body

curl example

curl -X POST https://api.verifiedstate.ai/decompress   -H "Authorization: Bearer vs_live_YOUR_KEY"   -H "Content-Type: application/json"   -d '{"namespace_id":"YOUR_NAMESPACE_ID","encoded_artifact_id":"ENCODED_ID"}'

POST /challenge

Creates a counterevidence record against an existing assertion, opens a conflict set, and updates the assertion status to disputed. Disputed assertions surface in /health counts.

Request body

curl example

curl -X POST https://api.verifiedstate.ai/challenge   -H "Authorization: Bearer vs_live_YOUR_KEY"   -H "Content-Type: application/json"   -d '{
    "namespace_id": "YOUR_NAMESPACE_ID",
    "assertion_id": "ASSERTION_ID",
    "reason": "Source was unreliable — conflicting data from primary DB",
    "counterevidence": "SELECT * FROM users WHERE id = 42 shows preference = light_mode"
  }'

POST /retract

Assertions are append-only — they are never deleted. Retraction creates a new assertion that supersedes the original, setting its status to retracted. The original is preserved in the audit trail with status = retracted.

Request body

curl example

curl -X POST https://api.verifiedstate.ai/retract   -H "Authorization: Bearer vs_live_YOUR_KEY"   -H "Content-Type: application/json"   -d '{
    "namespace_id": "YOUR_NAMESPACE_ID",
    "assertion_id": "ASSERTION_ID",
    "reason": "User corrected their preference directly"
  }'

GET /export

Exports all assertions, receipts, evidence spans, artifacts, policies, and encoded artifacts for a namespace as a self-contained JSON bundle. The bundle includes a bundle_sha256 computed over all contents — verify this before importing to detect tampering.

Query parameters

curl example

curl "https://api.verifiedstate.ai/export?namespace_id=YOUR_NAMESPACE_ID"   -H "Authorization: Bearer vs_live_YOUR_KEY"   -o bundle.json

GET /health/:namespace_id

Returns a health snapshot for a namespace: assertion counts, verification ratio, stale/expired counts, open conflict sets, and disputed assertions. Use this as a dashboard signal for memory quality.

Path parameter

Response

curl example

curl https://api.verifiedstate.ai/health/YOUR_NAMESPACE_ID   -H "Authorization: Bearer vs_live_YOUR_KEY"