docs: update API v2 tutorial for GA and add v1-to-v2 migration guide

[matthewhelmke]

[ ] Check if this is a typo or other quick fix and ignore the rest :)

Type of change

Documentation — updates an existing page and adds a new one.

What should this PR do?

Resolves DOCS-49.

• Updates the existing API v2 tutorial (content/platform/api/api-v2-tutorial.md) for GA: drops the beta framing, renames v2beta1 paths to v2, keeps the CREATE examples as parent-in-path (confirmed unchanged at GA in review), adds worked examples for the most-used direct-API operations (repos, tags, advisories), and fills in the endpoint table across all v2 domains.
• Adds a new migration guide (content/platform/api/api-v2-migration.md) for anyone calling the API directly and migrating from v1 to v2.
• Adds a sidebar crosslink from the Migration category (content/get-started/migration/_index.md) to the new guide, using the same crosslinks frontmatter pattern as the existing "Catalog Starter" entry under Self-serve.

Why are we making this change?

API v2 is going GA soon. The existing tutorial is beta-only. Direct API integrators also need a dedicated migration guide, which didn't exist yet.

What are the acceptance criteria?

Engineering has reviewed this PR and answered the open questions; the content has been updated to match (see the checklist below). Two minor items remain open but non-blocking. Before external publish: a final proofread, and Grace's optional call on the endpoint-table framing.

Out of scope, but flagged for follow-up once their generators catch up to GA: content/platform/administration/cloudevents/events-reference.md still references v2beta1 service names throughout (looks auto-generated), and content/platform/api/spec-api-v2.md still points at api-v2beta1.json.

How should this PR be tested?

Cannot be tested end-to-end against live GA endpoints — they aren't up yet. What was verified:

• Ran a local Hugo dev server and confirmed: the new page renders at /platform/api/api-v2-migration/, the alias from the stale /chainguard/administration/api-v2-migration/ path redirects correctly, the tutorial no longer shows beta framing, and the Migration sidebar shows the new crosslink with the external-link icon.
• The updateMask field-mask parameter name (called out as unconfirmed in the source docs) was previously tested and confirmed working against the live beta API in an earlier round — carried forward, not re-guessed.
• All other curl examples are unchanged from the previously-tested beta tutorial except for path renames; the CREATE examples remain parent-in-path, confirmed unchanged at GA in review.

Engineering review checklist — API v2 GA docs

This PR documents API v2 GA, which isn't final or published yet. Engineering has reviewed the items below; resolved items are checked and applied, and the two open items are non-blocking. Where the doc reflected GA guidance differing from the published v2beta1 spec, the resolution is noted.

Needs confirmation

• 1. CREATE request shape (highest impact — affects every create example). Doc uses collection-path + parent-in-body + a resource wrapper: POST /iam/v2/groups with {"parent": "<uid>", "group": {…}}. The v2beta1 spec instead uses parent-in-path with the resource fields sent directly: POST /iam/v2beta1/groups/{parent} with {"name": …, "description": …} (no parent field, no wrapper). Confirm GA moves to parent-in-body and the wrapper field names (group, identity, roleBinding).
  Where: tutorial §2 (Create a group / identity / Bind a role), §5 validation error; migration guide Step 3.

• 2. Query-parameter casing. Doc uses snake_case throughout: page_size, page_token, order_by, skip, uidp.descendants_of, uidp.children_of. The v2beta1 spec documents camelCase (pageSize, orderBy, uidp.descendantsOf, …). Confirm GA accepts snake_case (as beta did in live testing), or tell us to switch the doc to camelCase.
  Where: both files, all List examples.
  Update: Not addressed in review; treating as non-blocking. Keeping snake_case, which matches the live-captured examples — revisit if GA requires camelCase.

• 3. updateMask parameter. Doc uses ?updateMask=<field> for partial PATCH updates. This worked against the live beta API but isn't restated in the spec. Confirm the parameter name and partial-update behavior hold at GA.
  Where: tutorial §7 (Partial updates); migration guide Step 4.
  Update: Not separately restated in review; treating as non-blocking and stable, since reply 8 confirms v2beta1 is dropped across REST paths, proto packages, and the SDK at GA.

• 4. GA domains: Ecosystems (Libraries) and Integrations (Advisory). Doc lists these as new GA domains with resources TBD. Note: the beta spec already exposes /libraries/v2beta1/artifacts (so Ecosystems is not new at GA), and has no /advisory/ path at all. Confirm the GA resource names, path prefixes, and supported operations for both, and correct the domain tables.
  Where: tutorial "Available endpoints" table; migration guide "Path prefixes by domain" table.

• 5. Tag end-of-life. v1 had a dedicated ListEolTags call. The beta spec has no end-of-life endpoint or server-side filter — only a per-tag deprecated boolean. Confirm whether GA adds a dedicated filter/endpoint, or whether client-side filtering on deprecated is the intended path.
  Where: tutorial §4 (Check for deprecated tags).

