# API Reference

REST API v1 is the programmatic contract for authenticated clients. Discovery is public; search routes need a key. Every response includes a `_meta` provenance block.

## Base URL

`https://indieterminal.com/api/v1`

## Authentication

`Authorization: Bearer it_live_…`

**Connector keys** (Slack, Notion, HubSpot, Zapier, Airtable, OpenAI BYOK) live at /connectors — not for REST.

**REST index keys** (Pro Analyst+): while logged in, `POST /api/developer/keys` with optional label. Key shown once. Free Scout returns 403.

## Discovery

`GET /api/v1` — public, no auth. Returns endpoint list, rate limits, and schema.

## Rate limits

| Plan | Requests/day | Keys |
|------|--------------|------|
| Free Scout | No API access | 0 |
| Pro Analyst | 200 | 2 |
| Elite Operator | 2,000 | 5 |
| Growth Engine | 50,000 | 20 |

## Endpoints

- GET /api/v1 — public discovery (endpoints, rate limits, auth notes)
- GET /api/v1/startups/search — search by keyword, category, MRR range (`q` required, min 2 chars)
- GET /api/v1/startups/:slug — startup profile + category context
- GET /api/v1/categories — category benchmarks
- GET /api/v1/signals — market signals feed
- POST /api/v1/compare — deterministic comp aggregation (2–5 slugs)

## Errors

Responses use RFC 9457 `application/problem+json` with a stable `code`, `title`, `detail`, and `hint`. The JSON also includes `error` (same as `code`) for older clients.

| Status | Code | When |
|--------|------|------|
| 400 | QUERY_TOO_SHORT, INVALID_PAYLOAD, NEED_AT_LEAST_TWO_SLUGS, SLUG_REQUIRED | Bad input |
| 401 | MISSING_API_KEY, INVALID_API_KEY, KEY_REVOKED | Auth |
| 403 | PLAN_UPGRADE_REQUIRED | Live keys need Pro+ |
| 404 | NOT_FOUND | Unknown slug or unknown `/api/*` path |
| 429 | RATE_LIMIT_EXCEEDED | Daily quota; honor `Retry-After` |
| 500 | QUERY_FAILED | Retry with backoff |

## Versioning {#versioning}

Current major version is URL path `/api/v1`. Breaking changes require `/api/v2`. Optional request header `API-Version: v1` pins the major. Deprecations are announced with RFC 9745 `Deprecation` and `Sunset` headers at least 90 days before removal.

## OpenAPI and CLI

- OpenAPI 3.0: https://indieterminal.com/openapi.json
- RFC 9727 catalog: https://indieterminal.com/.well-known/api-catalog
- Developers: https://indieterminal.com/developers
- Official CLI: `npx indie-terminal` — https://indieterminal.com/cli

## Rate limits

IETF `RateLimit` / `RateLimit-Policy` structured fields plus `X-RateLimit-*`. HTTP 429 also sends `Retry-After`.

## Provenance

Every response includes `_meta` with api_version, as_of, live universe_size, methodology. MRR is estimated unless marked verified.

MCP adapter coming — same auth + schema as REST.