> ## 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 or ensure a draft App for a workspace (v1) > Idempotent per workspace. Ensures a draft App exists for the caller's workspace: creates a new draft on first call (returns the new draft) or returns the existing draft on re-entry (with any supplied app-field overrides applied as a PATCH). Always returns 200 with the resulting draft App. Status code is the same on first call and subsequent calls -- clients distinguish create-vs-existing by tracking whether they previously held this draft's id, not by the response status. ## OpenAPI ````yaml /api-specs/cloud/public-api.yaml post /api/apps/v1/apps/drafts openapi: 3.0.3 info: title: Domino Public API description: Domino Public API Endpoints version: cloud servers: [] security: - DominoApiKey: [] - BearerAuthentication: [] tags: - name: AIGateway - name: AppInstances - name: AppVersions - name: Apps - name: AsyncPredictions - name: AuditTrail - name: BillingTag - name: BillingTagSettings - name: Cost - name: CustomMetrics - name: DataSource - name: DatasetRw - name: DeploymentTargets - name: Environments - name: Extensions - name: GenAI - name: HardwareTier - name: Jobs - name: ModelAPI - name: ModelAPIVersion - name: ModelDeployment - name: Organizations - name: PPM - name: PersonalAccessToken - name: ProjectSharedDatasets - name: ProjectTemplates - name: Projects - name: ProjectsCommits - name: ProjectsFiles - name: RegisteredModels - name: ServiceAccounts - name: Users - name: Workspaces paths: /api/apps/v1/apps/drafts: post: tags: - Apps summary: Create or ensure a draft App for a workspace (v1) description: > Idempotent per workspace. Ensures a draft App exists for the caller's workspace: creates a new draft on first call (returns the new draft) or returns the existing draft on re-entry (with any supplied app-field overrides applied as a PATCH). Always returns 200 with the resulting draft App. Status code is the same on first call and subsequent calls -- clients distinguish create-vs-existing by tracking whether they previously held this draft's id, not by the response status. operationId: createAppDraftV1 requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateAppDraftRequestV1' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/CreateAppDraftResponseV1' description: Success '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '422': $ref: '#/components/responses/422' '500': $ref: '#/components/responses/500' components: schemas: CreateAppDraftRequestV1: description: > Request body for POST /apps/drafts. Idempotent per workspace. On first call (no draft linked to this workspace yet), creates a new draft App with isDraft=true, vanityUrlNamespace=AppDrafts, entryPoint=null, authorId=caller, and projectId resolved from the workspace; missing app fields use defaults (name=Draft App, visibility=GRANT_BASED, etc.). The new draft's id is then linked to the workspace. On re-entry (workspace already has a draft), returns the existing draft with any supplied DraftAppFields applied as a PATCH; missing fields leave the existing draft untouched. If the workspace's draft pointer references an App that was deleted out-of-band, the pointer is self-healed: a fresh draft is created and re-linked. Optional initialVersion sub-flow: when `initialVersion` is supplied, a createAndStart is performed against the resulting draft after the draft itself has been ensured. The new version inherits draft defaulting (omitted content reference fields default to the previous running version when one exists), bundleId is forced empty on the draft App's version, and an instance is initiated. The response then carries the version (and instance, when start initiation succeeds) alongside the draft App. properties: app: $ref: '#/components/schemas/DraftAppFields' description: > Optional draft App field overrides. On create, missing fields use defaults. On re-entry, supplied fields PATCH the existing draft; missing fields leave the existing values untouched. initialVersion: $ref: '#/components/schemas/CreateAndStartAppVersionRequestV1' description: > Optional initial-version createAndStart payload. When present, a createAndStart is performed against the draft after the draft is ensured. entryScript is required when initialVersion is supplied (drafts always require entryScript on the version since entryPoint is null on the App). targetAppId: description: > Optional id of an existing App the client plans to publish into. Not persisted. Currently advisory; the backend ignores it during draft creation. type: string workspaceId: description: > The workspace this draft is scoped to. Required. Must be visible to the caller; unknown or hidden workspaces return 404. type: string required: - workspaceId type: object CreateAppDraftResponseV1: description: > Response body for POST /apps/drafts. The draft App is always present; version and instance are populated only when an initialVersion was supplied. If the initial-version start initiation fails, the version is still returned alongside a `warnings` array describing the failure. properties: app: $ref: '#/components/schemas/AppResponseV1' instance: $ref: '#/components/schemas/AppInstanceSummaryResponseV1' description: >- Present only when an initialVersion was supplied AND start initiation succeeded. version: $ref: '#/components/schemas/AppVersionResponseV1' description: Present only when an initialVersion was supplied. warnings: description: Non-fatal warnings (e.g., initial start initiation failure). items: type: string type: array required: - app type: object DraftAppFields: description: > Optional draft App metadata. Two App-level fields are intentionally absent: - `entryPoint`: drafts always carry entryPoint=null at the App level; the running version's `entryScript` is what surfaces on responses as a draft App's effective entry point. - `vanityUrl`: drafts always carry vanityUrl=null and vanityUrlNamespace=AppDrafts. Drafts are addressed exclusively by id (`/preview/` via `ModelProductUri.generateModelProductUri`), so a vanity string would be reserved-but-invisible state. Vanity-URL ownership only enters the picture at publish time, where the resulting published App in the `Apps` namespace picks up either a request-supplied or randomly generated vanity. Supplying a vanityUrl via `initialVersion.startOverrides` on this endpoint, or via startOverrides on `POST /apps/{appId}/versions/{versionId}/start`, is rejected with 422 when the parent App is a draft. properties: accessStatuses: items: $ref: '#/components/schemas/AppAccessStatus' type: array configurationType: $ref: '#/components/schemas/AppConfigurationType' description: type: string discoverable: type: boolean mountDatasets: type: boolean name: type: string renderIFrame: type: boolean visibility: enum: - AUTHENTICATED - GRANT_BASED - GRANT_BASED_STRICT - PUBLIC type: string type: object CreateAndStartAppVersionRequestV1: description: > Request body for POST /apps/{appId}/versions/createAndStart and the optional initialVersion sub-flow on POST /apps/drafts. Content (reproducibility) fields (commits, refs, environment, mounts) and deployment (execution) fields (hardwareTier, autoscaling) are accepted on the new version. Run-time overrides for the initiated instance (vanityUrl, autoscalingSpecification, etc.) are carried separately under `startOverrides`. Draft-specific defaulting: when the parent App is a draft AND a previous running version exists, omitted content reference fields default to the previous running version's values (commitId, mainRepoGitRef, entryScript, environmentId, environmentRevisionId, hardwareTierId, externalVolumeMountIds, netAppVolumeIds). Governance only starts when a draft is published. properties: autoscalingSpecification: $ref: '#/components/schemas/AppAutoscalingSpecification' bundleId: description: Guardrails bundle ID. Not applicable on drafts. type: string dataPlaneId: type: string description: type: string dfsCommitId: type: string entryScript: description: Effective entry point for the App version. type: string environmentId: type: string environmentRevisionId: type: string extendedIdentityPropagationToAppsEnabled: default: false type: boolean externalVolumeMountIds: items: type: string type: array gitRef: $ref: '#/components/schemas/GitRef' hardwareTierId: type: string mountDatasets: description: > Optional. If supplied, overrides the App's default for this version. If omitted, inherits from the parent App. type: boolean netAppVolumeIds: items: type: string type: array resolvedDfsCommitId: type: string resolvedGitCommitId: type: string resolvedImportedGitRepos: items: $ref: '#/components/schemas/ImportedGitRepoSnapshot' type: array resolvedImportedProjects: items: $ref: '#/components/schemas/ImportedProjectSnapshot' type: array startOverrides: $ref: '#/components/schemas/StartAppVersionRequestV1' description: > Optional deployment-only run-time overrides for the initiated instance (`deployment.hardwareTierId`, `deployment.autoscalingSpecification`, `deployment.vanityUrl`, `deployment.renderIFrame`). Content fields are supplied at the top level of the request body for the version snapshot. tags: items: $ref: '#/components/schemas/AppVersionTag' type: array type: object AppResponseV1: properties: accessControl: $ref: '#/components/schemas/AppAccessControl' authorship: $ref: '#/components/schemas/AppAuthorship' configurationType: $ref: '#/components/schemas/AppConfigurationType' currentVersion: $ref: '#/components/schemas/AppVersionResponseV1' customFields: description: Custom field values assigned to this app, grouped by group name. items: $ref: '#/components/schemas/CustomFieldValueGroup' type: array description: type: string entryPoint: type: string id: type: string mountDatasets: description: >- App-level default for whether to mount Domino Datasets into the App's runtime. type: boolean name: type: string project: $ref: '#/components/schemas/AppProjectResponse' renderIFrame: type: boolean taxonomyTags: description: >- Taxonomy tags assigned to this app. Omitted when the taxonomy feature is disabled. items: $ref: '#/components/schemas/TaxonomyTag' type: array thumbnailEtag: type: string updatedAt: format: epoch type: number url: type: string vanityUrl: type: string views: type: number required: - id - name - project - entryPoint - renderIFrame - url - views - configurationType - authorship - accessControl - 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 publisher: allOf: - $ref: '#/components/schemas/AppUserResponse' description: User who started this run. nullable: true status: type: string required: - id - createdAt - status type: object AppVersionResponseV1: properties: bundle: $ref: '#/components/schemas/AppVersionBundle' content: $ref: '#/components/schemas/AppVersionContent' createdAt: format: epoch type: number currentInstance: $ref: '#/components/schemas/AppInstanceSummaryResponseV1' 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 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 AppAccessStatus: properties: status: enum: - ALLOWED - DENIED - PENDING type: string userId: type: string required: - userId - status type: object AppConfigurationType: default: STANDARD description: >- Type of configuration for the app which determines different deployment resources and settings. enum: - STANDARD - AISYSTEM type: string 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 GitRef: properties: type: enum: - head - commitId - branches - tags - custom type: string value: type: string required: - type type: object ImportedGitRepoSnapshot: properties: ref: type: string repoId: type: string repoName: type: string required: - repoId - repoName - ref 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 StartAppVersionRequestV1: description: > Deployment overrides applied at launch. `deployment.hardwareTierId` and `deployment.autoscalingSpecification` are mirrored back to the version so it always reflects the last launch. `deployment.vanityUrl` and `deployment.renderIFrame` write back to the App on published starts and are rejected with 422 on draft starts. properties: deployment: $ref: '#/components/schemas/AppVersionDeploymentUpdate' description: | Deployment overrides for this launch. type: object AppVersionTag: properties: key: type: string value: type: string required: - key - value type: object AppAccessControl: description: Visibility and access-grant settings for an App. properties: accessStatuses: items: $ref: '#/components/schemas/AppAccessStatus' type: array discoverable: type: boolean visibility: enum: - AUTHENTICATED - GRANT_BASED - GRANT_BASED_STRICT - PUBLIC type: string required: - visibility - accessStatuses - discoverable type: object AppAuthorship: description: >- Identity metadata for an App: whether it is a draft and the user who created it. properties: author: allOf: - $ref: '#/components/schemas/AppUserResponse' description: User who created this App. nullable: true isDraft: description: >- True when this App is a workspace-scoped draft. Always false for published Apps. type: boolean required: - isDraft type: object CustomFieldValueGroup: properties: fields: items: $ref: '#/components/schemas/CustomFieldValue' type: array groupName: description: Group name. "Ungrouped" for fields with no group. type: string required: - groupName - fields type: object AppProjectResponse: properties: id: type: string name: type: string ownerId: type: string ownerUsername: type: string projectType: enum: - Analytic - Dataset - Template type: string required: - id - projectType - name - ownerId - ownerUsername type: object TaxonomyTag: properties: description: type: string fullPath: description: >- Ancestor labels from root to direct parent. Empty for root-level tags. items: type: string type: array id: type: string label: type: string namespaceId: type: string namespaceLabel: type: string required: - id - label - namespaceId type: object AppUserResponse: properties: id: type: string name: type: string required: - id - name 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' 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 AppVersionDeployment: description: Execution settings for the version. properties: autoscalingSpecification: $ref: '#/components/schemas/AppAutoscalingSpecification' hardwareTierId: type: string vanityUrl: type: string 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 CustomFieldValue: properties: customFieldId: type: string customFieldLabel: type: string status: enum: - active - deprecated type: string type: enum: - text - number - date - boolean - url - user - organization - user_or_org type: string updatedAt: format: epoch type: number updatedBy: $ref: '#/components/schemas/CustomFieldUpdatedBy' value: description: >- Encoded scalar value as stored upstream; encoding depends on type. Absent when no value is set. type: string required: - customFieldId - customFieldLabel - type - status 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 CustomFieldUpdatedBy: properties: userId: type: string username: type: string required: - userId type: object responses: '400': content: application/json: schema: properties: error: type: string type: object description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/FailureEnvelopeV1' description: >- The current user cannot perform this operation because they are not logged in '403': content: application/json: schema: $ref: '#/components/schemas/FailureEnvelopeV1' description: The current user is not authorized to perform this operation '404': content: application/json: schema: properties: error: type: string type: object description: Not Found '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: in: header name: X-Domino-Api-Key type: apiKey BearerAuthentication: in: header name: Authorization type: apiKey ````