[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:

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.

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

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.

[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.

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

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.

[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.

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

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

Usage reports should go under Admin > Organizations, rather than the top level categories. I'll open this up and make some editorial changes.

Move into pre-reqs to replace curl/jq prereqs

Specifically some guidance around having available OATs, since some orgs have limitations; they need an open OAT slot to create a new one (if I'm understanding correctly)

turn into tip call out in prereqs

Per style guide, let's make this a complete sentence. For example:

Add some additional explanation in complete sentence form, per style guide

From a ToC POV, we want these specific actions to be nested and balanced for better visibility. We should add a sentence at minimum that describes why it's best practice to download a report, what you might use it for, and generalized information that's scattered in the below h3s. for example, this would be the place we say reports are downloaded as CSVs.

Super happy you included a troubleshooting section!