API User Guide

Many operations that you can perform in the Bigeye UI can also be accessed via our REST API. Using REST APIs helps in workflow automation, such as triggering Bigeye to validate a dataset after an ELT job has finished loading.

Use the API Reference to see what kinds of operations Bigeye supports and how to authenticate. If you need something that doesn't currently exist, reach out to us at [email protected].

📘

API calls are restricted by Bigeye access level.

The access level for authentication is based upon the access granted in Bigeye. Users with the view only, edit, and manage roles will be restricted from doing certain API calls based upon their access.

Workspace IDs

If your user has access to more than one workspace, some API endpoints will require you to pass in a workspace ID with your call. Without a workspace ID, you will get back a response with a 400 status code and the following error message:

{"code":400,"message":"A workspace ID must be supplied"}

For example, they are the endpoints where you list or count the resources in a workspace, or the endpoints where you create a new resource, since the API needs to know which workspace to save it in. In the API Reference, these endpoints accept a workspaceId parameter, either as a query parameter or as a request body parameter.

GET requests accept it as a query parameter, as in this example where we list all the collections in workspace 123:

GET /api/v1/collections?workspaceId=123

POST and other types of requests accept it as a body parameter, as in this example where we create a new collection in workspace 123:

POST /api/v1/collections

body:
{
  "workspaceId": 123,
  <other body parameters>
}

Alternatively, you can pass in the workspace ID via the X-Bigeye-Workspace-Id request header. Then you don't need to pass it in as a query or body parameter.

GET /api/v1/collections
X-Bigeye-Workspace-Id: 123

The easiest option may be to keep track of which workspace you are currently working in, and pass in the X-Bigeye-Workspace-Id header with every call.

Finding workspace IDs

Workspace IDs can be found by selecting the Settings option in the left navigation, then selecting Workspaces. On the workspaces page, the ID will be in the ID column next to its corresponding workspace.

Testing

For testing the API, you can use the Advanced REST Client tool because it handles things like auth and gives a way to save and share calls. The other alternate tool that you can use for testing is JSON reformatter.

You can skip this section for a GET request. For PUT or POST requests, fill in the parameters in the API Reference and generate the JSON body of the request as shown below:

Now, cut and paste the message body into ARC.

Fill in the API method and the request URL, and then click Send. You'll be prompted for your Bigeye credentials, but after that, the API call will be made and you can inspect the response. Congrats!