# SuggestAPI Agent Gateway

This host exposes machine-readable discovery and tenant-scoped search retrieval for assistants and agent runtimes.

## Canonical discovery
- OpenAPI: `https://agent.suggestapi.com/openapi.yaml`
- LLM guidance: `https://agent.suggestapi.com/llms.txt`
- Gateway discovery: `https://agent.suggestapi.com/.well-known/okg.json`
- Agent manifest: `https://agent.suggestapi.com/.well-known/agent.json`
- AI plugin manifest: `https://agent.suggestapi.com/.well-known/ai-plugin.json`
- AI catalog: `https://agent.suggestapi.com/.well-known/ai-catalog.json`
- DID document: `https://agent.suggestapi.com/.well-known/did.json`
- A2A Agent Card: `https://agent.suggestapi.com/.well-known/agent-card.json`
- A2A JSON-RPC endpoint: `https://agent.suggestapi.com/a2a` (methods: agent/card, message/send, tasks/get, tasks/cancel)
- AID fallback: `https://agent.suggestapi.com/.well-known/agent`
- AID index: `https://agent.suggestapi.com/.well-known/ai`
- DNS-AID index: `https://agent.suggestapi.com/.well-known/dns-aid.json`
- UCP profile: `https://agent.suggestapi.com/.well-known/ucp`
- Tenant UCP profile: `https://agent.suggestapi.com/oks/{tenant}/.well-known/ucp`
- ACP profile: `https://agent.suggestapi.com/.well-known/acp`
- Tenant ACP profile: `https://agent.suggestapi.com/oks/{tenant}/.well-known/acp`
- MCP Registry manifest: `https://agent.suggestapi.com/.well-known/mcp/server.json`
- MCP streamable-HTTP server: `https://agent.suggestapi.com/mcp`
- WebMCP manifest: `https://agent.suggestapi.com/.well-known/webmcp`
- API catalog (Linkset): `https://agent.suggestapi.com/.well-known/api-catalog`

## Primary runtime surfaces
- `GET /.well-known/ucp`
- `GET /oks/{tenant}/.well-known/ucp`
- `POST /oks/{tenant}/catalog/search`
- `POST /catalog/search` (requires `tenant`)
- `GET /.well-known/acp`
- `GET /oks/{tenant}/.well-known/acp`
- `GET /oks/{tenant}/feeds/default/products`
- `POST /oks/{tenant}/checkout_sessions`
- `GET /oks/{tenant}`
- `GET /oks/{tenant}/search?q=...`
- `QUERY /oks/{tenant}/search` (JSON query content)
- `GET /oks/{tenant}/products/{id}`
- `POST` or `QUERY /v1/agent/search`
- `POST /v1/agent/compare`
- `POST /v1/agent/recommend`
- `POST /v1/agent/cart`
- `POST /v1/agent/checkout/guide`
- `POST` or `QUERY /ard/v1/search`
- `POST /ard/v1/explore`
- `GET /catalogs/{tenant}/ai-catalog.json`

## Tenant resolution
- Production tenant routing is driven by Cloudflare KV through the `TENANT_MAP` binding.
- Unknown tenants return cacheable `404 tenant_not_found` responses.

## Content policy
- Allowed: live tool discovery, runtime retrieval, and agent execution against the published API.
- Not allowed: model training, offline bulk harvesting, or republishing tenant content without permission.
- The gateway stays on the search side; cart, checkout, and payment remain native merchant-platform flows.