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	ca54d60
🔍 Latest deploy log	https://app.netlify.com/projects/docsdocker/deploys/6a330d4859419400086ba096
😎 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.