> 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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.smaq.io/documentation/connections/custom-endpoint.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.