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.

Last updated on