AAPI docs · REST, JSON and server-sent events

One request. Every answer with its evidence.

Send a listing and get back Is it safe? and Is it real?, each with the official record or buyer report behind it. The same API runs the website, the Chrome extension, the Android app and the WhatsApp bot.

Make your first call Browse 62 endpoints

Base URL: https://safeshelf-api-368488022657.asia-south1.run.app
Status: Checking…
Format: JSON in and out · investigations stream as SSE
Access: Public reads, no key · reviewer and developer keys for writes
Runs on: Cloud Run, Mumbai (asia-south1) · Gemini on Vertex AI

Your first call, in three steps.

Each step is a real request to the live API. Copy it into your terminal or app, or press Run to send it from this page.

How to read an answer.

Code picks the colour from the evidence; Gemini only explains it. Show the colour, then the reasons, then let people open the evidence behind each one.

The four answersverdict.overall, and safe and real on their own

red
Don't buy
An official recall of this exact model, or the listing is not real.
amber
Be careful
Buyer hazard reports under review, a recall abroad, or a safety mark that doesn't match the registry.
green
No problems found
In what was checked. Never a promise that a product is safe.
unknown
Can't tell yet
Not enough evidence. SafeShelf says so instead of guessing, and never shows grey as green.

Only an exact model match carries a recall. A look-alike's recall is never blamed on the wrong product.

Every reason points at its evidence

{
  "verdict": {
    "safe": "red", "real": "unknown", "overall": "red",
    "reasons": [{
      "text": "Recalled in Japan: this exact model is on an
               official recall list (CAA, 2026-10-05)",
      "evidence_ids": ["EV-3F9A…"]
    }]
  }
}

# then fetch the source, quote and date behind it
GET /v1/evidence?ids=EV-3F9A…

Every endpoint.

All 62 operations, built from the same OpenAPI contract the server loads. Examples are the contract's sample answers. Endpoints marked RUN are read-only, and you can call them live from here.

Loading the endpoint list…

Access, limits and errors.

The API is public so shoppers and judges can use it without signing up. Calls that use Gemini are rate-limited, so one caller can't use up the day for everyone.

Who can call whatSend keys in the X-API-Key header

Access	Covers
public	Checks, product records, recalls, sources, benchmarks. No key needed
reviewer key	Deciding findings, cases and identity labels. A person signs off every consequential call
developer key	Catalog scans, signed webhooks and your own usage (`ssk_…` tenant keys)
MCP and A2A	`/mcp` and `/a2a` are open on the hosted demo (A2A is rate-limited); a self-hosted server can require `X-API-Key`. See For agents

Limits and status codesEvery refusal has CORS headers and a reason in detail

Code	When
200	The answer. A `partial` outcome means a source was down; the answer says which
401	Missing or wrong `X-API-Key` on a keyed route
413	Body over 1 MB (9 MB for photo routes: chat, camera, incidents)
422	The body doesn't match the contract; `detail` names the field
429	Over 30 Gemini checks a minute per caller, or the daily cap. Honour `Retry-After`

Database reads (recalls, sources, timelines, benchmarks) don't count against the check limit. A listing checked in the last 10 minutes is answered from memory.

Investigations stream as they work.

POST /v1/agent/sessions/stream sends server-sent events, so your screen can show each step as it happens: page read, product matched, 12 countries' recall lists searched, reviews read, verdict.

openEVENT

The session started: its session_id and the plan of steps.

stepEVENT

One step finished: tool, what it found, time taken. Many per session.

verdictEVENT

The colours and reasons, as soon as code has decided them.

doneEVENT

The full result. Fetch every step's model, time and cost at /v1/investigations/{id}/trace.

Build on the evidence. Never on a guess.

Building an AI agent? Connect it over MCP or A2A with the same read-only tools.

Connect an agent Interactive OpenAPI