docs: add Enterprise Data API reference and usage reports guide

[cassio-paesleme]

Summary

• Adds OpenAPI 3.0 spec and API reference page for the Docker Enterprise Data API at /reference/api/enterprise-data/
• Adds feature guide for enterprise usage reports at /manuals/enterprise/reports/

Context

Docker Enterprise subscribers will be able to programmatically export organization usage reports (pull data) via api.docker.com/enterprise-data/v1/. This is a new API surface, separate from the Hub API, supporting both PAT and OAT authentication.

Related PRs:

• API implementation: docker/data-platform#817
• FGA scope for OAT auth: docker/iam-services#1029

New pages

Path	Description
/reference/api/enterprise-data/api.yaml	OpenAPI 3.0 spec (4 endpoints: list types, list reports, download, schema)
/reference/api/enterprise-data/index.md	API reference landing page
/manuals/enterprise/reports/_index.md	Feature guide with auth setup, curl walkthrough, pagination, troubleshooting

Test plan

• API reference renders correctly at /reference/api/enterprise-data/
• Feature guide renders in the Enterprise sidebar
• curl examples are copy-pasteable and accurate

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for docsdocker ready!

Name	Link
🔨 Latest commit	a15fb91
🔍 Latest deploy log	https://app.netlify.com/projects/docsdocker/deploys/6a42949590b7ec00082167b7
😎 Deploy Preview	https://deploy-preview-25383--docsdocker.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[docker-agent]

Assessment: 🔴 CRITICAL

Two newly added documents (the OpenAPI spec and the feature guide) describe different URL structures for the same API endpoints. One of them is wrong, and users will get 404 errors following whichever document is incorrect.

[docker-agent]

[HIGH] OpenAPI spec paths missing /reports segment — inconsistent with guide

The OpenAPI spec defines the listReportTypes endpoint at /orgs/{org_name} (full URL: https://api.docker.com/enterprise-data/v1/orgs/{org_name}), but the feature guide and the API reference table both consistently use /orgs/{org}/reports as the list-report-types path. The same mismatch applies across all four endpoints:

OpenAPI spec path	Guide/table path
GET /orgs/{org_name}	GET /orgs/{org}/reports
GET /orgs/{org_name}/{type}/{cadence}	GET /orgs/{org}/reports/{type}/{cadence}
GET /orgs/{org_name}/{type}/{cadence}/{date}/download	GET /orgs/{org}/reports/{type}/{cadence}/{date}/download
GET /orgs/{org_name}/{type}/{cadence}/{date}/schema	GET /orgs/{org}/reports/{type}/{cadence}/{date}/schema

One of these is wrong. If the actual API requires /reports in the path (as the guide shows), users using the spec for client generation or manual calls will get 404 errors. If the spec is correct, every curl example in the guide will fail.

[cassio-paesleme]

Fixed in c8fe0a6. Added the missing /reports segment to all four OpenAPI spec paths. They now match the guide.

[docker-agent]

Perfect, thank you! Confirmed that all four paths now include /reports and align with the guide. The spec is now consistent and will generate correct client code.

[docker-agent]

[HIGH] curl examples include /reports path segment not present in OpenAPI spec

All curl examples in this guide include /reports in the path (e.g., /orgs/$ORG/reports, /orgs/$ORG/reports/usage_pulls/daily), but the OpenAPI spec defines paths without this segment (e.g., /orgs/{org_name}, /orgs/{org_name}/{type}/{cadence}).

Both documents are new and were published together, yet they describe different URL structures. Please reconcile: either add the missing /reports segment to all four paths in api.yaml, or remove it from the guide's curl examples and reference table to match the spec.

[cassio-paesleme]

Fixed in c8fe0a6. The OpenAPI spec paths now include /reports and match the curl examples.

[docker-agent]

Perfect, thank you! I verified the commit and all four paths in the OpenAPI spec now correctly include "/reports" to match the curl examples and documentation. The discrepancy is resolved.

[docker-agent]

[MEDIUM] Download-latest script silently produces broken output when no reports exist

When the API returns an empty reports list, jq -r '.reports[0].Date' outputs the literal string null (not an empty string). The script then silently:

• Creates a file named usage_pulls_null.csv
• Makes a download request to .../daily/null/download, which returns a 404

Consider adding a guard to catch this case:

DATE=$(
  curl -s "https://api.docker.com/enterprise-data/v1/orgs/$ORG/reports/usage_pulls/daily?page_size=1" \
    -H "Authorization: Bearer $TOKEN" \
  | jq -r '.reports[0].Date // empty'
)

if [ -z "$DATE" ]; then
  echo "No reports available."
  exit 1
fi

curl -L -o "usage_pulls_${DATE}.csv" \
  "https://api.docker.com/enterprise-data/v1/orgs/$ORG/reports/usage_pulls/daily/${DATE}/download" \
  -H "Authorization: Bearer $TOKEN"

Using // empty makes jq output nothing (empty string) instead of null, so the shell check [ -z "$DATE" ] works correctly for both the no-reports and API-error cases.

[cassio-paesleme]

Fixed in e983461. Added // empty to the jq expression and a shell guard that exits early with a message when no reports are available.

[docker-agent]

Perfect! Thanks for the quick fix. The guard now correctly handles the empty reports case and prevents the script from creating broken files.

[akristen]

@cassio-paesleme Thanks so much for filing this PR. I've made some comments for myself to act on when I implement a review.

If you could go through and tell me what you think about these suggestions before I start implementing, that would be amazing. :) I will handle all changes on my end since they're mostly editorial in nature and you already did the hard work of generating a draft.

