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.

Authentication

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

Additionally, similar to the Docker Hub UI features, API endpoint responses may vary depending on your plan (Free, 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 authentication token

Creates an authentication token that can be used to authenticate with the Docker Hub APIs.

The returned token is used in the HTTP Authentication header like Authentication: JWT {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

Login details.


username
string Required

The username of the Docker Hub account to authenticate with.
password
string Required

The password of the Docker Hub account to authenticate with.

Responses

200 Authentication successful
Response Schema

401 Authentication failed
Response Schema
post
/v2/users/login

Server URL

/v2/users/login
Request samples
Copy Expand all Collapse all 
{
  • "username": "myusername",
  • "password": "hunter2"
}

Response samples

  • 200 Authentication successful

  • 401 Authentication failed

Copy Expand all Collapse all 
{
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
Copy Expand all Collapse all 
{
  • "details": "Incorrect authentication credentials"
}

Advanced image management

The Advanced Image Management API endpoints allow you to manage Docker images across all repositories. For more information, see Advanced Image Management dashboard.

Get summary of repository's images

Gets the number of images in a repository and the number of images counted as active and inactive.

Parameters
path Parameters ?
namespace
string Required

Namespace of the repository.

repository
string Required

Name of the repository.

query Parameters ?
active_from
string

Sets the time from which an image must have been pushed or pulled to be counted as active.

Defaults to 1 month before the current time.

Responses

200 Success
Response Schema

401 Unauthorized - user does not have read access to the namespace
Response Schema
get
/v2/namespaces/{namespace}/repositories/{repository}/images-summary

Server URL

/v2/namespaces/{namespace}/repositories/{repository}/images-summary

Response samples

  • 200 Success

  • 401 Unauthorized - user does not have read access to the namespace

Copy Expand all Collapse all 
{
  • "active_from": "2021-01-25T14:25:37.076343059Z",
  • "statistics": 
    {
    }
}
Copy Expand all Collapse all 
{
  • "txnid": "string",
  • "message": "string",
  • "errinfo": 
    {
    }
}

Get details of repository's images

Gets details on the images in a repository.

Parameters
path Parameters ?
namespace
string Required

Namespace of the repository.

repository
string Required

Name of the repository.

query Parameters ?
status
string
"active" "inactive"

Filters to only show images of this status.

currently_tagged
boolean

Filters to only show images with:

  • true: at least 1 current tag.
  • false: no current tags.
ordering
string
"last_activity" "-last_activity" "digest" "-digest"

Orders the results by this property.

Prefixing with - sorts by descending order.

active_from
string

Sets the time from which an image must have been pushed or pulled to be counted as active.

Defaults to 1 month before the current time.

page
integer

Page number to get. Defaults to 1.

page_size
integer

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

Responses

200 Success
Response Schema

401 Unauthorized - user does not have read access to the namespace.
Response Schema

403 Forbidden - this API is only available to users on Pro or Team plans.
Response Schema
get
/v2/namespaces/{namespace}/repositories/{repository}/images

Server URL

/v2/namespaces/{namespace}/repositories/{repository}/images

Response samples

  • 200 Success

  • 401 Unauthorized - user does not have read access to the namespace.

  • 403 Forbidden - this API is only available to users on Pro or Team plans.

Copy Expand all Collapse all 
{}
Copy Expand all Collapse all 
{
  • "txnid": "string",
  • "message": "string",
  • "errinfo": 
    {
    }
}
Copy Expand all Collapse all 
{
  • "txnid": "string",
  • "message": "string",
  • "errinfo": 
    {
    }
}

Get image's tags

Gets current and historical tags for an image.

Parameters
path Parameters ?
namespace
string Required

Namespace of the repository.

repository
string Required

Name of the repository.

digest
string Required

Digest of the image.

query Parameters ?
page
integer

Page number to get. Defaults to 1.

page_size
integer

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

Responses

200 Success
Response Schema

401 Unauthorized - user does not have read access to the namespace
Response Schema

403 Forbidden - this API is only available to users on Pro or Team plans
Response Schema
get
/v2/namespaces/{namespace}/repositories/{repository}/images/{digest}/tags

Server URL

/v2/namespaces/{namespace}/repositories/{repository}/images/{digest}/tags

Response samples

  • 200 Success

  • 401 Unauthorized - user does not have read access to the namespace

  • 403 Forbidden - this API is only available to users on Pro or Team plans

Copy Expand all Collapse all 
{}
Copy Expand all Collapse all 
{
  • "txnid": "string",
  • "message": "string",
  • "errinfo": 
    {
    }
}
Copy Expand all Collapse all 
{
  • "txnid": "string",
  • "message": "string",
  • "errinfo": 
    {
    }
}

Delete images

Deletes one or more images within a namespace. This is currently limited to a single repostiory.

If you attempt to delete images that are marked as active or are currently tagged, the deletion does not happen and it displays the warnings. To continue with the deletion, you must ignore these warnings by putting them in the ignore_warnings property.

Deleting a currently tagged image deletes the tag from the repository.

You cannot ignore errors. It is not possible to directly delete children of multi-arch images.

Parameters
path Parameters ?
namespace
string Required

Namespace of the repository.

Request Body

Delete request.


dry_run
boolean

If true then will check and return errors and unignored warnings for the deletion request but will not delete any images.
active_from
string

Sets the time from which an image must have been pushed or pulled to be counted as active.

Defaults to 1 month before the current time.
manifests
object

Image manifests to delete.
ignore_warnings
object

Warnings to ignore. If a warning is not ignored then no deletions will happen and the warning is returned in the response.

These warnings include:

  • is_active: warning when attempting to delete an image that is marked as active.

  • current_tag: warning when attempting to delete an image that has one or more current tags in the repository.

Warnings can be copied from the response to the request.

Responses

200 Deletion completed
Response Schema

400 Deletion not possible
Response Schema

403 Forbidden - this API is only available to users on Pro or Team plans
Response Schema
post
/v2/namespaces/{namespace}/delete-images

Server URL

/v2/namespaces/{namespace}/delete-images
Request samples
Copy Expand all Collapse all 
{
  • "dry_run": false,
  • "active_from": "2020-12-01T12:00:00Z",
  • "manifests": 
    [
    ],
  • "ignore_warnings": 
    [
    ]
}

Response samples

  • 200 Deletion completed

  • 400 Deletion not possible

  • 403 Forbidden - this API is only available to users on Pro or Team plans

Copy Expand all Collapse all 
{
  • "dry_run": false,
  • "metrics": 
    {
    }
}
Copy Expand all Collapse all 
{
  • "txnid": "string",
  • "message": "string",
  • "errinfo": 
    {
    }
}
Copy Expand all Collapse all 
{
  • "txnid": "string",
  • "message": "string",
  • "errinfo": 
    {
    }
}

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.

Parameters
path Parameters ?
account
string Required

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>
1

page - specify page number. Page number to get.

page_size
integer <int32>
25

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

Responses

200 A successful response.
Response Schema

429
Response Schema

500
Response Schema

default An unexpected error response.
Response Schema
get
/v2/auditlogs/{account}

Server URL

/v2/auditlogs/{account}

Response samples

  • 200 A successful response.

  • 429

  • 500

  • default An unexpected error response.

Copy Expand all Collapse all 
{
  • "logs": 
    [
    ]
}
Copy Expand all Collapse all 
{
  • "detail": "Rate limit exceeded",
  • "error": false
}
 
 Sample unavailable
Copy Expand all Collapse all 

  



  




  
    


  

    
    
    

       Copy 
       Expand all 
       Collapse all 
    

    
{
  • "code": 0,
  • "message": "string",
  • "details": 
    [
    ]
}

  



  






    

  





  

    

        Returns list of audit log actions.
    

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



    
    
 Parameters 


  

    path Parameters
    ?
  

  

    

        

           account 
        

        

          

            
             string 
            
            Required
            
            
            
            
          

          
Namespace to query audit log actions for.



        

    

  





    
 Responses 



  

    
      
        
      
    
    
200 A successful response.


  

  

    
  
  

    Response Schema
  

  

  





  

    
      
        
      
    
    
429


  

  

    
  
  

    Response Schema
  

  

  





  

    
      
        
      
    
    
500


  

  

    
  
  

    Response Schema
  

  

  





  

    
      
        
      
    
    
default An unexpected error response.


  

  

    
  
  

    Response Schema
  

  

  





  

  


    

  
get

  /v2/auditlogs/{account}/actions
  
    
  




  

    
Server URL



    

       /v2/auditlogs/{account}/actions
    

  





    

        
    

    

        

        
 Response samples 


    
  
  • 200 A successful response.
    

  • 429
    

  • 500
    

  • default An unexpected error response.
    

    • 



  

  
    


  

    
    
    

       Copy 
       Expand all 
       Collapse all 
    

    
{
  • "actions": 
    {
    }
}

  



  




  
    


  

    
    
    

       Copy 
       Expand all 
       Collapse all 
    

    
{
  • "detail": "Rate limit exceeded",
  • "error": false
}

  



  




  
    


  

    
    
 Sample unavailable 

    

       Copy 
       Expand all 
       Collapse all 
    

    

  



  




  
    


  

    
    
    

       Copy 
       Expand all 
       Collapse all 
    

    
{
  • "code": 0,
  • "message": "string",
  • "details": 
    [
    ]
}