NUnullplatform
Package

Update a package

Changed on

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.

patch/packages/{id}

Request

  • Base URL
    https://api.nullplatform.com
  • URL
    https://api.nullplatform.com/packages/{id}
  • Auth
    HTTP bearer

Path parameters

idstring uuid required

The package id.

Request body

namestring

New display name.

visible_tostring[]

Replaces the package's visibility. An empty list collapses to [nrn].

default_revision_idstring uuid nullable

Pin the default to a revision of this package, or null to follow the latest revision.

versionstring

Explicit semver for the new revision. Paired with components.

bump'patch' | 'minor' | 'major'

Relative semver bump from the latest revision. Paired with components.

merge_componentsboolean

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.

defaultboolean

Promote the revision published in this call to default_revision_id. Requires components with version or bump. Mutually exclusive with default_revision_id.

Example request

{
  "name": "My scope",
  "visible_to": [
    "organization=1:account=*"
  ],
  "default_revision_id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
  "version": "1.5.0",
  "bump": "minor",
  "components": [
    {
      "name": "spec",
      "resource_type": "service_specification",
      "resource_id": "7b2d1c5e-8f4a-4e3b-9c6d-1a2b3c4d5e6f",
      "resource_revision_id": "0c9e8d7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f"
    }
  ]
}

Response

The updated package.

idstring uuid

The package id.

nrnstring

The owning NRN.

slugstring

URL-safe identifier, unique per NRN. Derived from name when omitted on create.

namestring

Human-readable display name.

visible_tostring[]

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_idstring uuid nullable

Pinned revision UUID, or null to follow latest_revision_id.

default_versionstring nullable

Server-derived semver of default_revision_id.

latest_revision_idstring uuid nullable

Highest-semver revision UUID. Server-managed.

latest_versionstring nullable

Server-derived semver of latest_revision_id.

created_atstring date-time

When the package was created.

updated_atstring date-time

When the package envelope last changed.

Example response

{
  "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "nrn": "organization=1:account=2",
  "slug": "my-scope",
  "name": "My scope",
  "visible_to": [
    "organization=1:account=2"
  ],
  "default_revision_id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
  "default_version": "1.4.0",
  "latest_revision_id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
  "latest_version": "1.4.0",
  "components": [
    {
      "name": "spec",
      "resource_type": "service_specification",
      "resource_id": "7b2d1c5e-8f4a-4e3b-9c6d-1a2b3c4d5e6f",
      "resource_revision_id": "0c9e8d7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f"
    }
  ],
  "created_at": "2026-09-14T12:00:00.000Z",
  "updated_at": "2026-09-14T12:00:00.000Z"
}

Changes