> ## Documentation Index
> Fetch the complete documentation index at: https://docs.summation.com/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

> Connect Summation to JSON REST APIs using OAuth2, Basic auth, custom headers, or no authentication.

The REST API connector lets Summation query JSON data from an HTTP endpoint. It supports request bodies, pagination, and common API authentication patterns, including both OAuth2 grants — refresh-token and client-credentials — for APIs such as NetSuite SuiteQL.

## What you'll need

* A public **base URL** for the API, for example `https://td3084888.suitetalk.api.netsuite.com`.
* The authentication details required by the API:
  * OAuth2 credentials: either a refresh token, or a client ID and secret for the client-credentials grant.
  * Basic auth username and password.
  * A custom header value, such as an API key or bearer token.
  * No authentication, if the endpoint is public.
* The request path and JSON request body for each dataset you want to expose.

<Note>
  HTTP endpoints must resolve to public IP addresses. Localhost, private network hosts, and internal domains are rejected. Authenticated connections should use `https://` URLs.
</Note>

## Form fields

| Field              | Required | Stored as | Notes                                                                                                    |
| ------------------ | -------- | --------- | -------------------------------------------------------------------------------------------------------- |
| **Base URL**       | Yes      | Config    | The API origin and optional base path. Do not include query parameters or fragments.                     |
| **Authentication** | Yes      | Config    | Choose **OAuth2 (Refresh Token)**, **OAuth2 (Client Credentials)**, **Basic**, **Headers**, or **None**. |

### OAuth2

The connector supports two OAuth2 grants. Pick the one your API uses:

* **OAuth2 (Refresh Token)** — Summation exchanges a stored refresh token for short-lived access tokens.
* **OAuth2 (Client Credentials)** — Summation requests access tokens directly with a client ID and secret, with no refresh token.

Both grants share these fields:

| Field                 | Required | Stored as | Notes                                                                                                                                                                         |
| --------------------- | -------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Token URL**         | Yes      | Config    | OAuth2 token endpoint. Must use `https://`.                                                                                                                                   |
| **Client ID**         | Yes      | Secret    | OAuth client ID.                                                                                                                                                              |
| **Client Secret**     | Yes      | Secret    | OAuth client secret.                                                                                                                                                          |
| **OAuth Client Auth** | Optional | Config    | How the client credentials reach the token endpoint. **Body** (default) sends `client_id` and `client_secret` in the form body; **Basic** sends them as an HTTP Basic header. |
| **Scopes**            | Optional | Config    | Space-separated OAuth scopes, for example `rest_webservices`. Leave blank to use the scopes bound server-side.                                                                |

The **Refresh Token** grant adds these fields (they do not apply to the client-credentials grant):

| Field                   | Required | Stored as | Notes                                                                                                                             |
| ----------------------- | -------- | --------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Refresh Token**       | Yes      | Secret    | OAuth refresh token used to obtain short-lived access tokens.                                                                     |
| **Prefer Header**       | Optional | Config    | Sent as a `Prefer` request header. Prefilled with `transient` (common for NetSuite SuiteQL); clear it to send no `Prefer` header. |
| **Content-Type Header** | Optional | Config    | Sent as a `Content-Type` request header. Prefilled with `application/json`; clear it to send no `Content-Type` header.            |

### Basic auth

Use **Basic** when the API expects an HTTP Basic `Authorization` header.

| Field        | Required | Stored as | Notes                                                       |
| ------------ | -------- | --------- | ----------------------------------------------------------- |
| **Username** | Yes      | Config    | API username. Usernames cannot contain colons or new lines. |
| **Password** | Yes      | Secret    | API password.                                               |

### Custom headers

Use **Headers** when the API authenticates with one or more request headers, such as `Authorization: Bearer ...` or `x-api-key: ...`.