Feel free to ping me on Slack for any questions / and a back and forth, as well as when you'd like this PR out. The main blocker is moving "Usage Reports" under "Admin > Org" so it's on the same level as Activity Logs and Insights. 🫡

made changes

[docker-agent]

Assessment: 🔴 CRITICAL

Two high-severity factual contradictions found in newly added content: the schema field names in the usage guide differ from the OpenAPI spec, and the changelog claims PAT authentication is supported while both the spec and guide explicitly prohibit it. One medium issue: the summary bar labels usage reports as "For Administrators" but the guide says custom roles with report read permission also qualify.

[docker-agent]

[HIGH] Schema example response fields differ from OpenAPI spec

The schema example in this guide shows a date field and omits tag, but the OpenAPI spec (latest.yaml) uses event_date and includes tag:

Guide example:

{ "name": "date", "type": "string", ... }

OpenAPI spec example:

- name: event_date
  type: date
- name: tag
  type: string
- name: pull_count
  ...

A user who reads this guide and then writes code to parse a real API response will find the field names don't match. Consider aligning the example here with the spec (use event_date, add tag), or update the spec if date is intentional.

[docker-agent]

[HIGH] Changelog incorrectly claims PAT authentication is supported

This bullet states PATs are a supported authentication method:

- Authentication via Personal Access Tokens (PAT) and Organization Access Tokens (OAT)

But both the OpenAPI spec (latest.yaml) and the usage reports guide explicitly state the opposite:

• Spec: "Personal Access Tokens (PATs) are not supported."
• Guide: "Personal Access Tokens (PATs) are unsupported for usage reports."

This contradicts the documented API contract and will mislead users who try to authenticate with a PAT and receive an error. The changelog entry should be updated to: - Authentication via Organization Access Tokens (OAT) with the Report Read scope

[docker-agent]

[MEDIUM] for: Administrators label is narrower than the actual access requirements

The summary bar will display "For Administrators," but the usage reports guide states that users with a custom role and the report read permission also qualify — not just organization owners/administrators.

A user who has a custom role with report read access may see the "For Administrators" label and incorrectly assume the feature is out of reach. Consider whether this summary bar entry accurately reflects the access requirements, or whether the for field should be omitted or adjusted.