NUnullplatform
Service

Package an existing service specification

Changed on

Create a package from a service specification that doesn't belong to a package yet. The server assembles the bill of materials for you, in a single database transaction:

  1. Pins the specification, each of its action specifications, each of its link specifications and each link's action specifications to a snapshot. An entity whose current content matches its latest snapshot reuses that snapshot; otherwise, including an entity with no snapshot yet, a new snapshot is minted.
  2. Resolves sources. An inline source (type and meta) registers the artifact, or a new revision of it, under nrn. A referenced source (artifact_id) pins an existing artifact at revision_id, or at its newest revision when you omit it.
  3. Creates the package and its first revision with these components:
    • spec: the service specification.
    • One component per source, named after the source (source when there's a single unnamed source).
    • One component per action specification, named after its slug.
    • One component per link specification, named after its slug.
    • One component per link action specification, named <link slug>:<action slug>.

The package's name and slug default to the specification's, and visible_to defaults to [nrn]. The response is the same package POST /packages returns.

ℹ️ Note: nrn must be concrete (no wildcards). The request fails with 409 when the specification already belongs to a package; to publish a new revision of that package, use PATCH /packages/{id}.

post/service_specification/{id}/package

Request

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

Path parameters

idstring uuid required

The service specification id.

Request body

nrnstring required

The owning NRN of the new package. Must be concrete (no wildcards).

namestring

Package name. Defaults to the specification's name.

slugstring

Package slug, unique per NRN. Defaults to the specification's slug.

visible_tostring[]

NRNs allowed to consume the package. Defaults to [nrn].

versionstring

Semver of the first revision.

Example request

{
  "nrn": "organization=1:account=2",
  "name": "My scope",
  "slug": "my-scope",
  "visible_to": [
    "organization=1:account=2"
  ],
  "version": "1.0.0",
  "sources": [
    {
      "meta": {
        "url": "https://github.com/acme/my-service.git",
        "reference": "v1.2.0"
      }
    }
  ]
}

Response

The created 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