---
title: "Create a new deployment"
method: POST
path: "/v13/deployments"
tags: ["deployments"]
---

# Create a new deployment

`POST /v13/deployments`

## Request

- Base URL: `https://api.vercel.com`
- URL: `https://api.vercel.com/v13/deployments`
- Auth: HTTP bearer

Creates a new deployment for the authenticated team or user. For non-git deployments, upload files first via the file upload API, then reference them here by SHA — or inline small files directly in the request body. To redeploy an existing deployment, provide its `deploymentId`; all settings are inherited unless explicitly overridden. The deployment begins building immediately and transitions through `QUEUED` → `INITIALIZING` → `BUILDING` before reaching `READY` or `ERROR`.

## Query parameters

- `forceNew` '0' | '1': Forces a new deployment even if there is a previous similar deployment. Set to `1` to bypass deployment deduplication and always trigger a fresh build.
- `skipAutoDetectionConfirmation` '0' | '1': Set to `1` to skip framework auto-detection and proceed without confirmation. By default, if Vercel detects a framework that differs from the project setting, the API returns a `400` asking you to confirm. Use this to suppress that check in automated pipelines.
- `teamId` string
- `slug` string

## Request body

- object
  - `buildMachine` 'turbo': Selects a custom build machine for this deployment without changing project settings.
  - `customEnvironmentSlugOrId` string: The slug or ID of a custom environment to deploy to, overriding the default target environment. When omitted, the deployment targets the environment inferred from the branch (production or preview).
  - `deploymentId` string: The ID of an existing deployment to redeploy. All project settings and environment variables are inherited from the original unless explicitly overridden in this request. The redeployment gets a new ID, URL, and build.
  - `files` union[]: The files to include in the deployment. Each entry is either an inlined file (with `data` and `encoding`) or a reference to a previously uploaded file (with `sha` and `size`). Required for non-git deployments. Cannot be used together with `gitSource`.
    - union
      - object: Used in the case you want to inline a file inside the request
        - `data` string, required: The file content, it could be either a `base64` (useful for images, etc.) of the files or the plain content for source code
        - `encoding` 'base64' | 'utf-8': The file content encoding, it could be either a base64 (useful for images, etc.) of the files or the plain text for source code.
        - `file` string, required: The file name including the whole path
      - object: Used in the case you want to reference a file that was already uploaded
        - `file` string, required: The file path relative to the project root
        - `sha` string: The file contents hashed with SHA1, used to check the integrity
        - `size` integer: The file size in bytes
  - `gitAccessToken` string: Available only to Vercel platform accounts. A read-only GitHub access token scoped to the requested repository. Use a token with a lifetime of 24 hours or less that remains valid until source retrieval completes.
  - `gitMetadata` object: Populates initial git metadata for different git providers.
    - `remoteUrl` string: The git repository's remote origin url
    - `commitAuthorName` string: The name of the author of the commit
    - `commitAuthorEmail` string: The email of the author of the commit
    - `commitMessage` string: The commit message
    - `commitRef` string: The branch on which the commit was made
    - `commitSha` string: The hash of the commit
    - `dirty` boolean: Whether or not there have been modifications to the working tree since the latest commit
    - `ci` boolean: True if process.env.CI was set when deploying
    - `ciType` string: The type of CI system used
    - `ciGitProviderUsername` string: The username used for the Git Provider (e.g. GitHub) if their CI (e.g. GitHub Actions) was used, if available
    - `ciGitRepoVisibility` string: The visibility of the Git repository if their CI (e.g. GitHub Actions) was used, if available
    - `rootDirectory` string: Path of the deployed directory relative to the detected git repository root. Empty string when deploying from the repository root.
  - `gitSource` union: Defines the Git Repository source to be deployed. This property can not be used in combination with `files`.
    - object
      - `type` 'vercel', required
      - `repoId` string, required: The stable Vercel Git repository ID.
      - `sha` string, required
    - object
      - `ref` string, required
      - `repoId` union, required
        - number
        - string
      - `sha` string
      - `type` 'github', required
    - object
      - `org` string, required
      - `ref` string, required
      - `repo` string, required
      - `sha` string
      - `type` 'github', required
    - object
      - `ref` string, required
      - `repoId` union, required
        - number
        - string
      - `sha` string
      - `type` 'github-limited', required
    - object
      - `org` string, required
      - `ref` string, required
      - `repo` string, required
      - `sha` string
      - `type` 'github-limited', required
    - object
      - `projectId` union, required
        - number
        - string
      - `ref` string, required
      - `sha` string
      - `type` 'gitlab', required
    - object
      - `ref` string, required
      - `repoUuid` string, required
      - `sha` string
      - `type` 'bitbucket', required
      - `workspaceUuid` string
    - object
      - `owner` string, required
      - `ref` string, required
      - `sha` string
      - `slug` string, required
      - `type` 'bitbucket', required
    - object: Deploys from the Cursor Origin repository linked to the target project. The repository ID must match the linked repository; Vercel resolves the owner and repository name from the project link.
      - `owner` string: The Origin workspace slug. Optional because Vercel resolves it from the linked project.
      - `ref` string, required: The branch or Git reference to deploy.
      - `repo` string: The Origin repository name. Optional because Vercel resolves it from the linked project.
      - `repoId` string, required: The stable Origin repository ID. Read it from the `link.repoId` field returned by the project API.
      - `sha` string: The commit SHA to deploy. When omitted, Vercel resolves the latest commit on `ref`.
      - `type` 'cursor-origin', required
  - `meta` object: An object containing the deployment's metadata. Multiple key-value pairs can be attached to a deployment. For deployments created with a Cursor Origin `gitSource`, Vercel automatically adds `cursorOriginDeployment`, `cursorOriginCommitSha`, `cursorOriginCommitRef`, `cursorOriginCommitMessage`, `cursorOriginCommitAuthorName`, `cursorOriginCommitAuthorEmail` when available, `cursorOriginOwner`, `cursorOriginRepo`, `cursorOriginRepoId`, and `cursorOriginPrId` for pull request deployments.
  - `monorepoManager` string, nullable: The monorepo manager that is being used for this deployment. When `null` is used no monorepo manager is selected
  - `name` string, required: A string with the project name used in the deployment URL
  - `project` string: The target project identifier in which the deployment will be created. When defined, this parameter overrides name
  - `projectSettings` object: Project settings that will be applied to the deployment. It is required for the first deployment of a project and will be saved for any following deployments
    - `buildCommand` string, nullable: The build command for this project. When `null` is used this value will be automatically detected
    - `commandForIgnoringBuildStep` string, nullable
    - `devCommand` string, nullable: The dev command for this project. When `null` is used this value will be automatically detected
    - `framework` 'null' | 'services' | 'container' | 'blitzjs' | 'nextjs' | 'gatsby' | 'remix' | 'react-router' | 'astro' | 'hexo' | 'eleventy' | 'docusaurus-2' | 'docusaurus' | 'preact' | 'solidstart-1' | 'solidstart' | 'dojo' | 'ember' | 'vue' | 'scully' | 'ionic-angular' | 'angular' | 'polymer' | 'svelte' | 'sveltekit' | 'sveltekit-1' | 'ionic-react' | 'create-react-app' | 'gridsome' | 'umijs' | 'sapper' | 'saber' | 'stencil' | 'nuxtjs' | 'redwoodjs' | 'hugo' | 'jekyll' | 'brunch' | 'middleman' | 'zola' | 'hydrogen' | 'vite' | 'tanstack-start' | 'tanstack-start-lovable' | 'vitepress' | 'vuepress' | 'parcel' | 'fastapi' | 'flask' | 'fasthtml' | 'django' | 'ash' | 'factory-eve' | 'eve' | 'sanity' | 'sanity-v2' | 'storybook' | 'nitro' | 'hono' | 'express' | 'h3' | 'koa' | 'nestjs' | 'elysia' | 'fastify' | 'xmcp' | 'python' | 'ruby' | 'rust' | 'axum' | 'actix-web' | 'bun' | 'node' | 'go' | 'mastra', nullable: The framework that is being used for this project. When `null` is used no framework is selected
    - `installCommand` string, nullable: The install command for this project. When `null` is used this value will be automatically detected
    - `nodeVersion` '26.x' | '24.x' | '22.x' | '20.x' | '18.x' | '16.x' | '14.x' | '12.x' | '10.x' | '8.10.x': Override the Node.js version that should be used for this deployment
    - `outputDirectory` string, nullable: The output directory of the project. When `null` is used this value will be automatically detected
    - `rootDirectory` string, nullable: The name of a directory or relative path to the source code of your project. When `null` is used it will default to the project root
    - `serverlessFunctionRegion` string, nullable: The region to deploy Serverless Functions in this project
    - `skipGitConnectDuringLink` boolean: Opts-out of the message prompting a CLI user to connect a Git repository in `vercel link`.
    - `sourceFilesOutsideRootDirectory` boolean: Indicates if there are source files outside of the root directory, typically used for monorepos
  - `target` string: Either not defined, `staging`, `production`, or a custom environment identifier. If `staging`, a staging alias in the format `<project>-<team>.vercel.app` will be assigned. If `production`, any aliases defined in `alias` will be assigned. If omitted, the target will be `preview`.
  - `withLatestCommit` boolean: When `true` and `deploymentId` is passed in, the sha from the previous deployment's `gitSource` is removed forcing the latest commit to be used.

