How do I connect a REST API source?

1. Overview

The REST API connector lets you pull data from an external HTTP endpoint into Vantage. You provide the URL, authentication details, and a JSON path to the data array — Vantage fetches the response and ingests the results into ClickHouse like any other source.

The API connector currently supports manual sync only. You trigger each pull by clicking "Sync now" in the source settings. Scheduled or automatic API polling is not yet available.

2. When to Use

• When you have an internal or third-party API that returns tabular data in JSON format.
• When you want to bring CRM records, ERP data, or other system data into Vantage for analysis.
• When you need a structured alternative to downloading CSVs and re-uploading them manually.

3. Concepts

• Authentication – Vantage supports three auth methods for API connections: Bearer token, API key, and Basic (username/password).
• Data Path – The JSON path that tells Vantage where the data array lives in the API response. For example, if the response is {"results": [{...}, {...}]}, the data path would be "results".
• Manual Sync – Each sync is triggered by an admin clicking "Sync now". The connector fetches the latest data from the API and replaces the previous dataset. There is no automatic or scheduled sync.

4. Set Up Guide

Step 1: Add a New Source

1. In Vantage, click Sources from the navigation.
2. Click Add Source.
3. Select API as the connector type.

Step 2: Enter the Endpoint URL

1. Provide the full URL of the API endpoint that returns your data.

Step 3: Configure Authentication

1. Choose your auth method:
   • Bearer token
   • API key
   • Basic auth (username/password)
2. Enter the credentials.

Step 4: Set the Data Path

1. Specify the JSON path pointing to the data array in the response.

Step 5: Sync

1. Click Sync now to pull the data.
2. Vantage fetches the response, extracts data at the specified path, and ingests it into ClickHouse.

Step 6: Verify

1. Confirm the row count in the Sources listing.
2. Spot-check column values in the source view.

5. Best Practices

• Test your API endpoint independently (e.g., in Postman or a browser) before configuring it in Vantage.
• If your API returns paginated results, point Vantage at a single-page or bulk export endpoint.
• Remember to sync manually whenever the upstream data changes — there is no automatic refresh.
• If your API credentials rotate, update them in the source settings promptly to avoid failed syncs.

6. Related Links / FAQs

Can I schedule automatic API syncs?
Not currently. API sources require a manual "Sync now" action each time. Scheduled pulls are planned for a future release.

What if my API needs custom headers?
The supported auth methods (Bearer, API key, Basic) cover most common patterns. Custom header configurations beyond these are not available in the current version.

Does the API connector support pagination?
No. Vantage makes a single request to the configured URL. Use an endpoint that returns the full dataset in one response.

7. Version Notes

Last Updated: 04 Sep 2026