API Reference

VerifiedState is for enterprise AI agents. Every assertion your agent stores comes with a cryptographic verification receipt — signed evidence of what the agent believed, what supported that belief, and when it was verified. Build autopilots that are auditable, defensible, and compliant by default.

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 — from zero to verified memory in 60 seconds

Three ways to get started. All create an API key, namespace, and MCP config in one step.

Option A — CLI (recommended)

npx @verifiedstate/sync init

The CLI asks for your email and project name, then auto-provisions everything and injects MCP config into Cursor, VS Code, or Windsurf automatically.

Option B — API directly

curl -X POST https://api.verifiedstate.ai/provision   -H "Content-Type: application/json"   -d '{"email":"you@company.com","project_name":"my-project","source":"cursor"}'

Returns your API key, namespace ID, MCP config, env vars, and quickstart commands in one response.

Option C — Web

Visit verifiedstate.ai/keys and enter your email. You'll get your API key, namespace, and MCP config to copy.

Then use the API

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}

MCP Server — recommended for AI agents

If you're using Claude Code, Cursor, Windsurf, Goose, or any MCP-compatible client, this is the fastest path. One config block gives your agent access to all 23 tools — memory, verification, metering, sessions, alerts, and teams.

Connect in one step

{
  "mcpServers": {
    "verifiedstate": {
      "url": "https://mcp.verifiedstate.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Or let the CLI do it automatically:

npx @verifiedstate/sync init

This provisions your API key, creates your namespace, and injects the MCP config into Claude Code and Cursor automatically.

Available tools (23)

See the Integrations page for per-tool setup guides.

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"

For AI Agents

Any AI agent can read our API spec to instantly know how to query and store verified memory. No integration needed.

GET https://api.verifiedstate.ai/openapi.json

GET https://api.verifiedstate.ai/.well-known/openapi.json

Point any agent, tool, or LLM at the spec URL. It describes every endpoint, required parameters, response schemas, and authentication. Compatible with OpenAPI-aware agents, function-calling models, and API clients like Swagger UI.

MCP Server (recommended)

For agents that support MCP, connect directly to our MCP server for tool-native access:

"url": "https://mcp.verifiedstate.ai/mcp"

This gives agents 23 tools — memory, verification, metering, sessions, working state, alerts, and teams — with no code required.