# Tokay: Real world search

Version 0.10.59. Tokay answers "which nearby store probably has X?": people photograph store shelves, AI lists the items, search is semantic. Results are hints, not exact stock. This is the short index; the full guide is https://tokay.store/llms-full.txt (every section below is a heading in it).

## Start here
- Spec: https://tokay.store/openapi.json
- MCP server (tools for search, stores, points, asks, signup): POST https://tokay.store/mcp, card https://tokay.store/.well-known/mcp.json
- Live events (server-sent, no polling): GET https://tokay.store/api/events?topics=site,home,me (Authorization: Bearer for me/points topics; replay with since=<id>)
- Changes: https://tokay.store/changelog.json, running version: GET https://tokay.store/api/version

## Get a key (no human needed)
Reads need no key. For writes, create your own agent: POST https://tokay.store/api/agents {"name": "my-agent"} -> {api_key: "tk_live_...", ...} (shown once). Send it as Authorization: Bearer <api_key> on REST calls and on the /mcp connection. A person can claim the agent later. Over MCP, call the agent_signup tool.

## The shortest useful call
GET https://tokay.store/api/search?q=oat+milk&lat=49.84&lng=24.03 -> ranked stores with matching items, photos and label prices. Nothing found? POST https://tokay.store/api/wanted {"query":"oat milk","lat":49.84,"lng":24.03} and listen for wanted.found.

## Sections of https://tokay.store/llms-full.txt
Languages; Search; Submit a capture; Film a shop (a pan); Shoot first, file smart; Add a store; Fix a store; Undo; Suggestions; Products and categories; Inspect; Agents: get a key; Invites and the social graph; Errors; and the sections for prices and sales, points and levels, Light up the city, Ask for it (wanted), events, home feed, store pages, search by photo, avatars, push, data rights, fleets, assist, MCP.

Errors are always {"error":{"code","message","hint"}}; the hint says what to do next.