Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?

Introduction

Welcome to the Dataloop API documentation!

To use the API you'll need an api key which can be created in Dataloop under your user account settings. When integrating services you may want to consider creating an application specific user in Dataloop with access to accounts at the correct role level.

You will also need to know the organisation name and account name that you want to work with. These match the organisation and account names in Dataloop. Use these details where you see <org name> and <account name> in the examples.

Authentication

To authorize, use this code to return a list of accounts:

curl -H "Authorization: Bearer changeme" https://app.dataloop.io/api/v1/orgs/<org name>/accounts
import requests

headers = {
            "Authorization": "Bearer changeme"
          }

requests.get('https://app.dataloop.io/api/v1/orgs/<org name>/accounts', headers=headers)

Make sure to replace changeme with your api key.

Dataloop expects the api key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer changeme

You must replace `changeme` with your `api key`.

Accounts

Get All Accounts

import requests

headers = {
            "Authorization": "Bearer changeme"
          }

requests.get('https://app.dataloop.io/api/v1/orgs/<org name>/accounts', headers=headers)
curl -H "Authorization: Bearer changeme" https://app.dataloop.io/api/v1/orgs/<org name>/accounts

The above command returns JSON structured like this:

[{
	"agent_keys": ["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"],
	"id": "568aa6f84db8230b69975211",
	"name": "default"
}]

This endpoint retrieves all accounts.

HTTP Request

GET https://app.dataloop.io/api/v1/orgs/<org name>/accounts

Create an Account

import requests

headers = {
            "Authorization": "Bearer changeme"
          }

payload = {
            "name": "<account name>"
          }

requests.post('https://app.dataloop.io/api/v1/orgs/<org name>/accounts', headers=headers, data=payload)
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer changeme" -d '{"name":"<account name>"}' https://app.dataloop.io/api/v1/orgs/<org name>/accounts

This endpoint creates an account.

HTTP Request

POST https://app.dataloop.io/api/v1/orgs/<org name>/accounts

Delete an Account

import requests

headers = {
            "Authorization": "Bearer changeme"
          }

requests.delete('https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>', headers=headers)
curl -X DELETE -H "Authorization: Bearer changeme" https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>

This endpoint deletes an account.

HTTP Request

DELETE https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>

Agents

Get All Agents

import requests

headers = {
            "Authorization": "Bearer changeme"
          }

requests.get('https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/agents', headers=headers)
curl -H "Authorization: Bearer changeme" https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/agents

The above command returns JSON structured like this:

[{
	"id": "8ccf364f-e33c-4061-8163-8c952b2f18de",
	"name": "dataloop",
	"hostname": "dcbe63762685",
	"mac": "02:42:ac:11:00:02",
	"created": "2015-12-11T12:05:09.879Z",
	"modified": "2016-01-10T14:31:45.066Z",
	"tags": ["all", "tag1"],
	"osName": "Linux",
	"heartbeat": "2016-01-10T14:31:45.065Z",
	"presence_state": "online",
	"status": "REGISTERED",
	"container_name": "Linux",
	"mode": "DEFAULT"
}]

This endpoint retrieves all agents.

HTTP Request

GET https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/agents

Get a Specific Agent

curl -H "Authorization: Bearer changeme" https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/agents/<id>
import requests

headers = {
            "Authorization": "Bearer changeme"
          }

requests.get('https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/agents/<id>', headers=headers)

The above command returns JSON structured like this:

{
	"id": "0a46e3a3-96dc-4ada-9e37-eea214c9b664",
	"name": "dataloop",
	"hostname": "dataloop",
	"mac": "00:80:27:a2:71:71",
	"interfaces": [{
		"addresses": [{
			"family": "AF_INET",
			"ips": ["127.0.0.1"]
		}],
		"interface": "lo0"
	}],
	"created": "2016-01-07T17:12:56.887Z",
	"modified": "2016-01-10T14:43:19.586Z",
	"org": "52d1bff881f2a2e087000007",
	"tags": ["all"],
	"osName": "Linux",
	"heartbeat": "2016-01-10T14:43:19.585Z",
	"presence_state": "online",
	"status": "REGISTERED",
	"running_plugin_names": ["base"],
	"process_summary": [{
		"name": "init",
		"count": 1
	}],
	"container_name": "Linux",
	"mode": "DEFAULT"
}

This endpoint retrieves a specific agent as specified by the <id> at the end of the url.

The id in the url matches the agent fingerprint that can be found in the agent.finger file on the server or the agent details page inside the web ui.

HTTP Request

GET https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/agents/<id>

Delete a Specific Agent

curl -H "Authorization: Bearer changeme" -X "DELETE" https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/agents/<id>
import requests

