# SuggestAPI — Agent Discovery

> Use this file to find SuggestAPI machine-readable interfaces for assistants, plugins, and autonomous agents.

SuggestAPI operates two public surfaces:

1. **Search acceleration API** — index, autocomplete, and query routing at `https://api.suggestapi.com`
2. **Knowledge Gateway** — tenant-aware agent commerce at `https://agent.suggestapi.com`

## Start here (www.suggestapi.com)

- Site overview: https://www.suggestapi.com/llms.txt
- API catalog (RFC 9727): https://www.suggestapi.com/.well-known/api-catalog
- Agent skills index: https://www.suggestapi.com/.well-known/agent-skills/index.json
- Marketing sitemap: https://www.suggestapi.com/sitemap.xml

Homepage `Link` headers include `rel="api-catalog"`, `rel="describedby"` for `/llms.txt` and `/agents.md`, and the Knowledge Gateway OKG document.

## Knowledge Gateway (agent.suggestapi.com)

Base URL: https://agent.suggestapi.com

### Discovery documents

| Document | URL | Purpose |
| --- | --- | --- |
| Gateway root | https://agent.suggestapi.com/ | Service index (`docs`, `openapi` paths) |
| OKG discovery | https://agent.suggestapi.com/.well-known/okg.json | Capabilities, endpoints, extensions |
| OpenAPI 3.1 | https://agent.suggestapi.com/openapi.yaml | Knowledge Gateway API specification |
| OpenAI Skills | https://agent.suggestapi.com/.well-known/skills.json | Skills extension discovery |
| MCP | https://agent.suggestapi.com/.well-known/mcp.json | MCP tool discovery |
| UCP | https://agent.suggestapi.com/.well-known/ucp | Universal Commerce Protocol discovery |

Fetch `/.well-known/okg.json` first. It lists agent endpoints, supported object types, and which extensions are enabled for a deployment.

### Core agent endpoints

| Endpoint | Method | Description |
| --- | --- | --- |
| `/v1/agent/search` | POST | Task-oriented search across a tenant knowledge surface |
| `/v1/agent/product/{id}` | GET | Normalized product lookup |
| `/v1/agent/compare` | POST | Compare products by ID |
| `/v1/agent/recommend` | POST | Recommendations from query + context |
| `/oks/{tenant}` | GET | Describe a tenant plugin surface (domain identifier) |
| `/oks/{tenant}/search` | GET | Plugin-style search (`q`, `mode`) |

Tenant identifier is typically the merchant **domain** (for example `demo.suggestapi.com`).

### Tenant content (OKS)

Mutable tenant bodies such as store policies and agent guides live under:

- `https://agent.suggestapi.com/oks/{tenant}/content/{object-id}`

Example: `https://agent.suggestapi.com/oks/demo.suggestapi.com/content/agents.md`

Content object IDs are case-insensitive (`agents.md` and `AGENTS.md` resolve to the same object).

## Search acceleration API (api.suggestapi.com)

| Document | URL |
| --- | --- |
| OpenAPI | https://api.suggestapi.com/openapi.json |
| Health | https://api.suggestapi.com/health |
| App (keys, UI) | https://app.suggestapi.com |

Use this API for indexes, ingestion, autocomplete, typeahead, and routing queries through the search acceleration layer in front of Algolia, Typesense, Elastic, or Meilisearch.

## Agent skills (Cursor / Agent Skills format)

- Index: https://www.suggestapi.com/.well-known/agent-skills/index.json
- `suggestapi` — platform API integration
- `suggestapi-discovery` — well-known URIs and Link headers

Verify each skill `SKILL.md` digest against the index before use.

## Content usage

https://www.suggestapi.com/robots.txt declares Content-Signal preferences:

- `ai-train=no`
- `search=yes`
- `ai-input=yes`

## Contact

- Email: help@suggestapi.com
- Book a meeting: https://meet.suggestapi.com/