---
title: "Create a new version"
method: POST
path: "/projects/{projectId}/versions"
tags: ["Versions"]
---

# Create a new version

`POST /projects/{projectId}/versions`

## Request

- Base URL: `https://app.ketryx.com/api/v1`
- URL: `https://app.ketryx.com/api/v1/projects/{projectId}/versions`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/ketryx/apis/ketryx-api/docs/projects/:projectId/versions/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a new version in the given project. Optionally accepts settings (referenced versions, repository settings, visibility) to fully configure the version in a single call. When the idempotentKey query parameter is provided, returns an existing version with the same key instead of creating a duplicate.

## Query parameters

- `idempotentKey` string

## Request body

- object
  - `name` string, required
  - `versionNumber` string: Explicit version number to use for this version instead of deriving it from the version name.
  - `visibility` 'VISIBLE' | 'HIDDEN': Controls version visibility in lists and pickers. Defaults to VISIBLE.
  - `referencedVersions` object[]
    - `project` union, required
      - object
        - `id` string
      - object
        - `name` string
    - `version` union, required
      - object
        - `id` string
      - object
        - `name` string
  - `repositorySettings` object[]: Version-specific repository settings that override the project-level repository configuration. This allows you to specify different Git references (tags, branches, or commit SHAs) for this specific version.
    - `url` string, required: Repository URL that matches one of the repositories configured for this project. Must exactly match a repository URL already associated with the project.
    - `releaseRefPattern` string, nullable: Git reference pattern for this version. Can be a tag (e.g., "refs/tags/v1.0"), branch name (e.g., "main" or "release/1.0"), or commit SHA (e.g., "abc123def456"). If null or omitted, the repository-wide release ref pattern will be used.

## Response `200`

OK

- object
  - `id` string

## Other responses

- `400`: The request is not valid.
- `401`: The requester is not authenticated.
- `403`: The requester is unauthorized.
- `404`: The resource was not found.

---

[API](https://skmtc.dev/ketryx/apis/ketryx-api.md) - [All operations](https://skmtc.dev/ketryx/apis/ketryx-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ketryx/apis/ketryx-api/revisions/a2a484dc35ca?raw)