---
id: package-create
title: "Create a package"
description: "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`."
sidebar_label: "Create a package"
hide_title: true
hide_table_of_contents: true
api: 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
sidebar_class_name: "post api-method"
info_path: docs/api/package
custom_edit_url: null
---

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a package"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/packages"}
  context={"endpoint"}
>
  
</MethodEndpoint>



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.


<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["nrn","name"],"description":"version and components must be sent together.","properties":{"nrn":{"type":"string","description":"The owning NRN.","example":"organization=1:account=2"},"slug":{"type":"string","minLength":1,"description":"URL-safe identifier, unique per NRN. Derived from name when omitted.","example":"my-scope"},"name":{"type":"string","minLength":1,"description":"Human-readable display name.","example":"My scope"},"visible_to":{"type":"array","items":{"type":"string"},"description":"Defaults to [nrn]. Use [\"organization=*\"] to publish globally.","example":["organization=1:account=2"]},"version":{"type":"string","description":"Semver of the first revision, for example \"1.0.0\". Paired with components.","example":"1.0.0"},"components":{"type":"array","items":{"type":"object","required":["name","resource_type","resource_id","resource_revision_id"],"description":"One entry of the bill of materials: a pinned (resource, revision) pair.","properties":{"name":{"type":"string","minLength":1,"description":"Name of the component within the revision, for example \"spec\" or \"runtime:main\". Unique within the revision; opaque to the package server.","example":"spec"},"resource_type":{"type":"string","minLength":1,"description":"Routing key that identifies which owning service resolves resource_id, for example \"service_specification\", \"action_specification\", \"link_specification\" or \"artifact\".","example":"service_specification"},"resource_id":{"type":"string","format":"uuid","description":"UUID of the underlying resource at its owning service.","example":"7b2d1c5e-8f4a-4e3b-9c6d-1a2b3c4d5e6f"},"resource_revision_id":{"type":"string","format":"uuid","description":"UUID of the revision this component pins: a specification snapshot for service, action and link specifications, or an artifact revision for artifacts.","example":"0c9e8d7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f"},"parent_id":{"type":"string","format":"uuid","nullable":true,"description":"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.","example":null}},"title":"packageComponent"},"description":"The first revision's bill of materials. Paired with version."}},"title":"packageCreate"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The created package.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The package id.","example":"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"},"nrn":{"type":"string","description":"The owning NRN.","example":"organization=1:account=2"},"slug":{"type":"string","description":"URL-safe identifier, unique per NRN. Derived from name when omitted on create.","example":"my-scope"},"name":{"type":"string","description":"Human-readable display name.","example":"My scope"},"visible_to":{"type":"array","items":{"type":"string"},"description":"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.","example":["organization=1:account=2"]},"default_revision_id":{"type":"string","format":"uuid","nullable":true,"description":"Pinned revision UUID, or null to follow latest_revision_id.","example":"e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b"},"default_version":{"type":"string","nullable":true,"description":"Server-derived semver of default_revision_id.","example":"1.4.0"},"latest_revision_id":{"type":"string","format":"uuid","nullable":true,"description":"Highest-semver revision UUID. Server-managed.","example":"e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b"},"latest_version":{"type":"string","nullable":true,"description":"Server-derived semver of latest_revision_id.","example":"1.4.0"},"components":{"type":"array","items":{"type":"object","required":["name","resource_type","resource_id","resource_revision_id"],"description":"One entry of the bill of materials: a pinned (resource, revision) pair.","properties":{"name":{"type":"string","minLength":1,"description":"Name of the component within the revision, for example \"spec\" or \"runtime:main\". Unique within the revision; opaque to the package server.","example":"spec"},"resource_type":{"type":"string","minLength":1,"description":"Routing key that identifies which owning service resolves resource_id, for example \"service_specification\", \"action_specification\", \"link_specification\" or \"artifact\".","example":"service_specification"},"resource_id":{"type":"string","format":"uuid","description":"UUID of the underlying resource at its owning service.","example":"7b2d1c5e-8f4a-4e3b-9c6d-1a2b3c4d5e6f"},"resource_revision_id":{"type":"string","format":"uuid","description":"UUID of the revision this component pins: a specification snapshot for service, action and link specifications, or an artifact revision for artifacts.","example":"0c9e8d7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f"},"parent_id":{"type":"string","format":"uuid","nullable":true,"description":"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.","example":null}},"title":"packageComponent"},"description":"The bill of materials of the resolved revision (default_revision_id, or latest_revision_id when no default is pinned)."},"created_at":{"type":"string","format":"date-time","description":"When the package was created.","example":"2026-09-14T12:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","description":"When the package envelope last changed.","example":"2026-09-14T12:00:00.000Z"}},"title":"package"}}}},"4XX":{"description":"Client error responses due to invalid input, missing parameters or insufficient permissions.","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":400},"code":{"type":"string","example":"bad_request"},"error":{"type":"string","example":"Bad Request"},"message":{"type":"string","description":"Human-readable explanation.","example":"Revision '1.4.0' exists with a different bill of materials (revision e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b)"}},"title":"errorResponse"}}}},"5XX":{"description":"Server error responses.","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":400},"code":{"type":"string","example":"bad_request"},"error":{"type":"string","example":"Bad Request"},"message":{"type":"string","description":"Human-readable explanation.","example":"Revision '1.4.0' exists with a different bill of materials (revision e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b)"}},"title":"errorResponse"}}}}}}
>
  
</StatusCodes>