---
id: package-list
title: "List packages"
description: "List packages. The listing must be scoped: send `nrn`, `visible_to`, or both."
sidebar_label: "List packages"
hide_title: true
hide_table_of_contents: true
api: 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
sidebar_class_name: "get api-method"
info_path: docs/api/package
custom_edit_url: null
---

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List packages"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/packages"}
  context={"endpoint"}
>
  
</MethodEndpoint>



List packages. The listing must be scoped: send `nrn`, `visible_to`, or both.

> 💡 **Tip:** Prefer `visible_to` for consumption. It matches packages owned at the NRN, shared by ancestors or trailing-wildcard scopes, and global packages published with `organization=*`. The `nrn` filter only matches packages owned at exactly that NRN.

The component filters (`component_name`, `resource_type`, `resource_id` and `resource_revision_id`) match against each package's resolved revision: `default_revision_id` when it's set, otherwise `latest_revision_id`.


<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"in":"query","name":"nrn","schema":{"type":"string"},"description":"Filter by exact owner NRN. Required unless you send `visible_to`.","example":"organization=1:account=2"},{"in":"query","name":"visible_to","schema":{"type":"string"},"description":"Return packages visible at this NRN: ancestors, trailing-wildcard scopes and the global wildcard all match. A trailing-wildcard value (for example, \"organization=1:account=*\") also matches packages visible to any of its descendants. Required unless you send `nrn`.","example":"organization=1:account=2"},{"in":"query","name":"slug","schema":{"type":"string"},"description":"Filter by exact slug. Combine it with `nrn` to resolve a slug to a package id.","example":"my-scope"},{"in":"query","name":"name","schema":{"type":"string"},"description":"Filter by name substring (case-insensitive).","example":"scope"},{"in":"query","name":"component_name","schema":{"type":"string"},"description":"Filter to packages whose resolved revision has a component with this name.","example":"worker-image"},{"in":"query","name":"resource_type","schema":{"type":"string"},"description":"Filter to packages whose resolved revision has a component of this resource type (for example, `service_specification` or `artifact`).","example":"artifact"},{"in":"query","name":"resource_id","schema":{"type":"string","format":"uuid"},"description":"Filter to packages whose resolved revision pins this resource, at any revision.","example":"5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f"},{"in":"query","name":"resource_revision_id","schema":{"type":"string","format":"uuid"},"description":"Filter to packages whose resolved revision pins exactly this resource revision.","example":"2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e"},{"in":"query","name":"sort","schema":{"type":"string","pattern":"^(created_at|updated_at|name|slug):(asc|desc)$"},"description":"Sort as `field:direction`, where field is one of `created_at`, `updated_at`, `name` or `slug`.","example":"created_at:desc"},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0,"default":0},"description":"The starting point for pagination.","example":0},{"in":"query","name":"limit","schema":{"type":"integer"},"description":"The maximum number of results to return per page.","example":20}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The packages matching the query.","content":{"application/json":{"schema":{"type":"object","properties":{"paging":{"type":"object","properties":{"offset":{"type":"integer","description":"The offset of this page.","example":0},"limit":{"type":"integer","description":"The maximum number of results in this page.","example":20},"total":{"type":"integer","minimum":0,"description":"The total number of results that match the query.","example":3}},"title":"paging"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The package id.","example":"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"},"nrn":{"type":"string","description":"The owning NRN.","example":"organization=1:account=2"},"slug":{"type":"string","description":"URL-safe identifier, unique per NRN. Derived from name when omitted on create.","example":"my-scope"},"name":{"type":"string","description":"Human-readable display name.","example":"My scope"},"visible_to":{"type":"array","items":{"type":"string"},"description":"NRNs allowed to consume (read and link) this package. Supports trailing-wildcard scopes (for example, \"organization=1:account=*\") and the global wildcard \"organization=*\". Defaults to [nrn]. Modifications stay gated on the owning NRN.","example":["organization=1:account=2"]},"default_revision_id":{"type":"string","format":"uuid","nullable":true,"description":"Pinned revision UUID, or null to follow latest_revision_id.","example":"e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b"},"default_version":{"type":"string","nullable":true,"description":"Server-derived semver of default_revision_id.","example":"1.4.0"},"latest_revision_id":{"type":"string","format":"uuid","nullable":true,"description":"Highest-semver revision UUID. Server-managed.","example":"e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b"},"latest_version":{"type":"string","nullable":true,"description":"Server-derived semver of latest_revision_id.","example":"1.4.0"},"components":{"type":"array","items":{"type":"object","required":["name","resource_type","resource_id","resource_revision_id"],"description":"One entry of the bill of materials: a pinned (resource, revision) pair.","properties":{"name":{"type":"string","minLength":1,"description":"Name of the component within the revision, for example \"spec\" or \"runtime:main\". Unique within the revision; opaque to the package server.","example":"spec"},"resource_type":{"type":"string","minLength":1,"description":"Routing key that identifies which owning service resolves resource_id, for example \"service_specification\", \"action_specification\", \"link_specification\" or \"artifact\".","example":"service_specification"},"resource_id":{"type":"string","format":"uuid","description":"UUID of the underlying resource at its owning service.","example":"7b2d1c5e-8f4a-4e3b-9c6d-1a2b3c4d5e6f"},"resource_revision_id":{"type":"string","format":"uuid","description":"UUID of the revision this component pins: a specification snapshot for service, action and link specifications, or an artifact revision for artifacts.","example":"0c9e8d7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f"},"parent_id":{"type":"string","format":"uuid","nullable":true,"description":"The resource_id of the parent component within this revision. Required for action_specification components (the parent is a service or link specification component) and link_specification components (the parent is a service specification component); null for service_specification and artifact components.","example":null}},"title":"packageComponent"},"description":"The bill of materials of the resolved revision (default_revision_id, or latest_revision_id when no default is pinned)."},"created_at":{"type":"string","format":"date-time","description":"When the package was created.","example":"2026-09-14T12:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","description":"When the package envelope last changed.","example":"2026-09-14T12:00:00.000Z"}},"title":"package"}}},"title":"packageListResponse"}}}},"4XX":{"description":"Client error responses due to invalid input, missing parameters or insufficient permissions.","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":400},"code":{"type":"string","example":"bad_request"},"error":{"type":"string","example":"Bad Request"},"message":{"type":"string","description":"Human-readable explanation.","example":"Revision '1.4.0' exists with a different bill of materials (revision e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b)"}},"title":"errorResponse"}}}},"5XX":{"description":"Server error responses.","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":400},"code":{"type":"string","example":"bad_request"},"error":{"type":"string","example":"Bad Request"},"message":{"type":"string","description":"Human-readable explanation.","example":"Revision '1.4.0' exists with a different bill of materials (revision e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b)"}},"title":"errorResponse"}}}}}}
>
  
</StatusCodes>