canonical: https://jentic.com/apis/hevodata.com/hevodata

# Hevo Data

The Hevo Data API provides programmatic control over data pipelines, sources, destinations, models, and workflows on Hevo's no-code ELT platform. Across 60 endpoints, agents can list and create pipelines, run them on demand, pause and resume specific objects, manage transformation models, and trigger workflow executions. Authentication uses HTTP Basic with an API Key as username and API Secret as password, generated from Account > API Keys in the Hevo UI, and the API is region-scoped so callers must use the host that matches their account (us, us2, eu, in, asia, or au).

## For AI agents

Manage Hevo Data ELT pipelines - create sources and destinations, run pipelines on demand, pause objects, and trigger transformation models - using HTTP Basic auth with API key and secret.

## Scope

Does not handle reverse ETL, customer data activation, or business-intelligence dashboards - use for managing Hevo source-to-warehouse pipelines only.

## Capabilities

- Create and configure pipelines that move data from source systems into a target warehouse without writing extraction code
- Run a pipeline on demand with POST `/api/public/v2.0/pipelines/{id}/run-now` to backfill data outside the regular schedule
- Pause, resume, or skip individual objects within a pipeline so a single broken table does not halt the whole flow
- Adjust pipeline schedule and priority to control sync frequency and resource allocation per pipeline
- Manage transformation models that materialise SQL-defined tables in the destination warehouse
- Trigger workflows that orchestrate dependent models in sequence with retry and notification rules
- Inspect object-level statistics including events ingested, last sync time, and current sync status

## Use cases

### Operational Pipeline Management

Use the Hevo API to monitor and recover pipelines without logging into the UI. Agents can poll GET `/api/public/v2.0/pipelines` for status, trigger POST `/api/public/v2.0/pipelines/{id}/run-now` after upstream issues, or pause specific objects with `/pipelines/{id}/objects/{object_name}/pause` when a schema change breaks a single table. This keeps the rest of the pipeline flowing while engineering investigates.

Example prompt: List pipelines with status=failed, then call POST `/api/public/v2.0/pipelines/{id}/run-now` on each to retry, capturing the new run id.

### Programmatic Pipeline Provisioning

Provision new pipelines as part of a customer onboarding workflow. Create source and destination connections, attach them to a pipeline, set the schedule, and verify that the first sync completes - all from the API. Combined with infrastructure-as-code, this lets a data team add tenants without manual clicks in the Hevo console.

Example prompt: Create a pipeline named tenant-acme with source PostgreSQL and destination Snowflake, set schedule to every 60 minutes, then verify the first sync finishes.

### Schema Evolution Handling

When a source schema changes, agents can detect the failing object via GET `/api/public/v2.0/pipelines/{id}/objects/{object_name}/stats`, pause the affected object with the pause endpoint, update the destination model, and resume - all without touching unrelated objects. This isolates blast radius and avoids manual escalation cycles.

Example prompt: Pause object orders in pipeline 1234 with POST `/api/public/v2.0/pipelines/1234/objects/orders/pause`, then resume it after the destination schema is updated.

### AI Agent Data Operations

Through Jentic, an AI agent can answer 'why is the warehouse stale?' by calling Hevo's pipeline status endpoints and surfacing the failing object. Jentic holds the Basic auth credentials in the vault and exposes Hevo operations to the agent by intent, so the agent can chase down a stalled pipeline without seeing the API secret directly.

