> For the complete documentation index, see [llms.txt](https://mcp.10ml.com/llms.txt). Every page is also served as Markdown at its URL plus .md.

# REST API

> 8 GET routes of the free perfume API, no key.

Plain GET requests with JSON answers, no key and no sign-in. Base [https://mcp.10ml.com/api/v1](https://mcp.10ml.com/api/v1). Each route returns the same answer as the matching MCP tool; query parameters are the tool parameters. Add `format=detailed` for the long form.

## Routes

- `GET /api/v1/perfumes`: Search perfumes (the search_perfumes tool; q for query)
- `GET /api/v1/perfumes/{id}`: Get one perfume (the get_perfume tool)
- `GET /api/v1/similar`: Find similar perfumes (the find_similar_perfumes tool)
- `GET /api/v1/alternatives`: Find alternatives to a perfume from other houses (the find_perfume_alternatives tool)
- `GET /api/v1/notes/{id}`: Explain a note (the explain_note tool)
- `GET /api/v1/houses`: List perfume houses (the list_houses tool)
- `GET /api/v1/houses/{id}`: Get one perfume house (the get_house tool)
- `GET /api/v1/guides`: Search 10ML guides (the search_guides tool; q for query)

## Examples

- `GET https://mcp.10ml.com/api/v1/perfumes?q=fresh+citrus+summer&gender=men`

- `GET https://mcp.10ml.com/api/v1/alternatives?perfume=Creed+Aventus`

- `GET https://mcp.10ml.com/api/v1/similar?perfume=Baccarat+Rouge+540&steer=fresher`

- `GET https://mcp.10ml.com/api/v1/notes/vanilla`

## Machine-readable descriptions

OpenAPI 3.1 as JSON: https://mcp.10ml.com/openapi.json. As YAML: https://mcp.10ml.com/openapi.yaml. Server card: https://mcp.10ml.com/.well-known/mcp/server-card.json. Index of these pages: [llms.txt](https://mcp.10ml.com/llms.txt).