Docker HUB API (beta)

Download OpenAPI specification:Download

Docker Hub is a service provided by Docker for finding and sharing container images with your team.

It is the world's largest library and community for container images.

In addition to the Docker Hub UI and Docker Hub CLI tool (currently experimental), Docker provides an API that allows you to interact with Docker Hub.

Browse through the Docker Hub API documentation to explore the supported endpoints.

Resources

The following resources are available to interact with the documented API:

Rate Limiting

The Docker Hub API is limited on the amount of requests you can perform per minute against it.

If you haven't hit the limit, each request to the API will return the following headers in the response.

  • X-RateLimit-Limit - The limit of requests per minute.
  • X-RateLimit-Remaining - The remaining amount of calls within the limit period.
  • X-RateLimit-Reset - The unix timestamp of when the remaining resets.

If you have hit the limit, you will receive a response status of 429 and the X-Retry-After header in the response.

The X-Retry-After header is a unix timestamp of when you can call the API again.

Note: These rate limits are separate from anti-abuse and Docker Hub download, or pull rate limiting. To learn more about Docker Hub pull rate limiting, see Usage and limits.

Authentication

Most Docker Hub API endpoints require you to authenticate using your Docker credentials before using them.

Additionally, similar to the Docker Hub UI features, API endpoint responses may vary depending on your plan (Personal, Pro, or Team) and your account's permissions.

To learn more about the features available in each plan and to upgrade your existing plan, see Docker Pricing.

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.

As of September 16, 2024, this route requires a PAT instead of a password if your organization has SSO enforced.

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": "p@ssw0rd"
}

Response samples

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

Second factor authentication

When a user has two-factor authentication (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"
}

Personal Access Tokens

The Personal Access Token endpoints lets you manage personal access tokens. For more information, see Access Tokens.

You can use a personal access token instead of a password in the Docker CLI or in the Create an authentication token route to obtain a bearer token.

Scopes

For each scope grouping (in this case "repo"), you only need to define 1 scope as any lower scopes are assumed. For example: If you define repo:write, the API assumes the scope of both repo:read and repo:public_read as well. If you were to define both repo:write and repo:read, then repo:read is assumed by repo:write and ignored.

Treat your personal access token like your password and keep it secret. You cannot retrieve your token after it is generated.

Create a personal access token

Creates and returns a personal access token.

Request Body schema: application/json
required
token_label
required
string [ 1 .. 100 ] characters

Friendly name for you to identify the token.

scopes
required
Array of strings

Valid scopes: "repo:admin", "repo:write", "repo:read", "repo:public_read"

Responses

Request samples

Content type
application/json
{
  • "token_label": "My read only token",
  • "scopes": [
    ]
}

Response samples

Content type
application/json
{
  • "uuid": "b30bbf97-506c-4ecd-aabc-842f3cb484fb",
  • "client_id": "HUB",
  • "creator_ip": "127.0.0.1",
  • "creator_ua": "some user agent",
  • "created_at": "2021-07-20T12:00:00.000000Z",
  • "last_used": null,
  • "generated_by": "manual",
  • "is_active": true,
  • "token": "a7a5ef25-8889-43a0-8cc7-f2a94268e861",
  • "token_label": "My read only token",
  • "scopes": [
    ]
}

Get a list of personal access tokens

Returns a paginated list of personal access tokens.

query Parameters
page
number
Default: 1
page_size
number
Default: 10

Responses

Response samples

Content type
application/json
{
  • "count": 1,
  • "next": null,
  • "previous": null,
  • "active_count": 1,
  • "results": [
    ]
}

Update a personal access token

Updates a personal access token partially. You can either update the token's label or enable/disable it.

path Parameters
uuid
required
string
Request Body schema: application/json
required
token_label
string [ 1 .. 100 ] characters
is_active
boolean

Responses

Request samples

Content type
application/json
{
  • "token_label": "My read only token",
  • "is_active": false
}

Response samples

Content type
application/json
{
  • "uuid": "b30bbf97-506c-4ecd-aabc-842f3cb484fb",
  • "client_id": "HUB",
  • "creator_ip": "127.0.0.1",
  • "creator_ua": "some user agent",
  • "created_at": "2021-07-20T12:00:00.000000Z",
  • "last_used": null,
  • "generated_by": "manual",
  • "is_active": true,
  • "token": "a7a5ef25-8889-43a0-8cc7-f2a94268e861",
  • "token_label": "My read only token",
  • "scopes": [
    ]
}

