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, rewrites the three CREATE examples to the GA parent-in-body pattern (a real behavior change from beta, not just a path rename), and expands the endpoint table to include the two domains added at GA (Ecosystems, Integrations).
• 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 (~July 27, GTM date July 30). The existing tutorial is beta-only and describes a CREATE pattern that changes at GA. Direct API integrators also need a dedicated migration guide, which didn't exist yet.

What are the acceptance criteria?

This is a draft PR for engineering review, not a final ship — several facts aren't confirmed yet, and I can't test against live GA (/v2, non-beta) endpoints because they don't exist yet. Every open item is marked inline with a CONFIRM WITH ENGINEERING callout:

• Exact CREATE request body schema (wrapper field names)
• Exact rate limit numbers and response headers
• v1 sunset date and phased-shutdown milestones
• Whether the Go SDK client library path renames from v2beta1 to v2 at GA
• Resource-level detail for the two new-at-GA domains (Ecosystems, Integrations) — not included as worked examples pending confirmation

Steven Johnson and Grace Larsen (Linear project owners) need to fill in the items above before this goes external — Matthew is following up in Slack directly rather than via a GitHub mention, since I don't have their handles here. Also flagging separately in Slack: 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 — neither is in scope for this PR, but both will need the same rename once their generators catch up to GA.

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 and the CREATE body restructure, which is illustrative pending engineering confirmation.

Engineering review checklist — API v2 GA docs

This PR documents API v2 GA, which isn't final or published yet. Where the doc reflects GA guidance that differs from the current published v2beta1 spec, that's called out below. Every item is also marked inline as CONFIRM WITH ENGINEERING, and the pages carry a "do not publish externally" banner until these are resolved. Please confirm each item or correct it.

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.

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

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

[netlify]

✅ Deploy Preview for ornate-narwhal-088216 ready!

Name	Link
🔨 Latest commit	eeb6dd9
🔍 Latest deploy log	https://app.netlify.com/projects/ornate-narwhal-088216/deploys/6a5f8d06c37d620008603192
😎 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.

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