Skip to main content

Using the REST API

How to use the API

You can access the DataOps.live application programming interface (API) using HTTPS GET and POST requests. There are many tools that enable you to make these requests. For this documentation, we will use curl (a tool to transfer data from or to a server) in a Unix-like environment.

Base URL

All DataOps.live API requests use the same base URL:

https://app.dataops.live/api/v4

This URL will prefix all requests.

Valid API request

The following is a basic example of a request to DataOps.live:

curl "https://app.dataops.live/api/v4/projects"

Example response:

[]
tip

Add the --include option to show server response headers and give useful debugging output.

Authentication

All API requests require authentication to return data. There are several ways you can authenticate with the DataOps.live API:

  • Personal access token (PAT)
  • Project access token
  • Group access token
  • Pipeline trigger token (limited endpoints only)

If the authentication information is not valid or is missing, DataOps.live returns an error message with a status code of 401:

{
"message": "401 Unauthorized"
}

Access tokens

Personal, project, or group access tokens are used similarly, i.e., via a private-token request header.

You can generate a PAT from your DataOps.live profile.

caution

Tokens are secret. Handle them securely like you would a sign-in password.

Project and group tokens are generated from the Settings -> Access Tokens menu.

Example of using personal, project, or group access token in a request header:

curl --header "private-token: your_access_token" "https://app.dataops.live/api/v4/projects"

Example response:

[
{
"id": 21816,
"description": "Example project description",
"name": "Example project name",
...
}
]
tip

When working on the command line, consider using a JSON formatter like jq to beautify the JSON responses.

Pipeline trigger tokens

A pipeline trigger token is scoped only for triggering a pipeline.

For detailed steps on getting a pipeline trigger token, refer to our Running pipelines - Pipeline trigger.

Pagination

Offset-based pagination

Sometimes, the response spans many pages. When listing resources, you can pass the following query parameters:

ParameterDescription
pagePage number (default: 1)
per_pageNumber of items to list per page (default: 20, max: 100)

Example of using the page and per_page query parameters:

curl --header "private-token: your_access_token" "https://app.dataops.live/api/v4/namespaces?per_page=30&page=1"

Example response:

[
{
"id": 320941,
"name": "Example group name",
"path": "example-group-name",
"kind": "group",
...
}
]

Learn more about query parameters in a URL query string via Wikipedia.

Request payload

JSON

DataOps.live supports a JSON request payload when making PUT and POST requests.

Example of sending a request with a data payload:

curl --request POST --header "Content-Type: application/json" \
--data '{"name":"<example-name>", "description":"<example-description>"}' "https://app.dataops.live/api/v4/projects"

Form fields

DataOps.live supports using the form submission type when making PUT and POST requests.

Example of sending a request with a form type:

curl --request POST \
--form "name=<example-name>" \
--form "description=<example-description>" \
--form "permissions[project_access]=null"
"https://app.dataops.live/api/v4/projects"a

Content type

The DataOps.live API supports the application/JSON content type by default.