Search · Product discovery · Agents
Supported protocols.
SuggestAPI exposes the same search and product-discovery jobs — find, look up, compare, recommend — over the protocols agents and storefronts already speak. This page is the human map of those surfaces.
Last updated:
Two hosts, one discovery job
Shoppers hit the search acceleration API. Agents hit the Knowledge Gateway. Both sit in front of the search engine you already run — Algolia, Typesense, Elastic, or Meilisearch — and return structured catalog results instead of scraped HTML.
| Host | Audience | What it is for | Start here |
|---|---|---|---|
| api.suggestapi.com | Storefronts, apps, ingestion | Autocomplete, typeahead, indexes, merchandising, and catalog APIs | openapi.json |
| agent.suggestapi.com | Agents, plugins, registries | Tenant search, product lookup, compare, recommend, and protocol discovery | okg.json |
The gateway service index is https://agent.suggestapi.com. Human protocol notes live in AGENTS.md.
Shared product-discovery skills
A2A and MCP expose the same four commerce tools. Each tool is a thin protocol wrapper over a Knowledge Gateway REST call. Tenant is the merchant domain (for example demo.suggestapi.com).
| Skill / tool | Required params | Optional | Backend |
|---|---|---|---|
| search | tenant, query | retrieval_mode (typeahead, autocomplete, search, hybrid), limit | POST /v1/agent/search |
| recommend | tenant, query | — | POST /v1/agent/recommend |
| compare | tenant, ids (≥2) | — | POST /v1/agent/compare |
| product_lookup | tenant, id | — | GET /v1/agent/product/{id} |
Knowledge Gateway protocol endpoints
Host agent.suggestapi.com. Discovery documents live under /.well-known/. Runtime JSON-RPC lives at /a2a and /mcp. UCP and ACP are REST commerce contracts on the same host.
| Protocol | Method | Path | What it is |
|---|---|---|---|
| A2A | GET | /.well-known/agent-card.json | Agent Card (protocol 0.2.0, four skills) |
| A2A | POST | /a2a | JSON-RPC: agent/card, message/send, tasks/get, tasks/cancel |
| AID | GET | /.well-known/agent | AID fallback document (aid2, proto a2a) |
| AID | GET | /.well-known/ai | AID agent index (agents[] with suggestapi) |
| DNS-AID | GET | /.well-known/dns-aid.json | Index of A2A + MCP agents; A2A capSha256 is base64url of the card |
| MCP | POST | /mcp | Streamable-HTTP JSON-RPC (protocol 2025-06-18) |
| WebMCP | GET | /.well-known/webmcp | Tool manifest plus REST endpoints for each commerce tool |
| MCP | GET | /.well-known/mcp-manifest.json | MCP tool/manifest alias |
| MCP | GET | /.well-known/mcp-server | Well-known MCP server document (draft-serra style) |
| MCP | GET | /.well-known/mcp/server.json | MCP Registry server schema (streamable-http remote) |
| MCP | GET | /.well-known/api-catalog | RFC 9727 linkset to WebMCP + MCP |
| UCP | GET | /.well-known/ucp | Universal Commerce Protocol profile; catalog search is tenant-scoped |
| ACP | GET | /.well-known/acp | Agent Commerce Protocol profile; feed and checkout sessions are tenant-scoped |
Live copies: Agent Card,/a2a,/mcp,WebMCP,AID,AID index,DNS-AID,api-catalog,UCP,ACP.
A2A and MCP runtimes
A2A is Agent-to-Agent: fetch the card, then send a message that names a skill. Tasks are stored for about 30 minutes so a client can poll or cancel. MCP is Model Context Protocol over streamable HTTP: handshake, list tools, call a tool. Both dispatch to the same gateway skills.
A2A JSON-RPC
| Method | Role |
|---|---|
| agent/card | Return the Agent Card |
| message/send | Run a skill; store task ~30 min |
| tasks/get | Fetch a stored task |
| tasks/cancel | Mark a stored task canceled |
MCP JSON-RPC
| Method | Role |
|---|---|
| initialize | Handshake + protocol version |
| notifications/initialized | Ack client ready |
| ping | Liveness |
| tools/list | Four commerce tools |
| tools/call | Dispatch via gateway skills |
| resources/list, prompts/list | Empty lists (supported, unused) |
MCP registry metadata is also at /.well-known/mcp.json.
What each protocol is for
Discovery protocols tell an agent what exists. Runtime protocols let it search the catalog. SuggestAPI publishes both so you are not locked into one agent stack.
| Protocol | Job | Search / product discovery role |
|---|---|---|
| A2A | Runtime | Another agent calls SuggestAPI as a commerce specialist: search, lookup, compare, recommend. |
| MCP | Runtime | Coding and shopping assistants attach /mcp and get the four catalog tools. See the MCP and WebMCP notes. |
| WebMCP | Discovery + REST | Browser and site agents read a tool list that also names the REST URLs behind each tool. See the MCP and WebMCP notes. |
| AID / DNS-AID | Discovery | Find the A2A (and MCP) agent on this host without hardcoding paths. DNS-AID includes a hash of the Agent Card. |
| ARD | Discovery | Google Agentic Resource Discovery catalog of commerce capabilities. Does not execute search itself. See ARD. |
| UCP | Runtime (REST) | Universal Commerce Protocol catalog search, tenant-scoped. See /.well-known/ucp. |
| ACP | Runtime (REST) | Agent Commerce Protocol product feed and checkout-session handoff, tenant-scoped. Sessions stay not_ready_for_payment; SuggestAPI does not capture payment. See /.well-known/acp. |
| OKF / OKS | Knowledge + plugin search | Portable knowledge plus /oks/{tenant}/search for shops that keep their existing catalog. See OKF. |
| HTTP QUERY | Runtime (HTTP) | RFC 10008 safe, idempotent search bodies on autocomplete, typeahead, and agent search. See the QUERY notes. |
| REST + OpenAPI | Runtime | Direct HTTP for apps that do not speak A2A or MCP. Gateway: openapi.yaml. API: openapi.json. |
| Agent Skills | Coding-agent playbooks | SKILL.md folders that teach Claude, Codex, Antigravity, Cursor, and similar clients how to call api.suggestapi.com. Install suggestapi/skills with npx skills add suggestapi/skills. Domain index: /.well-known/agent-skills/index.json. |
Knowledge Gateway REST (search and catalog)
Use these when you want JSON over HTTP without JSON-RPC. Tenant plugin search is the adoption path for existing shops.
| Method | Path | Purpose |
|---|---|---|
| POST / QUERY | /v1/agent/search | Task-oriented search across a tenant knowledge surface |
| GET | /v1/agent/product/{id} | Canonical product lookup |
| POST | /v1/agent/compare | Compare products by id |
| POST | /v1/agent/recommend | Recommendations from query + context |
| GET / QUERY | /oks/{tenant}/search | Plugin-style search (q, mode) |
| POST | /oks/{tenant}/catalog/search | UCP catalog search for that merchant |
| GET | /oks/{tenant}/feeds/default/products | ACP product feed for that merchant |
| POST | /oks/{tenant}/checkout_sessions | ACP checkout session (handoff only; payment complete is not offered) |
| GET | /.well-known/ai-catalog.json | ARD capability catalog |
Handoff helpers (/v1/agent/cart, checkout guide) exist for merchant-controlled checkout. They are not a payment API. Capability overview: Agent Discovery docs.
Search acceleration API
https://api.suggestapi.com is the HTTP API for storefront typeahead, autocomplete, indexes, ingestion, and graph-style recommendations. It is not the A2A/MCP host — agents that need tenant commerce tools should use the Knowledge Gateway.
| Method | Path | Purpose |
|---|---|---|
| GET / QUERY | /v1/autocomplete | Intent-ranked suggestions for the search bar |
| GET / QUERY | /v1/typeahead | Fast prefix typeahead from a precomputed table |
| GET / POST | /v1/indexes… | Create, ingest, merchandising, schema, export |
| GET / POST | /v1/graph/recommendations… | Structural, series, application, and spec recommendations |
| GET | /health | Liveness |
| GET | /openapi.json | Full machine-readable contract |
Coding agents that should implement against this API: install suggestapi/skills (npx skills add suggestapi/skills). Engineering adapters and response schema: Bring Your Own Search. Query routing: Retrieval abstraction.
Which protocol should I use?
| If you are… | Use |
|---|---|
| Wiring a storefront search bar | GET https://api.suggestapi.com/v1/autocomplete or typeahead |
| Building an MCP client (Cursor, Claude, custom) | POST https://agent.suggestapi.com/mcp |
| A coding agent (Claude, Codex, Antigravity, Cursor) implementing against the Search API | npx skills add suggestapi/skills → https://api.suggestapi.com |
| Calling from another A2A agent | Fetch the Agent Card, then POST https://agent.suggestapi.com/a2a |
| Indexing capabilities without a hardcoded tool list | ARD ai-catalog.json, AID, or DNS-AID |
| Implementing UCP shopping catalog search | POST /oks/{tenant}/catalog/search |
| Implementing ACP catalog feed and checkout handoff | GET /oks/{tenant}/.well-known/acp, then the tenant feed and checkout sessions. Complete stays on the merchant storefront. |
| Keeping the merchant site as the source of truth | OKS plugin search /oks/{tenant}/search |