Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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, 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 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

PreviousGoogle Drive
NextArchitecture & Security

Last updated