Get a personal access token

Returns a personal access token by UUID.

path Parameters
uuid
required
string

Responses

Response samples

Content type
application/json
{
  • "uuid": "b30bbf97-506c-4ecd-aabc-842f3cb484fb",
  • "client_id": "HUB",
  • "creator_ip": "127.0.0.1",
  • "creator_ua": "some user agent",
  • "created_at": "2021-07-20T12:00:00.000000Z",
  • "last_used": null,
  • "generated_by": "manual",
  • "is_active": true,
  • "token": "",
  • "token_label": "My read only token",
  • "scopes": [
    ]
}

Delete a personal access token

Deletes a personal access token permanently. This cannot be undone.

path Parameters
uuid
required
string

Responses

Response samples

Content type
application/json
{
  • "detail": "string",
  • "message": "string"
}

Audit Logs

The Audit Logs API endpoints allow you to query audit log events across a namespace.

For more information, see Audit Log.

Returns list of audit log events

Get audit log events for a given namespace.

path Parameters
account
required
string

Namespace to query audit logs for.

query Parameters
action
string

action name one of ["repo.tag.push", ...]. Optional parameter to filter specific audit log actions.

name
string

name. Optional parameter to filter audit log events to a specific name. For repository events, this is the name of the repository. For organization events, this is the name of the organization. For team member events, this is the username of the team member.

actor
string

actor name. Optional parameter to filter audit log events to the specific user who triggered the event.

from
string <date-time>

Start of the time window you wish to query audit events for.

to
string <date-time>

End of the time window you wish to query audit events for.

page
integer <int32>
Default: 1

page - specify page number. Page number to get.

page_size
integer <int32>
Default: 25

page_size - specify page size. Number of events to return per page.

Responses

Response samples

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

Returns list of audit log actions

Get audit log actions for a namespace to be used as a filter for querying audit events.

path Parameters
account
required
string

Namespace to query audit log actions for.

Responses

Response samples

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

Org Settings

The Org Settings API endpoints allow you to manage your organization's settings.

Get organization settings

Returns organization settings by name.

path Parameters
name
required
string

Name of the organization.

Responses

Response samples

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

Update organization settings

Updates an organization's settings. Some settings are only used when the organization is on a business plan.

Only users with administrative privileges for the organization (owner role) can modify these settings.

The following settings are only used on a business plan:

  • restricted_images
path Parameters
name
required
string

Name of the organization.

Request Body schema: application/json
required
required
object

Responses

Request samples

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

Response samples

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

Repositories

The repository endpoints allow you to access your repository's tags.

List repository tags

path Parameters
namespace
required
string
repository
required
string
query Parameters
page
integer

Page number to get. Defaults to 1.

page_size
integer

Number of items to get per page. Defaults to 10. Max of 100.

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "next": "string",
  • "previous": "string",
  • "results": [
    ]
}

Check repository tags

path Parameters
namespace
required
string
repository
required
string

Responses

Response samples

Content type
application/json
{
  • "detail": "string",
  • "message": "string"
}

Read repository tag

path Parameters
namespace
required
string
repository
required
string
tag
required
string

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "images": {
    },
  • "creator": 0,
  • "last_updated": "2021-01-05T21:06:53.506400Z",
  • "last_updater": 0,
  • "last_updater_username": "string",
  • "name": "string",
  • "repository": 0,
  • "full_size": 0,
  • "v2": "string",
  • "status": "active",
  • "tag_last_pulled": "2021-01-05T21:06:53.506400Z",
  • "tag_last_pushed": "2021-01-05T21:06:53.506400Z"
}

Check repository tag

path Parameters
namespace
required
string
repository
required
string
tag
required
string

Responses

Response samples

Content type
application/json
{
  • "detail": "string",
  • "message": "string"
}

SCIM

SCIM is a provisioning system that lets you manage users within your identity provider (IdP).

For more information, see System for Cross-domain Identity management.

Get service provider config

Returns a service provider config for Docker's configuration.

Authorizations:
None

Responses

Response samples