headers = {
            "Authorization":  "Bearer changeme"
          }

requests.delete('https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/agents/<id>', headers=headers)

This endpoint deletes a specific agent as specified by the <id> at the end of the url.

The id in the url matches the agent fingerprint that can be found in the agent.finger file on the server or the agent details page inside the web ui.

HTTP Request

DELETE https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/agents/<id>

Dashboards

Export a Dashboard

curl -H "Authorization: Bearer changeme" -H "Accept: application/yaml" https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/dashboards/<name>
import requests

headers = {
            "Authorization": "Bearer changeme",
            "Accept": "application/yaml"
          }
requests.get('https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/dashboards/<name>', headers=headers)

This endpoint exports a specific dashboard as specified by the <name> at the end of the url.

The name in the url matches the name of the dashboard as presented in the dashboard url in the web ui.

HTTP Request

GET https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/dashboards/<name>

Import a Dashboard

file='dash.yaml'
curl -H "Authorization: Bearer changeme" -X "PUT" --data-binary @$file -H "Content-Type: application/yaml"  https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/dashboards/<name>
import requests

headers = {
            "Authorization": "Bearer changeme",
            "Content-Type": "application/yaml"
          }

files = {'dash.yaml': open('dash.yaml', 'rb')}

requests.put('https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/dashboards/<name>', headers=headers, files=files)

This endpoint imports a specific dashboard as specified by the <name> at the end of the url.

The name in the url matches the name of the dashboard as presented in the dashboard url in the web ui.

HTTP Request

PUT https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/dashboards/<name>

Links

Get All Links

import requests

headers = {
            "Authorization": "Bearer changeme"
          }

requests.get('https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/links', headers=headers)
curl -H "Authorization: Bearer changeme" https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/links

The above command returns JSON structured like this:

[{
	"org": "52d1bff881f2a2e087000007",
	"plugin": "base",
	"id": "54dcd33803d166c35481367c",
	"tags": ["all"]
}]

This endpoint retrieves all links.

Links are used to bind plugins to tags so that they automatically deploy to agents.

HTTP Request

GET https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/links

Metrics

Get All Metrics for an Agent

curl -H "Authorization: Bearer changeme" https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/metrics?source=<id>
import requests

headers = {
            "Authorization": "Bearer changeme"
          }

params = { "source": "<name>" }

requests.get('https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/metrics', params=params, headers=headers)

The above command returns JSON structured like this:

[{
	"id": "53bcfd6d6f9b5f8269cd8af2",
	"name": "base.swap",
	"data_type": "number",
	"collector_id": "52d1bffb81f2a2e087000008",
	"collector_type": "plugin"
}]

This endpoint returns a list of metrics available for an agent as specified by <id> in the tag query parameter.

The matches the agent fingerprint found in the 'agent.finger' file or in the agent details page in the web UI.

HTTP Request

GET https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/metrics?source=<id>

Get All Metrics for a Tag

curl -H "Authorization: Bearer changeme" https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/metrics?tag=<tag name>
import requests

headers = {
            "Authorization": "Bearer changeme",
          }

params = { "tag": "<name>" }

requests.get('https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/metrics', params=params, headers=headers)

The above command returns JSON structured like this:

[{
	"id": "53bcfd6d6f9b5f8269cd8af2",
	"name": "base.swap",
	"data_type": "number",
	"collector_id": "52d1bffb81f2a2e087000008",
	"collector_type": "plugin"
}]

This endpoint returns a list of metrics available across all agents within a tag as specified by <tag name> in the tag query parameter.

HTTP Request

GET https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/metrics?tag=<tag name>

Series

Optional query parameters:

Query Parameter Description
resolution Distance between two data points in seconds
period Time span in second you want to display (e.g. for last hour 60 * 60 = 3600)
period[duration] Same as just using "period" but you can use only "period" or "period[duration]" with "period[end]", you can't mix them together.
period[end] Marks end point of time span you want to get. The value in UNIX timestamp in seconds.

Get Metric Series for an Agent

curl -H "Authorization: Bearer changeme" https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/metrics/<metric name>/series?source=<id>
import requests

headers = {
            "Authorization": "Bearer changeme"
          }

params = { "source": "<id>" }

requests.get('https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/metrics/<metric name>/series?source=<id>', params=params, headers=headers)

The above command returns JSON structured like this:

[{
	"origin": ["sts-redis-store"],
	"id": "568aac03aa27ad42a30009ea",
	"uom": "%",
	"metric": {
		"collector_type": "plugin",
		"id": "568aac03aa27ad42a30009cd",
		"data_type": "number",
		"name": "base.cpu"
	},
	"source": {
		"id": "0c78bf0e-5891-4eff-84d8-82832b824b8c",
		"name": "dataloop"
	},
	"points": [{
		"uom": "%",
		"value": 16,
		"time": 1455027939
	}]
}]

