These docs are a work in progress and may not be fully up to date. Some pages may contain internal notes for our team.
Skip to Content

API — Finders

CRUD, analytics, and integration management for the central Finder resource. All endpoints require auth:api, auth_session, and audit middleware. Most responses are workspace-scoped via ?workspace_id=<id>.

Endpoints

GET /finders

List all finders in the active workspace.

Query params: workspace_id (required for workspace-scoped results)

Response 200: Array of finder objects.

GET /finders/{id}

Get a single finder by numeric ID.

Response 200: Finder object with settings, design config, and relations.

GET /finders/token/{token}

Get a finder by its public widget token (string). Used when the dashboard needs to look up a finder by the same token the widget uses.

POST /finders

Create a new finder. Automatically creates a paired Map with the same name.

Body: { name, workspace_id }

Response 201: Created finder object including the auto-generated token.

⚠️ Warning: Creating a finder via API does not invoke the V2 builder defaults — the design and settings columns will be empty until the first save from the builder. Use the dashboard to create finders in normal workflows.

PUT /finders/{id}

Update a finder’s name, design config, settings, locations, authorized URLs, and advanced refinements. This is the most-called write endpoint in the system — every builder save lands here.

Body:

{
  "name": "My Finder",
  "settings": [...],
  "advanced_refinements": [...],
  "authorized_urls": ["https://example.com"],
  "locations": [...]
}

The settings array contains flat key-value pairs that encode the V2 design config. advanced_refinements is an array of named rules. Location associations are replaced wholesale on each save.

Response 200: Updated finder.

DELETE /finders/{id}

Delete a finder and its paired map.

Response 204

GET /finders/{id}/analytics?days=30

Return view/click/search analytics for a finder.

Query params: days — lookback window (default 30, max 90)

Response 200: { views, clicks, searches, ... } aggregated over the window.

Integration endpoints

GET /finders/{finder}/integrations

List autocomplete provider integrations configured for this finder.

Response 200: Array of { provider, has_api_key } objects. API keys are never returned in plaintext.

PUT /finders/{finder}/integrations/{provider}

Upsert an API key for a provider (google, mapbox, here, radar, geoapify).

Body: { api_key } — stored AES-256-CBC encrypted.

Response 200: Updated integration.

DELETE /finders/{finder}/integrations/{provider}

Remove a provider integration and delete the stored key.

Publish (ext) endpoint

Publishing a finder (writing the CDN payload) is done via a separate ext endpoint:

POST /ext/finders/details/{token}/sync

See API — Ext for the full publish flow.

Concepts