Content type
application/scim+json
{
  • "schemas": [
    ],
  • "documentationUri": "",
  • "patch": {
    },
  • "bulk": {
    },
  • "filter": {
    },
  • "changePassword": {
    },
  • "sort": {
    },
  • "etag": {
    },
  • "authenticationSchemes": {
    }
}

List resource types

Returns all resource types supported for the SCIM configuration.

Authorizations:
None

Responses

Response samples

Content type
application/scim+json
{
  • "schemas": [
    ],
  • "totalResults": 1,
  • "resources": [
    ]
}

Get a resource type

Returns a resource type by name.

Authorizations:
None
path Parameters
name
required
string
Example: User

Responses

Response samples

Content type
application/scim+json
{
  • "schemas": [
    ],
  • "id": "User",
  • "name": "User",
  • "description": "User",
  • "endpoint": "/Users",
  • "schema": "urn:ietf:params:scim:schemas:core:2.0:User"
}

List schemas

Returns all schemas supported for the SCIM configuration.

Authorizations:
None

Responses

Response samples

Content type
application/scim+json
{
  • "schemas": [
    ],
  • "totalResults": 1,
  • "resources": [
    ]
}

Get a schema

Returns a schema by ID.

Authorizations:
None
path Parameters
id
required
string
Example: urn:ietf:params:scim:schemas:core:2.0:User

Responses

Response samples

Content type
application/scim+json
{
  • "schemas": [
    ],
  • "id": "urn:ietf:params:scim:schemas:core:2.0:User",
  • "name": "User",
  • "description": "User Account",
  • "attributes": [ ]
}

List users

Returns paginated users for an organization. Use startIndex and count query parameters to receive paginated results.

Sorting:

Sorting allows you to specify the order in which resources are returned by specifying a combination of sortBy and sortOrder query parameters.

The sortBy parameter specifies the attribute whose value will be used to order the returned responses. The sortOrder parameter defines the order in which the sortBy parameter is applied. Allowed values are "ascending" and "descending".

Filtering:

You can request a subset of resources by specifying the filter query parameter containing a filter expression. Attribute names and attribute operators used in filters are case insensitive. The filter parameter must contain at least one valid expression. Each expression must contain an attribute name followed by an attribute operator and an optional value.

Supported operators are listed below.

  • eq equal
  • ne not equal
  • co contains
  • sw starts with
  • and Logical "and"
  • or Logical "or"
  • not "Not" function
  • () Precedence grouping
Authorizations:
None
query Parameters
startIndex
integer >= 1
Example: startIndex=1
count
integer [ 1 .. 200 ]
Example: count=10
filter
string
Example: filter=userName eq "jon.snow@docker.com"
attributes
string
Example: attributes=userName,displayName

Comma delimited list of attributes to limit to in the response.

sortOrder
string
Enum: "ascending" "descending"
sortBy
string
Example: sortBy=userName

User attribute to sort by.

Responses

Response samples

Content type
application/scim+json
{
  • "schemas": [
    ],
  • "totalResults": 1,
  • "startIndex": 1,
  • "itemsPerPage": 10,
  • "resources": [
    ]
}

Create user

Creates a user. If the user already exists by email, they are assigned to the organization on the "company" team.

Authorizations:
None
Request Body schema: application/scim+json
required
schemas
required
Array of strings (scim_user_schemas) [ items non-empty ]
userName
required
string (scim_user_username)

The user's email address. This must be reachable via email.

object (scim_user_name)

Responses

Request samples

Content type
application/scim+json
{
  • "schemas": [
    ],
  • "userName": "jon.snow@docker.com",
  • "name": {
    }
}

Response samples

Content type
application/scim+json
{
  • "schemas": [
    ],
  • "id": "d80f7c79-7730-49d8-9a41-7c42fb622d9c",
  • "userName": "jon.snow@docker.com",
  • "name": {
    },
  • "displayName": "jonsnow",
  • "active": true,
  • "emails": [
    ],
  • "groups": [
    ],
  • "meta": {}
}

Get a user

Returns a user by ID.

Authorizations:
None
path Parameters
id
required
string
Example: d80f7c79-7730-49d8-9a41-7c42fb622d9c

The user ID.

Responses

Response samples

