@netlify /reference/api/
[Preview the API
reference](https://deploy-preview-26048--docsdocker.netlify.app/reference/api/)
Adds a shared API reference experience for Hub, DVP, and Registry: a
catalog, operation navigation, linked schemas, request and response
examples, and matching HTML and Markdown output. A validation and
generation pipeline prepares the reference data for Hugo and runs as
part of Docker and Netlify builds.
Migrates the three specifications to OpenAPI 3.2, correcting response
shapes, nullable fields, and authentication and token examples. The Hub
migration also corrects SCIM contracts and CSV exports; DVP gains
complete report response schemas and examples. Registry keeps its
documented Hub-specific subset, with authentication and media
negotiation expressed through OpenAPI security and content fields.
Validation is strict for both checks and generation, with no exception
baseline or bypass flag. The build uses the migrated sources directly,
without migration scripts or records.
Page and specification URLs remain stable, including the DVP alias.
Operation and schema anchors change. Engine and Governance retain their
existing references.
Validated locally with Go tests, strict validation of all three
specifications (zero diagnostics), scoped formatting and lint, and a
full Hugo build checking all 176 HTML/Markdown page pairs, example
parity, reference links, and byte-identical published specifications. A
browser check confirmed raw CSV rendering and the generated request
header. No live API requests were made.
# To dos
~- Evaluate _index pages and standardize across account + admins
category~
~- Edit weights of topics~
- Notify TSEs, other stakeholders
- TW sign off
## Summary
This PR restructures the Platform documentation into a clearer Accounts,
Security, and Subscription and billing information architecture, with
aliases so existing URLs keep working.
Work from these PRs was merged into this feature branch:
- #25957 (Security IA)
- #25960 (Accounts and Admin)
- #25981 (Subscription and billing)
### Accounts
- Moves organization, company, and admin content under Accounts.
- Splits individual-account docs into their own subsection.
- Removes the standalone Admin section; those pages now live under
Accounts.
### Security
- Publishes Security at `/security/`, matching other Platform sections.
- Groups authentication (SSO, 2FA, OIDC), access tokens, provisioning,
and roles under Security.
- Leaves Enterprise Hardened Desktop and related enterprise security
docs under Enterprise.
- Restores shipped Hardened Desktop and security FAQ URLs so they match
`main`.
### Subscription and billing
- Merges Subscription and Billing into a single Subscription and billing
section.
- Drops the extra subcategory wrappers and nests billing tasks under
Manage.
- Shortens the billing details sidebar label.
### FAQs
- Consolidates Platform FAQs onto four pages: Accounts, Security,
Subscription and billing, and Platform.
- Folds leftover general, container, and network/VM security FAQs into
Platform FAQs.
- Folds SSO enforcement FAQs into the SSO FAQ.
- Templates FAQ pages with H2 topics and H3 questions, and limits the
table of contents to H2.
### Navigation and follow-ups
- Renames the manuals sidebar group from Platform to Accounts and admin,
and updates the manuals landing heading and copy to match.
- Fixes the MSI install Settings Management link after the security path
move.
- Updates CODEOWNERS, the labeler, and in-repo links to the new paths.
---------
Co-authored-by: Cursor <cursoragent@cursor.com>
## Summary
- Document that member `PUT` `role` accepts a custom role **name**, not
only `owner` | `editor` | `member`.
- Document `role` on team `PATCH` (core or custom role name) and on
`org_group` so the PATCH 200 can include the assigned role.
- Add `Editor` to `org_member.role` (title case). Live responses already
return it; the old enum was Owner / Member / Invitee only.
## Test plan
PM must confirm before merge:
- [ ] Member PUT 200: after assigning a custom role (body is not the
previous core role), is `role` still a core value (`Owner` / `Editor` /
`Member`), or is it the custom role **name**? If it is the custom name,
drop the `org_member.role` enum in a follow-up and describe a string
(core or custom name). If it stays a core value, this PR's enum (`Owner`
| `Editor` | `Member` | `Invitee`) is enough.
- [ ] List members: same field. Confirm a user with a custom role lists
as a core value vs the custom name.
- [ ] Casing: request stays lowercase (`editor`); response stays title
case (`Editor`). Confirm that split is real.
- [ ] Team PATCH 200: confirm `org_group.role` is present and is the
value just set (core or custom name).
- [ ] Team assignment is PATCH-only, not PUT.
- [ ] Unknown role names return an error; do not document them as valid.
- [ ] Custom role **name** (not label or UUID) is the request
identifier, matching Docker Home.
---------
Co-authored-by: Cursor <cursoragent@cursor.com>
## Summary
Documents which Docker Hub API endpoints accept org access token (OAT)
authentication, and the scope-dependent listing behavior for repository
listing.
### Changes
- **`content/reference/api/hub/latest.yaml`**: Added `<span
class="oat"></span>` markers to 11 repository endpoint groups under
`/v2/namespaces/{namespace}/repositories/`. Includes a note on
scope-based listing behavior for `GET
/v2/namespaces/{namespace}/repositories`.
- **`content/manuals/enterprise/security/access-tokens.md`**: New "Hub
API support" section covering supported endpoint categories and the
`scope-repository-list` listing behavior.
### OAT listing behavior
`GET /v2/namespaces/{namespace}/repositories`:
- OAT **with** `scope-repository-list` → returns all repos including
private
- OAT **without** that scope → returns only public repos
## Test plan
- [ ] Preview site renders `<span class="oat">` badge on repo endpoints
- [ ] Hub API support section appears correctly in access-tokens manual
page
- [ ] Listing behavior note is clear and accurate
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Alexa Kristensen <81787716+akristen@users.noreply.github.com>
PR to capture work:
- Update / simplify titles to match docs
- Create subcategories within org/company
- Wrestle with redirect nightmare part 2
Filing a follow up PR to create parallel structure in the `Company`
subcategory. This PR's scope is for `Organization` only.
Fixes discrepancies in the Docker Hub organization access token API
documentation to match actual API behavior.
Changes:
- Removed `created_by` field from create endpoint response (API only
returns `created_at`)
- Updated scope examples from `repo-pull` to `scope-image-pull` (correct
format with `scope-` prefix)
- Enhanced repository path documentation with validation requirements
for TYPE_REPO resources
These changes align the OpenAPI specification with the actual API
implementation as discovered during Terraform provider development.
Fixes#24406
---------
Co-authored-by: David Karlsson <dvdksn@users.noreply.github.com>
## Description
In order to better attribute upgrade sources, we are adding two params -
`ref` and `refAction` to the existing pricing url.
The `ref` will be "Docs" and the `refAction` will be the particular docs
page from where the pricing url click is originated.
## Related issues or tickets
https://docker.atlassian.net/browse/GRO-282
## Reviews
@akristen You should see the new url params when hovering over or
clicking any of the updated pricing urls
- [ ] Technical review
- [ ] Editorial review
- [ ] Product review
---------
Co-authored-by: Alexa Kristensen <81787716+akristen@users.noreply.github.com>
<!--Delete sections as needed -->
## Description
Adds the Offload activity log events to the activity-logs documentation.
Adds all activity log actions to the audit-logs API spec.
## Related issues or tickets
<!-- Related issues, pull requests, or Jira tickets -->
## Reviews
<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->
- [ ] Technical review
- [ ] Editorial review
- [ ] Product review
---------
Signed-off-by: Nick Adcock <nick.adcock@docker.com>
<!--Delete sections as needed -->
## Description
[docker-hub-api] Fix `Assign repository group` endpoints
request/response.
see https://github.com/docker/hub-feedback/issues/2495
<!-- Tell us what you did and why -->
## Related issues or tickets
<!-- Related issues, pull requests, or Jira tickets -->
## Reviews
<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->
- [x] Technical review
- [ ] Editorial review
- [ ] Product review
<!--Delete sections as needed -->
## Description
<!-- Tell us what you did and why -->
Add `Create repository` endpoint
## Related issues or tickets
<!-- Related issues, pull requests, or Jira tickets -->
## Reviews
<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->
- [x] Technical review
- [ ] Editorial review
- [ ] Product review
<!--Delete sections as needed -->
## Description
<!-- Tell us what you did and why -->
[docker-hub-api] Add repository immutable tags endpoints to update
settings and validate regex before update.
## Related issues or tickets
<!-- Related issues, pull requests, or Jira tickets -->
- https://docker.atlassian.net/browse/RG-3017
- https://docker.atlassian.net/browse/RG-3018
## Reviews
<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->
- [x] Technical review
- [ ] Editorial review
- [ ] Product review
<!--Delete sections as needed -->
## Description
- Add "new" list repositories in a given namespace endpoint : `GET
/v2/namespaces/{namespace}/repositories`
---
After the comments from @thaJeztah
- Split DVP Data API and Docker Hub API for better visiblity
- Standardize sub entries in the side menu : Changelog, Deprecated and
OpenAPI
- Deprecated is now a table like in
https://docs.docker.com/engine/deprecated/
## Related issues or tickets
- https://github.com/docker/hub-feedback/issues/2357
## Reviews
<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->
- [x] Technical review
- [ ] Editorial review
- [ ] Product review
<!--Delete sections as needed -->
## Description
<!-- Tell us what you did and why -->
## Related issues or tickets
<!-- Related issues, pull requests, or Jira tickets -->
https://docker.atlassian.net/browse/IAM-1301
## Reviews
<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->
- [ ] Technical review
- [ ] Editorial review
- [ ] Product review
Adding API documentation for assign a group (Team) to a repository for
access
<!--Delete sections as needed -->
## Description
<!-- Tell us what you did and why -->
## Related issues or tickets
<!-- Related issues, pull requests, or Jira tickets -->
## Reviews
<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->
- [ ] Technical review
- [ ] Editorial review
- [ ] Product review
---------
Co-authored-by: Sarah Sanders <sarah.sanders@docker.com>
<!--Delete sections as needed -->
## Description
- Adds missing information for org members calls.
- Improves some areas of the docs.
## Reviews
<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->
- [x] Technical review
- [x] Editorial review
- [ ] Product review
<!--Delete sections as needed -->
## Description
This improves our authentication docs in our API. Additionally, we need
to note on certain routes where OAT bearers are allowed.
## Related issues or tickets
<!-- Related issues, pull requests, or Jira tickets -->
## Reviews
<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->
- [x] Technical review
- [x] Editorial review
- [ ] Product review
---------
Co-authored-by: Sarah Sanders <sarah.sanders@docker.com>
