> For the complete documentation index, see [llms.txt](https://docs.smaq.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.smaq.io/documentation/connections/custom-endpoint.md).

# Custom endpoint

If a platform you use isn't natively supported, you can connect to it via its REST/JSON API using the Custom endpoint builder.

### What you'll need

* The endpoint URL (must return JSON).
* The auth method:
  * **None** (public endpoints)
  * **API key in header** (e.g. `Authorization: Bearer xxx`)
  * **API key in query string** (e.g. `?api_key=xxx`)
* Optional: query parameters, pagination scheme, and JSONPath expressions to extract the data SMAQ should treat as rows.

### Steps to connect

1. **Data Source → Add data source**.
2. Pick **Custom endpoint**.
3. Fill in:
   * **Endpoint URL** — full URL including any path.
   * **Method** — usually GET.
   * **Headers** — add `Authorization`, `Accept`, etc. as needed.
   * **Query parameters** — add any required params (date ranges, pagination cursors).
4. Click **Test** to fetch a sample response.
5. In the **Response mapping** section, set the **JSONPath** that points to the array of rows (e.g. `$.data.results`).
6. SMAQ auto-detects fields. Optionally rename or change types.
7. Name and click **Save**.

> **\[Screen video needed]** Connect to a public weather API as an example — paste URL, hit Test, set JSONPath, see rows appear. \~90 seconds.

> **\[Screenshot needed]** Response mapping section with auto-detected fields visible and one field's type being changed.

### Tips

* **Test before saving.** The Test button shows the raw response — confirms auth works and reveals the JSON shape.
* **Date columns**: tag them as Date type so SMAQ can filter and aggregate by date.
* **Pagination**: if the API uses cursors or `?page=N` style pagination, SMAQ can iterate — set the pagination params during connection.

### Limitations

* SMAQ doesn't support endpoints that need OAuth (use a native integration instead, or pre-fetch with a server-side proxy).
* No write-back. Custom endpoints are read-only like every other connection.
* Heavy paginated fetches (1000+ pages) may time out — break the date range smaller, or pull through a staging table.

### Use cases

* Internal sales CRM you've built in-house
* Niche ad networks (e.g. retail media platforms without an OAuth API)
* SEO tools (Ahrefs/SEMrush) — connect their API endpoints directly
* Inventory systems, helpdesks, anything with a documented JSON API