Content type
application/scim+json
{
  • "schemas": [
    ],
  • "id": "d80f7c79-7730-49d8-9a41-7c42fb622d9c",
  • "userName": "jon.snow@docker.com",
  • "name": {
    },
  • "displayName": "jonsnow",
  • "active": true,
  • "emails": [
    ],
  • "groups": [
    ],
  • "meta": {}
}

Update a user

Updates a user. This route is used to change the user's name, activate, and deactivate the user.

Authorizations:
None
path Parameters
id
required
string
Example: d80f7c79-7730-49d8-9a41-7c42fb622d9c

The user ID.

Request Body schema: application/scim+json
required
schemas
required
Array of strings (scim_user_schemas) [ items non-empty ]
object

If this is omitted from the request, the update will skip the update on it. We will only ever change the name, but not clear it.

enabled
boolean
Default: false

If this is omitted from the request, it will default to false resulting in a deactivated user.

Responses

Request samples

Content type
application/scim+json
{
  • "schemas": [
    ],
  • "name": {
    },
  • "enabled": false
}

Response samples

Content type
application/scim+json
{
  • "schemas": [
    ],
  • "id": "d80f7c79-7730-49d8-9a41-7c42fb622d9c",
  • "userName": "jon.snow@docker.com",
  • "name": {
    },
  • "displayName": "jonsnow",
  • "active": true,
  • "emails": [
    ],
  • "groups": [
    ],
  • "meta": {}
}

Organizations

The organization endpoints allow you to interact with and manage your organizations.

For more information, see Organization administration overview.

List org members

Returns a list of members for an organization"

path Parameters
org_name
required
string
Example: myorganization

Name of the organization (namespace).

query Parameters
search
integer

Search term.

page
integer

Page number (starts on 1).

page_size
integer

Number of items (rows) per page.

invites
boolean

Include invites in the response.

type
string
Enum: "all" "invitee" "member"
Example: type=all
role
string
Enum: "owner" "editor" "member"
Example: role=owner

Responses

Response samples

Content type
application/json
[]

Export org members CSV

Export members of an organization as a CSV

path Parameters
org_name
required
string
Example: myorganization

Name of the organization (namespace).

Responses

Response samples

Content type
application/json
{
  • "errinfo": { },
  • "detail": "string",
  • "message": "string"
}

Update org member (role)

Updates the role of a member in the organization. Only users in the "owners" group of the organization can use this endpoint.

path Parameters
org_name
required
string
Example: myorganization

Name of the organization (namespace).

username
required
string
Example: jonsnow

Username, identifier for the user (namespace, DockerID).

Request Body schema: application/json
required
role
required
string
Enum: "owner" "editor" "member"

Role of the member

Responses

Request samples

Content type
application/json
{
  • "role": "owner"
}

Response samples

Content type
application/json
{
  • "email": "example@docker.com",
  • "role": "Owner",
  • "groups": [
    ],
  • "is_guest": false,
  • "primary_email": "example@docker.com",
  • "id": "0ab70deb065a43fcacd55d48caa945d8",
  • "company": "Docker Inc",
  • "date_joined": "2021-01-05T21:06:53.506400Z",
  • "full_name": "Jon Snow",
  • "gravatar_email": "string",
  • "gravatar_url": "string",
  • "location": "string",
  • "profile_url": "string",
  • "type": "User",
  • "username": "dockeruser"
}

Remove member from org

Removes the member from the org, ie. all groups in the org, unless they're the last owner

path Parameters
org_name
required
string
Example: myorganization

Name of the organization (namespace).

username
required
string
Example: jonsnow

Username, identifier for the user (namespace, DockerID).

Responses

Response samples

Content type
application/json
{
  • "errinfo": { },
  • "detail": "string",
  • "message": "string"
}

Groups (Teams)

The groups endpoints allow you to manage your organization's teams and their members.

For more information, seee Create and manage a team.

Get groups of an organization

path Parameters
org_name
required
string
Example: myorganization

Name of the organization (namespace).

query Parameters
page
integer

Page number (starts on 1).

page_size
integer

Number of items (rows) per page.

username
string

Get groups for the specified username in the organization.

search
string

Get groups for the specified group in the organization.

Responses

Response samples

