Deploy a zip file to a production website using Netlify's Build API

Let’s take a look at how a dynamic, zipped up website can be deployed to production in just a few commands using Netlify’s Build API.

Previously, we’ve shown how to deploy sites from AI tools, which walks through deploying a static build output to Netlify. We can take that one step further and deploy a fully dynamic application to production using Netlify’s new build API endpoints.

This provides tools building websites on behalf of their users with a simple way to deploy a fully dynamic application to production, with control over the flexibility and scalability of Netlify’s platform, including build settings, redirects, headers, edge functions, and more.

#TL;DR

We’ll walk through how the API authentication process, and then move on to create a new site, and then deploy zipped build output to a production website using Netlify’s Build API.

This is the recommended way for AI tools to deploy a fully dynamic application to production.

#Setup and API authentication

Working with the Netlify API requires a personal access token (PAT), which gets sent in the Authorization header of the request.

#Authentication for single users

If you’re deploying on behalf of a single user, or users that won’t need to claim their site on Netlify, you can generate a PAT in your user settings.

Here’s a video that shows how to generate a PAT for a single user:

#Authentication for multiple users

More common is the case that you’ll want to provide users with the ability to claim their site. In this case, you should create an OAuth application first, and then generate a PAT for that application. Refer to our guide about deploying sites from your AI tool for more details on this process.

#Create a new site

Before you create a build, you need to create a new site. Do this by sending a POST request to the /sites endpoint.

curl \
  -H "Authorization: Bearer <PERSONAL_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name": "<SITE_NAME>", "created_via": "<TOOL_NAME>", "session_id": "<SESSION_ID>"}' \
     "https://api.netlify.com/api/v1/sites"

Replace the following values:

• <PERSONAL_ACCESS_TOKEN>: the PAT you generated in the previous step.
• <SITE_NAME> (optional): the name of the site you want to create. If not provided, the site is named randomly.
• <TOOL_NAME> (optional): for Netlify partners that create sites on behalf of their users.
• <SESSION_ID> (optional): a unique identifier for the user creating the site. This is used by Netlify partners that create sites on behalf of their users.

Learn more about how our partners create sites on behalf of their users, and allow users to claim their site.

#New site response

The response will be a JSON object representing the site. It will include a few useful properties, including:

• id (and site_id): Unique identifier for the site
• url: URL for the site live in production
• admin_url: URL to the Netlify site admin UI

Note that the site will be live in production after the site is created and the URL is assigned. But, because you haven’t deployed anything, the site will be empty and the root route will return a 404 error.

#New site example request

Here’s a video that shows how to create a new site using the Netlify API and the curl command:

#Triggering a new build

Once you have a site, you can trigger a new build by sending a POST request to the /sites/<site_id>/builds endpoint, attaching the zip file to the request body.

Here’s a video that walks through the entire process:

#Build your site

First, you need to build your site locally. Usually this is something like npm run build, but may vary depending on the developer’s configuration.

npm run build

#Zip the build output

Next, you need to zip the build output. Frameworks often have a specific directory for the build output, so you need to zip that directory. Note that depending on the framework, the build output directory may be configurable.

With the output directory known, you can zip the build output with the following command:

zip -r build.zip <OUTPUT_DIR>/*

You now have a zip file that you can upload to Netlify to trigger a new build!

#Trigger a new production build and deploy

Now that you have a zip file, you can trigger a new production build and deploy by sending a POST request to the /sites/<site_id>/builds endpoint, attaching the zip file to the request body, and using the id or site_id property returned from the site creation request.

 curl -X POST \
      -H "Content-Type: application/zip" \
      -H "Authorization: Bearer <PERSONAL_ACCESS_TOKEN>" \
      --data-binary "@build.zip" \
      "https://api.netlify.com/api/v1/sites/<site-id>/builds"

Note the syntax for how the zip file is attached to the request body. It is the value of the data-binary option, and we use quotes with the @ symbol to attach the file.

#Checking on build success

If the endpoint fails, it returns an error HTTP status code with the following JSON response:

{
  "code": <error-code>,
  "message": "...."
}

You can use the deploy id returned by the upload endpoint to fetch the current status of the build and deploy.

#Set up notifications

Deploy notifications can help automate key workflows after a build completes, ensuring everything stays in sync without manual effort.

For example, once a build is successful, you might need to trigger an SEO audit, update a search index, or notify a CRM or email platform that fresh content is ready to go live. Instead of handling these updates manually, deploy notifications can automatically kick off these processes.

Similarly, if the site integrates with a chatbot platform that pulls dynamic content, a deploy notification can prompt the chatbot to refresh its responses with the latest updates. By leveraging deploy notifications, you can streamline these post-build tasks and keep external services up to date effortlessly.

Learn more about how to set up notifications when the status changes.

#Conclusion

With the Build API, you get full control over your deployment workflow while leveraging Netlify’s infrastructure to make site generation and deployment smoother for your users.

Whether you’re building landing pages, e-commerce stores, or full-stack apps, Netlify’s build system gives you the flexibility to customize each deployment with environment-specific settings, Functions, and Edge Functions. Instead of maintaining your own build pipeline, you can rely on Netlify to handle the heavy lifting, reducing complexity and freeing you up to focus on delivering the best possible experience for your users.