> ## Documentation Index > Fetch the complete documentation index at: https://docs.domino.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create App Version (v1) > Create a new version. Does NOT start an instance. ## OpenAPI ````yaml /api-specs/cloud/public-api.json post /api/apps/v1/apps/{appId}/versions openapi: 3.0.3 info: title: Domino Public API description: Reference for Domino's public REST API endpoints. version: 6.4.0 x-catalog-key: nucleus servers: - url: https://mycluster.domino.tech description: >- Replace 'mycluster.domino.tech' with your Domino cluster hostname. For Domino Cloud customers, that is `your-subdomain`.domino.tech (e.g., acme.domino.tech). For self-hosted deployments, it is the hostname you reach the Domino UI at. security: [] tags: - name: Projects - name: Project templates - name: Workspaces - name: Jobs - name: HPC Jobs - name: Environments - name: Hardware Tiers - name: Datasets - name: Data Sources - name: GenAI - name: AI Systems - name: Apps - name: App versions - name: App instances - name: Model APIs - name: Registered models - name: Model deployment - name: Extensions - name: Cost and billing - name: Users and organizations - name: Service accounts - name: Personal Access Tokens - name: Personal Access Tokens (admin) - name: Audit Trail - name: Custom metrics - name: PPM - name: Model Monitoring models - name: Model Monitoring drift and quality - name: Model Monitoring settings - name: Model Monitoring authentication - name: Governance bundles - name: Governance policies - name: Governance evidence and results - name: Governance operations - name: NetApp Volumes - name: NetApp Volumes snapshots - name: NetApp Volumes filesystems - name: NetApp Volumes transfers - name: Tags - name: Properties externalDocs: description: OpenAPI url: https://swagger.io/resources/open-api/ paths: /api/apps/v1/apps/{appId}/versions: post: tags: - App versions summary: Create App Version (v1) description: | Create a new version. Does NOT start an instance. operationId: createAppVersionV1 parameters: - in: path name: appId required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/AppVersionCreationRequestV1' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/AppVersionResponseV1' description: Success '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '422': $ref: '#/components/responses/422' '500': $ref: '#/components/responses/500' security: - DominoApiKey: [] - BearerAuthentication: [] components: schemas: AppVersionCreationRequestV1: description: > Create a new version of an App. The content sub-object carries reproducibility fields (including the per-version mountDatasets override) and deployment carries execution settings. Top-level fields are version metadata that don't fit cleanly into the content/deployment groupings. properties: bundleId: description: Guardrails bundle ID. type: string content: $ref: '#/components/schemas/AppVersionContentUpdate' deployment: $ref: '#/components/schemas/AppVersionDeploymentUpdate' description: description: Optional version description. type: string tags: items: $ref: '#/components/schemas/AppVersionTag' type: array workspaceId: description: > Draft only. ID of the apps-authoring workspace to associate with this draft version. Returns 422 if the parent App is not a draft. type: string type: object AppVersionResponseV1: properties: bundle: $ref: '#/components/schemas/AppVersionBundle' content: $ref: '#/components/schemas/AppVersionContent' createdAt: format: epoch type: number currentInstance: $ref: '#/components/schemas/AppInstanceSummaryResponseV1' description: The most recently created instance for this AppVersion. deployment: $ref: '#/components/schemas/AppVersionDeployment' description: type: string id: type: string tags: items: $ref: '#/components/schemas/AppVersionTag' type: array updatedAt: format: epoch type: number versionNumber: description: Monotonically increasing version number derived from creationOrder. format: int64 type: integer required: - id - createdAt - updatedAt - tags type: object AppVersionContentUpdate: description: > Reproducibility fields that define the version's content. All fields are optional; omitted fields fall back to App-level defaults or the previous draft's values depending on context. Mirrors the response-side AppVersionContent shape. properties: dataPlaneId: description: > Target data plane ID. If omitted but hardwareTierId is provided in deployment, auto-populated from the hardware tier's data plane. Returns 422 if both are provided and they don't match. type: string dfsCommitId: type: string entryScript: description: Effective entry point for the draft App version. type: string environmentId: type: string environmentRevisionId: type: string extendedIdentityPropagationToAppsEnabled: type: boolean externalVolumeMountIds: items: type: string type: array gitRef: $ref: '#/components/schemas/GitRef' importedGitRepoRefPatches: description: > Per-`repoId` patches applied to the version's imported-git-repo reference list. The baseline the patches apply over is endpoint-specific: the prior running version's references when iterating a draft, the publish base's references when publishing, and the project's currently-configured references otherwise. items: $ref: '#/components/schemas/ImportedGitRepoRefPatch' type: array mountDatasets: description: > Per-version override of the App-level mountDatasets default for whether to mount Domino Datasets into this version's runtime. When omitted, the App-level default applies. type: boolean netAppVolumeIds: items: type: string type: array resolvedCommits: $ref: '#/components/schemas/ResolvedCommitsUpdate' type: object AppVersionDeploymentUpdate: description: > Execution settings for the version. All fields are optional; omitted fields fall back to App-level defaults or the previous version's values depending on context. Mirrors the response-side AppVersionDeployment shape. properties: autoscalingSpecification: $ref: '#/components/schemas/AppAutoscalingSpecification' hardwareTierId: type: string renderIFrame: description: > Deployment-field override for App-level renderIFrame. Only valid when starting a published App version: the override is written back to the App alongside launch (mirrors the vanityUrl writeback) so the value reflects the running version. Returns 422 when supplied on a draft start, since drafts rebaseline renderIFrame from the draft App on publish and any override would be silently lost. type: boolean vanityUrl: type: string type: object AppVersionTag: properties: key: type: string value: type: string required: - key - value type: object AppVersionBundle: properties: id: description: Guardrails bundle ID. Immutable after creation. type: string name: type: string type: object AppVersionContent: description: Reproducibility fields that define the version's content. properties: dataPlaneId: nullable: true type: string dfsCommitId: type: string entryScript: description: Effective entry point for the App version. type: string environmentId: type: string environmentRevisionId: type: string extendedIdentityPropagationToAppsEnabled: type: boolean externalVolumeMountIds: items: type: string type: array gitRef: $ref: '#/components/schemas/GitRef' importedGitRepoRefs: description: > Imported-git-repo references recorded on this version. A subset of `resolvedCommits.importedGitRepos` by `repoId`; entries omitted from this list use the project's currently-configured ref at run time. Sorted by `repoId`. items: $ref: '#/components/schemas/ImportedGitRepoRef' type: array mountDatasets: description: >- Whether to mount Domino Datasets into the App's runtime for this version. type: boolean netAppVolumeIds: items: type: string type: array resolvedCommits: $ref: '#/components/schemas/ResolvedCommits' required: - mountDatasets type: object AppInstanceSummaryResponseV1: properties: createdAt: format: epoch type: number describeUrl: type: string dfsCommitId: description: The DFS commit ID that was used for this instance's execution. type: string gitCommitId: description: The git commit SHA that was used for this instance's execution. type: string id: type: string lastSynced: allOf: - $ref: '#/components/schemas/AppInstanceLastSyncedState' description: >- The code state last successfully synced to the preview pod. Absent for non-preview instances or preview instances that have not yet been synced. nullable: true publisher: allOf: - $ref: '#/components/schemas/AppUserResponse' description: User who started this run. nullable: true status: type: string required: - id - createdAt - status type: object AppVersionDeployment: description: Execution settings for the version. properties: autoscalingSpecification: $ref: '#/components/schemas/AppAutoscalingSpecification' hardwareTierId: type: string vanityUrl: type: string type: object ErrorV1: properties: code: description: Machine-readable error code. example: NOT_FOUND type: string message: description: Human-readable description of the error. example: The requested HPC Job could not be found. type: string required: - message type: object FailureEnvelopeV1: properties: errors: description: Errors that caused a request to fail items: type: string type: array requestId: description: Id used to correlate a request with server actions. example: bbd78579-93c4-45ee-a983-0d5c8da6d5b1 type: string required: - requestId - errors type: object GitRef: properties: type: enum: - head - commitId - branches - tags - custom type: string value: type: string required: - type type: object ImportedGitRepoRefPatch: description: > Per-`repoId` patch entry for the stored imported-git-repo reference list. A non-null `gitRef` sets the reference for `repoId` on this version; a `null` or omitted `gitRef` drops `repoId` from the list (the run-time ref then falls back to the project's currently-configured ref). Within a single request the last entry for a given `repoId` wins. properties: gitRef: allOf: - $ref: '#/components/schemas/GitRef' nullable: true repoId: type: string required: - repoId type: object ResolvedCommitsUpdate: description: > Pre-resolved commit and import snapshot information supplied at version creation time. When provided, these values bypass the commit resolver and are persisted directly. All fields are optional. Field names mirror the response-side ResolvedCommits shape so request and response use the same vocabulary. `importedGitRepos` carries per-`repoId` patch entries rather than a full replacement list: each entry upserts (`ref` set) or tombstones (`ref` omitted or null) the resolved pin for that repo. The full set of pinned imports for the new version is computed by applying these patches over the baseline (the prior version's resolved imports on draft re-iteration / publish; the project-current set on first-version creation). Repos with no patch entry inherit their baseline pin. properties: dfsCommitId: description: >- Pre-resolved DFS commit ID; bypasses the commit resolver when provided. type: string gitCommitId: description: >- Pre-resolved git commit SHA; bypasses the commit resolver when provided. type: string importedGitRepos: description: > Per-`repoId` patches against the baseline resolved imports. See the schema description above. items: $ref: '#/components/schemas/ImportedGitRepoSnapshotPatch' type: array importedProjects: description: >- Pre-resolved imported project snapshots; bypasses the resolver when provided. items: $ref: '#/components/schemas/ImportedProjectSnapshot' type: array type: object AppAutoscalingSpecification: properties: enabled: type: boolean maxReplicas: maximum: 30 minimum: 1 type: integer minReplicas: maximum: 30 minimum: 1 type: integer scaleDownStabilizationWindowSeconds: maximum: 3600 minimum: 0 type: integer scaleUpStabilizationWindowSeconds: maximum: 3600 minimum: 0 type: integer targetCpuAvgUtilizationPct: maximum: 100 minimum: 1 type: integer targetMemoryAvgUtilizationPct: maximum: 100 minimum: 1 type: integer useSessionAffinity: type: boolean required: - enabled type: object ImportedGitRepoRef: description: > Imported-git-repo reference recorded on a version. The companion list `resolvedCommits.importedGitRepos` covers the same `repoId` set (and may additionally cover `repoId`s absent here); entries omitted from this list use the project's currently-configured ref at run time. properties: gitRef: $ref: '#/components/schemas/GitRef' repoId: type: string repoName: type: string required: - repoId - repoName - gitRef type: object ResolvedCommits: description: >- Resolved commit and import snapshot information captured at version creation time. properties: dfsCommitId: description: The DFS commit ID resolved at version creation time. type: string gitCommitId: description: The git commit SHA resolved at version creation time. type: string importedGitRepos: description: Imported git repo snapshots resolved at version creation time. items: $ref: '#/components/schemas/ImportedGitRepoSnapshot' type: array importedProjects: description: Imported project snapshots resolved at version creation time. items: $ref: '#/components/schemas/ImportedProjectSnapshot' type: array type: object AppInstanceLastSyncedState: description: >- A snapshot of the commit state after a successful live sync to a running preview instance. properties: dfsCommitId: description: DFS commit SHA currently running in the preview pod. nullable: true type: string importedRepoCommits: description: >- Commit SHAs for each imported git repo currently running in the preview pod. items: $ref: '#/components/schemas/AppInstanceLastSyncedRepoCommit' type: array mainRepoCommitId: description: Main git repo commit SHA currently running in the preview pod. nullable: true type: string syncedAt: description: Epoch timestamp (ms) when the last successful sync completed. format: epoch type: number required: - syncedAt type: object AppUserResponse: type: object required: - id - name properties: id: type: string name: type: string ImportedGitRepoSnapshotPatch: description: > Per-`repoId` patch entry for the resolved imported-git-repo snapshot list. A non-null `ref` pins the commit for `repoId` on this version (no resolution performed); a `null` or omitted `ref` drops `repoId` from the snapshot list. `repoName` is optional; when omitted the server fills it from the project's enabled-repo list at request time. properties: ref: nullable: true type: string repoId: type: string repoName: type: string required: - repoId type: object ImportedProjectSnapshot: properties: commitId: type: string directoryName: type: string ownerId: type: string projectId: type: string projectName: type: string release: type: string required: - projectId - projectName - ownerId - directoryName - commitId type: object ImportedGitRepoSnapshot: properties: ref: type: string repoId: type: string repoName: type: string required: - repoId - repoName - ref type: object AppInstanceLastSyncedRepoCommit: properties: ref: description: The commit SHA currently running for this imported repo. type: string repoId: description: The imported git repo ID. type: string required: - repoId - ref type: object responses: '400': content: application/json: schema: properties: error: type: string type: object description: Bad Request '401': content: application/json: example: code: UNAUTHORIZED message: Authentication is required to access this resource. schema: $ref: '#/components/schemas/ErrorV1' description: Unauthorized - authentication is required or has failed. '403': content: application/json: example: code: FORBIDDEN message: You do not have permission to perform this action. schema: $ref: '#/components/schemas/ErrorV1' description: Forbidden - the caller lacks permission to perform this action. '422': content: application/json: schema: $ref: '#/components/schemas/FailureEnvelopeV1' description: >- The server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions. '500': content: application/json: schema: properties: error: type: string type: object description: Internal Server Error securitySchemes: DominoApiKey: type: apiKey in: header name: X-Domino-Api-Key BearerAuthentication: type: apiKey name: Authorization in: header ```` ## Related topics - [Create App (v1)](/api-reference/apps/create-app-v1.md) - [Create App Version and Start (v1)](/api-reference/app-versions/create-app-version-and-start-v1.md) - [Create or ensure a draft App for a workspace (v1)](/api-reference/apps/create-or-ensure-a-draft-app-for-a-workspace-v1.md) - [Publish and deploy App versions](/cloud/platform-capabilities/features/apps/publish-and-deploy-app-versions.md)