--- title: "Update a package" method: PATCH path: "/packages/{id}" tags: ["Package"] --- # Update a package `PATCH /packages/{id}` ## Request - Base URL: `https://api.nullplatform.com` - URL: `https://api.nullplatform.com/packages/{id}` - Auth: HTTP bearer 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`. ## Path parameters - `id` string, uuid, required ## Request body - PackageUpdate: version and bump are mutually exclusive; either one must be paired with components. id, nrn and slug are immutable (400 on any attempt). - `name` string: New display name. - `visible_to` string[]: Replaces the package's visibility. An empty list collapses to [nrn]. - `default_revision_id` string, uuid, nullable: Pin the default to a revision of this package, or null to follow the latest revision. - `version` string: Explicit semver for the new revision. Paired with components. - `bump` 'patch' | 'minor' | 'major': Relative semver bump from the latest revision. Paired with components. - `components` PackageComponent[]: The components to publish. Merged by name onto the current bill of materials unless merge_components is false. - `name` string, required: Name of the component within the revision, for example "spec" or "runtime:main". Unique within the revision; opaque to the package server. - `resource_type` string, required: Routing key that identifies which owning service resolves resource_id, for example "service_specification", "action_specification", "link_specification" or "artifact". - `resource_id` string, uuid, required: UUID of the underlying resource at its owning service. - `resource_revision_id` string, uuid, required: UUID of the revision this component pins: a specification snapshot for service, action and link specifications, or an artifact revision for artifacts. - `parent_id` string, uuid, nullable: 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. - `merge_components` boolean: 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` boolean: Promote the revision published in this call to default_revision_id. Requires components with version or bump. Mutually exclusive with default_revision_id. ## Response `200` The updated package. - Package - `id` string, uuid: The package id. - `nrn` string: The owning NRN. - `slug` string: URL-safe identifier, unique per NRN. Derived from name when omitted on create. - `name` string: Human-readable display name. - `visible_to` string[]: 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. - `default_revision_id` string, uuid, nullable: Pinned revision UUID, or null to follow latest_revision_id. - `default_version` string, nullable: Server-derived semver of default_revision_id. - `latest_revision_id` string, uuid, nullable: Highest-semver revision UUID. Server-managed. - `latest_version` string, nullable: Server-derived semver of latest_revision_id. - `components` PackageComponent[]: The bill of materials of the resolved revision (default_revision_id, or latest_revision_id when no default is pinned). - `name` string, required: Name of the component within the revision, for example "spec" or "runtime:main". Unique within the revision; opaque to the package server. - `resource_type` string, required: Routing key that identifies which owning service resolves resource_id, for example "service_specification", "action_specification", "link_specification" or "artifact". - `resource_id` string, uuid, required: UUID of the underlying resource at its owning service. - `resource_revision_id` string, uuid, required: UUID of the revision this component pins: a specification snapshot for service, action and link specifications, or an artifact revision for artifacts. - `parent_id` string, uuid, nullable: 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. - `created_at` string, date-time: When the package was created. - `updated_at` string, date-time: When the package envelope last changed. ## Other responses - `4XX`: Client error responses due to invalid input, missing parameters or insufficient permissions. - `5XX`: Server error responses. ## Changes - **2026-09-17** `43b3c1ecdfd8`: 1 info - endpoint added [Operation history](https://skmtc.dev/nullplatform/apis/nullplatform-api/changes/packages/:id/patch.md) --- [API](https://skmtc.dev/nullplatform/apis/nullplatform-api.md) - [All operations](https://skmtc.dev/nullplatform/apis/nullplatform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nullplatform/apis/nullplatform-api/revisions/d3f66bc633d4?raw)