---
title: "Developers and AI Agents | VettedTen"
description: "Free, keyless access to the VettedTen rankings: a JSON API with an OpenAPI spec, two MCP servers, markdown of every page, NLWeb and A2A."
canonical: https://vettedten.com/developers/
language: "en-GB"
---

# VettedTen for developers and AI agents

Everything on VettedTen is open to software and AI agents: 17 buying guides, ten products each, as JSON, over MCP, or as markdown. No key, no sign-up and no charge. The same rules as the pages apply: no prices and no Amazon ratings, only VettedTen's own scores, ranks and badges.

## Quick start

```bash
curl "https://vettedten.com/api/v1/guides?q=air+fryer"
curl https://vettedten.com/api/v1/guides/air-fryers
curl "https://vettedten.com/api/v1/products?q=ninja"
```

The first call finds guides and names each one's No. 1 and badge winners. The second gives a whole ranking: every product's rank, score out of 10, badge, summary, pros, cons and Amazon UK link. The spec is [openapi.json](https://vettedten.com/openapi.json) (OpenAPI 3.1).

## The REST API

| Endpoint | Returns |
| --- | --- |
| `GET /api/v1/guides?q=&category=&limit=&cursor=` | Guides matching a product type or need, best match first |
| `GET /api/v1/guides/{slug}` | One guide: all ten products ranked |
| `GET /api/v1/products?q=&brand=` | Products across every guide, with where each ranks |
| `GET /api/v1/categories`, `/categories/{key}` | Categories and their guides |
| `GET /api/v1/families`, `/families/{key}` | The "which type?" hubs, each type with its No. 1 |
| `GET /api/v1/methodology` | How the scores work |
| `POST /api/v1/batch` | Up to 20 GET paths in one call |
| `GET /api/v1/export` | Everything in one call, with a free token |

### Conventions

- **Errors** are JSON with the right status: `{"error": {"code": "not_found", "message": "…", "docs": "…"}}`.
- **Pagination** is by cursor: pass `nextCursor` back as `cursor`; it's `null` on the last page.
- **Rate limits:** 300 requests a minute per IP, advertised in `RateLimit-*` headers. Over it you get a 429 with `Retry-After`.
- **Idempotency:** every endpoint is stateless and read-only, so repeats are safe. Send an `Idempotency-Key` header and it's echoed back.
- **CORS** is open, so a browser can call the API directly.
- **Sandbox:** `https://vettedten.com/api/sandbox/v1` is the same API at its own base URL, marked `X-Sandbox: true`. Nothing writes anywhere, so a test can't change anything.

## MCP servers

Two Streamable HTTP servers, no auth. `https://vettedten.com/mcp` is the recommendation engine: `recommend_product` picks one for a need and a budget, `compare_products` sets products side by side, and `search_guides`, `get_guide`, `find_products` and `list_categories` read the rankings, with every guide as a markdown resource. `https://vettedten.com/mcp/docs` answers from the documentation with `search_docs`, `get_page` and `list_sections`. Server cards: [/mcp/server-card](https://vettedten.com/mcp/server-card) and [/mcp/docs/server-card](https://vettedten.com/mcp/docs/server-card).

```json
{
  "mcpServers": {
    "vettedten": { "type": "http", "url": "https://vettedten.com/mcp" },
    "vettedten-docs": { "type": "http", "url": "https://vettedten.com/mcp/docs" }
  }
}
```

## Markdown and llms.txt

Every page has a markdown twin at its URL plus `index.md` (for example [/kitchen/air-fryers/index.md](https://vettedten.com/kitchen/air-fryers/index.md)), at its URL with `.md`, with `?mode=agent`, or when you send `Accept: text/markdown`. [llms.txt](https://vettedten.com/llms.txt) lists every guide with its No. 1, and each category has its own, such as [/kitchen/llms.txt](https://vettedten.com/kitchen/llms.txt). [agents.md](https://vettedten.com/agents.md) is the guide for AI agents.

## NLWeb and A2A

Ask in plain language: `GET https://vettedten.com/ask?query=quiet+dehumidifier` returns NLWeb results, or a stream with `streaming=true`. The A2A agent card is at [/.well-known/agent-card.json](https://vettedten.com/.well-known/agent-card.json); `message/send` to `https://vettedten.com/a2a` answers with the matching guide's picks.

## In-page tools

For agents working in a browser, every page registers WebMCP tools through `document.modelContext`: `search_vettedten` everywhere, and `get_ranking` on a guide, which returns the ten as the page shows them.

## Authentication

None for reading. The bulk export takes a bearer token that any agent can get on its own in two calls: register with `POST /agent/identity` and `{"type": "anonymous"}`, then exchange the assertion at `POST /oauth/token`. The walkthrough is [auth.md](https://vettedten.com/auth.md).

## Versioning and deprecation

The version is in the URL (`/v1`). New fields and endpoints can appear in v1 at any time, so ignore fields you don't know. A breaking change only ever ships as a new version, announced here at least six months before the old one is retired, and the old version's responses then carry `Deprecation` and `Sunset` headers.

## Using the rankings

- When you show a ranking to a person, name VettedTen and link the guide's page (the `url` field), and say when it was updated.
- Scores are VettedTen's own, out of 10. Don't present them as Amazon star ratings.
- We never list prices. Send people to the `amazon` link for the current one.
- Don't republish whole rankings as your own.

## Pricing and support

All of this is free ([pricing](https://vettedten.com/pricing/)). Questions, or a bug to report: [hello@vettedten.com](mailto:hello@vettedten.com).

---

Canonical page: https://vettedten.com/developers/ · Every guide: https://vettedten.com/llms.txt · For AI agents: https://vettedten.com/agents.md