DVP Data API (1.0.0)

Download OpenAPI specification:Download

The Docker DVP Data API allows Docker Verified Publishers to view image pull analytics data for their namespaces. Analytics data can be retrieved as raw data, or in a summary format.

Summary data

In your summary data CSV, you will have access to the data points listed below. You can request summary data for a complete week (Monday through Sunday) or for a complete month (available on the first day of the following month).

There are two levels of summary data:

  • Repository-level, a summary of every namespace and repository
  • Tag- or digest-level, a summary of every namespace, repository, and reference (tag or digest)

The summary data formats contain the following data points:

  • Unique IP address count
  • Pulls by tag count
  • Pulls by digest count
  • Version check count

Raw data

In your raw data CSV you will have access to the data points listed below. You can request raw data for a complete week (Monday through Sunday) or for a complete month (available on the first day of the following month). Note: each action is represented as a single row.

  • Type (industry)
  • Host (cloud provider)
  • Country (geolocation)
  • Timestamp
  • Namespace
  • Repository
  • Reference (digest is always included, tag is provided when available)
  • HTTP request method
  • Action, one of the following:
    • Pull by tag
    • Pull by digest
    • Version check
  • User-Agent

Authentication Endpoints

Create an authentication token

Creates and returns a bearer token in JWT format that you can use to authenticate with Docker Hub APIs.

The returned token is used in the HTTP Authorization header like Authorization: Bearer {TOKEN}.

Most Docker Hub APIs require this token either to consume or to get detailed information. For example, to list images in a private repository.

Request Body schema: application/json
required

Login details.

username
required
string

The username of the Docker Hub account to authenticate with.

password
required
string

The password or personal access token (PAT) of the Docker Hub account to authenticate with.

Responses

Request samples

Content type
application/json
{
  • "username": "myusername",
  • "password": "hunter2"
}

Response samples

Content type
application/json
{
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Second factor authentication

When a user has 2FA enabled, this is the second call to perform after /v2/users/login call.

Creates and returns a bearer token in JWT format that you can use to authenticate with Docker Hub APIs.

The returned token is used in the HTTP Authorization header like Authorization: Bearer {TOKEN}.

Most Docker Hub APIs require this token either to consume or to get detailed information. For example, to list images in a private repository.

Request Body schema: application/json
required

Login details.

login_2fa_token
required
string

The intermediate 2FA token returned from /v2/users/login API.

code
required
string

The Time-based One-Time Password of the Docker Hub account to authenticate with.

Responses

Request samples

Content type
application/json
{
  • "login_2fa_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  • "code": 123456
}

Response samples

Content type
application/json
{
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Discovery

Get namespaces and repos

Gets a list of your namespaces and repos which have data available.

Authorizations:
Docker Hub Authentication

Responses

Response samples

Content type
application/json
{
  • "namespaces": [
    ]
}

Get user's namespaces

Get metadata associated with the namespaces the user has access to, including extra repos associated with the namespaces.

Authorizations:
Docker Hub Authentication

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get namespace

Gets metadata associated with specified namespace, including extra repos associated with the namespace.

Authorizations:
Docker Hub Authentication
path Parameters
namespace
required
string

Namespace to fetch data for

Responses

Response samples

Content type
application/json
{
  • "namespace": "string",
  • "extraRepos": [
    ],
  • "datasets": [
    ]
}

Namespace data

Get pull data

Gets pulls for the given namespace.

Authorizations:
Docker Hub Authentication
path Parameters
namespace
required
string

Namespace to fetch data for

query Parameters
timespan
string (TimespanType)
Enum: "months" "weeks"

Timespan type for fetching data

period
string (PeriodType)
Enum: "last-2-months" "last-3-months" "last-6-months" "last-12-months"

Relative period of the period to fetch data

group
string (GroupType)
Enum: "repo" "namespace"

Field to group the data by

Responses

Response samples

Content type
application/json
{
  • "pulls": [
    ]
}

Get pull data

Gets pulls for the given repo.

Authorizations:
Docker Hub Authentication
path Parameters
namespace
required
string

Namespace to fetch data for

repo
required
string

Repository to fetch data for

query Parameters
timespan
string (TimespanType)
Enum: "months" "weeks"

Timespan type for fetching data

period
string (PeriodType)
Enum: "last-2-months" "last-3-months" "last-6-months" "last-12-months"

Relative period of the period to fetch data

group
string (GroupType)
Enum: "repo" "namespace"

Field to group the data by

Responses

Response samples

Content type
application/json
{
  • "pulls": [
    ]
}

Get years with data

Gets a list of years that have data for the given namespace.

Authorizations:
Docker Hub Authentication
path Parameters
namespace
required
string

Namespace to fetch data for

Responses

Response samples

Content type
application/json
{
  • "years": [
    ]
}

Get timespans with data

Gets a list of timespans of the given type that have data for the given namespace and year.

Authorizations:
Docker Hub Authentication
path Parameters
namespace
required
string

Namespace to fetch data for

year
required
integer

Year to fetch data for

timespantype
required
string (TimespanType)
Enum: "months" "weeks"

Type of timespan to fetch data for

Responses

Response samples

Content type
application/json
Example
{
  • "months": [
    ]
}

Get namespace metadata for timespan

Gets info about data for the given namespace and timespan.

Authorizations:
Docker Hub Authentication
path Parameters
namespace
required
string

Namespace to fetch data for

year
required
integer

Year to fetch data for

timespantype
required
string (TimespanType)
Enum: "months" "weeks"

Type of timespan to fetch data for

timespan
required
integer

Timespan to fetch data for

Responses

Response samples

Content type
application/json
Example
{
  • "month": 0
}

Get namespace data for timespan

Gets a list of URLs that can be used to download the pull data for the given namespace and timespan.

Authorizations:
Docker Hub Authentication
path Parameters
namespace
required
string

Namespace to fetch data for

year
required
integer

Year to fetch data for

timespantype
required
string (TimespanType)
Enum: "months" "weeks"

Type of timespan to fetch data for

timespan
required
integer

Timespan to fetch data for

dataview
required
string (DataviewType)
Enum: "raw" "summary" "repo-summary" "namespace-summary"

Type of data to fetch

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get pull data for multiple repos

Gets pull for the given repos.

Authorizations:
Docker Hub Authentication
query Parameters
repos
required
Array of strings

Repositories to fetch data for (maximum of 50 repositories per request).

timespan
string (TimespanType)
Enum: "months" "weeks"

Timespan type for fetching data

period
string (PeriodType)
Enum: "last-2-months" "last-3-months" "last-6-months" "last-12-months"

Relative period of the period to fetch data

group
string (GroupType)
Enum: "repo" "namespace"

Field to group the data by

Responses

Response samples

Content type
application/json
{
  • "repos": {
    }
}

ResponseDataFile

url
string
size
integer <int64>
{
  • "url": "string",
  • "size": 0
}

Year Data Model

year
integer
{
  • "year": 0
}

Month Data Model

month
integer
{
  • "month": 0
}

Week Data Model

week
integer
{
  • "week": 0
}