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 — Ext (widget-facing)

The /ext/ route group exposes the four endpoints the embeddable widget calls at runtime. These routes are not authenticated with JWT — the widget has no user session. Authorization uses the finder’s public token. See Integration points: External → Backend for the full protocol.

Unauthenticated widget endpoints

GET /ext/finders/details/{key}

The widget’s primary data fetch. Returns the full finder payload (design config, settings, location list, advanced refinements).

Params: key — finder token (public string, not numeric ID)

Headers checked: Origin or Referer against the finder’s authorized_urls list.

Response 200: Full finder payload JSON. Response is cached server-side for 60 seconds (Laravel Cache) to absorb widget spike traffic.

Response 403: Origin not in authorized_urls list (if restrictions are configured).

GET /mapping/autocomplete

Proxy for the autocomplete provider configured on the finder.

Query params: q (search text), finder_key, lat?, lng?, country?

Throttle: throttle:30,1 (30 requests per IP per minute)

The backend resolves the finder’s autocomplete provider via a 60-second server-side cache (provider slug only, not the API key). The key is decrypted fresh per request from FinderIntegration. Falls back to DropaSearch (Nominatim) if no provider is configured.

Response 200: { suggestions: [{ place_id, description }] }

GET /mapping/places

Fetch place details for a selected autocomplete result (coordinates, address components).

Query params: place_id, provider, finder_key

Throttle: throttle:30,1

Response 200: { lat, lng, address, ... }

POST /analytics

Capture widget events (views, searches, clicks, location selections).

Body: { finder_token, events: [{ type, ... }] }

This endpoint is unauthenticated and has no rate limit documented in routes.php. Events are stored in the analytics table.

Response 200: { received: N }

Authenticated ext endpoints (dashboard-only)

These routes require auth:api, auth_session, audit.

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

Publish a finder. Builds the full payload, computes a SHA-1 hash, uploads v/{hash}.json to R2, and overwrites the pointer file config.json. This is the endpoint the V2 builder calls on “Publish”.

Params: key — finder token

Response 200: { hash } — the new payload hash.

GET /ext/finders/details/{key}/info

Return metadata about the current published payload (hash, last_synced_at).

DELETE /ext/finders/details/{key}

Delete the finder’s CDN payload (pointer + versioned file). Used during finder deletion.

Concepts