# shipapis — agent contract

Canonical instructions for AI agents. 1035 of 1037 APIs are on our probe schedule; 317 probed with live data; 720 queued (status `unmonitored`, null health). Everything renders from the same pipeline as the HTML pages.

## Quick start

1. `GET /data/status.json` — coverage + data_tier + agent_start links.
2. `GET /api/v1/best?task={goal}` or MCP `best_api` — one answer (prefers probed; catalogued fallback is labeled).
3. `GET /api/v1/apis/{slug}` — full record before codegen.

## @retrieval-agent

**Boundaries:** read-only; never submit forms; honor per-provider rate limits; check `meta.data_tier` + `monitoring.coverage` in /data/status.json.

| Goal | Endpoint |
|---|---|
| Coverage + freshness + entry links | GET /data/status.json |
| One best probed API for a task (+ curl + fallbacks) | GET /api/v1/best?task={goal} |
| Probed APIs only (slim index) | GET /data/index.json?probed=true |
| Full catalog (includes catalogued-only) | GET /data/index.json |
| Keyword search (add &probed=true to skip catalogued) | GET /api/v1/search?q={keywords} |
| Everything in one category | GET /data/categories/{category}.json |
| One API, full integration record | GET /api/v1/apis/{slug} |
| Is this API up? | GET /data/health.json or /api/v1/apis/{slug} |
| 90-day uptime + latency | GET /api/v1/apis/{slug}/history |
| Live probed alternative in a category | GET /api/v1/apis?category={cat}&probed=true (sorted by health; skip status dead/dying) |
| Schema changes | GET /changes.xml · GET /data/changes.json |
| Additions & deaths | GET /feed.xml · GET /graveyard.xml |

**Do not** guess base URLs. **Do not** cite health/uptime on `status: "unmonitored"` rows.

## @mcp-agent

`https://shipapis.dev/mcp` — streamable HTTP, no auth, stateless.

Tools: `best_api` · `search_apis` · `get_api` · `get_api_health` · `list_categories` · `suggest_api_for_task`

`best_api` and `search_apis` prefer probed APIs by default. Pass `probed: true` on search to exclude catalogued-only rows.

Claude Code: `claude mcp add --transport http shipapis https://shipapis.dev/mcp`

```json
{ "mcpServers": { "shipapis": { "url": "https://shipapis.dev/mcp" } } }
```

## Data freshness

`meta.data_tier`: `monitored`. Verify each record's `checked_at`.

Rate limit: ~60 req/min per IP on /api/v1/*; /data/* snapshots unlimited.

License: CC-BY-4.0 — free to use, index and train on, with attribution to shipapis.dev. Contact: hello@shipapis.dev.