## Response `200`

Returns the newly created deployment object. Poll `readyState` to track build progress. See https://vercel.com/docs/deployments/deployment-states for possible states.
Returns the reduced deployment view for anonymous (`vcn_`) callers. Pool-team details are withheld.

- union
  - object: Returns the reduced deployment view for anonymous (`vcn_`) callers. Pool-team details are withheld.
    - `alias` string[]
    - `aliasAssigned` false | true, required
    - `aliasError` object, nullable: An object that will contain a `code` and a `message` when the aliasing fails, otherwise the value will be `null`
      - `code` string, required
      - `message` string, required
    - `aliasWarning` object, nullable
      - `action` string
      - `code` string, required
      - `link` string
      - `message` string, required
    - `duration` object, required
      - `endTime` number: Unix timestamp in milliseconds when the build container exited.
      - `endTimeCapped` number: Build-container exit Unix timestamp in milliseconds, capped at 45 minutes after `startTime`.
      - `startTime` number: Unix timestamp in milliseconds when the deployment entered BUILDING.
      - `timeForBilling` number: Billable build-container duration in milliseconds, capped at 45 minutes, rounded up to a whole minute, with a one-minute minimum.
      - `timeToContainerExit` number: Milliseconds from entering BUILDING until the build container exited, without the billing cap.
      - `timeToContainerExitCapped` number: Build-container duration in milliseconds, capped at 45 minutes and without billing rounding.
      - `timeToReady` number: Milliseconds from entering BUILDING until the deployment reached its current ready state.
    - `errorCode` string
    - `errorMessage` string, nullable
    - `id` string, required: A string holding the unique ID of the deployment
    - `readyState` 'BLOCKED' | 'BUILDING' | 'CANCELED' | 'ERROR' | 'INITIALIZING' | 'QUEUED' | 'READY', required: The state of the deployment depending on the process of deploying, or if it is ready or in an error state
    - `target` 'production' | 'staging' | 'null', nullable: If defined, either `staging` if a staging alias in the format `<project>.<team>.now.sh` was assigned upon creation, or `production` if the aliases from `alias` were assigned. `null` value indicates the "preview" deployment.
  - object: Returns the newly created deployment object. Poll `readyState` to track build progress. See https://vercel.com/docs/deployments/deployment-states for possible states.
    - `alias` string[]: A list of all the aliases (default aliases, staging aliases and production aliases) that were assigned upon deployment creation
    - `aliasAssigned` false | true, required: A boolean that will be true when the aliases from the alias property were assigned successfully
    - `aliasAssignedAt` union
      - number
      - false | true
    - `aliasError` object, nullable: An object that will contain a `code` and a `message` when the aliasing fails, otherwise the value will be `null`
      - `code` string, required
      - `message` string, required
    - `aliasFinal` string, nullable
    - `aliasWarning` object, nullable
      - `action` string
      - `code` string, required
      - `link` string
      - `message` string, required
    - `alwaysRefuseToBuild` false | true
    - `atproto` union
      - object
        - `enabled` false, required
      - object
        - `enabled` true, required
        - `subscription` object, required
          - `collections` string[], required
          - `dids` string[]
          - `kinds` string[]
          - `path` string, required
    - `attribution` object: Attribution metadata for the deployment, linking commit author to git and Vercel users. Only populated when the `enable-deployment-attribution` flag is enabled.
      - `commitMeta` object: Commit metadata from the git commit author
        - `email` string: Email from git commit author
        - `isVerified` false | true: Whether the commit was signed/verified (GitHub only, others return undefined)
        - `name` string: Name from git commit author
      - `gitUser` object: Git provider user associated with the commit author email (only set if resolved)
        - `id` union, required
          - string
          - number
        - `login` string, required: Git provider username/login
        - `provider` string: The git provider (github, gitlab, bitbucket)
        - `type` string: User type
      - `vercelUser` object: Vercel user linked to the git provider account (only set if resolved)
        - `id` string, required: Vercel user ID
        - `teamRoles` string[]: Team roles at time of deployment
        - `username` string, required: Vercel username
    - `autoAssignCustomDomains` false | true: applies to custom domains only, defaults to `true`
    - `automaticAliases` string[]
    - `bootedAt` number, required
    - `build` object, required
      - `env` string[], required
    - `buildArtifactUrls` string[]
    - `buildContainerFinishedAt` number: Since April 2025 it necessary for On-Demand Concurrency Minutes calculation
    - `buildErrorAt` number
    - `buildingAt` number, required
    - `builds` object[]
      - `config` object
      - `src` string
      - `use` string, required
    - `buildSkipped` false | true, required
    - `canceledAt` number
    - `checks` object
      - `deployment-alias` object, required
        - `completedAt` number
        - `startedAt` number, required
        - `state` 'failed' | 'pending' | 'succeeded', required
    - `checksConclusion` 'canceled' | 'failed' | 'skipped' | 'succeeded'
    - `checksState` 'completed' | 'registered' | 'running'
    - `config` object: Since February 2025 the configuration must include snapshot data at the time of deployment creation to capture properties for the /deployments/:id/config endpoint utilized for displaying Deployment Configuration on the frontend This is optional because older deployments may not have this data captured
      - `functionMemoryType` 'performance' | 'performance_xl' | 'standard' | 'standard_legacy', required
      - `functionTimeout` number, nullable, required
      - `functionType` 'fluid' | 'standard', required
      - `isUsingActiveCPU` false | true
      - `resourceConfig` object: Build resource configuration snapshot for this deployment.
        - `buildQueue` object: Build resource configuration snapshot for this deployment.
          - `configuration` 'SKIP_NAMESPACE_QUEUE' | 'WAIT_FOR_NAMESPACE_QUEUE': Build resource configuration snapshot for this deployment.
        - `elasticConcurrency` 'PROJECT_SETTING' | 'SKIP_QUEUE' | 'TEAM_SETTING': When elastic concurrency is used for this deployment, a value is set. The value tells the reason where the setting was coming from. - TEAM_SETTING: Inherited from team settings - PROJECT_SETTING: Inherited from project settings - SKIP_QUEUE: Manually triggered by user to skip the queues
        - `buildMachine` object
          - `purchaseType` '14cpu-28gb' | 'basic' | 'enhanced' | 'standard' | 'turbo' | 'null', nullable: Machine type that was used for the build.
      - `secureComputeFallbackRegion` string, nullable, required
      - `secureComputePrimaryRegion` string, nullable, required
      - `version` number
    - `connectBuildsEnabled` false | true
    - `connectConfigurationId` string
    - `createdAt` number, required: A number containing the date when the deployment was created in milliseconds
    - `createdIn` string, required
    - `creator` object, required: Information about the deployment creator
      - `avatar` string: The avatar of the user that created the deployment
      - `type` 'app' | 'integration' | 'project' | 'system' | 'user': Principal type of the deployment creator.
      - `uid` string, required: Stable creator id across principal types (user id, app id, integration configuration id, or `system`).
      - `username` string: The username of the user that created the deployment
    - `crons` object[]
      - `path` string, required
      - `schedule` string, required
    - `customEnvironment` union
      - object: If the deployment was created using a Custom Environment, then this property contains information regarding the environment used.
        - `branchMatcher` object: Configuration for matching git branches to this environment
          - `pattern` string, required: The pattern to match against branch names
          - `type` 'endsWith' | 'equals' | 'startsWith', required: The type of matching to perform
        - `createdAt` number, required: Timestamp when the environment was created
        - `currentDeploymentAliases` string[]: List of aliases for the current deployment
        - `description` string: Optional description of the environment's purpose
        - `domains` object[]: List of domains associated with this environment
          - `apexName` string, required
          - `createdAt` number
          - `customEnvironmentId` string, nullable
          - `gitBranch` string, nullable
          - `name` string, required
          - `projectId` string, required
          - `redirect` string, nullable
          - `redirectStatusCode` 301 | 302 | 307 | 308 | null, nullable
          - `updatedAt` number
          - `verification` object[]: A list of verification challenges, one of which must be completed to verify the domain for use on the project. After the challenge is complete `POST /projects/:idOrName/domains/:domain/verify` to verify the domain. Possible challenges: - If `verification.type = TXT` the `verification.domain` will be checked for a TXT record matching `verification.value`.
            - `domain` string, required
            - `reason` string, required
            - `type` string, required
            - `value` string, required
          - `verified` false | true, required: `true` if the domain is verified for use with the project. If `false` it will not be used as an alias on this project until the challenge in `verification` is completed.
        - `id` string, required: Unique identifier for the custom environment (format: env_*)
        - `slug` string, required: URL-friendly name of the environment
        - `type` 'development' | 'preview' | 'production', required: The type of environment (production, preview, or development)
        - `updatedAt` number, required: Timestamp when the environment was last updated
      - object: If the deployment was created using a Custom Environment, then this property contains information regarding the environment used.
        - `id` string, required
    - `defaultRoute` string: Computed field that is only available for deployments with a microfrontend configuration.
    - `deletedAt` number, nullable: A number containing the date when the deployment was deleted at milliseconds
    - `duration` object, required
      - `endTime` number: Unix timestamp in milliseconds when the build container exited.
      - `endTimeCapped` number: Build-container exit Unix timestamp in milliseconds, capped at 45 minutes after `startTime`.
      - `startTime` number: Unix timestamp in milliseconds when the deployment entered BUILDING.
      - `timeForBilling` number: Billable build-container duration in milliseconds, capped at 45 minutes, rounded up to a whole minute, with a one-minute minimum.
      - `timeToContainerExit` number: Milliseconds from entering BUILDING until the build container exited, without the billing cap.
      - `timeToContainerExitCapped` number: Build-container duration in milliseconds, capped at 45 minutes and without billing rounding.
      - `timeToReady` number: Milliseconds from entering BUILDING until the deployment reached its current ready state.
    - `env` string[], required
    - `errorCode` string
    - `errorLink` string
    - `errorMessage` string, nullable
    - `errorStep` string
    - `flags` union
      - object: Flags defined in the Build Output API, used by this deployment. Primarily used by the Toolbar to know about the used flags.
        - `definitions` object, required
      - object[]: Flags defined in the Build Output API, used by this deployment. Primarily used by the Toolbar to know about the used flags.
    - `functions` object, nullable
    - `gitRepo` union
      - object
        - `defaultBranch` string, required
        - `name` string, required
        - `namespace` string, required
        - `ownerType` 'team' | 'user', required
        - `path` string, required
        - `private` false | true, required
        - `projectId` number, required
        - `type` 'gitlab', required
        - `url` string, required
      - object
        - `defaultBranch` string, required
        - `name` string, required
        - `org` string, required
        - `ownerType` 'team' | 'user', required
        - `path` string, required
        - `private` false | true, required
        - `repo` string, required
        - `repoId` number, required
        - `repoOwnerId` number, required
        - `type` 'github', required
      - object
        - `defaultBranch` string, required
        - `name` string, required
        - `owner` string, required
        - `ownerType` 'team' | 'user', required
        - `path` string, required
        - `private` false | true, required
        - `repoUuid` string, required
        - `slug` string, required
        - `type` 'bitbucket', required
        - `workspaceUuid` string, required
      - object
        - `defaultBranch` string, required
        - `name` string, required
        - `org` string, required
        - `ownerType` 'team' | 'user', required
        - `path` string, required
        - `private` false | true, required
        - `repo` string, required
        - `type` 'vercel', required
      - object
        - `defaultBranch` string, required
        - `name` string, required
        - `owner` string, required: Owner (namespace) slug.
        - `ownerType` 'team' | 'user', required
        - `path` string, required
        - `private` false | true, required
        - `repo` string, required
        - `repoId` string, required: Origin repository id.
        - `type` 'cursor-origin', required
    - `gitSource` union
      - object
        - `prId` number, nullable
        - `ref` string, nullable
        - `repoId` union, required
          - string
          - number
        - `sha` string
        - `type` 'github', required
      - object
        - `org` string, required
        - `prId` number, nullable
        - `ref` string, nullable
        - `repo` string, required
        - `sha` string
        - `type` 'github', required
      - object
        - `host` string, required
        - `prId` number, nullable
        - `ref` string, nullable
        - `repoId` union, required
          - string
          - number
        - `sha` string
        - `type` 'github-custom-host', required
      - object
        - `host` string, required
        - `org` string, required
        - `prId` number, nullable
        - `ref` string, nullable
        - `repo` string, required
        - `sha` string
        - `type` 'github-custom-host', required
      - object
        - `prId` number, nullable
        - `ref` string, nullable
        - `repoId` union, required
          - string
          - number
        - `sha` string
        - `type` 'github-limited', required
      - object
        - `org` string, required
        - `prId` number, nullable
        - `ref` string, nullable
        - `repo` string, required
        - `sha` string
        - `type` 'github-limited', required
      - object
        - `prId` number, nullable
        - `projectId` union, required
          - string
          - number
        - `ref` string, nullable
        - `sha` string
        - `type` 'gitlab', required
      - object
        - `prId` number, nullable
        - `ref` string, nullable
        - `repoUuid` string, required
        - `sha` string
        - `type` 'bitbucket', required
        - `workspaceUuid` string
      - object
        - `owner` string, required
        - `prId` number, nullable
        - `ref` string, nullable
        - `sha` string
        - `slug` string, required
        - `type` 'bitbucket', required
      - object
        - `commitMetadata` object
          - `author` object, required
            - `date` string, required
            - `email` string, required
            - `name` string, required
          - `committer` object, required
            - `date` string, required
            - `email` string, required
            - `name` string, required
          - `message` string, required
        - `org` string
        - `prId` number, nullable
        - `ref` string, nullable
        - `repo` string
        - `repoId` string, required
        - `repoPushedAt` number
        - `sha` string, required
        - `type` 'vercel', required
      - object
        - `owner` string: Owner (namespace) slug.
        - `prId` number, nullable
        - `ref` string, nullable
        - `repo` string
        - `repoId` string, required: Origin repository id.
        - `sha` string
        - `type` 'cursor-origin', required
      - object: Allows custom git sources (local folder mounted to the container) in test mode
        - `gitUrl` string, required
        - `ref` string, required
        - `sha` string, required
        - `type` 'custom', required
      - object
        - `org` string
        - `ref` string, required
        - `repo` string
        - `repoId` number, required
        - `sha` string, required
        - `type` 'github', required
      - object
        - `host` string, required
        - `org` string
        - `ref` string, required
        - `repo` string
        - `repoId` number, required
        - `sha` string, required
        - `type` 'github-custom-host', required
      - object
        - `org` string
        - `ref` string, required
        - `repo` string
        - `repoId` number, required
        - `sha` string, required
        - `type` 'github-limited', required
      - object
        - `projectId` number, required
        - `ref` string, required
        - `sha` string, required
        - `type` 'gitlab', required
      - object
        - `owner` string
        - `ref` string, required
        - `repoUuid` string, required
        - `sha` string, required
        - `slug` string
        - `type` 'bitbucket', required
        - `workspaceUuid` string, required
      - object
        - `commitMetadata` object
          - `author` object, required
            - `date` string, required
            - `email` string, required
            - `name` string, required
          - `committer` object, required
            - `date` string, required
            - `email` string, required
            - `name` string, required
          - `message` string, required
        - `org` string, required
        - `ref` string, required
        - `repo` string, required
        - `repoId` string
        - `repoPushedAt` number
        - `sha` string, required
        - `type` 'vercel', required
      - object
        - `owner` string, required
        - `ref` string, required
        - `repo` string, required
        - `repoId` string, required
        - `sha` string, required
        - `type` 'cursor-origin', required
    - `id` string, required: A string holding the unique ID of the deployment
    - `images` object
      - `contentDispositionType` 'attachment' | 'inline'
      - `contentSecurityPolicy` string
      - `dangerouslyAllowSVG` false | true
      - `domains` string[]
      - `formats` string[]
      - `localPatterns` object[]
        - `pathname` string: Can be literal or wildcard. Single `*` matches a single path segment. Double `**` matches any number of path segments.
        - `search` string: Can be literal query string such as `?v=1` or empty string meaning no query string.
      - `minimumCacheTTL` number
      - `qualities` number[]
      - `remotePatterns` object[]
        - `hostname` string, required: Can be literal or wildcard. Single `*` matches a single subdomain. Double `**` matches any number of subdomains.
        - `pathname` string: Can be literal or wildcard. Single `*` matches a single path segment. Double `**` matches any number of path segments.
        - `port` string: Can be literal port such as `8080` or empty string meaning no port.
        - `protocol` 'http' | 'https': Must be `http` or `https`.
        - `search` string: Can be literal query string such as `?v=1` or empty string meaning no query string.
      - `sizes` number[]
    - `initReadyAt` number
    - `inspectorUrl` string, nullable, required
    - `integrations` object
      - `claimedAt` number
      - `completedAt` number
      - `skippedAt` number
      - `skippedBy` string
      - `startedAt` number, required
      - `status` 'error' | 'pending' | 'ready' | 'skipped' | 'timeout', required
    - `isFirstBranchDeployment` false | true
    - `isInConcurrentBuildsQueue` false | true, required
    - `isInstantStatic` false | true: Whether this deployment completed through the instant static fast path.
    - `isInSystemBuildsQueue` false | true, required
    - `lambdas` object[]
      - `createdAt` number
      - `entrypoint` string, nullable
      - `id` string, required
      - `readyState` 'BUILDING' | 'ERROR' | 'INITIALIZING' | 'READY'
      - `readyStateAt` number
      - `output` object[], required
        - `functionName` string, required
        - `path` string, required
    - `manualProvisioning` object: Present when deployment was created with manual provisioning enabled, either explicitly or via the experimental BYOC git flow. The deployment stays in INITIALIZING until /continue is called.
      - `completedAt` number: Timestamp when manual provisioning completed
      - `state` 'COMPLETE' | 'PENDING' | 'TIMEOUT', required: Current provisioning state
    - `meta` object, required
    - `microfrontends` union
      - object
        - `defaultAppProjectName` string, required: The project name of the default app of this deployment's microfrontends group.
        - `defaultRoute` string: A path that is used to take screenshots and as the default path in preview links when a domain for this microfrontend is shown in the UI.
        - `groupIds` string[], required: The group of microfrontends that this project belongs to. Each microfrontend project must belong to a microfrontends group that is the set of microfrontends that are used together.
        - `isDefaultApp` false
      - object
        - `defaultAppProjectName` string, required: The project name of the default app of this deployment's microfrontends group.
        - `defaultRoute` string: A path that is used to take screenshots and as the default path in preview links when a domain for this microfrontend is shown in the UI.
        - `groupIds` string[], required: The group of microfrontends that this project belongs to. Each microfrontend project must belong to a microfrontends group that is the set of microfrontends that are used together.
        - `isDefaultApp` true, required
        - `mfeConfigUploadState` 'no_config' | 'success' | 'waiting_on_build': The result of the microfrontends config upload during deployment creation / build. Only set for default app deployments. The config upload is attempted during deployment create, and then again during the build. If the config is not in the root directory, or the deployment is prebuilt, the config cannot be uploaded during deployment create. The upload during deployment build finds the config even if it's not in the root directory, as it has access to all files. Uploading the config during create is ideal, as then all child deployments are guaranteed to have access to the default app deployment config even if the default app has not yet started building. If the config is not uploaded, the child app will show as building until the config has been uploaded during the default app build. - `success` - The config was uploaded successfully, either when the deployment was created or during the build. - `waiting_on_build` - The config could not be uploaded during deployment create, will be attempted again during the build. - `no_config` - No config was found. Only set once the build has not found the config in any of the deployment's files. - `undefined` - Legacy deployments, or there was an error uploading the config during deployment create.
    - `monorepoManager` string, nullable
    - `name` string, required: The name of the project associated with the deployment at the time that the deployment was created
    - `nodeVersion` '10.x' | '12.x' | '14.x' | '16.x' | '18.x' | '20.x' | '22.x' | '24.x' | '26.x' | '8.10.x': If set it overrides the `projectSettings.nodeVersion` for this deployment.
    - `oidcTokenClaims` object
      - `aud` string, required
      - `custom_environment_id` string
      - `deployment_id` string
      - `environment` string, required
      - `iss` string, required
      - `mfe_group_ids` string[]
      - `owner` string, required
      - `owner_id` string, required
      - `plan` string
      - `project` string, required
      - `project_id` string, required
      - `scope` string, required
      - `sub` string, required
    - `oomReport` 'out-of-memory'
    - `originCacheRegion` string
    - `ownerId` string, required
    - `passiveConnectConfigurationId` string: Since November 2023 this field defines a Secure Compute network that will only be used to deploy passive lambdas to (as in passiveRegions)
    - `passiveRegions` string[]: Since November 2023 this field defines a set of regions that we will deploy the lambda to passively Lambdas will be deployed to these regions but only invoked if all of the primary `regions` are marked as out of service
    - `plan` 'enterprise' | 'hobby' | 'pro', required
    - `platform` object: Metadata about the source platform that triggered the deployment. Allows us to map a deployment back to a platform (e.g. the chat that created it)
      - `creator` object, required: The user on the external platform who triggered the deployment.
        - `avatar` string: URL of the platform user's avatar image.
        - `name` string, required: Display name of the platform user.
      - `meta` object: Arbitrary key-value metadata provided by the platform.
      - `origin` object, required: Reference back to the entity on the platform that initiated the deployment.
        - `type` 'id' | 'url', required: Whether the value is an opaque identifier or a URL.
        - `value` string, required: The identifier or URL pointing to the originating entity.
      - `source` object, required: The external platform that created the deployment (e.g. its display name).
        - `name` string, required: Display name of the platform.
    - `prebuilt` false | true
    - `previewCommentsEnabled` false | true: Whether or not preview comments are enabled for the deployment
    - `project` object: The public project information associated with the deployment.
      - `framework` string, nullable
      - `id` string, required
      - `name` string, required
    - `projectId` string, required
    - `projectSettings` object, required
      - `buildCommand` string, nullable
      - `commandForIgnoringBuildStep` string, nullable
      - `devCommand` string, nullable
      - `framework` 'actix-web' | 'angular' | 'ash' | 'astro' | 'axum' | 'blitzjs' | 'brunch' | 'bun' | 'container' | 'create-react-app' | 'django' | 'docusaurus' | 'docusaurus-2' | 'dojo' | 'eleventy' | 'elysia' | 'ember' | 'eve' | 'express' | 'factory-eve' | 'fastapi' | 'fasthtml' | 'fastify' | 'flask' | 'gatsby' | 'go' | 'gridsome' | 'h3' | 'hexo' | 'hono' | 'hugo' | 'hydrogen' | 'ionic-angular' | 'ionic-react' | 'jekyll' | 'koa' | 'mastra' | 'middleman' | 'nestjs' | 'nextjs' | 'nitro' | 'node' | 'nuxtjs' | 'parcel' | 'polymer' | 'preact' | 'python' | 'react-router' | 'redwoodjs' | 'remix' | 'ruby' | 'rust' | 'saber' | 'sanity' | 'sanity-v2' | 'sapper' | 'scully' | 'services' | 'solidstart' | 'solidstart-1' | 'stencil' | 'storybook' | 'svelte' | 'sveltekit' | 'sveltekit-1' | 'tanstack-start' | 'tanstack-start-lovable' | 'umijs' | 'vite' | 'vitepress' | 'vue' | 'vuepress' | 'xmcp' | 'zola' | 'null', nullable
      - `installCommand` string, nullable
      - `nodeVersion` '10.x' | '12.x' | '14.x' | '16.x' | '18.x' | '20.x' | '22.x' | '24.x' | '26.x' | '8.10.x'
      - `outputDirectory` string, nullable
      - `speedInsights` object
        - `canceledAt` number
        - `dataReceivedAt` number: When the first free (not Speed Insights Plus) production data point was observed, in ms. Set once by subscriber-analytics-events; projects that already had data before this field shipped get it backfilled on their next batch, so it reads "first free data point observed", not necessarily "first ever".
        - `disabledAt` number
        - `enabledAt` number
        - `hasData` false | true
        - `id` string, required
        - `paidAt` number
      - `vercelFlags` object: Vercel Flags activation metadata copied from the project at deployment creation.
        - `enabledAt` number
      - `webAnalytics` object
        - `canceledAt` number
        - `disabledAt` number
        - `enabledAt` number
        - `hasData` true
        - `id` string, required
    - `public` false | true, required: A boolean representing if the deployment is public or not. By default this is `false`
    - `ready` number
    - `readyState` 'BLOCKED' | 'BUILDING' | 'CANCELED' | 'ERROR' | 'INITIALIZING' | 'QUEUED' | 'READY', required: The state of the deployment depending on the process of deploying, or if it is ready or in an error state
    - `readyStateReason` string
    - `readySubstate` 'PROMOTED' | 'ROLLING' | 'STAGED': Substate of deployment when readyState is 'READY' Tracks whether or not deployment has seen production traffic: - STAGED: never seen production traffic - ROLLING: in the process of having production traffic gradually transitioned. - PROMOTED: has seen production traffic
    - `regions` string[], required: The regions the deployment exists in
    - `resourceConfig` object
      - `buildMachine` union
        - object
          - `machineSelectionType` 'elastic', required: The build ran on an elastic machine. Drives billing.
          - `purchaseType` '14cpu-28gb' | 'basic' | 'enhanced' | 'standard' | 'turbo': Machine type purchased for this build. `basic` is the 2vCPU tier, recorded so the build pipeline can detect a basic build without consulting the project.
          - `cores` number: Build cores. Deployment creation sets the requested value; dispatch replaces it with the cores assigned by routing.
          - `defaultPurchaseType` 'basic' | 'enhanced' | 'none' | 'standard': The build machine tier included with the customer's plan. For most customers this is standard; enhanced entitlements include enhanced, while `none` means every build is billed at its purchase type.
          - `memory` number: Build memory, in MiB. Deployment creation sets the requested value; dispatch replaces it with the memory assigned by routing.
          - `selectionSource` 'deployment-override' | 'elastic-algorithm' | 'plan-default' | 'project-setting' | 'team-entitlement' | 'team-setting': The setting which selected the build machine when the deployment was created. Frozen here so later project or team changes do not rewrite its history.
        - object
          - `machineSelectionType` 'fixed': The build ran on a fixed machine. Drives billing.
          - `purchaseType` 'basic' | 'enhanced' | 'standard' | 'turbo': Machine type purchased for this build.
          - `cores` number: Build cores. Deployment creation sets the requested value; dispatch replaces it with the cores assigned by routing.
          - `defaultPurchaseType` 'basic' | 'enhanced' | 'none' | 'standard': The build machine tier included with the customer's plan. For most customers this is standard; enhanced entitlements include enhanced, while `none` means every build is billed at its purchase type.
          - `memory` number: Build memory, in MiB. Deployment creation sets the requested value; dispatch replaces it with the memory assigned by routing.
          - `selectionSource` 'deployment-override' | 'elastic-algorithm' | 'plan-default' | 'project-setting' | 'team-entitlement' | 'team-setting': The setting which selected the build machine when the deployment was created. Frozen here so later project or team changes do not rewrite its history.
    - `routes` union[], nullable, required
      - union
        - object
          - `caseSensitive` false | true
          - `check` false | true
          - `continue` false | true
          - `dest` string
          - `destination` union
            - string
            - object
              - …
          - `env` string[]
          - `has` union[]
            - union
              - …
          - `headers` object
          - `important` false | true
          - `locale` object
            - `cookie` string
            - `redirect` object
          - `methods` string[]
          - `middleware` number: A middleware index in the `middleware` key under the build result
          - `middlewarePath` string: A middleware key within the `output` key under the build result. Overrides a `middleware` definition.
          - `middlewareRawSrc` string[]: The original middleware matchers.
          - `missing` union[]
            - union
              - …
          - `mitigate` object
            - `action` 'challenge' | 'deny', required
          - `override` false | true
          - `respectOriginCacheControl` false | true
          - `source` string: Aliases for `src`, `dest`, and `status`. These provide consistency with the `rewrites`, `redirects`, and `headers` fields which use `source`, `destination`, and `statusCode`. During normalization, the string forms are converted to their canonical forms (`src`, `dest`, `status`) and stripped from the route object. `destination` may also be a service-targeted object, in which case routing is delegated into the named service's internal route table and the object is preserved as-is (not folded into `dest`).
          - `src` string, required
          - `status` number
          - `statusCode` number
          - `transforms` union[]
            - union
              - …
        - object
          - `dest` string
          - `handle` 'error' | 'filesystem' | 'hit' | 'miss' | 'resource' | 'rewrite', required
          - `src` string
          - `status` number
        - object
          - `continue` false | true, required
          - `middleware` 0, required
          - `src` string, required
    - `seatBlock` object: NSNB Blocked metadata
      - `blockCode` 'COMMIT_AUTHOR_REQUIRED' | 'TEAM_ACCESS_REQUIRED', required: The NSNB decision code for the seat block. TODO: We should consolidate block types.
      - `gitProvider` 'bitbucket' | 'github' | 'gitlab': The git provider type associated with gitUserId.
      - `gitUserId` union
        - string
        - number
      - `isVerified` false | true: Determines if the user was verified during the block. In the git integration case, the commit sender was the author.
      - `userId` string: The blocked vercel user ID.
    - `services` union[]: Services detected during build from vercel.json experimentalServices or auto-detected from project structure. Used to inject service URLs as environment variables at runtime.
      - union
        - object: Services detected during build from vercel.json experimentalServices or auto-detected from project structure. Used to inject service URLs as environment variables at runtime.
          - `buildCommand` string
          - `builder` object, required
            - `config` object
              - …
            - `src` string
            - `use` string, required
          - `entrypoint` string
          - `env` object
          - `framework` string
          - `group` string
          - `handlerFunction` string
          - `installCommand` string
          - `name` string, required
          - `preDeployCommand` string
          - `routePrefix` string
          - `routePrefixSource` 'configured' | 'generated'
          - `runtime` string
          - `schedule` union
            - string
            - string[]
          - `schema` 'experimentalServices', required
          - `subdomain` string
          - `topics` union
            - string[]
            - object[]
              - …
          - `trigger` 'queue' | 'schedule' | 'workflow'
          - `type` 'cron' | 'job' | 'web' | 'worker', required
          - `workspace` string, required
        - object: Services detected during build from vercel.json experimentalServices or auto-detected from project structure. Used to inject service URLs as environment variables at runtime.
          - `bindings` object[]: Caller-side bindings to other services.
            - `env` string, required: Environment variable name that will store the generated value
            - `format` 'url', required: Generated value shape, must be `"url"`.
            - `service` string, required: Target service name from `services`.
            - `type` 'service': If present, must be `"service"` for Service-to-Service HTTP bindings.
          - `buildCommand` string
          - `builder` object, required: Builder selected by the resolver.
            - `config` object
              - …
            - `src` string
            - `use` string, required
          - `cleanUrls` false | true
          - `command` string[]: Command override for `runtime: "container"` services.
          - `devCommand` string
          - `entrypoint` string: Resolved entrypoint, relative to the service root.
          - `framework` string
          - `functions` object: Function configuration scoped to this service.
          - `headers` object[]
            - `has` union[]
              - …
            - `headers` object[], required
              - …
            - `missing` union[]
              - …
            - `source` string, required
          - `ignoreCommand` string
          - `installCommand` string
          - `name` string, required
          - `outputDirectory` string
          - `redirects` object[]
            - `destination` string, required
            - `env` string[]
            - `has` union[]
              - …
            - `missing` union[]
              - …
            - `permanent` false | true
            - `source` string, required
            - `statusCode` number
          - `rewrites` object[]
            - `destination` union, required
              - …
            - `env` string[]
            - `has` union[]
              - …
            - `missing` union[]
              - …
            - `respectOriginCacheControl` false | true
            - `source` string, required
            - `statusCode` number
            - `transforms` object[]
              - …
          - `root` string, required: Path to the service root, relative to the project root.
          - `routes` union[]
            - union
              - …
          - `runtime` string
          - `schema` 'experimentalServicesV2', required
          - `trailingSlash` false | true
    - `softDeletedByRetention` false | true: flag to indicate if the deployment was deleted by retention policy
    - `source` 'api-trigger-git-deploy' | 'cli' | 'clone/repo' | 'drop' | 'git' | 'git-deploy-hook' | 'import' | 'import/repo' | 'redeploy' | 'v0-web': Where was the deployment created from. Best-effort guess for metrics only — not authoritative; do not gate behavior on it.
    - `status` 'BLOCKED' | 'BUILDING' | 'CANCELED' | 'ERROR' | 'INITIALIZING' | 'QUEUED' | 'READY', required
    - `target` 'production' | 'staging' | 'null', nullable: If defined, either `staging` if a staging alias in the format `<project>.<team>.now.sh` was assigned upon creation, or `production` if the aliases from `alias` were assigned. `null` value indicates the "preview" deployment.
    - `team` object: The team that owns the deployment if any
      - `avatar` string
      - `id` string, required
      - `name` string, required
      - `slug` string, required
    - `ttyBuildLogs` false | true
    - `type` 'LAMBDAS', required
    - `undeletedAt` number: A number containing the date when the deployment was undeleted at milliseconds
    - `url` string, required: A string with the unique URL of the deployment
    - `userAliases` string[]: An array of domains that were provided by the user when creating the Deployment.
    - `userConfiguredDeploymentId` string: Since January 2025 User-configured deployment ID for skew protection with pre-built deployments. This is set when users configure a custom deploymentId in their next.config.js file. This allows Next.js to use skew protection even when deployments are pre-built outside of Vercel's build system.
    - `version` 2, required: The platform version that was used to create the deployment.