Content type
application/json
{
  • "count": 1,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Create a new group

Create a new group within an organization.

path Parameters
org_name
required
string
Example: myorganization

Name of the organization (namespace).

Request Body schema: application/json
name
required
string
description
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": 10,
  • "uuid": "string",
  • "name": "mygroup",
  • "description": "Groups description",
  • "member_count": 10
}

Get a group of an organization

path Parameters
org_name
required
string
Example: myorganization

Name of the organization (namespace).

group_name
required
string
Example: developers

Name of the group (team) in the organization.

Responses

Response samples

Content type
application/json
{
  • "id": 10,
  • "uuid": "string",
  • "name": "mygroup",
  • "description": "Groups description",
  • "member_count": 10
}

Update the details for an organization group

path Parameters
org_name
required
string
Example: myorganization

Name of the organization (namespace).

group_name
required
string
Example: developers

Name of the group (team) in the organization.

Request Body schema: application/json
name
required
string
description
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": 10,
  • "uuid": "string",
  • "name": "mygroup",
  • "description": "Groups description",
  • "member_count": 10
}

Update some details for an organization group

path Parameters
org_name
required
string
Example: myorganization

Name of the organization (namespace).

group_name
required
string
Example: developers

Name of the group (team) in the organization.

Request Body schema: application/json
name
string
description
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": 10,
  • "uuid": "string",
  • "name": "mygroup",
  • "description": "Groups description",
  • "member_count": 10
}

Delete an organization group

path Parameters
org_name
required
string
Example: myorganization

Name of the organization (namespace).

group_name
required
string
Example: developers

Name of the group (team) in the organization.

Responses

Response samples

Content type
application/json
{
  • "errinfo": { },
  • "detail": "string",
  • "message": "string"
}

List members of a group

List the members (users) that are in a group. If user is owner of the org or has otherwise elevated permissions, they can search by email and the result will also contain emails.

path Parameters
org_name
required
string
Example: myorganization

Name of the organization (namespace).

group_name
required
string
Example: developers

Name of the group (team) in the organization.

query Parameters
page
integer

Page number (starts on 1).

page_size
integer

Number of items (rows) per page.

search
string

Search members by username, full_name or email.

Responses

Response samples

Content type
application/json
{
  • "count": 1,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Adds a member to a group

path Parameters
org_name
required
string
Example: myorganization

Name of the organization (namespace).

group_name
required
string
Example: developers

Name of the group (team) in the organization.

Request Body schema: application/json
required
member
required
string

Responses

Request samples

Content type
application/json
{
  • "member": "jonsnow"
}

Response samples

Content type
application/json
{
  • "errinfo": { },
  • "detail": "string",
  • "message": "string"
}

Removes a user from a group

path Parameters
org_name
required
string
Example: myorganization

Name of the organization (namespace).

group_name
required
string
Example: developers

Name of the group (team) in the organization.

username
required
string
Example: jonsnow

Username, identifier for the user (namespace, DockerID).

Responses

Response samples

Content type
application/json
{
  • "errinfo": { },
  • "detail": "string",
  • "message": "string"
}

Invites

The invites endpoints allow you to manage invites for users to join your Docker organization.

For more information, see Invite members.

List org invites

Return all pending invites for a given org, only team owners can call this endpoint

path Parameters
org_name
required
string
Example: myorganization

Name of the organization (namespace).

Responses

Response samples

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

Cancel an invite

Mark the invite as cancelled so it doesn't show up on the list of pending invites

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "errinfo": { },
  • "detail": "string",
  • "message": "string"
}

Resend an invite

Resend a pending invite to the user, any org owner can resend an invite

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "errinfo": { },
  • "detail": "string",
  • "message": "string"
}

Bulk create invites

Create multiple invites by emails or DockerIDs. Only a team owner can create invites.

header Parameters
X-Analytics-Client-Feature
string

Optional string that indicates the feature used to submit the bulk invites (e.g.'file', 'web')

Request Body schema: application/json
required
org
required
string

organization name

team
string

team name

role
string

role for invitees

invitees
required
Array of strings

list of invitees emails or Docker Ids

dry_run
boolean

Optional, run through validation but don't actually change data.

Responses

Request samples

Content type
application/json
{
  • "org": "docker",
  • "team": "owners",
  • "role": "member",
  • "invitees": [
    ],
  • "dry_run": true
}

Response samples

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