AI Catalog and ARD discovery

A static JSON envelope that supports multiple artifact types, typically served at /.well-known/ai-catalog.json. Each entry identifies an artifact by its Internet Assigned Numbers Authority (IANA) media type and either links to it (url) or embeds it (data).

A discovery standard that extends AI Catalog with a domain-based identifier scheme (urn:air:<publisher>:<namespace>:<name>) and a required POST /search REST API for dynamic discovery. It also defines optional GET /agents and POST /explore endpoints. The standard path for publishing and retrieving an ARD catalog is /.well-known/ard.json.

Returns the AI Catalog document. This earlier path remains available for clients that support only AI Catalog.

Returns the same AI Catalog document. An ARD crawler retrieves the document from this path as required by the ARD specification. A client conforms to the specification even if it retrieves only ard.json. If you can serve only one path, use this path.

Each entry has an identifier in the urn:air:<publisher>:<namespace>:<name> form. Entries for AGENT_CARD artifacts use application/a2a-agent-card+json. Entries for MCP_TOOL artifacts use application/mcp-server-card+json.

When apicurio.ard.enabled=true, the first entry in the catalog has the type application/ai-registry+json and identifies the registry. This entry points to the /.well-known/ard/search endpoint. A crawler that retrieves only the static catalog can discover the search API from this entry, as defined by the ARD specification.

Apicurio Registry filters Agent Card entries by the apicurio.agent.visibility label with the same rules as /.well-known/agents. MCP tool entries have no visibility label, so Apicurio Registry always includes them. When neither OpenID Connect (OIDC) nor basic authentication is configured, Apicurio Registry applies no visibility filtering.

Both endpoints require read-level authorization when authentication is enabled. Anonymous clients can read them only if apicurio.auth.anonymous-read-access.enabled is true. The same documents are also available at /apis/registry/v3/well-known/ai-catalog.json and /apis/registry/v3/well-known/ard.json.

The required ARD search endpoint accepts a query object with a required text field and an optional structured filter. The supported filter keys are type, tags, capabilities, and publisher. Apicurio Registry matches the text value against artifact names and artifact IDs as a partial match. A value without matches anywhere, and you can use as a prefix or suffix wildcard. Values within a filter key use the OR operator; different keys use the AND operator. A tags value of the form key=value matches an artifact label exactly. A value without = matches any artifact that has a label with that key. A capabilities value matches a skill ID of an Agent Card entry. A type value must match, or be a substring of, one of the two media types that Apicurio Registry emits. pageSize defaults to 10, and Apicurio Registry clamps larger values to 100. To fetch the next page, pass the pageToken value from the previous response. The last page has no pageToken.

{
  "query": {
    "text": "translation",
    "filter": {
      "type": ["application/a2a-agent-card+json"]
    }
  },
  "pageSize": 10
}

{
  "results": [
    {
      "identifier": "urn:air:registry.example.com:8080:ai-agents:translator-agent",
      "displayName": "Translation Agent",
      "type": "application/a2a-agent-card+json",
      "url": "http://registry.example.com:8080/.well-known/agents/ai-agents/translator-agent",
      "description": "Translates text between languages",
      "capabilities": ["translation"],
      "version": "1.0.0",
      "updatedAt": "2026-09-01T10:15:30Z",
      "tags": ["apicurio.agent.visibility=public", "department=localization"],
      "score": 100,
      "source": "http://registry.example.com:8080"
    }
  ]
}

The optional, deterministic browsing endpoint accepts a filter query parameter in the form key=value[ AND key=value]*. It supports the same filter keys and matching rules as POST /ard/search. The endpoint also accepts orderBy, pageSize, and pageToken parameters. Apicurio Registry accepts orderBy for compatibility with ARD clients, but the parameter has no effect. Apicurio Registry returns Agent Card entries before MCP tool entries and orders each group newest first. pageSize defaults to 20, and Apicurio Registry clamps larger values to 500. The endpoint returns an AI Catalog document. When more results remain, the response includes a nextPageToken value that you can use to request the next page.

curl -G "http://localhost:8080/.well-known/ard/agents" \
  --data-urlencode "filter=type=application/a2a-agent-card+json" \
  --data-urlencode "pageSize=10"

The optional facet aggregation endpoint accepts an optional query in the same form as POST /ard/search. It requires a resultType.facets array that names the fields to aggregate. The supported fields are type and publisher. Each facet request can also set limit (the maximum number of buckets to return) and minCount (the minimum count for a bucket). Apicurio Registry sums the counts of buckets beyond limit into otherCount. The endpoint returns counts grouped by field value instead of ranked entries.

{
  "resultType": {
    "facets": [
      { "field": "type" }
    ]
  }
}

{
  "resultType": "facets",
  "facets": {
    "type": {
      "buckets": [
        { "value": "application/a2a-agent-card+json", "count": 4 },
        { "value": "application/mcp-server-card+json", "count": 2 }
      ],
      "otherCount": 0
    }
  }
}