This endpoint returns a series of points for a metrics as specified by <metric name> for an agent.

HTTP Request

GET https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/metrics/<metric name>/series?source=<id>

Get Metric Series for a Tag

curl -H "Authorization: Bearer changeme" https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/metrics/<metric name>/series?tag=<tag name>
import requests

headers = {
            "Authorization": "Bearer changeme"
          }

params = { "tag": "<tag name>" }

requests.get('https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/metrics/<metric name>/series?tag=<tag name>', params=params, headers=headers)

The above command returns JSON structured like this:

[{
	"origin": ["sts-redis-store"],
	"id": "568aac03aa27ad42a30009ea",
	"uom": "%",
	"metric": {
		"collector_type": "plugin",
		"id": "568aac03aa27ad42a30009cd",
		"data_type": "number",
		"name": "base.cpu"
	},
	"source": {
		"id": "0c78bf0e-5891-4eff-84d8-82832b824b8c",
		"name": "dataloop"
	},
	"points": [{
		"uom": "%",
		"value": 16,
		"time": 1455027939
	}]
}]

This endpoint returns a series of points for a metrics as specified by <metric name> for a tag.

HTTP Request

GET https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/metrics/<metric name>/series?tag=<tag name>

Plugins

Get All Plugins

import requests

headers = {
            "Authorization": "Bearer changeme"
          }

requests.get('https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/plugins', headers=headers)
curl -H "Authorization: Bearer changeme" https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/plugins

The above command returns JSON structured like this:

[{
	"org": "52d1bff881f2a2e087000007",
	"plugin": "base",
	"id": "54dcd33803d166c35481367c",
	"tags": ["all"]
}]

This endpoint retrieves all plugins.

HTTP Request

GET https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/plugins

Export a Plugin

import requests

headers = {
            "Authorization": "Bearer changeme"
          }

requests.get('https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/plugins/<plugin name>', headers=headers)
curl -H "Authorization: Bearer changeme" https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/plugins/<plugin name>

The above command returns JSON structured like this:

{
	"content": "<base64 encoded file content>",
	"id": "568aa6f82121ac8ee1fbde31",
	"name": "base",
	"extension": "py",
	"description": "",
	"interval": 30,
	"hash": "bc4e961de223b88dffee6a3d06f67ec2fb83ef55",
	"encoding": "base64",
	"params": "",
	"org": "568aa6f84db8230b69975211",
	"shellArgs": "",
	"type": "INPROCESS",
	"pack": "base"
}
import requests
import base64

headers = {
            "Authorization": "Bearer changeme"
          }

plugin = requests.get('https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/plugins/<plugin name>', headers=headers).json()

base64.b64decode(plugin['content'])
curl -s -H "Authorization: Bearer changeme" https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/plugins/<plugin name> | jq -r '.content' | base64 --decode

The above command returns the file contents.

This endpoint exports a plugin.

HTTP Request

GET https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/plugins

Import a Plugin

import requests
import base64

name = "file"
extension = "py"

headers = {
            "Authorization": "Bearer changeme"
          }

with open(name + '.' + extension, 'r') as file:
    content = file.read()

base64_content = base64.b64encode(content)

payload = {
			"name": name,
			"extension": extension,
            "content": base64_content
          }

requests.post('https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/plugins', headers=headers, data=payload)
name=file
extension=py
content=$(cat ${name}.${ext} | base64)
json=$(jq -n --arg v "${content}" --arg n "${name}" --arg e "${extension}" '{"content": $v,"name": $n,"extension": $e}')

curl -H "Authorization: Bearer changeme" -H "Content-Type: application/json" -X POST -d "${json}" https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/plugins

The above commands imports a file called file.py as a plugin.

This endpoint imports a plugin.

HTTP Request

POST https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/plugins

Update a Plugin

import requests
import base64

name = "file"
extension = "py"

headers = {
            "Authorization": "Bearer changeme"
          }

with open(name + '.' + extension, 'r') as file:
    content = file.read()

base64_content = base64.b64encode(content)

payload = {
            "content": base64_content,
            "encoding": "base64"
          }

requests.patch('https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/plugins/<plugin name>', headers=headers, data=payload)
name=file
extension=py
content=$(cat ${name}.${ext} | base64)
json=$(jq -n --arg v "${content}" '{"content": $v,"encoding": "base64"}')

