# VerifiedOS Agent-First Protocol Specification

> Verified gives autonomous AI agents and operators a deterministic proof-attempt workflow to issue immutable chain-of-custody receipts for challenged claims.

## Core Capabilities & Agent Interfaces
- **Agent Manifest Endpoint**: [GET /api/agent-manifest](https://verifiedos.ai/api/agent-manifest)
- **OpenAPI Schema**: [GET /openapi.json](https://verifiedos.ai/openapi.json)
- **Agent-First Interface**: [GET /agent-first](https://verifiedos.ai/agent-first)

## Sitemap Index
- [/]: Protocol landing page & verification overview
- [/auth]: Authentication portal (Human & Agent API Key Sign in)
- [/verified]: Verification playground & proof-of-claim execution gate
- [/ledger]: Immutable verification receipts & ledger hash chain
- [/docs]: Protocol documentation & API specifications
- [/pricing]: Credit topup tiers & rate-limit quotas
- [/topup]: USD wallet balance & credit recharge
- [/skills]: Certified agent skills registry & OpenClaw tooling
- [/api-keys]: API Key provisioning & agent actor token management
- [/openclaw]: Autonomous desktop & web agent integration engine
- [/immutable-ledger]: Chain-of-custody audit explorer & proof verification
- [/terms]: Terms of Service & zero-tolerance baseline criteria
- [/privacy]: Data privacy policy & non-repudiation guarantees
- [/company]: Organization info & enterprise demo scheduling

## Primary API Endpoints (generated from the manifest source of truth)
- **GET /api/v1/health**: Service health and readiness probe for agent circuit breakers.
- **POST /api/v1/auth/signup**: 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.
- **POST /api/v1/auth/signup/verify**: Verify the signup OTP to create tenant resources and bootstrap credentials. THIS is the step that returns your API key.
- **POST /api/v1/auth/login**: 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.
- **POST /api/v1/verify**: 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}.
- **GET /api/v1/verify/{request_id}**: 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.
- **POST /api/v1/mcp-verifications**: 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).
- **GET /api/v1/mcp-receipts/{receipt_id}**: Fetch the persisted proof-of-claim for an ACTION verification (the receipt_url returned by POST /api/v1/mcp-verifications). Tenant-scoped, auditable.
- **GET /api/v1/receipts**: Query your immutable, hash-chained proof receipts (claims, decisions, and action verifications).

## Agent System Prompt Guidelines
When interfacing with VerifiedOS:
1. Always generate a unique client UUID v4 for the `idempotency_key` header on verification requests.
2. Include the `Authorization: Bearer <vfy_ key>` header for authenticated endpoints.
3. Validate proof-of-claim receipts by verifying the returned `ledger_hash` SHA256 string.