# API policy — Doctors Index Israel

Updated: 2026-09-25. Free public read-only API; no account or API key required.

## Versioning and deprecation
The /api/v1 route family supports legacy endpoints and the 2.0.0 response envelope on the newer endpoints. The envelope version is separate from the route family. Additive fields may appear; clients should ignore unknown fields. Breaking contract changes will use a new route family or explicitly versioned operation. Deprecations will be announced in /updates and this document with replacement routes and any planned removal date before removal. There is currently no scheduled sunset, so no Sunset or Deprecation response header is emitted.

## Pagination
Use limit between 1 and 100 (default 20) and offset (default 0). Continue until offset plus returned count reaches total. The search endpoint caps offset at 10,000; other paginated modern endpoints cap it at 100,000. IDs are stable within the supplied snapshots. Preserve filters across pages. A later dataset release may change ordering and totals; do not treat offset as a cross-release cursor. Counts across source layers are records, not deduplicated people.

## Retries and availability
Reads are safe to retry. Retry transient 5xx responses with exponential backoff and jitter. On a 429, honor Retry-After if supplied by the hosting layer. Do not retry validation errors unchanged. Cache reads using the response Cache-Control header and keep concurrency modest. No application-level request quota or availability SLA is currently promised; no invented rate-limit counters are emitted.

## Synchronous, read-only operations
REST GET and MCP tools retrieve data synchronously and do not mutate records. Idempotency-Key storage, background jobs, job polling and payment operations are not provided. The compare endpoint retrieves 2–4 records for factual comparison; it does not rank clinical quality.

## Data freshness
Registry snapshot: 2026-09-24. Enrichment snapshot: 2026-09-25. Documentation updates are not source refreshes. There is no scheduled refresh. Cross-source candidate links remain unverified.

[OpenAPI](/openapi.json) · [Agent instructions](/agents.md) · [Updates](/updates) · [Contact](/contact)