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:
[]
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.
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",
...
}
]
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:
Parameter | Description |
---|---|
page | Page number (default: 1) |
per_page | Number 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.