DocumentationAgentic Resource Discovery (ARD) lets agents find published gateway and domain capabilities. It is capability discovery, not product or content search. To search a domain’s inventory, call /oks/{domain}/search instead.
Discovery documents
| Document | URL | Purpose |
|---|---|---|
| Gateway document | /.well-known/okg.json |
Describes the SuggestAPI Knowledge Gateway, its capabilities, endpoint map, supported types, and authentication modes. |
| Agent manifest | /.well-known/agent.json |
Describes the public agent-facing search service, operations, search schema, and preferred retrieval order. |
| ARD catalog | /.well-known/ai-catalog.json |
Lists gateway-level published capability entries for ARD discovery. |
| Domain ARD catalog | /catalogs/{domain}/ai-catalog.json |
Publishes one domain’s configured capabilities and content revision. |
| DID document | /.well-known/did.json |
Supplies the did:web:agent.suggestapi.com publisher identity used by catalogs. |
| OpenAPI discovery | /.well-known/openapi.json |
Points clients to the canonical contract. |
| OpenAPI contract | /openapi.yaml |
Defines gateway endpoints, parameters, and schemas. |
The gateway also exposes compatibility and extension discovery documents, including ai-plugin.json, llms.txt, UCP, MCP, and Skills paths. Their presence does not imply the corresponding capability is enabled for every domain.
ARD endpoints
| Endpoint | Purpose |
|---|---|
POST /ard/v1/search |
Return ranked ARD catalog entries that match a capability-discovery query. |
POST /ard/v1/explore |
Return facets over the published capability catalog, such as capabilities, publishers, and media types. |
ARD searches published capability catalogs. It does not search merchant inventory and is not a substitute for the domain search surface.
Link a domain catalog from an origin
Publish the domain catalog from the merchant’s own HTML:
<link rel="ai-catalog" href="https://agent.suggestapi.com/catalogs/{domain}/ai-catalog.json">This lets a capable agent associate the merchant origin with the SuggestAPI-hosted catalog. Keep the domain name aligned with the domain gateway URL and refresh the published catalog when capabilities or domain configuration change.