NUnullplatform
Package

Create or publish a package by slug

Changed on

Create a package, or publish a new revision of an existing one, in a single idempotent call keyed on nrn and slug.

  • When nrn has no package with that slug, creates the package and returns 201. name is required. To publish the first revision in the same call, send components with an explicit version; bump needs a prior revision, so it can't be used here.
  • Otherwise, applies the call to the existing package and returns 200: it publishes a new revision when you send components, and updates visible_to or default_revision_id when you send them. name is ignored on this path; rename a package with PATCH.

version (explicit semver) and bump (patch, minor or major, relative to the latest revision) are mutually exclusive, and either one must be paired with components. With merge_components (default true) the components overlay the current bill of materials by name; with false the body must list the complete new bill of materials. default: true promotes the published revision in the same call.

:::tip PUT or PATCH? PUT is the pipeline-friendly call. It needs no package id, creates the package on the first run, and every later run publishes against the same nrn and slug, so re-running it is safe. Use PATCH /packages/{id} when you already have the id, or to rename the package. :::

ℹ️ 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.

put/packages

Request

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

Request body

nrnstring required

The owning NRN.

slugstring required

The package slug, unique per NRN. Together with nrn, it decides whether the call creates or publishes.

namestring

Required when the call creates the package; ignored otherwise.

visible_tostring[]

Visibility of a new package, or the replacement visibility of an existing one. Defaults to [nrn].

default_revision_idstring uuid nullable

On an existing package, pin the default to one of its revisions, 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. Can't be used when the call creates the package (send version instead).

merge_componentsboolean

Overlay components on the current bill of materials by name (true) or replace it (false).

defaultboolean

Promote the revision published in this call to default_revision_id. Mutually exclusive with default_revision_id.

Example request

{
  "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",
  "version": "1.4.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 existing package after the call.

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