# Chainguard API v2 tutorial

URL: https://deploy-preview-3798--ornate-narwhal-088216.netlify.app/platform/api/api-v2-tutorial.md
Last Modified: August 11, 2026
Tags: Chainguard Console, Procedural

Tutorial with examples showing how you can use the Chainguard API v2.

The v2 API is now Generally Available (GA) and introduces cursor-based pagination, server-side ordering, consistent resource patterns, and structured error responses across all endpoints.
This guide walks through the v2 API using real curl commands. If you&rsquo;re migrating an existing v1 or beta (v2beta1) integration, see Migrating from API v1 to API v2 instead.
Note: The example output in this guide was captured from a development environment. Your organization&rsquo;s resource names, UIDs, timestamps, and counts will differ. The response structure and field names are the same across all environments.
What&rsquo;s the same Authentication — same OIDC token model as v1 Authorization — same identity-based access control Scoping — same uidp.descendants_of / uidp.children_of hierarchy filters What&rsquo;s new in v2 Cursor-based pagination with page_size, page_token, total_count Server-side ordering with order_by (ascending/descending on any sortable field) Random-access pagination with skip for UI page jumping Structured errors with typed detail payloads (AIP-193) Consistent resource patterns — every resource has uid, createTime, updateTime Hydrated references — role binding responses include full identity, group, and role objects FieldMask updates — partial updates via updateMask instead of sending the full resource Available endpoints Domain Resources Operations IAM Groups, Identities, Roles, RoleBindings, IdentityProviders, AccountAssociations, GroupInvites, ExternalGroupRoleMappings, Terms List, Get, Create, Update, Delete (Terms: accept + list acceptances) Registry Repos (incl. readme), Tags, Images Repos: List, Get, Create, Update, Delete; Tags: List, Get, Create, Delete; Images: architectures &amp; size (read-only) Vulnerabilities Advisories List, Get Libraries Artifacts List artifacts, list versions, artifact count (read-only) Advisory Security advisory documents, vulnerability metadata, resolved-vulnerability reports List (read-only) Events Subscriptions List, Get, Create, Delete Ping Ping (connectivity check) Ping All endpoints live under a versioned path per domain: /iam/v2/, /registry/v2/, /vulnerabilities/v2/, /libraries/v2/, /advisory/v2/, /events/v2/, and /ping/v2/.
The worked examples in this guide focus on IAM, Registry, and Vulnerabilities. The other domains follow the same request and response conventions.
Prerequisites Get an API token and set your organization ID:
export TOKEN=$(chainctl auth token) export API=https://console-api.enforce.dev # ORG_ID is the UID of your root organization group export ORG_ID=YOUR_ORG_IDThe following examples use $TOKEN, $API, and $ORG_ID for brevity.
Operational notes Keep the following in mind as you work through this guide.
Page tokens expire after 3 days (AIP-158). If a token expires, the query restarts from the beginning — no error is returned. gRPC — all endpoints are also available via gRPC at the same host. Proto definitions are at chainguard.dev/sdk/proto/chainguard/platform/, and the Go SDK clients live under chainguard.dev/sdk/proto/chainguard/platform/clients/v2. 1. Your first v2 request List the first 3 repos in your organization:
curl -s -H &#34;Authorization: Bearer $TOKEN&#34; \ &#34;$API/registry/v2/repos?uidp.descendants_of=$ORG_ID&amp;page_size=3&amp;order_by=name&#34; | jq .{ &#34;repos&#34;: [ { &#34;uid&#34;: &#34;d9e2f1a0.../06626efd8c6b3fb7&#34;, &#34;name&#34;: &#34;nginx&#34;, &#34;createTime&#34;: &#34;2026-01-28T12:54:21.189Z&#34;, &#34;updateTime&#34;: &#34;2026-01-28T12:54:21.189Z&#34; }, { &#34;uid&#34;: &#34;d9e2f1a0.../0ed18f0f929f4c60&#34;, &#34;name&#34;: &#34;python&#34;, &#34;createTime&#34;: &#34;2026-01-23T14:54:42.774Z&#34;, &#34;updateTime&#34;: &#34;2026-01-23T14:54:42.774Z&#34; }, { &#34;uid&#34;: &#34;d9e2f1a0.../12b4208b23740c37&#34;, &#34;name&#34;: &#34;static&#34;, &#34;createTime&#34;: &#34;2026-01-23T14:54:39.021Z&#34;, &#34;updateTime&#34;: &#34;2026-01-23T14:54:39.021Z&#34; } ], &#34;nextPageToken&#34;: &#34;CqQBV3lK...&#34;, &#34;totalCount&#34;: &#34;12&#34;, &#34;skipped&#34;: 0 }Every v2 response follows the same shape:
uid — unique resource identifier (replaces id in v1) createTime / updateTime — timestamps on every resource nextPageToken — cursor for the next page (empty when no more results) totalCount — total matching results across all pages Get a single resource New in v2: fetch a resource directly by UID. In v1, this required a List call with an ID filter.
# REPO_UID is a uid value from the List repos response above export REPO_UID=YOUR_REPO_UID curl -s -H &#34;Authorization: Bearer $TOKEN&#34; \ &#34;$API/registry/v2/repos/$REPO_UID&#34; | jq &#39;{uid, name, createTime}&#39;{ &#34;uid&#34;: &#34;d9e2f1a0.../06626efd8c6b3fb7&#34;, &#34;name&#34;: &#34;nginx&#34;, &#34;createTime&#34;: &#34;2026-01-28T12:54:21.189Z&#34; }Use direct UID lookups when you already know the resource identifier — they are faster than a List call with an ID filter.
Filter by name Find a specific repo without knowing its UID:
curl -s -H &#34;Authorization: Bearer $TOKEN&#34; \ &#34;$API/registry/v2/repos?uidp.descendants_of=$ORG_ID&amp;name=nginx&#34; \ | jq &#39;[.repos[] | {uid, name, createTime}]&#39;[ { &#34;uid&#34;: &#34;d9e2f1a0.../06626efd8c6b3fb7&#34;, &#34;name&#34;: &#34;nginx&#34;, &#34;createTime&#34;: &#34;2026-01-28T12:54:21.189Z&#34; } ]Name filtering returns exact matches. Combine with uidp.descendants_of to scope the search to your organization.
2. Set up access for a new team A common workflow: create a CI identity at your organization and bind a role to it.
Note: Create identities under your root organization group ($ORG_ID) so they can reach the resources that live there, including your registry. An identity created under a subgroup is scoped to that subgroup and won&rsquo;t see your registry — so it can&rsquo;t pull images.
Create an identity curl -s -X POST -H &#34;Authorization: Bearer $TOKEN&#34; \ -H &#34;Content-Type: application/json&#34; \ &#34;$API/iam/v2/identities/$ORG_ID&#34; \ -d &#39;{ &#34;name&#34;: &#34;ci-bot&#34;, &#34;description&#34;: &#34;CI/CD pipeline identity&#34;, &#34;claimMatch&#34;: { &#34;issuer&#34;: &#34;https://token.actions.githubusercontent.com&#34;, &#34;subject&#34;: &#34;repo:my-org@123456/my-repo@654321:ref:refs/heads/main&#34; } }&#39; | jq .{ &#34;uid&#34;: &#34;d9e2f1a0.../f462d354ca32ca9f&#34;, &#34;name&#34;: &#34;ci-bot&#34;, &#34;description&#34;: &#34;CI/CD pipeline identity&#34;, &#34;lastSeenTime&#34;: &#34;2026-03-27T13:55:00.783Z&#34;, &#34;createTime&#34;: &#34;2026-03-27T13:55:00.785Z&#34;, &#34;updateTime&#34;: &#34;2026-03-27T13:55:00.785Z&#34;, &#34;claimMatch&#34;: { &#34;issuer&#34;: &#34;https://token.actions.githubusercontent.com&#34;, &#34;subject&#34;: &#34;repo:my-org@123456/my-repo@654321:ref:refs/heads/main&#34; } } Note: The subject shown here uses GitHub&rsquo;s immutable format, which embeds the numeric owner ID (123456) and repository ID (654321). Match the exact subject your repository&rsquo;s token carries. For how to find these IDs and when the format applies, see Create an Assumable Identity for a GitHub Actions Workflow.
Note the identity uid in the response — you will use it in the next step when binding a role.
Bind a role First, find the viewer role:
curl -s -H &#34;Authorization: Bearer $TOKEN&#34; \ &#34;$API/iam/v2/roles&#34; | jq &#39;.roles[] | select(.name == &#34;viewer&#34;) | {uid, name, description}&#39;{ &#34;uid&#34;: &#34;63921b2c44617e3f2603851537be0123af4a57d7&#34;, &#34;name&#34;: &#34;viewer&#34;, &#34;description&#34;: &#34;Viewer Role (built-in)&#34; }Then bind it:
# ROLE_UID is the uid of the viewer role, retrieved above ROLE_UID=&#34;63921b2c44617e3f2603851537be0123af4a57d7&#34; # IDENTITY_UID is the uid value returned in the Create an identity response above export IDENTITY_UID=YOUR_IDENTITY_UID curl -s -X POST -H &#34;Authorization: Bearer $TOKEN&#34; \ -H &#34;Content-Type: application/json&#34; \ &#34;$API/iam/v2/roleBindings/$ORG_ID&#34; \ -d &#34;{\&#34;identityUid\&#34;: \&#34;$IDENTITY_UID\&#34;, \&#34;roleUid\&#34;: \&#34;$ROLE_UID\&#34;}&#34; | jq .{ &#34;uid&#34;: &#34;d9e2f1a0.../9b822036a7075d75&#34;, &#34;identity&#34;: { &#34;uid&#34;: &#34;d9e2f1a0.../f462d354ca32ca9f&#34;, &#34;name&#34;: &#34;ci-bot&#34;, &#34;description&#34;: &#34;CI/CD pipeline identity&#34;, &#34;subject&#34;: &#34;repo:my-org@123456/my-repo@654321:ref:refs/heads/main&#34;, &#34;issuer&#34;: &#34;https://token.actions.githubusercontent.com&#34; }, &#34;group&#34;: { &#34;uid&#34;: &#34;d9e2f1a0...&#34;, &#34;name&#34;: &#34;my-org&#34;, &#34;description&#34;: &#34;Root organization group&#34; }, &#34;role&#34;: { &#34;uid&#34;: &#34;63921b2c44617e3f2603851537be0123af4a57d7&#34;, &#34;name&#34;: &#34;viewer&#34;, &#34;description&#34;: &#34;Viewer Role (built-in)&#34; }, &#34;createTime&#34;: &#34;2026-03-27T13:55:01.475Z&#34; }The response includes fully hydrated identity, group, and role objects — no need for follow-up lookups.
3. Pagination Every List endpoint supports cursor-based pagination with consistent parameters.
Basic pagination curl -s -H &#34;Authorization: Bearer $TOKEN&#34; \ &#34;$API/registry/v2/repos?uidp.descendants_of=$ORG_ID&amp;page_size=5&#34; \ | jq &#39;{totalCount, repos: [.repos[].name], nextPageToken: .nextPageToken[:20]}&#39;{ &#34;totalCount&#34;: &#34;12&#34;, &#34;repos&#34;: [&#34;apko&#34;, &#34;busybox&#34;, &#34;go&#34;, &#34;jdk&#34;, &#34;nginx&#34;], &#34;nextPageToken&#34;: &#34;CqQBV3lKbE16Z3dPVE0y&#34; }Follow the cursor for the next page:
curl -s -H &#34;Authorization: Bearer $TOKEN&#34; \ &#34;$API/registry/v2/repos?uidp.descendants_of=$ORG_ID&amp;page_size=5&amp;page_token=CqQBV3lK...&#34; \ | jq &#39;{repos: [.repos[].name]}&#39;{ &#34;repos&#34;: [&#34;node&#34;, &#34;php&#34;, &#34;postgres&#34;, &#34;python&#34;, &#34;redis&#34;] }When nextPageToken is absent from the response, you have reached the last page.
Server-side ordering Sort by name:
curl -s -H &#34;Authorization: Bearer $TOKEN&#34; \ &#34;$API/registry/v2/repos?uidp.descendants_of=$ORG_ID&amp;page_size=5&amp;order_by=name&#34; \ | jq &#39;[.repos[].name]&#39;[&#34;apko&#34;, &#34;busybox&#34;, &#34;go&#34;, &#34;jdk&#34;, &#34;nginx&#34;]Reverse the order:
curl -s -H &#34;Authorization: Bearer $TOKEN&#34; \ &#34;$API/registry/v2/repos?uidp.descendants_of=$ORG_ID&amp;page_size=5&amp;order_by=name%20desc&#34; \ | jq &#39;[.repos[].name]&#39;[&#34;static&#34;, &#34;ruby&#34;, &#34;redis&#34;, &#34;python&#34;, &#34;postgres&#34;]Sort by creation time (newest first):
curl -s -H &#34;Authorization: Bearer $TOKEN&#34; \ &#34;$API/registry/v2/repos?uidp.descendants_of=$ORG_ID&amp;page_size=5&amp;order_by=created_at%20desc&#34; \ | jq &#39;[.repos[] | {name, createTime}]&#39;[ {&#34;name&#34;: &#34;redis&#34;, &#34;createTime&#34;: &#34;2026-02-14T09:11:05.488Z&#34;}, {&#34;name&#34;: &#34;postgres&#34;, &#34;createTime&#34;: &#34;2026-02-10T17:02:05.135Z&#34;}, {&#34;name&#34;: &#34;node&#34;, &#34;createTime&#34;: &#34;2026-02-03T11:48:04.814Z&#34;}, {&#34;name&#34;: &#34;nginx&#34;, &#34;createTime&#34;: &#34;2026-01-28T12:54:21.189Z&#34;}, {&#34;name&#34;: &#34;python&#34;, &#34;createTime&#34;: &#34;2026-01-23T14:54:42.774Z&#34;} ]Pagination and ordering combine: pages maintain sort order across cursors.
Random-access with skip Jump directly to page 3 (skip the first 10 results):
curl -s -H &#34;Authorization: Bearer $TOKEN&#34; \ &#34;$API/registry/v2/repos?uidp.descendants_of=$ORG_ID&amp;page_size=5&amp;order_by=name&amp;skip=10&#34; \ | jq &#39;{skipped: .skipped, repos: [.repos[].name]}&#39;{ &#34;skipped&#34;: 10, &#34;repos&#34;: [&#34;ruby&#34;, &#34;static&#34;] }The skipped field in the response confirms how many results were skipped, useful for building UI page controls.
Pagination parameters Parameter Description page_size Number of results per page (default 50, max 200) page_token Opaque cursor from previous response&rsquo;s nextPageToken order_by Sort field and direction, for example name or created_at desc skip Number of results to skip (for random-access / UI page jumping) 4. Tags and end-of-life Tags live under a repo. List them with the same patterns you used for repos, scoped to a single repo with uidp.children_of.
List tags in a repo Each tag carries its digest and a deprecated flag:
curl -s -H &#34;Authorization: Bearer $TOKEN&#34; \ &#34;$API/registry/v2/tags?uidp.children_of=$REPO_UID&amp;page_size=3&#34; \ | jq &#39;[.tags[] | {name, digest, deprecated, updateTime}]&#39;[ {&#34;name&#34;: &#34;latest&#34;, &#34;digest&#34;: &#34;sha256:6b3f...&#34;, &#34;deprecated&#34;: false, &#34;updateTime&#34;: &#34;2026-07-14T09:12:44.501Z&#34;}, {&#34;name&#34;: &#34;1.27&#34;, &#34;digest&#34;: &#34;sha256:8c1a...&#34;, &#34;deprecated&#34;: false, &#34;updateTime&#34;: &#34;2026-07-14T09:12:44.502Z&#34;}, {&#34;name&#34;: &#34;1.26&#34;, &#34;digest&#34;: &#34;sha256:a90d...&#34;, &#34;deprecated&#34;: true, &#34;updateTime&#34;: &#34;2026-05-02T18:30:10.114Z&#34;} ] Check for deprecated tags In v1, a dedicated ListEolTags call surfaced end-of-life tags. v2 has no separate end-of-life endpoint or server-side filter. Instead, each tag carries a deprecated boolean, which you filter on client-side:
curl -s -H &#34;Authorization: Bearer $TOKEN&#34; \ &#34;$API/registry/v2/tags?uidp.children_of=$REPO_UID&amp;page_size=200&#34; \ | jq &#39;[.tags[] | select(.deprecated) | .name]&#39; Note: Client-side filtering on deprecated is the intended approach in v2. A v2 equivalent of ListEolTags is on the backlog with no committed date; until it ships, the v1 ListEolTags endpoint remains available.
5. Querying vulnerabilities The Vulnerabilities domain exposes advisory data. In v2 it covers advisories with List and Get.
List advisories Advisories are scoped and paginated like every other List endpoint, with extra filters such as artifactNames and advisoryIds:
curl -s -H &#34;Authorization: Bearer $TOKEN&#34; \ &#34;$API/vulnerabilities/v2/advisories?uidp.descendants_of=$ORG_ID&amp;page_size=3&#34; \ | jq &#39;[.advisories[] | {uid, advisoryId, artifactName, updateTime}]&#39;[ {&#34;uid&#34;: &#34;d9e2f1a0.../3b1c&#34;, &#34;advisoryId&#34;: &#34;CGA-abcd-1234-wxyz&#34;, &#34;artifactName&#34;: &#34;nginx&#34;, &#34;updateTime&#34;: &#34;2026-07-18T21:04:11.220Z&#34;}, {&#34;uid&#34;: &#34;d9e2f1a0.../7f2a&#34;, &#34;advisoryId&#34;: &#34;CGA-efgh-5678-stuv&#34;, &#34;artifactName&#34;: &#34;python&#34;, &#34;updateTime&#34;: &#34;2026-07-18T21:04:11.221Z&#34;}, {&#34;uid&#34;: &#34;d9e2f1a0.../a1b2&#34;, &#34;advisoryId&#34;: &#34;CGA-ijkl-9012-mnop&#34;, &#34;artifactName&#34;: &#34;openssl&#34;, &#34;updateTime&#34;: &#34;2026-07-18T21:04:11.222Z&#34;} ]Fetch a single advisory by UID at /vulnerabilities/v2/advisories/{uid}.
Vulnerability reports The v1 GetVulnReport and ListVulnCountReports calls have no v2 equivalent today, and advisories are not a replacement — they serve a different, advisory-feed purpose. The ListResolvedVulnsReports endpoint under /advisory/v2/ is also advisory-feed oriented, not a vulnerability-report replacement. If your integration reads vulnerability reports, continue using the v1 endpoints, which remain fully supported. v2 coverage arrives with the Vulnerabilities domain&rsquo;s migration.
6. Structured errors API v2 returns structured error responses with machine-parseable codes and details.
Validation error curl -s -X POST -H &#34;Authorization: Bearer $TOKEN&#34; \ -H &#34;Content-Type: application/json&#34; \ &#34;$API/iam/v2/identities/$ORG_ID&#34; \ -d &#39;{}&#39; | jq .{ &#34;code&#34;: 3, &#34;message&#34;: &#34;Invalid argument: name: name must match \&#34;^[a-z0-9 ._-]{1,}$\&#34;&#34;, &#34;details&#34;: [ { &#34;@type&#34;: &#34;type.googleapis.com/google.rpc.ErrorInfo&#34;, &#34;reason&#34;: &#34;INVALID_ARGUMENT&#34;, &#34;domain&#34;: &#34;iam.chainguard.dev&#34; }, { &#34;@type&#34;: &#34;type.googleapis.com/google.rpc.BadRequest&#34;, &#34;fieldViolations&#34;: [ { &#34;field&#34;: &#34;name&#34;, &#34;description&#34;: &#34;name must match \&#34;^[a-z0-9 ._-]{1,}$\&#34;&#34; } ] } ] }The fieldViolations array identifies exactly which fields failed validation and why.
Precondition failure Attempting to delete a group that still contains child resources returns a precondition failure:
{ &#34;code&#34;: 9, &#34;message&#34;: &#34;Precondition failed: cannot delete group with child repos&#34;, &#34;details&#34;: [ { &#34;@type&#34;: &#34;type.googleapis.com/google.rpc.ErrorInfo&#34;, &#34;reason&#34;: &#34;FAILED_PRECONDITION&#34;, &#34;domain&#34;: &#34;iam.chainguard.dev&#34; }, { &#34;@type&#34;: &#34;type.googleapis.com/google.rpc.PreconditionFailure&#34;, &#34;violations&#34;: [ { &#34;type&#34;: &#34;RESOURCE_NOT_EMPTY&#34;, &#34;description&#34;: &#34;cannot delete group with child repos&#34; } ] } ] }Error responses follow Google AIP-193 with typed detail payloads you can switch on programmatically.
7. Partial updates with FieldMask Update specific fields without sending the full resource. Only the fields listed in updateMask are changed:
curl -s -X PATCH -H &#34;Authorization: Bearer $TOKEN&#34; \ -H &#34;Content-Type: application/json&#34; \ &#34;$API/registry/v2/repos/$REPO_UID&#34; \ -d &#39;{ &#34;description&#34;: &#34;Updated description — only this field changes&#34; }&#39; | jq &#39;{uid, name, description}&#39;{ &#34;uid&#34;: &#34;d9e2f1a0.../06626efd8c6b3fb7&#34;, &#34;name&#34;: &#34;nginx&#34;, &#34;description&#34;: &#34;Updated description — only this field changes&#34; }The name field was not in the request body, so it&rsquo;s unchanged. In v1, updates required sending the entire resource — any omitted field would be reset to its zero value.
To be explicit about which fields to update, pass updateMask:
curl -s -X PATCH -H &#34;Authorization: Bearer $TOKEN&#34; \ -H &#34;Content-Type: application/json&#34; \ &#34;$API/registry/v2/repos/$REPO_UID?updateMask=description&#34; \ -d &#39;{ &#34;description&#34;: &#34;Only this field is updated&#34;, &#34;name&#34;: &#34;this-is-ignored&#34; }&#39; | jq &#39;{uid, name, description}&#39;{ &#34;uid&#34;: &#34;d9e2f1a0.../06626efd8c6b3fb7&#34;, &#34;name&#34;: &#34;nginx&#34;, &#34;description&#34;: &#34;Only this field is updated&#34; }The name in the body is ignored because updateMask only includes description. This PATCH-with-field-mask pattern applies to every updatable resource.
Migration from v1 v2 is additive — v1 endpoints remain available during a transition period, so you can migrate at your own pace. For the full field-by-field mapping and migration timeline, see Migrating from API v1 to API v2.
Cleanup Delete resources you created during this walkthrough:
# Delete in reverse order: role binding, then identity # BINDING_UID is the uid value returned in the Bind a role response above curl -s -X DELETE -H &#34;Authorization: Bearer $TOKEN&#34; &#34;$API/iam/v2/roleBindings/$BINDING_UID&#34; curl -s -X DELETE -H &#34;Authorization: Bearer $TOKEN&#34; &#34;$API/iam/v2/identities/$IDENTITY_UID&#34;Each DELETE returns an empty response body on success.