curl -H "Authorization: Bearer changeme" -H "Content-Type: application/json" -X PATCH -d "${json}" https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/plugins</plugin name>

The above commands updates <plugin name> with the contents of file.py.

This endpoint updates a plugin.

HTTP Request

PATCH https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/plugins/<plugin name>

Delete a Plugin

import requests

headers = {
            "Authorization": "Bearer changeme"
          }

requests.delete('https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/plugins/<plugin name>', headers=headers)
curl -H "Authorization: Bearer changeme" -X DELETE https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/plugins/<plugin name>

The above command deletes a plugin.

This endpoint deletes a plugin.

HTTP Request

DELETE https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/plugins/<plugin name>

Rules

Export a Rule

curl -H "Authorization: Bearer changeme" -H "Accept: application/yaml" https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/rules/<name>
import requests

headers = {
            "Authorization": "Bearer changeme",
            "Accept": "application/yaml"
          }
requests.get('https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/rules/<name>', headers=headers)

This endpoint exports a specific rule as specified by the <name> at the end of the url.

The name in the url matches the name of the dashboard as presented in the dashboard url in the web ui.

HTTP Request

GET https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/rules/<name>

Import a Rule

file='dash.yaml'
curl -H "Authorization: Bearer changeme" -X "PUT" --data-binary @$file -H "Expect: application/yaml"  https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/rules/<name>
import requests

headers = {
            "Authorization": "Bearer changeme",
            "Expect": "application/yaml"
          }

files = {'rule.yaml': open('rule.yaml', 'rb')}

requests.put('https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/rules/<name>', headers=headers, files=files)

This endpoint imports a specific rule as specified by the <name> at the end of the url.

The name in the url matches the name of the rule as presented in the rule url in the web ui.

HTTP Request

GET https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/rules/<name>

Tags

Get All Tags

import requests

headers = {
            "Authorization": "Bearer changeme"
          }

requests.get('https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/tags', headers=headers)
curl -H "Authorization: Bearer changeme" https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/tags

The above command returns JSON structured like this:

[{"name": "all"}]

This endpoint retrieves all tags.

HTTP Request

GET https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/tags

Annotations

Get All Annotation Streams

curl https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/annotations \
  -H "Authorization: Bearer changeme"

The above command returns JSON structured like this:

[
   "stream-1",
   "stream-2",
   "stream-3"
]

Get All Annotations for a Stream

curl https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/annotations/<stream name> \
  -H "Authorization: Bearer changeme"
[
    {
        "description": "",
        "id": "577ce1d21bfffd8b2b072dc9",
        "name": "v4",
        "start_time": "2016-07-06T10:47:46.951Z",
        "stream": "test-stream"
    },
    {
        "description": "a",
        "id": "577ce1d21bfffd8b2b072dc8",
        "name": "v3",
        "start_time": "2016-07-06T10:47:46.853Z",
        "stream": "test-stream"
    },
    {
        "description": "",
        "id": "577ce1d21bfffd8b2b072dc7",
        "name": "v2",
        "start_time": "2016-07-06T10:47:46.756Z",
        "stream": "test-stream"
    }
]

Delete a Stream

curl -X DELETE https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/annotations/<stream name> \
  -H "Authorization: Bearer changeme"

Create an Annotation

curl -X POST https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/annotations/test-stream \
 -H "Authorization: Bearer changeme" \
 -H "Content-Type: application/json" \
 -d '{"name": "deploy v23"}'

The above command returns JSON structured like this:

{
    "id": "577e67edd150c070753a1b39",
    "stream": "test-stream",
    "name": "deploy v23",
    "description": "",
    "start_time": "2016-07-07T14:32:13.144Z"
}

Get an Annotation

curl https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/annotations/test-stream/<id> \
 -H "Authorization: Bearer changeme"

The above command returns JSON structured like this:

{
    "id": "577e67edd150c070753a1b39",
    "stream": "test-stream",
    "name": "deploy v23",
    "description": "",
    "start_time": "2016-07-07T14:32:13.144Z"
}

Update an Annotation

curl -X PUT https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/annotations/test-stream/<id> \
 -H "Authorization: Bearer changeme" \
 -H "Content-Type: application/json" \
 -d '{"description": "new description"}'

The above command returns JSON structured like this:

{
    "id": "577e67edd150c070753a1b39",
    "stream": "test-stream",
    "name": "deploy v23",
    "description": "new description",
    "start_time": "2016-07-07T14:32:13.144Z"
}

Delete an Annotation

curl -X DELETE https://app.dataloop.io/api/v1/orgs/<org name>/accounts/<account name>/annotations/test-stream/<id> \
 -H "Authorization: Bearer changeme"
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment