Skip to main content

​
Overview

The /validate endpoint checks whether an AGENTS.md file’s content conforms to the expected schema and format. It performs structural validation and can optionally verify endpoint reachability when using the beacon-ai-cloud provider.

​
Endpoint

POST /validate

​
Rate Limiting

This endpoint is rate-limited to 20 requests per minute per IP address.

​
Authentication

No direct authentication is required for basic validation. When using the beacon-ai-cloud provider for enhanced validation with endpoint checking, payment verification is required (similar to the /generate endpoint).

​
Request

​
Request Body

​
content
string
required
The complete AGENTS.md file content as a string to be validated.
​
provider
string
default:"none"
The validation provider to use:
  • "none" - Basic schema validation (default)
  • "beacon-ai-cloud" - Enhanced validation with AI-powered checks (requires payment)

​
Example Request

curl -X POST http://localhost:8080/validate \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# AGENTS.md — my-service\n\n> Service description\n\n## Capabilities\n...",
    "provider": "none"
  }'

​
Example Request with Payment (beacon-ai-cloud)

curl -X POST http://localhost:8080/validate \
  -H "Content-Type: application/json" \
  -H "x-payment-txn-hash: 0xabc123..." \
  -H "x-payment-chain: base" \
  -H "x-payment-run-id: run_xyz789" \
  -d '{
    "content": "# AGENTS.md — my-service\n...",
    "provider": "beacon-ai-cloud"
  }'

​
Response

​
Success Response (200 OK)

​
success
boolean
required
Always true for successful validation requests (even if the content is invalid).
​
valid
boolean
Whether the AGENTS.md content is valid according to the schema.
​
errors
array
Array of error messages describing validation failures. Empty if no errors found.Each item is a string describing a specific validation error.
​
warnings
array
Array of warning messages for non-critical issues. Empty if no warnings.Each item is a string describing a potential improvement or minor issue.
​
endpoint_results
array
Array of endpoint reachability check results (only populated when endpoints are checked).Each object contains:
  • endpoint (string): The endpoint path that was checked
  • reachable (boolean): Whether the endpoint responded successfully
  • status_code (number): HTTP status code received (if reachable)
  • error (string): Error message if the endpoint check failed

​
Example Valid Response

{
  "success": true,
  "valid": true,
  "errors": [],
  "warnings": [],
  "endpoint_results": []
}

​
Example Invalid Response

{
  "success": true,
  "valid": false,
  "errors": [
    "Missing required section: Capabilities",
    "Invalid capability schema: 'create_user' missing required field 'input_schema'"
  ],
  "warnings": [
    "No version specified in frontmatter",
    "Rate limits section could be more specific"
  ],
  "endpoint_results": []
}

​
Example with Endpoint Checks

{
  "success": true,
  "valid": true,
  "errors": [],
  "warnings": [
    "Consider adding more detailed examples for capabilities"
  ],
  "endpoint_results": [
    {
      "endpoint": "https://api.example.com/health",
      "reachable": true,
      "status_code": 200,
      "error": null
    },
    {
      "endpoint": "https://api.example.com/users",
      "reachable": false,
      "status_code": null,
      "error": "Connection timeout"
    }
  ]
}

​
Error Responses

​
402 Payment Required

Returned when using beacon-ai-cloud provider without valid payment. 
{
  "success": false,
  "error": "Payment required"
}
Response Headers:
  • x-payment-run-id: Unique run identifier for this validation request
  • x-payment-amount: Amount required in USDC (e.g., “0.09”)
  • x-payment-currency: Always “USDC”
  • x-payment-address-base: Base blockchain wallet address
  • x-payment-address-solana: Solana blockchain wallet address

​
409 Conflict

Returned when a transaction hash has already been used. 
{
  "success": false,
  "error": "Transaction hash already used"
}

​
429 Too Many Requests

Returned when rate limit is exceeded (>20 requests/minute).

​
500 Internal Server Error

Returned when validation fails unexpectedly. 
{
  "success": false,
  "error": "Validation failed: <error details>"
}

​
Validation Checks

The validator performs several types of checks:

​
Schema Validation

  • Required sections: Ensures all mandatory sections are present (name, description, capabilities/endpoints)
  • Field types: Verifies that fields have the correct data types
  • Required fields: Checks that required fields within capabilities and endpoints are not missing
  • Schema structure: Validates input/output schemas are valid JSON

​
Content Validation

  • Frontmatter: Checks for proper markdown frontmatter if present
  • Examples: Validates that examples are well-formed
  • Parameters: Ensures endpoint parameters have required fields

​
Endpoint Checks (Optional)

When endpoint checking is enabled (via CLI --check-endpoints flag or when using certain validation providers):
  • Reachability: Makes HTTP requests to verify endpoints are accessible
  • Response codes: Records HTTP status codes returned
  • Timeout handling: Reports timeouts and connection errors

​
Payment Flow (beacon-ai-cloud)

The payment flow for beacon-ai-cloud validation is identical to the /generate endpoint:
  1. Initial request without payment headers returns 402 with payment details
  2. Submit payment to Base or Solana wallet address
  3. Retry request with payment verification headers:
    • x-payment-txn-hash: Your transaction hash
    • x-payment-chain: "base" or "solana"
    • x-payment-run-id: Run ID from initial response
See the Generate endpoint documentation for detailed payment flow instructions.

​
Implementation Details

The endpoint (defined in src/main.rs:299-370):
  1. Handles payment verification for beacon-ai-cloud provider
  2. Calls validator::validate_content() to perform schema and structural validation
  3. Returns detailed validation results including errors, warnings, and endpoint check results

​
Use Cases

  • Pre-commit validation: Validate AGENTS.md files before committing to version control
  • CI/CD integration: Add validation checks to your continuous integration pipeline
  • Quality assurance: Ensure generated AGENTS.md files meet quality standards
  • Endpoint monitoring: Verify that declared endpoints are actually reachable
  • Schema compliance: Confirm that documentation follows the AGENTS.md specification

Build docs developers (and LLMs) love

Get started for freeTalk to us