agents.json is an OpenAPI extension from Wildcard (v0.1.0) that declares which API operations agents are meant to call. A document has four top-level fields — agentsJson (version), info, sources (OpenAPI specs), and flows (each flow references operations by operationId). It narrows an OpenAPI spec down to the operations you want agents using, rather than the full API surface.

Who should publish an agents.json file?

API-first products (payments, messaging, search, data platforms) where agents are expected to call specific endpoints on behalf of users. Docs and marketing sites without a callable API should skip it — even if the file exists, it signals nothing useful.

Where should agents.json live?

Either at /agents.json or /.well-known/agents.json on your API's domain. Both paths are accepted by validators. The spec is pre-standard (v0.1.0) so field requirements are guidance rather than hard rules.

agents.json validation

agents.json validator

Check that your API-first site publishes an agents.json that validates against the Wildcard agents.json v0.1.0 schema.

Last updated 2026-07-14

What is agents.json?

Wildcard’s agents.json (v0.1.0) is an OpenAPI extension that declares which API operations agents are meant to call. A document has four top-level fields — agentsJson, info, sources, and flows — and lives at /agents.json or /.well-known/agents.json.

Why should I add an agents.json file?

If your product has a public API (payments, messaging, search, data), agents.json is the hint that lets agents call it without a human hand-wiring OpenAPI. It narrows OpenAPI down to the operations you actually want agents hitting, each referenced by its operationId. First-mover advantage matters - early coverage means your API shows up in agent workflows other people build.

What does the agents.json validator check?

C6 - Exists. agents.json returns HTTP 200 with parseable JSON, and the site looks API-first (sitemap entries under /api/, /reference/, etc.). Docs/marketing sites are skipped even if the file exists.
Validates. When the file exists and the site is API-first, it is validated against the published Wildcard agents.json v0.1.0 schema (draft-07, via ajv). It passes a document with the required top-level fields (agentsJson, info, sources, flows) and fails one that is missing or invalid them, naming the exact fields. The schema is pre-standard, so there is no warn tier — valid or not.

Minimal valid example

{
  "agentsJson": "0.1.0",
  "info": {
    "title": "Acme Payments",
    "version": "1.0.0",
    "description": "Process payments via the Acme API."
  },
  "sources": [
    { "id": "acme", "path": "https://api.acme.dev/openapi.json" }
  ],
  "flows": [
    {
      "id": "charge_customer_flow",
      "title": "Charge a customer",
      "description": "Creates a charge against a customer.",
      "actions": [
        { "id": "charge_action", "sourceId": "acme", "operationId": "createCharge" }
      ],
      "links": [],
      "fields": {
        "parameters": [],
        "responses": { "success": { "type": "object" } }
      }
    }
  ]
}

Served at /agents.json or /.well-known/agents.json. Flows reference OpenAPI operations by their operationId, so agents get full request/response shapes from the linked source without re-declaring them.

Caveat

Wildcard’s agents.json v0.1.0 is an OpenAPI extension, not a standalone standard. The schema is published and we validate against it directly (ajv, draft-07), so a document either conforms or it does not — there is no warn tier. Operations are referenced only by their operationId; there is no top-level name or auth field in the spec.