{"protocol":"VerifiedOS Agent-First Specification","version":"2.0.0","manifest_version":"3.1.0","standard":"AEO-1 (Agent Engine Optimization)","generated_at":"2026-09-02T13:59:11.059Z","integrity":"sha256-unkeyed","host":"https://verifiedos.ai","api_base_url":"https://verifiedos.ai/api/v1","quickstart":{"step_1_start_signup":"POST /api/v1/auth/signup — passwordless (owner name + email or phone + workspace). Response returns signup_session_id; the OTP is delivered to the contact. In local development (SIGNUP_DEV_OTP_ENABLED=1) the response also returns development_otp_code; in production it never does.","step_2_verify_otp_get_credentials":"POST /api/v1/auth/signup/verify with { signup_session_id, otp_code }. THIS returns your API key (vfy_…) and access_token. Already have a key? Skip to step 3 — protected routes accept Bearer <vfy_ key> directly, no login required.","step_3_verify_a_claim":"POST /api/v1/verify with claim_text + evidence_text + idempotency_key. Response carries receipt_id + public_result; the X-Request-ID response header is your request_id for step 4.","step_4_verify_decisions_and_actions":"DECISIONS: GET /api/v1/verify/{request_id} to fetch the stored adjudication outcome, or GET /api/v1/receipts/{receipt_id} to audit the proof record. ACTIONS: POST /api/v1/mcp-verifications with an MCP tool-call manifest in evidence_text to get a deterministic security verdict.","minimal_example":"# ── 1. sign up (passwordless) ─────────────────────────────\ncurl -X POST https://verifiedos.ai/api/v1/auth/signup \\\\\n  -H \"Content-Type: application/json\" \\\\\n  -d '{\"owner_first_name\":\"Ada\",\"owner_last_name\":\"Agent\",\"owner_email\":\"ada@example.com\",\"workspace_name\":\"ada-lab\"}'\n# → signup_session_id: sgn_…  (dev: development_otp_code returned inline)\n\n# ── 2. verify OTP → receive API key + token ───────────────\ncurl -X POST https://verifiedos.ai/api/v1/auth/signup/verify \\\\\n  -H \"Content-Type: application/json\" \\\\\n  -d '{\"signup_session_id\":\"sgn_…\",\"otp_code\":\"123456\"}'\n# → api_key: vfy_… , access_token: oauth_…\n\n# ── 3. verify a claim (idempotent; Bearer = the vfy_ key) ──\ncurl -X POST https://verifiedos.ai/api/v1/verify \\\\\n  -H \"Authorization: Bearer vfy_…\" \\\\\n  -H \"Content-Type: application/json\" \\\\\n  -d '{\"claim_text\":\"Water boils at 100C at sea level\",\"evidence_text\":\"NIST SP 220: ...\",\"idempotency_key\":\"'\"$(uuidgen)\"'\"}'\n# → receipt_id + public_result + attempt_terminal_outcome; header X-Request-ID → req_…\n\n# ── 4a. fetch the decision (adjudication outcome) ──────────\ncurl https://verifiedos.ai/api/v1/verify/req_… -H \"Authorization: Bearer vfy_…\"\n# 4b. verify an action (MCP tool-call manifest)\ncurl -X POST https://verifiedos.ai/api/v1/mcp-verifications \\\\\n  -H \"Authorization: Bearer vfy_…\" -H \"Content-Type: application/json\" \\\\\n  -d '{\"claim_text\":\"tool call is safe\",\"evidence_text\":\"{\\\"name\\\":\\\"filesystem\\\",\\\"version\\\":\\\"1.0.0\\\",\\\"tools\\\":[]}\",\"idempotency_key\":\"'\"$(uuidgen)\"'\"}'"},"compliance":{"data_classes_processed":["claim text you submit","evidence text you submit","MCP manifests you submit for action verification","derived verification verdicts and confidence scores","identity: account email, workspace name","billing: wallet balance and transaction records"],"immutable_ledger":"Every verification (claims and MCP action verifications) produces a receipt bound into a hash chain. Receipts are tamper-evident and available for audit.","audit_log_availability":"Every API action that mutates state (verifications, key provisioning, profile changes) writes an immutable audit event.","retention":"Receipts and audit events are retained for audit purposes; sandbox data purged weekly.","deletion":"Contact the operator for account deletion; immutable ledger entries are retained as required for non-repudiation.","residency":"US-East (primary data region).","non_repudiation":"Hash-chained receipts mean neither party can deny a verified claim, decision, or action after the fact."},"sitemap":[{"path":"/","description":"Protocol landing page & verification overview","agent_readable":true},{"path":"/auth","description":"Authentication portal (human / agent API key login)","agent_readable":true},{"path":"/verified","description":"Verification playground & proof-of-claim execution","agent_readable":true},{"path":"/ledger","description":"Immutable verification receipts & hash chain","agent_readable":true},{"path":"/pricing","description":"Credit tiers & rate-limit policy","agent_readable":true},{"path":"/skills","description":"Certified agent skills registry","agent_readable":true},{"path":"/api-keys","description":"API key provisioning & agent token management","agent_readable":true},{"path":"/immutable-ledger","description":"Chain-of-custody audit explorer","agent_readable":true},{"path":"/terms","description":"Terms of service","agent_readable":true},{"path":"/privacy","description":"Privacy policy & non-repudiation guarantees","agent_readable":true}],"api_endpoints":[{"path":"/api/v1/health","method":"GET","description":"Service health and readiness probe for agent circuit breakers.","auth":"none","request_body":null,"response":{"status":"ok","timestamp":"ISO 8601 UTC string","redis":"connected | unconfigured | unreachable | error","llamaindex":"connected | error","neo4j":"connected | unreachable | unavailable","kernel":"healthy | unhealthy | error","hermes":"string (agent connectivity status)"}},{"path":"/api/v1/auth/signup","method":"POST","description":"Start passwordless signup. Creates an OTP challenge; does NOT yet create tenant resources or keys. The OTP is delivered to the contact; in local development (SIGNUP_DEV_OTP_ENABLED=1) it is returned inline as development_otp_code and in production never is.","auth":"none","request_body":{"owner_first_name":"string (required)","owner_last_name":"string (required)","owner_email":"string (optional, max 254)","owner_phone":"string (optional, max 40)","workspace_name":"string (optional, max 160)","initial_plan":"free | plus | pro (default free)"},"response":{"signup_session_id":"string (sgn_…)","verification_channel":"email | phone","masked_destination":"string (masked contact)","expires_in":"number (seconds, 600)","delivery_status":"delivered | no_provider_configured | local_testing_code_returned (dev only)","development_otp_code":"string (local development only — SIGNUP_DEV_OTP_ENABLED=1; never in production)","message":"string"}},{"path":"/api/v1/auth/signup/verify","method":"POST","description":"Verify the signup OTP to create tenant resources and bootstrap credentials. THIS is the step that returns your API key.","auth":"none","request_body":{"signup_session_id":"string (required, from signup)","otp_code":"string (required, exactly 6 digits)"},"response":{"tenant_id":"string UUID","tenant_member_id":"string UUID","api_key_id":"string","api_key":"string (vfy_… — treat as a secret)","access_token":"string (oauth_… bearer)","token_type":"bearer","expires_in":"number (seconds)","message":"string"}},{"path":"/api/v1/auth/login","method":"POST","description":"Optional: exchange an existing vfy_ API key for a short-lived bearer access token. Not required for verification — protected routes accept the raw vfy_ key as Bearer directly.","auth":"none","request_body":{"api_key":"string (required, format vfy_…)"},"response":{"tenant_id":"string UUID","name":"string (workspace name)","status":"string (tenant status)","plan_code":"string (free | plus | pro)","access_token":"string (bearer)","token_type":"bearer","expires_in":"number (seconds)"}},{"path":"/api/v1/verify","method":"POST","description":"Submit a claim and evidence for deterministic proof-of-claim verification. This is the core operation (claims surface). The response's X-Request-ID header is the request_id for GET /api/v1/verify/{request_id}.","auth":"bearer","headers":{"Authorization":"Bearer <vfy_ api key or access_token>","Content-Type":"application/json"},"request_body":{"claim_text":"string (required, max 8000 chars)","evidence_text":"string (required, max 16000 chars)","idempotency_key":"string (required, 1-128 chars — safe retries)","metadata":"object (optional, serialized ≤ 4000 chars)"},"response":{"receipt_id":"string (vfy_…, immutable ledger key)","public_result":"VERIFIED | UNVERIFIED | CHALLENGED | INCONCLUSIVE","attempt_terminal_outcome":"string (terminal attempt state)","social_summary":"string (human-readable verdict rationale)","receipt_url":"string (path to the receipt artifact)","free_tries_remaining":"number","credit_balance_usd":"number (4dp)","total_cost_usd":"number (4dp)","tenant_tier":"string | null","billing_source":"string | null","routing_mode":"string | null","operational_route":"string | null"},"rate_limits":{"policy":"Per-key. 429 responses carry Retry-After and X-RateLimit-* headers."},"webhooks":{"events":["verification.completed","verification.failed"],"retry_policy":"exponential backoff, max 3"}},{"path":"/api/v1/verify/{request_id}","method":"GET","description":"Fetch a verification result by request id (async / polling pattern). This is the DECISIONS surface: the stored adjudication outcome for a submitted claim. Use the X-Request-ID header from the POST /api/v1/verify response.","auth":"bearer","response":{"status":"string (request state)","public_result":"string (the recorded decision)","receipt":"object (receipt artifact)"}},{"path":"/api/v1/mcp-verifications","method":"POST","description":"Verify an agent ACTION: submit an MCP server/tool-call manifest and receive a deterministic security verdict (analysis → evidence → judge → adjudication → proof-of-claim). evidence_text must contain the MCP manifest as JSON (plain or fenced).","auth":"bearer","headers":{"Authorization":"Bearer <vfy_ api key or access_token>","Content-Type":"application/json"},"request_body":{"claim_text":"string (required, max 4096 chars)","evidence_text":"string (required, max 65536 chars — the MCP manifest JSON)","idempotency_key":"string (required, 1-128 chars)","metadata":"object (optional)"},"response":{"receipt_id":"string (proof-of-claim receipt)","public_result":"VERIFIED | CHALLENGED | UNVERIFIED","attempt_terminal_outcome":"string (terminal attempt state)","social_summary":"string (adjudication rationale)","receipt_url":"string (path to the proof-of-claim)","runtime_response_version":"string","execution_envelope_version":"string","receipt_core_version":"string"},"rate_limits":{"policy":"Per-key. 429 responses carry Retry-After and X-RateLimit-* headers."}},{"path":"/api/v1/mcp-receipts/{receipt_id}","method":"GET","description":"Fetch the persisted proof-of-claim for an ACTION verification (the receipt_url returned by POST /api/v1/mcp-verifications). Tenant-scoped, auditable.","auth":"bearer","response":{"receipt_id":"string","request_id":"string","tenant_id":"string UUID","public_result":"string (VERIFIED | CHALLENGED | UNVERIFIED)","ledger_hash":"string SHA256","evidence_hash":"string SHA256","created_at":"ISO 8601 UTC string","canonical":"object (full MCP_PROOF_OF_CLAIM payload)"}},{"path":"/api/v1/receipts","method":"GET","description":"Query your immutable, hash-chained proof receipts (claims, decisions, and action verifications).","auth":"bearer","params":{"limit":"number (default 50, max 200)","cursor":"string (opaque token)","result_filter":"VERIFIED | UNVERIFIED | CHALLENGED | INCONCLUSIVE","from_date":"ISO 8601 UTC (optional)","to_date":"ISO 8601 UTC (optional)"},"response":{"receipts":"array[Receipt]","has_more":"boolean","next_cursor":"string | null"},"pagination":{"style":"cursor","sort_order":"desc_by_timestamp"}}],"authentication":{"scheme":"Bearer token","token_format":"vfy_{env}_{random_base64url} (env = test | live)","environments":["test","live"],"signup_paths":{"human":"POST /api/v1/auth/signup — passwordless (owner name + email/phone + workspace). No password field.","agent_key_direct":"POST /api/v1/auth/login with an existing vfy_ key (optional — protected routes accept Bearer <vfy_ key> directly)."},"scopes_note":"Keys are scoped; 429 responses carry Retry-After and X-RateLimit-* headers — treat them as authoritative rather than pre-computing limits."},"rate_limit_policy":"Rate limits are enforced per key and returned on every 429 via Retry-After (seconds) and X-RateLimit-Limit/Remaining/Reset headers. Back off on 429; do not pre-compute numeric budgets.","observability":{"required_headers":["X-Request-ID"],"optional_headers":["X-Agent-ID","X-Org-ID","X-Trace-ID"],"description":"Include X-Request-ID (UUID v4) for tracing; X-Agent-ID / X-Org-ID enable multi-tenancy observability. The verify endpoint echoes the request id back on its X-Request-ID response header — use it for GET /api/v1/verify/{request_id}."},"companion_endpoints":{"GET /api/agent-manifest":"This manifest (JSON, public tier)","GET /api/agent-manifest?full=true":"Full manifest — schemas, error tables, sandbox (requires Bearer vfy_ key)","GET /api/agent-skill":"Downloadable agent skill markdown (machine-readable protocol summary)"},"manifest_sha256":"4c22b37b7112f0a2557543c2a565739c58927b9014baff07c21dc4404df5d1c9"}