The Hevo API is a programmatic interface to your Hevo account. It gives you the same control over your Pipelines and Destinations that the Hevo UI does, from your own code. You can create a Destination, create a Pipeline that loads data into it, choose the Source objects that Pipeline replicates, move data on demand, and read the history of every job the Pipeline runs.
The Hevo UI and the API work on the same Pipelines, so a Pipeline created through one can be read and changed through the other. The Hevo UI lets you set up a Pipeline and watch it run, while the API lets you do the same work from a script, a scheduler, or a service of your own. For example, if your team creates a Pipeline for every new customer you onboard, you can call the API from your provisioning script and create it automatically, rather than repeating the same steps in the Hevo UI for each customer.
The Hevo API is organized around REpresentational State Transfer (REST). It uses HTTP requests to access and use data, accepts JSON request bodies, returns JSON responses, and uses standard HTTP response codes and HTTP Basic authentication. Read Authentication for more information.
With the Hevo API, you can:
- Create and configure Destinations: Create a Destination for the database, data warehouse, or any other storage you want to load data into, view and change its settings, and delete it.
- Create and configure Pipelines: Create a Pipeline with the Source and Destination you want, change its settings, and enable, disable, or delete it.
- Select the objects to replicate: Choose the Source objects that a Pipeline replicates, and set how each one is loaded into your Destination.
- Move data on demand: Run a Pipeline sync, resync a set of objects, or resync an entire Pipeline without waiting for the next scheduled run.
- Track Pipeline jobs: Read the history of every job a Pipeline has run, including how much data moved and which objects failed.
- Track replication progress: Read the replication position of each object in a Pipeline.
- Rotate Source credentials: Replace the credentials of a Pipeline’s Source without signing in through a browser.
REST API Overview
REST stands for REpresentational State Transfer. A REST API (also known as RESTful API) is a web API that is based on the REST architecture and can interact with RESTful web services. REST APIs use HTTP requests to interact with the data. For example, with a REST API, you can use HTTP requests such as GET, POST, PUT, PATCH, and DELETE to read, create, update, and delete data stored on a computer or a system. The path of the request identifies the resource, the HTTP method sets the action, and the request body carries the data you send.
In API terminology, the endpoint is the URL used to make the request. The resource is the object that the endpoint acts on. For example, in the endpoint https://us.hevodata.com/api/v2/pipelines/{pipeline_id} for fetching a Pipeline based on the ID, the resource is pipelines.
You can have multiple endpoints with the same resource based on the action you need to perform. Refer to the API Reference section to find information about the different endpoints that are available for each resource and how to successfully use each of these. You can also try these out with sample values and review the response. These requests run against your Hevo account, so a request that creates, changes, or deletes something changes your real data.
Hevo API Versions
The Hevo API is available in two versions, and both are supported. Version 1 creates and manages Pipelines for database Sources, such as PostgreSQL, MySQL, and Oracle, and loads the data they replicate into a Snowflake, BigQuery, or Amazon Redshift Destination.
Version 2 covers most of what version 1 does, and extends it to the rest of the Sources and Destinations that Hevo supports. You can create a Pipeline for a SaaS application such as HubSpot, Stripe, or Salesforce, and load data into a Destination such as Databricks or Snowflake Iceberg. Version 2 also adds the replication position of each object, and the ability to rotate the OAuth credentials of a SaaS Source through the API. It does not yet provide the Source schema refresh that version 1 offers.
Version 2 opens by default. To use the version 1 endpoints, select v1.0 from the version selector at the top left of any page.
The following table compares the two versions:
| Criteria | Version 1 | Version 2 |
|---|---|---|
| Path | /api/v1/ | /api/v2/ |
| Sources | Database Sources, including all supported variants of PostgreSQL, MySQL, and Oracle. | Every Source for which you can send the credentials or an OAuth token in the request, including SaaS applications such as HubSpot, Stripe and Salesforce. A Source that can be authorized only by signing in through a browser cannot be created through the API. |
| Destinations | Snowflake, BigQuery, and Amazon Redshift. | Every Destination that your team can use, including Databricks and Snowflake Iceberg. The list depends on your region, and a Destination that is in beta appears only when it has been enabled for your team. |
| State of a new Pipeline | A Pipeline starts replicating data as soon as it is created. | A Pipeline is created in a disabled state by default. You can review the objects Hevo identified in your Source and select the ones you want, and then enable the Pipeline when you are ready. The objects appear once Hevo has read the schema of your Source, which it does after the create call returns, so the list can be empty for a while. At least one object must be selected before the Pipeline can be enabled. |
| Replication position | Not available. | Available through the API. You can read the replication position of each object. |
| Source schema refresh | You can trigger a refresh. | Not available. Use version 1, or the Hevo UI, to refresh the Source schema. |
| Job history | A data refresher run does not appear in the job history. | A data refresher run, which re-reads recent data from your Source, appears in the job history as a REFRESHER job. |
| Pipeline status detail | The Pipeline returns its state. | Alongside the state, the Pipeline returns a health object that reports the condition of its runs, as the Pipeline Overview in the Hevo UI shows it. The health object contains a value, a display_name and a severity. The response also includes the Pipeline's recent runs and the status of its Source schema. |
| API responses | Each endpoint documents the response that it returns when the request succeeds. | Each endpoint documents the responses that it returns when the request succeeds and when it fails. Every error returns the same body, so you handle a failure the same way whichever endpoint you called. A request that does not match any endpoint is the exception. A path that does not exist, a method that an endpoint does not accept, and a request body that is not valid JSON are covered by Hevo’s error handling mechanism rather than by this body. |
You work with the same Pipelines in both versions. A Pipeline created with one version can be read and changed with the other. Version 1 cannot change the Source configuration of a Source that authorizes with OAuth, or of a Source that needs values that Hevo fetches from the Source. The two versions address objects differently. Version 1 uses an object identifier, while version 2 uses the object’s fully qualified name. A fully qualified name is the database, the schema and the table of the object joined by dots, leaving out any level that your Source does not have. For example, shop.public.orders for a table in a Source that uses databases and schemas, and public.orders for a table in a Source that has no databases.
When to Use the Hevo API
Use the Hevo API when you want to:
- Set up a new customer or environment from end to end. A single script can create the Destination, set up the Pipeline that loads data into it, and select the objects to replicate.
- Create Pipelines from your own tools, such as a provisioning script or an internal admin portal, instead of creating each one manually.
- Run a sync when your data is ready rather than when the schedule says so. Trigger a sync from your orchestrator, so that the tasks that depend on it always run on fresh data. Read Using Edge Pipelines with Airflow for an example.
- Replicate objects that are added to your Source after the Pipeline was created. Hevo reads the schema of your Source at regular intervals, and again whenever you resync the Pipeline. Once a new object is listed, select the ones you want the Pipeline to replicate.
- Rotate the credentials behind a Source at the interval your security policy requires, without signing in through a browser.
- Apply the same change, such as a new schedule or load mode, to many Pipelines from a script.
API Breaking Changes Policy
Hevo will try to notify you in advance of any updates or removal of API features that may require you to update your deployed code.