REST API Overview

The Zoomdata REST API provides methods for retrieving, updating, and deleting Zoomdata metadata pertaining to accounts, connections, users, and so forth. For an up-to-date description of methods and Swagger reference documentation for the APIs, see the Zoomdata developer zone .


The API currently uses basic access authentication. Most actions require admin-level access to the particular account manipulated using the API. Supervisor credentials can be used to access any account.

Version Compatibility

Each version of the API maintains backward compatibility with previous versions. The HTTP Accepts/Content-type header is used to specify the version for the resources that are produced and used by the API. When sending data to or receiving data from the API, you must use the appropriate HTTP header.

When working with the API, you should explicitly set the version of the API that you want to use. For example, in curl requests, you would include the --header parameter as shown below.

   # For submitting data   
curl --header "Content-type: application/vnd.zoomdata.v1+json" ...
# Consuming data
curl --header "Accept: application/vnd.zoomdata.v1+json,application/vnd.zoomdata+json" ...

To ensure you always use the latest version of Zoomdata, use the generic media type: application/vnd.zoomdata+json.

There is a risk associated with using this generic media time to ensure you always use the latest version presents a risk. Because this approach does not tie calls to specific API versions, if the latest version changes, your integration may break. It is safer to tie your API calls to specific versions.

The current API media type version will be sent as a header, X-Zoomdata-Media-Type, in the response to every API request.

The rule for specifying media types is simple. Always include the generic media type application/vnd.zoomdata+jsonand, if you specify a particular version, always put it first. For example:

  • Correct: application/vnd.zoomdata.v1+json,application/vnd.zoomdata+json
  • Incorrect: application/vnd.zoomdata+json, application/vnd.zoomdata.v1+json

HATEOAS Architecture

The Zoomdata API implements the HATEOAS architectural pattern. Most resources returned by the API have a links element. The links elements is an array of objects, each with two properties:

  • rel: short description of how this link relates to the parent object
  • href: the actual link value

Every resource will at least have a rel: "self" link, which is the canonical reference to that object. You can use the other links to explore the relations of a given object, for example, the users in an account or the sources tied to a connection. There are examples of links elements below.

   data: [   
{ created: {...},
lastModified: {...},
email: "",
username: "adam",
fullName: "Adam Appleton",
enabled: true,
administrator: false,
links: [
{ rel: "self",
href: "" },
{ rel: "",
href: "" },
{ rel: "",
href: "" },
{ rel: "account",
href: "" }, { rel: "groups",
href: "" }
] },

API Entry Point

The initial entry point to the API is http://<host>:<port>/<context>/api. For example:


This URL points to the root API resources that you can use to browse through the API.

The /service/ Path

Some functions of the Zoomdata client application call APIs using a /service/ path. Except where noted in Zoomdata's developer documentation, endpoints that use the /service/ path are for Zoomdata's internal use only.

Applications built with Zoomdata's internal-use APIs, are subject to a high risk of unexpected breakage.

APIs on the /service/ path that are safe to use include, for example, the /service/sources/key endpoint.

Reference Documentation

Zoomdata maintains Swagger-based reference materials for the REST APIs. It is found at In this testing environment, you can experiment with the APIs features.