Clarviaclarvia

API Reference

Complete documentation for the Clarvia AEO Scanner API. Scan any API, track agent traffic, and optimize your service for AI agents.

Base URL: https://api.clarvia.art|JSON responses|No SDK required

Quickstart: Your first scan in 30 seconds

1

Scan your API

curl -X POST https://api.clarvia.art/api/scan \
  -H "Content-Type: application/json" \
  -d '{"url": "your-api.com"}'
2

Get your score

The response includes your Clarvia Score (0-100), rating, and a breakdown across 4 dimensions. Save the scan_id for badges and history.

3

Get fix suggestions

curl -X POST https://api.clarvia.art/api/v1/fix \
  -H "Content-Type: application/json" \
  -d '{"sub_factor": "rate_limit_info", "stack": "python"}'
4

Embed your badge

![Clarvia Score](https://api.clarvia.art/api/badge/YOUR_SCAN_ID)
5

Monitor agent traffic (optional)

Register at POST /api/v1/traffic/register to get middleware snippets and track how AI agents use your API.

Authentication

Most endpoints require no authentication. For authenticated endpoints, include your API key in the X-Clarvia-Key header. Get a free key at POST /api/v1/keys.

curl -H "X-Clarvia-Key: clv_your_key_here" https://api.clarvia.art/api/v1/keys/validate

API Versioning

How Clarvia manages API versions, deprecation timelines, and backward compatibility.

v1

Current stable version

All production endpoints use the /api/v1/ prefix. This is the recommended version for all new integrations.

v0

Legacy endpoints (deprecation planned)

POST /api/scan is a legacy v0 endpoint. It will continue to work but is scheduled for deprecation. Migrate to GET /api/v1/score for new projects.

Versioning Strategy

●All versioned endpoints use the /api/v{N}/ URL prefix
●Breaking changes are introduced only in a new major version (e.g. v2)
●Deprecated versions receive a minimum 6-month notice before removal
●Additive changes (new fields, new endpoints) are non-breaking and added to the current version

API-Version Response Header

Every response includes an API-Version header indicating which version served the request. Use this to verify your integration targets the correct version.

HTTP/1.1 200 OK
Content-Type: application/json
API-Version: v1
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29

Migration tip: If you are using POST /api/scan, switch to GET /api/v1/score?url=... for better caching, simpler integration, and guaranteed long-term support.

Public API

No authentication required. Generous rate limits for exploration.

Authenticated API

Requires X-Clarvia-Key header. Higher rate limits and advanced features.

Traffic Monitoring

Track how AI agents interact with your API in real time.

CI/CD Integration

Block PR merges when your AEO score drops below a threshold. Keep your API agent-ready on every deploy.

Setup in 3 steps

1

Generate an API key

curl -X POST https://api.clarvia.art/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"email": "ci@yourteam.com"}'
2

Add to GitHub Secrets

Go to Settings → Secrets and variables → Actions and add:

  • CLARVIA_API_KEY — your API key from step 1
  • API_URL (variable) — your API domain (e.g. api.example.com)
3

Add the workflow file

Create .github/workflows/aeo-check.yml in your repo:

GitHub Actions.github/workflows/aeo-check.yml
name: AEO Score Check
on: [pull_request]

jobs:
  aeo-check:
    runs-on: ubuntu-latest
    steps:
      - name: Check AEO Score
        run: |
          RESULT=$(curl -s -H "X-Clarvia-Key: ${{ secrets.CLARVIA_API_KEY }}" \
            -X POST https://clarvia-api.onrender.com/api/v1/ci/check \
            -H "Content-Type: application/json" \
            -d '{"url": "${{ vars.API_URL }}", "min_score": 60}')
          PASSED=$(echo $RESULT | jq -r '.passed')
          SCORE=$(echo $RESULT | jq -r '.score')
          echo "AEO Score: $SCORE"
          if [ "$PASSED" != "true" ]; then
            echo "::error::AEO Score $SCORE is below minimum threshold"
            exit 1
          fi
Direct curl usage
curl -s -X POST https://api.clarvia.art/api/v1/ci/check \
  -H "X-Clarvia-Key: clv_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "api.example.com",
    "min_score": 60,
    "required_dimensions": {
      "api_accessibility": 15,
      "agent_compatibility": 10
    }
  }'

Error Handling

All errors return JSON with a consistent structure.

{
  "detail": "Human-readable error message"
}

Status Codes

200Success
400Bad request — missing or invalid parameters
401Unauthorized — invalid or missing API key
404Not found — scan ID or resource does not exist
422Unprocessable — URL is invalid or unreachable
429Rate limit exceeded — wait and retry
500Server error — scan failed internally

Rate Limiting

Rate limits are per IP for public endpoints and per API key for authenticated endpoints. When rate limited, you receive a 429 status code. Check X-RateLimit-Remaining and X-RateLimit-Reset headers to manage your usage.

Ready to optimize your API for AI agents?

Scan your API|Optimization Guide|Scoring Methodology