---
title: "Create a package"
method: POST
path: "/packages"
tags: ["Package"]
---

# Create a package

`POST /packages`

## Request

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

Create a package. To publish its first revision in the same call, send `version` together with `components`. The first revision also becomes the package's `default_revision_id`.

You need read access to every resource the bill of materials references.

> ℹ️ **Note:** A service specification belongs to at most one package. Each `service_specification` component claims its specification for this package, and the request fails with `409` when another package already claimed it. It also fails with `409` when the NRN already has a package with the same slug.

## Request body

- PackageCreate: version and components must be sent together.
  - `nrn` string, required: The owning NRN.
  - `slug` string: URL-safe identifier, unique per NRN. Derived from name when omitted.
  - `name` string, required: Human-readable display name.
  - `visible_to` string[]: Defaults to [nrn]. Use ["organization=*"] to publish globally.
  - `version` string: Semver of the first revision, for example "1.0.0". Paired with components.
  - `components` PackageComponent[]: The first revision's bill of materials. Paired with version.
    - `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.

## Response `200`

The created 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/post.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)