## Other responses

- `400`: One of the provided values in the request body is invalid. One of the provided values in the request query is invalid.
- `401`: The request is not authorized.
- `402`: The account is missing a payment so payment method must be updated Pro customers are allowed to deploy Serverless Functions to up to `proMaxRegions` regions, or if the project was created before the limit was introduced. Deploying to Serverless Functions to multiple regions requires a plan update
- `403`: You do not have permission to access this resource.
- `404`
- `409`: The deployment project is being transferred
- `410`
- `426`
- `429`
- `500`
- `503`

## Changes

- **2026-10-28** `06344f7b73dd`: 1 breaking, 1 info
  - added `subschema #1, subschema #2` to the `oneOf[subschema #2]/resourceConfig/buildMachine` response property `oneOf` list for the response status `200`
  - removed `subschema #1, subschema #2` from the `oneOf[subschema #2]/resourceConfig/buildMachine` response property `oneOf` list for the response status `200`
- **2026-10-27** `ef8042371d97`: 1 breaking, 1 info
  - added `subschema #1, subschema #2` to the `oneOf[subschema #2]/services/items/` response property `oneOf` list for the response status `200`
  - removed `subschema #1, subschema #2` from the `oneOf[subschema #2]/services/items/` response property `oneOf` list for the response status `200`
- **2026-10-26** `b1c16fd8828a`: 1 info
  - added the optional property `oneOf[subschema #2]/projectSettings/vercelFlags` to the response with the `200` status
- **2026-10-23** `2060b55dc517`: 1 warning
  - added the new `project` enum value to the `oneOf[subschema #2]/creator/type` response property for the response status `200`
- **2026-10-21** `74d3a3591515`: 1 breaking, 1 info
  - added `subschema #1, subschema #2` to the `oneOf[subschema #2]/services/items/` response property `oneOf` list for the response status `200`
  - removed `subschema #1, subschema #2` from the `oneOf[subschema #2]/services/items/` response property `oneOf` list for the response status `200`

[Operation history](https://skmtc.dev/vercel/apis/vercel-api/changes/v13/deployments/post.md)

---

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