Wherebox
Get API key

Generated from code

On this page

HTTP: endpoints, auth parameters and headers

The endpoints of the server, and the request parameters and headers outside the map description: authentication, URL signatures, caching and limits. Entries marked keys apply only when the server runs with API keys (WHEREBOX_AUTH=keys, the hosted service).

Endpoints#

Every GET endpoint also answers HEAD. Parameters and responses of the map and lookup endpoints are in openapi.json. The hosted service also serves the account console (sign-in, API keys, usage), which is a website, not an API.

Endpoint What it does SDK method (TypeScript / Python)
GET /v1/map Render a map from query parameters Same as /v1/map.{ext}; the SDKs' url always writes the format as the extension.
GET /v1/map.{ext} Render a map; the extension picks the format url / url (builds the URL)
POST /v1/map Render a map from a JSON MapSpec render / render
renderJson / render_json (response=json)
GET /v1/images/{key} Fetch a cached image by content hash The url that renderJson returns: a public, immutable link for <img> or any HTTP client.
GET /v1/areas/search Search areas by name (with hierarchy context for disambiguation) searchAreas / search_areas
GET /v1/areas/{id} Get one area getArea / get_area
GET /v1/places/search Search named places (cities, peaks, mountain ranges…) searchPlaces / search_places
GET, POST, DELETE /mcp MCP server (Streamable HTTP) for AI agents: render maps, search areas and places Spoken by MCP clients (Claude, @wherebox/mcp), not by the REST SDKs.
GET /openapi.json OpenAPI 3.1 document of this API For tools and code generators.
GET /playground Interactive playground (a redirect to the website's playground when a site URL is configured) Browser page.
GET / Redirects to /playground Browser entry point.
GET /healthz Liveness check For load balancers and orchestrators.
GET /readyz Readiness: database reachable, data and render versions, render queue For load balancers and orchestrators.
GET /metrics Prometheus metrics (disabled unless a metrics token is configured) For the operator's monitoring.
GET /.well-known/oauth-authorization-server OAuth authorization server metadata (RFC 8414) For OAuth clients (connected apps, MCP); the SDKs authenticate with keys.
GET /.well-known/oauth-protected-resource/mcp Protected resource metadata of /mcp (RFC 9728) For OAuth clients (connected apps, MCP); the SDKs authenticate with keys.
GET /.well-known/oauth-protected-resource/v1 Protected resource metadata of /v1 (RFC 9728) For OAuth clients (connected apps, MCP); the SDKs authenticate with keys.
POST, OPTIONS /oauth/register Dynamic client registration (RFC 7591) For OAuth clients (connected apps, MCP); the SDKs authenticate with keys.
GET, POST /oauth/authorize Consent page; the POST records the user's decision For OAuth clients (connected apps, MCP); the SDKs authenticate with keys.
POST, OPTIONS /oauth/token Token endpoint (authorization code with PKCE, refresh token) For OAuth clients (connected apps, MCP); the SDKs authenticate with keys.
POST, OPTIONS /oauth/revoke Token revocation (RFC 7009) For OAuth clients (connected apps, MCP); the SDKs authenticate with keys.

Query parameters#

Accepted on every /v1/map request in addition to the map parameters.

Parameter Description Example
apikey Publishable key (pk_…) for <img> embeds. Only valid together with sig. Secret keys (sk_…) are rejected in URLs. apikey=pk_8fK2aQ1mZr9TbL0x4WcYvN3sHd7uJe6p
sig URL signature: HMAC-SHA256 of the canonical request with the key's signing secret (see the signing guide). Proves the URL was created by the key owner, so a leaked pk_ cannot be reused for other maps. sig=Jx3w0b2kQnVt9yRmZsLc4u8hAe1pDfGo
exp Optional expiry of a signed URL (Unix seconds). Covered by the signature. exp=1798761600

Request headers#

Header Description Example
Authorization keys Secret key for server-to-server calls (Bearer sk_…), or an OAuth access token from a connected app (Bearer wba_…). Bearer sk_…
X-Provider-Key Key for a commercial basemap style (style=); kept out of URLs and logs. your-maptiler-key
X-Routing-Key Key for openrouteservice / GraphHopper routing; kept out of URLs and logs. your-ors-key
X-Request-Id Optional id for this request (letters, digits, ._:-, ≤ 64 chars), e.g. from your proxy; otherwise the server generates one. 3f2c9a1e-…
If-None-Match Send a previous ETag to get 304 Not Modified when the image is unchanged. "e1b4…png"

Response headers#

Header Description Example
ETag Content hash of the image (also its cache key). SDKs: etag / etag of the render result. "e1b4d02…7b6.png"
Cache-Control Rendered maps may be cached for a day; /v1/images/{key} is immutable. public, max-age=86400
X-Cache HIT when served from the image cache, MISS when rendered for this request. SDKs: cached / cached of the render result. HIT
X-Render-Ms Render time in milliseconds (on a MISS). 212
X-Image-Width Final pixel width. Can exceed w × scale when neighborfit=extend grew the image. SDKs: width / width of the render result. 556
X-Image-Height Final pixel height. SDKs: height / height of the render result. 296
Retry-After Seconds to wait after a 503 busy or 429 response. 2
X-RateLimit-Limit keys Requests per minute allowed for this key's plan (without a key: the anonymous demo allowance, per client network). 120
X-RateLimit-Remaining keys Requests left in the current window. 117
X-RateLimit-Reset keys Unix seconds when the window is full again. 1798761660
WWW-Authenticate keys On 401 when OAuth is enabled: where OAuth clients find the authorization server (RFC 9728), with error="invalid_token" when a presented access token was rejected (expired, revoked, or issued for another resource). Bearer resource_metadata="https://app.wherebox.dev/.well-known/oauth-protected-resource/v1"
X-Quota-Remaining keys Renders left this calendar month (UTC). Cache hits do not count. Without a key (anonymous demo allowance): renders left today (UTC) for your network, or for all anonymous visitors together when that is lower. 24120
X-Request-Id Id of this request; also in every error body as requestId and in the server logs. Quote it in support requests. 3f2c9a1e-7b1d-4c0e-9a55-0d2f6e8b1c44
X-Attribution The data credits for this image, as drawn in its corner (items joined with " · "). Always sent, also with attribution=none, when you must show this text next to the image yourself. HTTP headers are ASCII, so % and every character outside printable ASCII are percent-encoded as UTF-8 (© is %C2%A9): decode with decodeURIComponent (JavaScript) or urllib.parse.unquote (Python). SDKs: attribution / attribution of the render result. OpenFreeMap %C2%B7 %C2%A9 OpenStreetMap
Access-Control-Allow-Origin CORS: images and JSON can be fetched from any origin. *
Access-Control-Expose-Headers CORS: lets browser code read these headers on a cross-origin fetch (X-Attribution in particular). X-Attribution, X-Cache, X-Image-Width, X-Image-Height, X-Request-Id