---
title: agents.json Validator
description: Validate your Wildcard agents.json file. Check that API-first sites publish a discoverable agents.json describing authentication, inputs, and outputs.
last_updated: 2026-05-11
canonical_url: https://agent-ready.dev/agents-json-validator
---

# agents.json Validator

> Validate your Wildcard agents.json file. Check that API-first sites publish a discoverable agents.json describing authentication, inputs, and outputs.

## What is agents.json?

agents.json is an OpenAPI extension from Wildcard (v0.1.0) that declares which API endpoints agents are meant to call, with inline descriptors for authentication, inputs, and outputs. It narrows OpenAPI down to the operations you want agents using, rather than the full API surface.

## Why should I add an agents.json file?

If you publish a REST API and want AI agents to call it, agents.json is the cheapest way to make that discoverable. It builds on the OpenAPI spec you (probably) already have — no need to invent a new protocol like MCP or A2A. Agents fetch agents.json, follow the OpenAPI Pointer references, and know exactly which operations are safe to invoke with what auth.

## What does the agents.json validator check?

- File at `/agents.json` or `/.well-known/agents.json` returns HTTP 200
- Valid JSON
- Required `name` field present
- `auth` block (Basic / ApiKey / Bearer) declared if applicable
- `flows` array references operations in your underlying OpenAPI spec
- Recommended descriptors for inputs and outputs

Spec is pre-standard (v0.1.0), so the validator treats missing fields as warnings rather than hard failures.

## Minimal valid example

```json
{
  "name": "Acme API agents.json",
  "auth": {
    "type": "Bearer"
  },
  "flows": [
    {
      "name": "create-widget",
      "operation": { "$ref": "openapi.json#/paths/~1widgets/post" },
      "description": "Create a new widget for the agent's user."
    }
  ]
}
```

## Reference

- [wild-card-ai/agents-json](https://github.com/wild-card-ai/agents-json) — Wildcard's spec
- [OpenAPI Specification](https://www.openapis.org/) — what agents.json extends

---

Validate your agents.json: <https://agent-ready.dev/agents-json-validator>

Related guide: [MCP vs A2A vs agents.json](https://agent-ready.dev/mcp-vs-a2a-vs-agents-json)

## Sitemap

See the full [sitemap](https://agent-ready.dev/sitemap.md) for all pages on agent-ready.dev.