Example prompt: Search Jentic for 'list failed pipelines', execute the call against Hevo, then trigger run-now on the first result.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/public/v2.0/pipelines` | List all pipelines |
| POST | `/api/public/v2.0/pipelines` | Create a new pipeline |
| POST | `/api/public/v2.0/pipelines/{id}/run-now` | Trigger an immediate pipeline run |
| POST | `/api/public/v2.0/pipelines/{id}/objects/{object_name}/pause` | Pause a single object inside a pipeline |
| POST | `/api/public/v2.0/pipelines/{id}/objects/{object_name}/resume` | Resume a paused object |
| GET | `/api/public/v2.0/pipelines/{id}/objects/{object_name}/stats` | Get sync stats for a single object |
| PUT | `/api/public/v2.0/pipelines/{id}/schedule` | Update the pipeline schedule |

## Key resources

- **Pipelines** — List, create, update, pause, resume, run on demand, and inspect stats for ELT pipelines
- **Pipeline Objects** — Pause, resume, skip, or include individual tables within a pipeline
- **Sources** — Manage source connection settings and credentials per pipeline
- **Models** — Create and manage SQL-based transformation models in the destination warehouse
- **Workflows** — Orchestrate dependent models with retry and notification rules

## Why Jentic

- **Setup:** Wiring the Hevo Data API by hand means base64-encoding your API key and secret into a Basic auth header and picking the right regional host, since us, us2, eu, in, asia, and au each have their own hevodata.com endpoint. Through Jentic you install once, import Hevo Data from the API Directory, store the key and secret once, and your agent calls it.
- **Permission scoping:** Hevo puts the pipeline id and object name in the URL path (`/pipelines/{id}/objects/{object_name}/...`), so a rule can pin your agent to one pipeline. You choose the operations it may call, so running a pipeline now, pausing, or resuming an object is only included if you add it, while reading pipelines and object stats stays separate.
- **Credential handling:** Your Hevo API key and secret are stored once, encrypted, by your own Jentic One instance and base64-encoded into the Basic auth header at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'run a pipeline now' or 'pause a pipeline object', and Jentic returns the matching Hevo operation with its input schema so the agent calls the right endpoint without scanning Hevo's docs.

## Related APIs

- **Airbyte API** — Airbyte is the open-source ELT alternative with a connector marketplace and self-hosted option
- **Stitch Data API** — Stitch is Talend's managed ELT service with similar source-to-warehouse coverage
- **OpenAI API** — OpenAI provides language model inference for analyzing the data Hevo lands in the warehouse

## FAQ

### What authentication does the Hevo Data API use?

Hevo uses HTTP Basic authentication: the API Key is the username and the API Secret is the password, both generated from Account > API Keys in the Hevo UI. Through Jentic, both values live in the encrypted vault and are concatenated and base64-encoded by the runtime, so the agent never sees the raw secret.

### Can I trigger an immediate pipeline run with the Hevo Data API?

Yes. POST `/api/public/v2.0/pipelines/{id}/run-now` schedules an on-demand run for the specified pipeline. The response includes a run id you can correlate with subsequent GET `/api/public/v2.0/pipelines/{id}` polls to see when the run finishes and its status.

### Which region should I call for the Hevo Data API?

Hevo is region-scoped - call the host that matches your account: https://us.hevodata.com, https://us2.hevodata.com, https://eu.hevodata.com, https://in.hevodata.com, https://asia.hevodata.com, or https://au.hevodata.com. Calling the wrong region returns 404 or auth errors even with valid credentials.

### How do I pause a single failing table without stopping the whole pipeline through Jentic?

Search Jentic for 'pause a pipeline object', load the schema, and execute against POST `/api/public/v2.0/pipelines/{id}/objects/{object_name}/pause.` The other objects in the pipeline continue syncing; resume the paused object with the matching /resume endpoint once the schema is fixed.

### What rate limits apply to the Hevo Data API?

Hevo does not publish a fixed rate-limit number in the spec, but heavy callers should batch list requests using the page and limit query parameters and back off on HTTP 429 responses. Most pipeline mutations also debounce - repeated run-now calls within a short window may be coalesced into a single run.

### Can I limit what my agent is allowed to do with the Hevo Data API?

Yes. Because you run Jentic One yourself, your own rules decide which Hevo operations and credentials the agent may use. Since Hevo puts the pipeline id and object name in the URL path (`/pipelines/{id}/objects/{object_name}/...`), you can pin the agent to a single pipeline and pick exactly which operations it may call. You can grant read-only access to GET /pipelines and object stats while withholding write actions like POST `/pipelines/{id}/run-now` or the object pause and resume endpoints unless you explicitly add them.