Validation API

The validation API can be used to validate agent cards in bulk or individually. It's available for free and Pro/Team subscriptions and adheres to the rate limits of those subscription tiers.

Rate Limits

We like to keep things simple with rate limits. They're determined by your subscription tier:

• Unauthenticated: 5 validations per day
• Free: 10 validations per day
• Pro/Team: Unlimited validations

Endpoints

Single Validation

POST /v1/validate

Validate a single agent card.

Authentication: Optional (but recommended)

Request Body:

{
  "agent_card": {
    "protocolVersion": "0.2.6",
    "name": "My Agent",
    "description": "Agent description",
    // ... rest of agent card
  },
  "validation_mode": "standard",
  "options": {
    "include_suggestions": true,
    "include_score": true,
    "protocolVersion": "0.2.6"
  }
}

Parameters:

• agent_card (required): The agent card JSON to validate
• validation_mode (optional): Validation mode (standard or cli)
• options (optional): Validation options
  • include_suggestions (boolean): Include improvement suggestions
  • include_score (boolean): Include quality score
  • protocolVersion (string): Specific protocol version to validate against

Response:

{
  "valid": true,
  "errors": [],
  "warnings": [
    {
      "path": "description",
      "message": "Description could be more detailed"
    }
  ],
  "score": 85,
  "suggestions": [
    {
      "type": "improvement",
      "field": "tags",
      "suggestion": "Consider adding more specific tags"
    }
  ],
  "report_id": "rpt_1705312200000_abc123",
  "report_url": "https://valgent.io/reports/rpt_1705312200000_abc123",
  "response_time_ms": 45,
  "recorded": true,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "version": "0.2.6",
  "rateLimitInfo": {
    "used": 1,
    "limit": 10,
    "remaining": 9,
    "plan": "free"
  }
}

Error Response:

{
  "valid": false,
  "errors": [
    {
      "path": "name",
      "message": "Name is required"
    }
  ]
}

Batch Validation

POST /v1/validate/batch

Validate multiple agent cards in a single request. Available for Pro and Team plans.

Authentication: Required

Request Body:

{
  "cards": [
    {
      "id": "card1",
      "agent_card": {
        "protocolVersion": "0.2.6",
        "name": "Agent 1",
        // ... rest of agent card
      }
    },
    {
      "id": "card2", 
      "agent_card": {
        "protocolVersion": "0.2.6",
        "name": "Agent 2",
        // ... rest of agent card
      }
    }
  ]
}

Parameters:

• cards (required): Array of cards to validate
  • id (required): Unique identifier for this card in the batch
  • agent_card (required): The agent card JSON to validate

Response:

{
  "batch_id": "batch_1705312200000_xyz789",
  "total": 2,
  "valid": 1,
  "invalid": 1,
  "results": [
    {
      "id": "card1",
      "valid": true,
      "errors": [],
      "warnings": [],
      "score": 92
    },
    {
      "id": "card2",
      "valid": false,
      "errors": [
        {
          "path": "protocolVersion",
          "message": "Protocol version is required"
        }
      ],
      "score": 0
    }
  ],
  "summary": {
    "total_processed": 2,
    "success_rate": 0.5,
    "average_score": 46,
    "processing_time_ms": 120
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Error Responses:

Batch not allowed:

{
  "error": "Batch validation requires Pro or Team plan",
  "code": "BATCH_NOT_ALLOWED"
}

Invalid format:

{
  "error": "Invalid request format. Expected \"cards\" array.",
  "code": "INVALID_BATCH_FORMAT"
}

Error Codes

Response Headers

All API responses include these headers:

Content-Type: application/json
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 1705315800

SDK Examples

Node.js

const response = await fetch('https://api.valgent.io/v1/validate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.VALGENT_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    agent_card: agentCardData,
    options: {
      include_suggestions: true,
      include_score: true
    }
  })
});

const result = await response.json();

Python

import requests
import os

response = requests.post(
    'https://api.valgent.io/v1/validate',
    headers={
        'Authorization': f"Bearer {os.environ.get('VALGENT_API_KEY')}",
        'Content-Type': 'application/json'
    },
    json={
        'agent_card': agent_card_data,
        'options': {
            'include_suggestions': True,
            'include_score': True
        }
    }
)

result = response.json()

cURL

curl -X POST https://api.valgent.io/v1/validate \
  -H "Authorization: Bearer $VALGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d @agent-card.json