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

> Agent Watch monitors the agent economy's endpoints: liveness, latency,
> schema drift, auth posture, and price integrity for MCP servers and
> paid agent services. AI agents are first-class users: every capability
> below is a plain HTTPS+JSON call.

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

## Endpoints

### GET /health
Liveness. Returns `{"ok": true, "service": "agent-watch", "version": "0.1.0"}`.

### POST /v1/probe — probe an endpoint now
```json
POST /v1/probe
{"url": "https://example-server.com/mcp/"}
```
- Probes the endpoint: liveness (MCP handshake), latency (p50/p95),
  tool count, schema hash (drift detection), auth metadata (RFC 9728).
- Returns: `{"alive": true, "name": "...", "tool_count": N, "latency_p50_ms": ...,
  "tool_schema_hash": "...", "auth_metadata_present": bool}`
- Rate limit: applies to all requests.
- Timeout: 30s default (configurable via `timeout` field).

### GET /v1/endpoints
List all monitored endpoints: `{"count": N, "endpoints": [...]}`

### GET /v1/alerts
Dead/unresponsive endpoints: `{"status": "dead_endpoints", "count": N, "dead": [...]}` (first 500)

### GET /v1/census — registry liveness census
Full-census summary across the official MCP registry (7,454 endpoints probed
2026-09-07):
```json
{"seeded": true, "total": 7454, "alive": 2208, "dead": 4889, "unknown": 357,
 "pct_alive": 29.6, "pct_dead": 65.6, "pct_unknown": 4.8}
```
States: `alive` = MCP initialize handshake succeeded; `dead` = no answer on
initialize; `unknown` = answered but auth-gated (401/403/402) or redirecting —
liveness unprovable without credentials.

### GET /v1/grantwatch/audit — OAuth grant audit (POST)
```json
POST /v1/grantwatch/audit
{"tenant_id": "your-domain.com"}
```
Audits which third-party AI agents hold OAuth grants in a Google Workspace
tenant and whether granted scope matches usage. Requires the tenant to be in
the authorized list (403 otherwise). Findings only — no graded verdict.

### GET /v1/watch — customer watchlist status (auth required)
`GET /v1/watch?email=you@example.com&token=YOUR_WATCH_TOKEN`
Returns your plan, monitored count, and per-endpoint status. The watch_token
is issued at registration and delivered by email. Write via
`POST /v1/watch {email, urls}` with plan quotas (free 5 / builder 50 / team 500).

### GET /stats
Funnel counters: `{"monitored": N, "probes_run": N, "alive": N, "dead": N}`

## What Agent Watch does NOT do
- Does not sell, solicit, or negotiate insurance (that's QuoteOS, separate product)
- Does not provide real quotes or rates (sandbox data only)
- Not an insurance producer

## Contact
entradox@icloud.com

## Cite
- Registry listing: io.github.entradox/agent-watch (after publish)
- Perimeter Watch (sibling product): https://github.com/entradox/perimeter-watch-scanner