A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Docker Hub API is how an app or AI agent works with a Docker Hub account: listing and creating repositories, reading the tags published to an image, managing access tokens, and reviewing an organization's members and audit log. Access is granted by exchanging a Docker ID and a personal access token for a short-lived bearer token, and the scopes on that token, such as read-only or read and write, set what each call can reach. Docker ships changes to the API through a dated changelog rather than new version numbers.
How an app or AI agent connects to Docker Hub determines what it can reach. Each route is governed by the token behind it and the scopes that token carries.
The Docker Hub API answers at https://hub.docker.com over HTTPS, with resources under the /v2 path. Calls send a bearer token in JWT format, obtained by exchanging a Docker ID and a personal access token.
Docker's first-party Docker Hub MCP Server lets an agent call Docker Hub through the Model Context Protocol. It runs locally as a Node process and exposes tools such as searching the catalogue, listing repositories by namespace, listing repository tags, and creating a repository. The source is at github.com/docker/hub-mcp, and it authenticates with a Docker ID and a personal access token.
A personal access token is exchanged, with a Docker ID, for a bearer token, and its scope, from public read only up to full administration, bounds everything done with it. It is the recommended credential for automation and is required instead of a password when single sign-on is enforced.
An organization access token authenticates as the organization rather than an individual, so the access does not depend on any one person's account. It is created and revoked through the organization access token methods.
A Docker ID and account password can be exchanged for a bearer token, but a personal access token is recommended instead, and a password is not accepted when the organization enforces single sign-on.
The Docker Hub API is split into areas an agent can act on, such as repositories, tags, access tokens, organization members, and audit logs. Each area has its own methods and its own scopes, and some grant access to far more than others.
Exchange a Docker ID and a personal access token for a short-lived bearer token, complete two-factor authentication, and use the older login route.
List the repositories in a namespace, read or check a single repository, create a repository, and manage its immutable-tag rules and group access.
List the tags published to a repository, read a single tag, and check whether a tag or any tags exist.
List, read, create, update, and delete the personal access tokens on an account.
List, read, create, update, and delete the access tokens that belong to an organization.
List organization members, change a member's role, remove a member, and manage the groups, called teams, inside an organization.
Read an organization's settings and update them, including which images members are allowed to use.
List the audit log events for an account and list the action types available to filter that log.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
AuthenticationExchange a Docker ID and a personal access token for a short-lived bearer token, complete two-factor authentication, and use the older login route.3 | ||||||
| POST | /v2/auth/token | Exchange a Docker ID and a secret for a short-lived bearer token in JWT format. | read | — | Current | |
Needs no scope; it authenticates with the identifier and secret in the body. The secret can be a personal access token, an organization access token, or a password. This is the current route, replacing the deprecated login method. Acts ontoken Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/users/login | Create a bearer token in JWT format from a Docker ID and a secret (deprecated). | read | — | Current | |
Deprecated in favour of the create access token method, but still functional. As of 16 September 2024 it requires a personal access token instead of a password when the organization enforces single sign-on. Acts ontoken Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/users/2fa-login | Complete two-factor authentication and return a bearer token after the login method. | read | — | Current | |
Called after the login method when the account has two-factor authentication enabled, to obtain the usable bearer token. Acts ontoken Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
RepositoriesList the repositories in a namespace, read or check a single repository, create a repository, and manage its immutable-tag rules and group access.6 | ||||||
| GET | /v2/namespaces/{namespace}/repositories | List the repositories in a namespace, with filtering and ordering. | read | repo:read | New | |
Public repositories are returned anonymously; private ones need at least repo:read. This namespace-scoped method replaced the legacy listing route, deprecated on 27 June 2025. Acts onrepository Permission (capability) repo:readVersionIntroduced 2025-06-27 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/namespaces/{namespace}/repositories | Create a repository in a namespace with its name, description, and privacy. | write | repo:write | New | |
Introduced on 19 September 2025 alongside the namespace-scoped read methods, replacing the legacy create route. Acts onrepository Permission (capability) repo:writeVersionIntroduced 2025-09-19 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/namespaces/{namespace}/repositories/{repository} | Get a single repository in a namespace. | read | repo:read | New | |
A public repository is returned anonymously; a private one needs at least repo:read. Acts onrepository Permission (capability) repo:readVersionIntroduced 2025-09-19 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/namespaces/{namespace}/repositories/{repository} | Check whether a repository exists in a namespace without returning its body. | read | repo:read | New | |
Returns 200 when the repository exists and the token can see it, and 404 otherwise. A public repository can be checked anonymously. Issued as an HTTP HEAD request, so it returns headers only with no response body. Acts onrepository Permission (capability) repo:readVersionIntroduced 2025-09-19 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v2/namespaces/{namespace}/repositories/{repository}/immutabletags | Update the immutable-tag rules for a repository, which prevent matching tags from being overwritten. | write | repo:admin | New | |
Only a user with administrative privileges on the repository can change these settings. Added on 29 July 2025. Acts onrepository Permission (capability) repo:adminVersionIntroduced 2025-07-29 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/repositories/{namespace}/{repository}/groups | Assign a group, called a team, to a repository with a chosen permission. | write | repo:admin | Current | |
Grants a team read or write access to the repository. Request and response formatting on this method was corrected on 25 September 2025. Acts onrepository Permission (capability) repo:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TagsList the tags published to a repository, read a single tag, and check whether a tag or any tags exist.3 | ||||||
| GET | /v2/namespaces/{namespace}/repositories/{repository}/tags | List the tags published to a repository. | read | repo:read | Current | |
Paginated through page and page_size, where page_size tops out at 100. Tags on a public repository can be listed anonymously. Acts ontag Permission (capability) repo:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/namespaces/{namespace}/repositories/{repository}/tags/{tag} | Read a single tag in a repository. | read | repo:read | Current | |
A tag on a public repository can be read anonymously. Acts ontag Permission (capability) repo:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/namespaces/{namespace}/repositories/{repository}/tags/{tag} | Check whether a tag exists in a repository without returning its body. | read | repo:read | Current | |
Returns 200 when the tag exists and the token can see it, and 404 otherwise. Issued as an HTTP HEAD request, so it returns headers only with no response body. Acts ontag Permission (capability) repo:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Personal access tokensList, read, create, update, and delete the personal access tokens on an account.5 | ||||||
| GET | /v2/access-tokens | List the personal access tokens on the authenticated account. | read | repo:read | Current | |
Returns token metadata, not the secret values. Paginated through page and page_size. Acts onaccess token Permission (capability) repo:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/access-tokens | Create a personal access token and return its secret once. | write | repo:admin | Current | |
The new token's secret is returned only in this response and cannot be retrieved later. The token's own scope is chosen at creation. The expires_at field was added on 21 November 2025. Acts onaccess token Permission (capability) repo:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/access-tokens/{uuid} | Get a single personal access token by its identifier. | read | repo:read | Current | |
Returns metadata without the secret value. Acts onaccess token Permission (capability) repo:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v2/access-tokens/{uuid} | Update a personal access token's label or enable or disable it. | write | repo:admin | Current | |
Changes the label or active state; it does not change the token's scope. Acts onaccess token Permission (capability) repo:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/access-tokens/{uuid} | Delete a personal access token permanently. | write | repo:admin | Current | |
This cannot be undone, and any integration using the token loses access immediately. Acts onaccess token Permission (capability) repo:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Organization access tokensList, read, create, update, and delete the access tokens that belong to an organization.3 | ||||||
| GET | /v2/orgs/{name}/access-tokens | List the access tokens that belong to an organization. | read | repo:admin | Current | |
Organization access token management was introduced on 25 March 2025. Reading them needs organization administrative access. Acts onaccess token Permission (capability) repo:adminVersionIntroduced 2025-03-25 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/orgs/{name}/access-tokens | Create an access token for an organization. | write | repo:admin | Current | |
An organization access token authenticates as the organization rather than a person. Its secret is returned only at creation. Acts onaccess token Permission (capability) repo:adminVersionIntroduced 2025-03-25 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/orgs/{org_name}/access-tokens/{access_token_id} | Delete an organization's access token permanently. | write | repo:admin | Current | |
This cannot be undone, and any integration using the token loses access immediately. Acts onaccess token Permission (capability) repo:adminVersionIntroduced 2025-03-25 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Members & teamsList organization members, change a member's role, remove a member, and manage the groups, called teams, inside an organization.5 | ||||||
| GET | /v2/orgs/{org_name}/members | List the members of an organization. | read | repo:admin | Current | |
Reading the member roster needs organization administrative access. Acts onmember Permission (capability) repo:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v2/orgs/{org_name}/members/{username} | Update an organization member's role. | write | repo:admin | Current | |
Changes what the member can do across the organization. Needs organization administrative access. Acts onmember Permission (capability) repo:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/orgs/{org_name}/members/{username} | Remove a member from an organization. | write | repo:admin | Current | |
The removed member loses access to the organization's repositories. Needs organization administrative access. Acts onmember Permission (capability) repo:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/orgs/{org_name}/groups | List the groups, called teams, in an organization. | read | repo:admin | Current | |
A group is the unit a repository's access is granted to. Reading them needs organization administrative access. Acts ongroup Permission (capability) repo:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/orgs/{org_name}/groups | Create a group, called a team, in an organization. | write | repo:admin | Current | |
Members are added to the group separately, and the group is then granted access to repositories. Acts ongroup Permission (capability) repo:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Organization settingsRead an organization's settings and update them, including which images members are allowed to use.2 | ||||||
| GET | /v2/orgs/{name}/settings | Get an organization's settings. | read | repo:admin | Current | |
Includes which images members are restricted to. Some settings apply only on a business subscription. Acts onorganization Permission (capability) repo:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v2/orgs/{name}/settings | Update an organization's settings, such as which images members may use. | write | repo:admin | Current | |
Only a user with the owner role can modify these settings. The restricted images setting applies only on a business subscription. Acts onorganization Permission (capability) repo:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Audit logsList the audit log events for an account and list the action types available to filter that log.2 | ||||||
| GET | /v2/auditlogs/{account} | List the audit log events for an account. | read | repo:admin | Current | |
Records who did what and when across the organization. Access to organization access token events was added on 18 March 2025. Acts onaudit event Permission (capability) repo:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/auditlogs/{account}/actions | List the audit log action types available to filter the event log. | read | repo:admin | Current | |
Returns the catalogue of action names, such as plan and member actions, used as filters when querying events. Acts onaudit event Permission (capability) repo:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Docker Hub does not document push or autobuild webhooks in its current API reference, so this Atlas does not list webhook events. Repository webhooks are configured in the Docker Hub interface, and the events they send are outside the documented v2 API.
| Event | What it signals | Triggered by |
|---|
Docker Hub does not publish a per-method rate limit for its management API in the API reference. The well-known Docker Hub pull rate limits apply to the separate image registry, not to the calls listed here.
Docker Hub does not state a per-method rate limit for the management API in its API reference, so this Atlas does not attach a numeric limit to each method. The separate image registry has its own well-known pull rate limits, decided by plan and whether the puller is signed in, but those govern pulling images, not the management calls listed here. An agent should still back off and retry when a response signals throttling.
List methods use page-number pagination through the page and page_size query parameters. page_size defaults to 10 and tops out at 100 on the repository and tag listings. A list response carries a count of total items along with next and previous URLs, and the next URL should be followed rather than built by hand.
Requests and responses are JSON. Listings are capped through page_size, which reaches at most 100 items per page on the documented list methods, so large result sets are read across multiple pages.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request was malformed or a parameter was invalid, such as an unrecognized ordering value on the repository listing. | Read the error body, correct the named field or parameter, and resend. |
| 401 | Unauthorized | Authentication is missing or the bearer token is invalid or expired. The bearer token returned by the authentication methods is short-lived. | Obtain a fresh bearer token through the create access token method and resend with a valid Authorization header. |
| 403 | Forbidden | The token is valid but its scope or the account's role does not permit the action, such as a read-only token attempting a write or a non-owner changing organization settings. | Use a token with a higher scope, such as repo:write or repo:admin, or have an owner perform the action. |
| 404 | Not Found | The resource does not exist, or the token cannot see a private resource. A private repository a token cannot reach can appear as not found. | Confirm the namespace and name are correct and the token has access to the resource. |
The Docker Hub API is labelled 2-beta in its specification, and Docker ships dated changes through a published changelog rather than minting new version numbers. The newest dated change is 21 November 2025.
The Docker Hub API is labelled 2-beta in its specification and answers at a single base URL. Rather than minting new dated versions, Docker publishes a changelog of added endpoints and deprecations, and the entries below are the notable dated changes from that changelog.
The personal access token management methods began returning an expires_at field, so an integration can see when a token will stop working.
New methods to create, read, and check a repository within a namespace were added, and the legacy repository methods were deprecated. The assign repository group method had its request and response formatting corrected on 25 September 2025.
Methods were added to update and verify a repository's immutable-tag rules, which prevent matching tags from being overwritten.
The method to list repositories within a namespace was added, and the legacy listing route was deprecated.
Organization access token management methods were introduced, letting automation authenticate as an organization rather than a person. Audit log access was extended to organization access token events on 18 March 2025.
An integration calls the same base URL and follows the changelog for added endpoints and deprecations.
Docker Hub API changelog ↗Bollard AI sits between a team's AI agents and Docker Hub. Grant each agent exactly the access it needs, read or write, repository by repository, and every call is checked and logged.