Create package version

Registers an immutable version for an existing Package. OCI-backed Packages verify the supplied version metadata against the published artifact before durable registration. Hosted Packages publish the immutable version from an authored repository while preserving the Package, Products, Offers, and existing Installs.

POST /packages/{id}/versions

Create package version

cURL

curl --request POST \
  --url https://api.akua.dev/v1/packages/{id}/versions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "semver": "1.2.3",
  "ref": "<string>",
  "input_schema": {}
}
'

201

{
  "id": "<string>",
  "package_id": "<string>",
  "semver": "<string>",
  "ref": "<string>",
  "input_schema": {},
  "published_at": 1,
  "created_at": 1,
  "etag": "<string>"
}

Authorizations

Authorization · string · header · required

workspace API token (sk_akua_...) or OAuth2 JWT. Create tokens at https://akua.dev/developers/api-tokens

Headers

akua-context · string

Optional workspace/scope context for the request. Carries a single workspace wire id (ws_…) today. Only needed for broad tokens - a workspace-owned token implies its workspace.

Required string length: 1 - 53

Example:

"ws_j572abc123def456"

idempotency-key · string

Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.

Required string length: 1 - 64

Example:

"create-prod-2026-05-07"

Path Parameters

id · string · required

Package ID

Required string length: 1 - 54

Example:

"pkg_j572abc123def456"

Body

application/json

Option 1

Option 2

semver · string · required

Required string length: 1 - 128

Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$

Example:

"1.2.3"

ref · string · required

Immutable package content reference. For OCI-backed packages this is normally the digest returned by akua publish; Akua verifies it against the published artifact before registering the version.

Required string length: 1 - 512

input_schema · object · required

JSON Schema exported from the Akua package version. Used to render future install forms; Akua verifies it against the published artifact before registering the version.

compatibility · object

Show child attributes

Response

201

application/json

Package version created

id · string · required

Required string length: 1 - 55

package_id · string · required

Required string length: 1 - 54

semver · string · required

Required string length: 1 - 128

Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$

ref · string · required

input_schema · object · required

published_at · integer · required

Unix timestamp (seconds)

Required range: x >= 0

created_at · integer · required

Unix timestamp (seconds)

Required range: x >= 0

etag · string