API reference
v1 REST API
The FindDoc v1 API exposes the same clinic and specialist directory that powers the map. Requests are stateless, authenticated with a Bearer token, and respond with JSON. All endpoints live under https://finddoc-ten.vercel.app/api/v1.
Overview
Base URL
Every endpoint in this reference is rooted at the URL below. The path examples (e.g. /clinics) are relative.
https://finddoc-ten.vercel.app/api/v1Overview
Authentication
Send your API key as a Bearer token on every request. Keys are issued and revoked from the API keys page; keep them out of source control.
Authorization: Bearer fd_test_xxxx…Missing or invalid keys return 401 unauthorized.
Overview
RapidAPI access
If you reach this API through the RapidAPI marketplace, you do not need a FindDoc account or an Authorization header — RapidAPI injects the credentials its proxy needs on every call, and FindDoc authenticates the request from those. Subscribe to the plan on RapidAPI and call the endpoints below with your RapidAPI key as documented there. Direct (non-RapidAPI) consumers still use a Bearer token exactly as described above.
Overview
Rate limits
Each key gets a sliding 60-second window. Basic keys allow 100 requests per minute; enterprise keys allow 1,000. The response carries X-RateLimit-* headers on every call.
| Header | Meaning |
|---|---|
| X-RateLimit-Limit | Total requests allowed in the current 60-second window. |
| X-RateLimit-Remaining | Requests remaining before throttling kicks in. |
| X-RateLimit-Reset | Unix timestamp (seconds) when the window resets. |
Overview
Errors
Errors come back as JSON with a stable error code. Treat the code as the contract, not the human-readable message.
{
"error": "rate_limit_exceeded",
"limit": 100,
"remaining": 0,
"reset": 1715890800
}| Status | Error code | When |
|---|---|---|
| 400 | missing_param | A required query parameter is missing — specialty on /specialists, or q on /doctors/search. |
| 401 | unauthorized | Bearer token missing, malformed, or the key has been revoked. |
| 404 | not_found | The requested doctor (cpso) or clinic (id) does not exist. Returned by the detail and reviews endpoints. |
| 429 | rate_limit_exceeded | Per-key rate limit exceeded. Inspect X-RateLimit-* headers for the window. |
| 500 | internal_server_error | Unexpected server error. Safe to retry with backoff. |
Reference
Endpoints
Every v1 endpoint, grouped by resource. Each opens its own page with stripe-style samples, a parameter table, and a live request runner.
Doctors
Clinics
Specialists