Clarvia

The discovery and trust standard for the agent economy.

What is Clarvia? | Why AEO? | Quick Start | Clarvia Score | Docs

---

What is Clarvia?

Clarvia is an open standard that makes services discoverable, comparable, and trustworthy for AI agents.

SEO made websites visible to search engines. Clarvia makes services visible to AI agents.

As AI agents increasingly discover APIs, evaluate providers, and make integration decisions autonomously, they need a structured way to understand what a service does, how reliable it is, and how to connect. Clarvia provides this through:

• Clarvia Profile — A JSON schema describing your service in a format agents can parse
• Clarvia Score — A 0-100 metric quantifying agent-readiness across reliability, compatibility, and trust
• AEO Standard — The methodology and best practices for Agent Engine Optimization

Why AEO Matters

The agent economy is here. Over 5,800 MCP servers are live, AI agents are making real API calls and transactions, and every major AI lab is building agent infrastructure.

Yet most services are invisible to agents. No machine-readable description. No standardized trust signals. No MCP server. Pricing buried in marketing pages.

Agent Engine Optimization (AEO) is how you fix this — and Clarvia is the open standard that defines it.

SEO	AEO
Optimizes for search crawlers	Optimizes for AI agents
HTML pages, meta tags	APIs, MCP servers, JSON schemas
Backlinks and domain authority	Clarvia Score and API reliability
Click-through rate	Agent integration rate

Read the full comparison in our AEO Guide.

Clarvia Score

The Clarvia Score (0–100) measures how agent-ready your service is across four dimensions:

Dimension	Weight	What It Measures
API Accessibility	25 pts	Endpoint reachability, speed, auth docs
Data Structuring	25 pts	Schema quality, pricing clarity, error format
Agent Compatibility	25 pts	MCP server, robots.txt policy, discovery
Trust Signals	25 pts	Uptime, success rate, documentation, freshness
Onchain Bonus	+25 pts	Verifiable on-chain activity (capped at 100 total)

Score ranges: Exceptional (90-100) · Strong (75-89) · Moderate (60-74) · Basic (40-59) · Low (0-39)

See the full algorithm in scorer/algorithm.md and weights in scorer/weights.json.

Quick Start

1. Create Your Clarvia Profile

{
  "@context": "clarvia.io/schema/v1",
  "@type": "Clarvia:Service",
  "name": "Your Service",
  "description": "What your service does.",
  "category": "developer-tools",
  "api": {
    "endpoint": "https://api.yourservice.com/v1",
    "docs": "https://docs.yourservice.com",
    "mcp_server": null,
    "latency_ms": 200,
    "auth_type": "api_key"
  },
  "pricing": {
    "model": "freemium",
    "amount": null,
    "currency": "USD",
    "agent_payable": false
  },
  "trust": {
    "clarvia_score": 0,
    "success_rate": 0.99,
    "uptime": 0.999,
    "onchain_verified": false
  },
  "capabilities": ["your-capability"],
  "metadata": {
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "version": "1.0.0"
  }
}

2. Validate Your Profile

# Using ajv-cli
npx ajv validate -s v1/clarvia-profile.schema.json -d your-profile.json

# Using Python
python -m jsonschema -i your-profile.json v1/clarvia-profile.schema.json

3. Host It

Serve your profile at:

https://yourservice.com/.well-known/clarvia-profile.json

4. Improve Your Score

Follow the AEO Checklist to systematically improve your Clarvia Score.

Examples

Real-world Clarvia Profile examples for major services:

Service	Category	Score	Profile
Stripe API	Payments	92	examples/stripe-api.json
GitHub API	Developer Tools	88	examples/github-api.json
Notion API	Productivity	78	examples/notion-api.json

Documentation

Document	Description
Clarvia Profile Schema	JSON Schema for Clarvia Profile v1
AEO Guide	Comprehensive guide to Agent Engine Optimization
Scoring Algorithm	How the Clarvia Score is calculated
Scoring Weights	Machine-readable scoring weights

Repository Structure

schema/
├── v1/
│   └── clarvia-profile.schema.json   # JSON Schema definition
├── scorer/
│   ├── algorithm.md                   # Scoring algorithm documentation
│   └── weights.json                   # Machine-readable weights
├── examples/
│   ├── stripe-api.json                # Stripe API profile (score: 92)
│   ├── github-api.json                # GitHub API profile (score: 88)
│   └── notion-api.json                # Notion API profile (score: 78)
├── docs/
│   └── aeo-guide.md                   # AEO beginner's guide
├── LICENSE                            # MIT License
└── README.md                          # This file

Contributing

Clarvia is an open standard and we welcome contributions.

How to Contribute

1. Fork this repository
2. Create a branch for your changes (git checkout -b feature/my-improvement)
3. Make your changes — ensure all JSON files validate against the schema
4. Submit a Pull Request with a clear description of your changes

Areas We Need Help With

• Schema extensions — Propose new fields or categories for the Clarvia Profile
• Example profiles — Add Clarvia Profiles for more real-world services
• Scoring refinements — Suggest improvements to the scoring algorithm
• Language support — Translate documentation into other languages
• Tooling — Build validators, generators, or integrations

Guidelines

• All documentation and code comments must be in English
• JSON files must validate against the Clarvia Profile schema
• Follow existing formatting conventions
• Include tests or validation for any schema changes

License

MIT — Copyright (c) 2026 Clarvia

---

Built for the agent economy. 🤖

Website · Documentation · Examples