Reference

Custom blocks

Start with our Custom Blocks and Actions that speed up your usage of the Vercel API.

Projects & Deployments API reference

Create project

Create a new Vercel project using the create project API.

SDK:

import { Vercel } from "@vercel/sdk";

const vercel = new Vercel({
  bearerToken: "<YOUR_BEARER_TOKEN_HERE>",
});

async function run() {
  const result = await vercel.projects.createProject({
    teamId: "team_1a2b3c4d5e6f7g8h9i0j1k2l",
    slug: "my-team-url-slug",
    requestBody: {
      name: "a-project-name",
    },
  });

  console.log(result);
}

run();

Deploy to project

Create a deployment for a project using the create deployment API.

SDK:

import { Vercel } from "@vercel/sdk";

const vercel = new Vercel({
  bearerToken: "<YOUR_BEARER_TOKEN_HERE>",
});

async function run() {
  const result = await vercel.deployments.createDeployment({
    teamId: "team_1a2b3c4d5e6f7g8h9i0j1k2l",
    slug: "my-team-url-slug",
    requestBody: {
      deploymentId: "dpl_2qn7PZrx89yxY34vEZPD31Y9XVj6",
      files: [
        {
          data: "<value>",
          file: "folder/file.js",
        },
      ],
      gitMetadata: {
        remoteUrl: "https://github.com/vercel/next.js",
        commitAuthorName: "kyliau",
        commitAuthorEmail: "kyliau@example.com",
        commitMessage:
          "add method to measure Interaction to Next Paint (INP) (#36490)",
        commitRef: "main",
        commitSha: "dc36199b2234c6586ebe05ec94078a895c707e29",
        dirty: true,
        ci: true,
        ciType: "github-actions",
        ciGitProviderUsername: "rauchg",
        ciGitRepoVisibility: "private",
      },
      gitSource: {
        projectId: 987654321,
        ref: "main",
        sha: "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
        type: "gitlab",
      },
      meta: {
        foo: "bar",
      },
      name: "my-instant-deployment",
      project: "my-deployment-project",
      projectSettings: {
        buildCommand: "next build",
        installCommand: "pnpm install",
      },
      target: "production",
    },
  });

  console.log(result);
}

run();

List deployments

Get deployments for a project using the list deployments API.

SDK:

import { Vercel } from "@vercel/sdk";

const vercel = new Vercel({
  bearerToken: "<YOUR_BEARER_TOKEN_HERE>",
});

async function run() {
  const result = await vercel.deployments.getDeployments({
    app: "docs",
    from: 1612948664566,
    limit: 10,
    projectId: "QmXGTs7mvAMMC7WW5ebrM33qKG32QK3h4vmQMjmY",
    projectIds: ["prj_123", "prj_456"],
    target: "production",
    to: 1612948664566,
    users: "kr1PsOIzqEL5Xg6M4VZcZosf,K4amb7K9dAt5R2vBJWF32bmY",
    since: 1540095775941,
    until: 1540095775951,
    state: "BUILDING,READY",
    teamId: "team_1a2b3c4d5e6f7g8h9i0j1k2l",
    slug: "my-team-url-slug",
  });

  console.log(result);
}

run();

Delete project

Remove a project and all its deployments using the delete project API.

SDK:

import { Vercel } from "@vercel/sdk";

const vercel = new Vercel({
  bearerToken: "<YOUR_BEARER_TOKEN_HERE>",
});

async function run() {
  const result = await vercel.deployments.deleteDeployment({
    id: "dpl_5WJWYSyB7BpgTj3EuwF37WMRBXBtPQ2iTMJHJBJyRfd",
    url: "https://files-orcin-xi.vercel.app/",
    teamId: "team_1a2b3c4d5e6f7g8h9i0j1k2l",
    slug: "my-team-url-slug",
  });

  console.log(result);
}

run();

Error codes

Troubleshooting

Deployment Failures

Problem: Deployments failing with build errors.

Solution:

• Check build logs via SDK
• Verify package.json dependencies
• Ensure build command is correct
• Check for environment variable issues
• Verify Node.js version compatibility

Project Creation Limits

Problem: Cannot create more projects.

Solution:

• Check current project count against plan limit
• Delete unused projects
• Upgrade to higher tier plan
• Contact sales for enterprise limits

Domain Conflicts

Problem: Domain already in use error.

Solution:

• Domain must be unique across Vercel
• Remove domain from other project first
• Use subdomain instead (tenant1.yourdomain.com)
• Verify domain ownership if domain exists elsewhere

Build Errors

Problem: Builds timing out or failing.

Solution:

• Optimize build process
• Check build time limits for your plan
• Reduce dependencies
• Use build caching
• Split large builds into stages

Resource Quota Issues

Problem: Hitting function size or execution limits.

Solution:

• Review function sizes
• Optimize bundle size
• Check execution time limits
• Consider upgrading plan
• Split large functions

FAQ

What's the difference between Multi-Project and Multi-Tenant?

Multi-Project: Multiple Vercel projects, each with unique code and isolated deployments. Complete separation between tenants.

Multi-Tenant: Single project serving multiple tenants with different content. All tenants share the same codebase.

Use Multi-Project when tenants need custom code. Use Multi-Tenant when tenants share functionality but have different content.

How many projects can I create?

Project limits depend on your plan:

• Hobby: Limited projects per account
• Pro: Higher limits
• Enterprise: Custom limits based on needs

Contact sales for specific limits.

How is pricing calculated per tenant?

Each project is billed based on:

• Build minutes: Time spent building deployments
• Function invocations: Number of function calls
• Bandwidth: Data transferred
• Edge requests: CDN requests

All usage follows standard Vercel pricing. See pricing documentation.

Are there isolation guarantees?

Yes, Multi-Project provides complete isolation:

• Build isolation: Separate build environments
• Runtime isolation: Independent function execution
• Data isolation: No shared state between projects
• Configuration isolation: Separate environment variables

How does data retention work?

When you delete a project:

• Deployments are deleted immediately
• Build logs are retained for 30 days
• Environment variables are deleted
• Domains are released

Export any data you need before deleting projects.

How can I monitor multiple projects?

Monitor projects using:

• Vercel Dashboard: View all projects per team
• SDK: Query project and deployment status
• Webhooks: Get real-time deployment notifications
• Analytics: View usage and performance metrics

Can I migrate from Multi-Tenant to Multi-Project?

Yes, but it requires architectural changes:

1. Export tenant data from shared database
2. Create separate projects per tenant
3. Deploy tenant code to each project
4. Configure domains for each project
5. Update tenant routing in your application

This is a significant migration. Consider carefully before switching.

What are the rate limits?

API rate limits for project operations:

• Create project: 100 requests per hour
• Create deployment: 1000 requests per hour
• Delete project: 100 requests per hour
• Other operations: Standard API limits

See API rate limits documentation.

How do I handle CI/CD per tenant?

Each project can have its own CI/CD:

• Connect to tenant's Git repository
• Configure build settings per project
• Set up deployment webhooks
• Use GitHub Actions or other CI tools
• Test and deploy independently

Can tenants manage their own projects?

No, programmatically created projects are managed by your team. Tenants cannot access the Vercel dashboard for their projects unless you add them as team members (not recommended for platforms).

Instead, build your own interface for tenants to:

• Trigger deployments
• View deployment status
• Configure environment variables
• Monitor usage

Next steps

• Concepts: Understand multi-project architecture
• Quickstart: Get started with multi-project platforms
• Vercel SDK: Complete SDK documentation