| Field            | Required | Stored as | Notes                                               |
| ---------------- | -------- | --------- | --------------------------------------------------- |
| **Header Name**  | Yes      | Config    | Header names must use valid HTTP header characters. |
| **Header Value** | Yes      | Secret    | Header values are stored as secrets.                |

### No authentication

Use **None** only for public endpoints that do not require credentials or API keys.

## OAuth behavior

When you test or use the connection, Summation obtains an access token from the token URL — exchanging the refresh token (Refresh Token grant) or the client credentials (Client Credentials grant) — and then sends `Authorization: Bearer <access_token>` with API requests. Access tokens are refreshed automatically before they expire.

Token endpoints that redirect are not supported. A `400`, `401`, or `403` from the token endpoint usually means the OAuth credentials, refresh token, or client-auth mode are wrong.

## Basic auth behavior

For Basic auth, Summation combines the username and password and sends them as an HTTP Basic `Authorization` header on connection tests and dataset requests.

## Custom header behavior

For custom header auth, Summation sends the configured headers on connection tests and dataset requests. Use this mode for bearer tokens, API keys, or APIs that require a non-standard auth header.

## Adding datasets

Each dataset maps to one request path under the base URL. The connector sends JSON requests and expects a JSON response.

| Field                       | Required | Notes                                                                                                                               |
| --------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Dataset Name**            | Yes      | The table name Summation will expose. Must be unique in your tenant.                                                                |
| **Request Path**            | Yes      | Path appended to **Base URL**, for example `/services/rest/query/v1/suiteql`. Must start with `/`.                                  |
| **Request Body**            | Optional | JSON body template sent to the API. Use `${column_name}` placeholders if the request body should be parameterized by query filters. |
| **Response Data Pointer**   | Optional | JSON pointer to the array of rows in the response, for example `/items`.                                                            |
| **Page Size**               | Optional | Number of rows requested per page.                                                                                                  |
| **Pagination Query Params** | Optional | Query string template for pagination, for example `limit={limit}&offset={offset}`.                                                  |

For a NetSuite SuiteQL dataset, use a request path like:

```text theme={null}
/services/rest/query/v1/suiteql
```

and a request body like:

```json theme={null}
{
  "q": "SELECT id, tranid, trandate FROM transaction WHERE rownum <= 1000"
}
```

With a base URL of `https://td3084888.suitetalk.api.netsuite.com`, the dataset source becomes:

```text theme={null}
https://td3084888.suitetalk.api.netsuite.com/services/rest/query/v1/suiteql
```

Source references use the resolved request URL:

```text theme={null}
https://api.example.com/path/to/resource
```

## Common problems

| Error or symptom                                                | Likely cause                                                                                                                                   |
| --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `http_base_url host must resolve to a public IP address`        | The base URL points to localhost, a private network, or an internal DNS name. Use a public API endpoint.                                       |
| `auth_token_url must be a fully-qualified https:// URL`         | The token URL is missing `https://` or uses plaintext HTTP.                                                                                    |
| `http_username is required for Basic auth`                      | **Authentication** is set to **Basic**, but the username is empty.                                                                             |
| `http_password secret is required for Basic auth`               | **Authentication** is set to **Basic**, but the password is empty or not stored.                                                               |
| `http_headers must include at least one header for Header auth` | **Authentication** is set to **Headers**, but no custom header is configured.                                                                  |
| `HTTP OAuth token exchange failed`                              | OAuth client credentials, refresh token, scopes, or **OAuth Client Auth** mode are wrong.                                                      |
| `HTTP OAuth token endpoint response is missing access_token`    | The token endpoint returned JSON, but not an OAuth access-token response. Check the token URL and grant type.                                  |
| `HTTP connection test failed`                                   | The base URL is not reachable, the endpoint rejected the configured auth, or the API requires a dataset-specific path for successful requests. |
| Empty dataset                                                   | **Response Data Pointer** does not point to the array in the JSON response, or the request body query returned no rows.                        |