---
id: package-update
title: "Update a package"
description: "Update `name`, `visible_to` or `default_revision_id`, publish a new revision, or both. To publish, pair `components` with exactly one of `version` or `bump`. `default: true` promotes the revision published in this call and can't be combined with `default_revision_id`."
sidebar_label: "Update a package"
hide_title: true
hide_table_of_contents: true
api: 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
sidebar_class_name: "patch 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={"Update a package"}
>
</Heading>

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



Update `name`, `visible_to` or `default_revision_id`, publish a new revision, or both. To publish, pair `components` with exactly one of `version` or `bump`. `default: true` promotes the revision published in this call and can't be combined with `default_revision_id`.

`id`, `nrn` and `slug` are immutable: sending any of them fails with `400`.

:::tip PATCH or PUT?
`PATCH` works on an existing package by id and never creates one. When you don't have the id, or you're publishing from a pipeline, use `PUT /packages`: it creates or publishes by `nrn` and `slug`.
:::

> ℹ️ **Note:** Publishing a bill of materials identical to the latest revision's doesn't create a new revision. Publishing an existing version with a different bill of materials fails with `409`.


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

<ParamsDetails
  parameters={[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"The package id.","example":"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","description":"version and bump are mutually exclusive; either one must be paired with components. id, nrn and slug are immutable (400 on any attempt).","properties":{"name":{"type":"string","minLength":1,"description":"New display name.","example":"My scope"},"visible_to":{"type":"array","items":{"type":"string"},"description":"Replaces the package's visibility. An empty list collapses to [nrn].","example":["organization=1:account=*"]},"default_revision_id":{"type":"string","format":"uuid","nullable":true,"description":"Pin the default to a revision of this package, or null to follow the latest revision.","example":"e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b"},"version":{"type":"string","description":"Explicit semver for the new revision. Paired with components.","example":"1.5.0"},"bump":{"type":"string","enum":["patch","minor","major"],"description":"Relative semver bump from the latest revision. Paired with components.","example":"minor"},"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 components to publish. Merged by name onto the current bill of materials unless merge_components is false."},"merge_components":{"type":"boolean","default":true,"description":"When true (default), the components array overlays the current resolved bill of materials by component name: listed components override, unlisted ones carry over. When false, the body must list the complete new bill of materials; unlisted components are dropped."},"default":{"type":"boolean","description":"Promote the revision published in this call to default_revision_id. Requires components with version or bump. Mutually exclusive with default_revision_id."}},"title":"packageUpdate"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The updated package.","content":{"application/json":{"schema":{"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"}}}},"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>