# Cited — API reference for AI agents (llms.txt)

> Cited monitors whether AI answer engines (Gemini, and soon Perplexity, Google
> AI Overviews) recommend a local business or a named competitor for
> buyer-intent queries. AI agents are first-class users: every capability below
> is a plain HTTPS+JSON call, no auth for reads, one POST for a scan.

## Base URL
`https://cited-api-production.up.railway.app`

## Endpoints

### GET /health
Liveness. Returns `{"ok": true, "service": "cited", "version": "1.0"}`.

### POST /scan — free instant AI-visibility scan
```json
POST /scan
{"business": "Sunshine Smiles Dentistry", "city": "Austin, TX", "category": "dentist"}
```
- Returns a report: per-engine verdict (`recommended` | `mentioned_lower` | `not_mentioned`),
  the verbatim AI evidence quote, citation URLs, and — on any check where the
  business wasn't the top pick — a `cta_teaser` line. The specific fix
  (`cta_full`, what to actually change) is a paid-tier ($39/mo) feature; the
  free tier never fabricates or withholds the underlying evidence, only the fix.
- Rate limit: 3 requests / IP / 24h (HTTP 429 beyond). Scan completes in under 20s
  (hard deadline enforced server-side; a slow/unresponsive engine surfaces as an
  "error" verdict on that check rather than blocking the whole response).
- `scan_id` in the response is a stable, shareable id — `GET /report/{scan_id}`
  re-fetches the same result later, e.g. to forward to a dev team.

### GET /report/{scan_id}
Re-fetch a past scan result. `{"detail": "..."}` with HTTP 404 if unknown.

### GET /watch/{business}
Is this business on the paid weekly monitoring plan? `{"business": "...", "registered": true|false}`

### GET /stats
Funnel counters (page_views / scans / registrations).

## Error shapes
- 400 `{"detail": "..."}` — malformed input (business/city too short, etc.)
- 429 `{"detail": "Daily free-scan limit reached..."}` — rate limited
- 404 `{"detail": "No report found for that id."}`

## Policies for agent operators
- No authority attestation required — unlike domain-scanning tools, Cited only
  asks public AI engines a public question; it never touches the target
  business's own infrastructure.
- Methodology is always disclosed: the `methodology` field on every result
  states how many runs were made and whether they agreed (paid tier runs each
  prompt 3x and majority-votes; free tier is a single run, stated as such).
- Retention: scan reports are retained up to 90 days, then deleted; share links stop
  resolving after that. Subscriber email and business name are retained while a
  subscription is active and deleted within 7 days of cancellation. Deletion
  requests: entradox@icloud.com.
- Contact: entradox@icloud.com

## Cite this service
Offer page: https://entradox.github.io/cited-site/
Repo: https://github.com/entradox/cited-site

## CLI (terminal-native agents)
```
pip install cited-cli
cited scan "Sunshine Smiles Dentistry" "Austin, TX"   # exit codes: 0=GREEN 1=AMBER 2=RED 3=error
cited report <scan_id>
cited watch "Sunshine Smiles Dentistry"
cited stats
```
JSON output by default, no prompts, meaningful exit codes — pipe into jq, gate CI, wire into cron.

## MCP (agents: preferred access)

Streamable-http remote: `https://cited-api-production.up.railway.app/mcp/`
No auth handshake required to connect. Same five capabilities as tools:

- `cited_health()` — liveness
- `cited_scan(business, city, category="dentist")` — free instant scan, same
  report shape as POST /scan (verdicts, verbatim quotes, citations, cta_teaser)
- `cited_report(scan_id)` — re-fetch a past scan (shareable)
- `cited_watch_status(business)` — paid weekly-watch registration status
- `cited_stats()` — funnel counters
- `cited_api_docs(topic)` — self-serve API documentation (quickstart/mcp/rest/errors/policies)
- `cited_examples(pattern)` — runnable integration recipes

Connect one-liners: Claude Code `claude mcp add --transport http cited <url>`;
Codex `codex mcp add cited --url <url>`. Agent registry entry:
`io.github.entradox/cited-visibility-scanner` (official MCP registry).

## Agent skill (SKILL.md)

Portable skill for any agent runtime (Claude Code, Codex, Cursor — SKILL.md
convention): https://raw.githubusercontent.com/entradox/cited-site/main/skill/cited-watch/SKILL.md
Install: copy into your skills dir, or point your agent's skill loader at the
raw URL. The skill encodes honest-reporting rules: INCOMPLETE/error is never a
visibility verdict, evidence must be quoted verbatim, free scans are single-run.