• 6. Vulnerability reports. v1's GetVulnReport and ListVulnCountReports (heavily used by direct HTTP integrations) have no equivalent in the beta spec, which exposes only advisories. Confirm whether GA adds vulnerability-report endpoints, or whether advisory data is meant to replace them.
  Where: tutorial §5 (Vulnerability reports).

• 7. Rate limits and headers. Doc states rate limits are enforced at GA but gives no values. Confirm the specific limits and any response headers (for example, remaining-quota), and whether a rate-limits reference page exists to link to.
  Where: tutorial "Operational notes"; migration guide Step 8.

• 8. Go SDK package path. Confirm whether the Go SDK client library moves from chainguard.dev/sdk/proto/platform/clients/v2beta1 to a v2 path at GA, or keeps the v2beta1 package name internally after the REST paths rename.
  Where: tutorial "Operational notes"; migration guide Step 9.

• 9. Migration timeline. All dates and phase triggers (parallel availability → warning escalation → soft shutdown → hard removal) are placeholders. Confirm real dates/criteria, or tell us to drop the table until they exist.
  Where: migration guide "Timeline".

Already verified against the published v2beta1 spec (no action needed)

• Repo Get (/repos/{uid}) and Update (PATCH /repos/{repo.uid}, writable name/description) paths and fields.
• Tag list path (/registry/v2/tags), uidp.children_of scoping, and fields (name, digest, deprecated, updateTime).
• Advisory list path and fields (uid, advisoryId, artifactName, updateTime).
• Pagination envelope (nextPageToken, totalCount, skipped) across List endpoints.
• Field-naming conventions (uid, createTime, updateTime).

---

Created in collaboration with Claude Code running Claude Sonnet 5 on 2026-07-20.
Updated in collaboration with Claude Code running Claude Opus 4.8 on 2026-08-04.

[netlify]

✅ Deploy Preview for ornate-narwhal-088216 ready!

Name	Link
🔨 Latest commit	3a59630
🔍 Latest deploy log	https://app.netlify.com/projects/ornate-narwhal-088216/deploys/6a75d7da8090b100088318de
😎 Deploy Preview	https://deploy-preview-3613--ornate-narwhal-088216.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.

[matthewhelmke]

Note to self: There are mentions in this content of v2beta1. That is because there were things I was able to check using that spec that I could not yet check in the not-yet-available v2 GA spec. Before this can be finalized and published, the entire set of new content needs to be reviewed to make sure none of these outdated references remain un-updated. EDIT: Done.

[matthewhelmke]

Added a commit updating the OIDC subject claim in the identity and role-binding examples to GitHub's new immutable format (repo:org@<owner-id>/repo@<repo-id>:...).

Context and the full cross-doc update live in #3616. The tutorial's note links into that PR's "Finding your repository's numeric identifiers" section, so #3616 should merge first — it's a small, focused change and expected to land quickly.

[gracelarsen-star]

Let's also ensure we update the "available endpoints" table (if that is in the updated version) to include a summary of all migrated endpoints. Steven will be able to provide the up to date list.

[matthewhelmke]

Let's also ensure we update the "available endpoints" table (if that is in the updated version) to include a summary of all migrated endpoints. Steven will be able to provide the up to date list.

I'm happy to do that. @heplayskeys, the table is here: https://github.com/chainguard-dev/edu/pull/3613/changes#diff-0c8a4e1c87c3ba99c075670d8ca05b2f81f938bc2a7731fd4cfc60e2b44489fcR39-R52

[matthewhelmke]

@gracelarsen-star and @cmdpdx thanks for the discussion of this in the beta version of the v2 tutorial page. I've folded the fix into this GA update that will merge soon with the APIv2 GA.

In the most recent commit, the tutorial now leads with the registry:

• Sections 1 & §: use repos instead of groups (list/get/filter/paginate); the nested-subgroup filter example is gone.
• Section 2: has the main fix where identity is now created under the root org and bound there, with a note on why (so it can reach the registry). No subgroup creation.
• Section 4: deduped to only include "Tags and end-of-life."
• Section 6: the validation error now uses an identity create, not a subgroup create.
• Section 7: field-mask examples unified on repos.
• Cleanup: group deletion dropped.

The migration guide was brought to parity: Steps 3/4/5 and the full example now use repos.

Verified clean (no group-endpoint paths, no dangling $GROUP_UID, no backend-team), pre-commit checks and related-pages scan both clear. That last one looked for any other uses of sub-groups across our entire docs set and confirmed none found, so we don't have a similar bit of content elsewhere left to confuse.

@gracelarsen-star and @heplayskeys , we still have the remaining

Let's also ensure we update the "available endpoints" table (if that is in the updated version) to include a summary of all migrated endpoints. Steven will be able to provide the up to date list.
to take care of. Reminder,
@heplayskeys, the table is here: https://github.com/chainguard-dev/edu/pull/3613/changes#diff-0c8a4e1c87c3ba99c075670d8ca05b2f81f938bc2a7731fd4cfc60e2b44489fcR39-R52