> For the complete documentation index, see [llms.txt](https://docs.rootcause.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rootcause.ai/data-sources-and-connectors/connectors/rest-api.md). # REST API Connect RootCause to any REST API. Paste a spec and the connector configures itself; APIs without a spec are configured manually. *** ### Setting up the connection 1. In the Import Manager, click the **REST API** card and name the connection 2. Paste a URL into **API URL** and click **Parse** You can paste an OpenAPI, Swagger, Google Discovery, OData or CKAN URL, or any working data URL, and RootCause works out the base URL, authentication, endpoints, pagination and where the records live. Review the detected base URL and the endpoint count, then test a real request under **Verify**. The picker there offers the detected GET endpoints, minus the authentication ones: login, logout, sign-in, sign-out, sign-up, session, OAuth and token paths. The record count, row picker and preview appear once the request succeeds; a failed test shows only its error.
REST API connection after parsing an OpenAPI spec

A parsed OpenAPI spec: detected version, endpoints, auth scheme and base URL.

If the API has no spec, click **No spec? Configure manually**: | Field | Description | | ----------------------- | ------------------------------------------------------------------ | | Base URL | Base API endpoint, for example `https://api.example.com` | | Authentication Type | None, API Key, Bearer Token, Basic Auth or OAuth 2.0 | | API Key Name / Location | For API Key auth: the header or query parameter name to send it in | | Access token | For Bearer Token: sent as an Authorization: Bearer header | | Username / Password | For Basic Auth | *** ### Connecting an OAuth 2.0 API Choosing **OAuth 2.0**, or parsing a spec that declares it, replaces the credential fields with the OAuth connection panel. There is no token to paste. 1. Pick the **OAuth app**: the registration your organisation holds with the API provider. 2. Click **Connect**. The connection is saved first, then the provider's consent screen opens in a new window; allow pop-ups for the site if it is blocked. An app registered for machine access connects without a consent screen. 3. **Account connected** then names the account, the app and the granted scopes. **Reconnect**, **Disconnect** and **Refresh status** manage it from there. Access is renewed automatically while tests, previews, imports and direct queries run, so a connected account keeps working without intervention. Apps are registered once per organisation under [Organisation settings](/more-details/organisation-administration.md#oauth-apps), with ready-made profiles for Google Analytics 4, HubSpot, Ramp, Ramp sandbox, Salesforce and Google Drive, and **Custom API** for everything else. **Add app** in the panel registers one without leaving the connection, if you have write access to organisation settings; otherwise the panel asks you to request one from an administrator. *** ### Importing data Pick an endpoint, set its parameters, and preview the response. With a parsed spec, the endpoint's own **Parameters** grid is where query parameters are set; without a spec, the import step has a free-form **Query parameters** editor instead. Either way the values are merged over any defaults the connection carries under **Defaults for every request**, with the import's own values winning where names clash. The connector detects where the records array lives and how the API paginates (page numbers, offsets, cursors or a next URL) and follows it to a configurable page cap. Under **Next URL**, leave **Next URL JSON path** empty to follow the HTTP `Link` header, or point it at the response field carrying the next page's URL; where the API signals the last page with a boolean rather than by omitting the link, name that field in **Completion flag JSON path**. Imports can also be incremental, using a watermark field to append only new records on each sync. The REST connector has no import-mode picker; scheduling is configured on the import itself, and endpoints bound to time or entity parameters can be read on demand, fetching just what a query needs. *** ### Provider presets Some providers come with a ready-made read configuration, offered in the import step once the connection's base URL identifies them. Each is a starting point: the usual endpoint, parameter and pagination editors sit below it. * **Google Analytics 4** (base URL `https://analyticsdata.googleapis.com`) switches between **API request** and **GA4 report**. The report form takes the numeric property ID, an inclusive start and end date, up to 9 **Dimensions** (default `date`) and 1 to 10 **Metrics** (default `activeUsers`), with **Rows per page** (1 to 10,000, default 1,000) and **Maximum pages** (1 to 1,000, default 100). **Preview report** runs it against the connected account, which needs access to the property. * **Ramp** (base URL `https://api.ramp.com` or `https://demo-api.ramp.com`) offers **Use Ramp transactions**, which reads `/developer/v1/transactions` with `state=ALL`, 100 rows a page, following `page.next`. The connected account needs the `transactions:read` scope. * **Salesforce** (a My Domain base URL) offers **Use Salesforce query**, which reads `/services/data/v68.0/query` with `SELECT Id, Name, CreatedDate FROM Account` in the `q` query parameter. Edit the SOQL there and the API version in the path; the import follows `nextRecordsUrl` until `done` is true. *** ### Troubleshooting **Parse failed** * The URL may need auth to read the spec; configure manually and add credentials first * The URL downloads a file (a spreadsheet, zip, PDF or Parquet file) rather than returning API data. A connector reads API responses, so it refuses the URL: download the file and add it with [Local File Upload](/data-sources-and-connectors/local-uploads.md) instead, extracting a zip first. A connected AI client can upload it with `upload_files`. **401 / 403** * Check the auth type and where the key is sent (header vs query parameter) **Rows nested oddly** * Point the record path at the array inside the response envelope **This account needs to be reconnected** * The provider withdrew the grant, or the OAuth app's settings changed. Open the connection and click **Reconnect**