Netlify API Getting Started: Quickstart Guide (2026)

Getting started overview

To begin using the Netlify API, developers generally follow a three-step process: account creation, personal access token generation, and executing a first authenticated request. The API allows for the automation of tasks such as deploying sites, managing build settings, configuring custom domains, and interacting with Netlify serverless functions. Understanding these foundational steps is crucial for integrating Netlify into continuous integration/continuous deployment (CI/CD) pipelines or custom developer tooling.

The Netlify API follows a RESTful architecture, utilizing standard HTTP methods (GET, POST, PUT, DELETE) for operations on resources. Responses are typically formatted in JSON. Authentication is primarily handled via personal access tokens, which act as bearer tokens in the Authorization header of API requests. For applications requiring user authorization without direct credential exposure, Netlify also supports OAuth 2.0, a common framework for delegated authorization OAuth 2.0 specification overview.

Before making any API calls, ensure you have a Netlify account. The Netlify Starter plan is available for individual users and small projects, offering a free tier that supports core functionalities necessary for initial API exploration. This plan provides 100 GB bandwith and 300 build minutes per month, suitable for developing and testing API integrations.

Quick reference table

Create an account and get keys

The first step to interacting with the Netlify API is to create a Netlify account. If you already have an account, you can proceed directly to generating an access token. The signup process is straightforward, allowing registration via email, GitHub, GitLab, or Bitbucket. For new users, Netlify typically guides you through linking a Git repository to deploy your first site, which is not strictly necessary for API access but can be a useful way to familiarize yourself with the platform's deployment model Netlify Get Started documentation.

Generating a Personal Access Token

After creating and logging into your Netlify account, navigate to your User Settings under the Applications tab. Here you will find the section for Personal Access Tokens. Click on "New access token" to generate a new token. You will be prompted to provide a descriptive name for the token, such as "API Integration" or "CI/CD Bot". This name helps you identify the token's purpose later, especially if you manage multiple tokens.

Once generated, the token will be displayed on your screen. It is crucial to copy this token immediately and store it securely. Netlify does not store these tokens in a retrievable format, meaning if you lose it, you will need to generate a new one. Treat your access token like a password, as it grants full programmatic access to your Netlify account and its associated sites and resources. Avoid hardcoding it directly into your codebase; instead, use environment variables or a secure secret management system.

Your first request

With your personal access token in hand, you can now make your first API call. A common initial request is to list your sites, which confirms that your authentication is set up correctly and your token has the necessary permissions. The Netlify API reference provides comprehensive documentation for all available endpoints Netlify OpenAPI Specification.

Using cURL

The simplest way to test your token is using cURL from your terminal:

curl -X GET \ 
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ 
  "https://api.netlify.com/api/v1/sites"

Replace YOUR_ACCESS_TOKEN with the personal access token you generated. A successful response will return a JSON array of your Netlify sites, similar to this (truncated for brevity):

[
  {
    "id": "your-site-id-1",
    "name": "my-first-netlify-site",
    "url": "https://my-first-netlify-site.netlify.app",
    "admin_url": "https://app.netlify.com/sites/my-first-netlify-site",
    "created_at": "2023-01-01T12:00:00Z",
    "updated_at": "2024-05-29T10:30:00Z",
    "build_settings": {
      "repo_url": "https://github.com/your-username/my-first-netlify-site",
      "repo_branch": "main"
    }
  },
  {
    "id": "your-site-id-2",
    "name": "another-project",
    "url": "https://another-project.netlify.app",
    "admin_url": "https://app.netlify.com/sites/another-project",
    "created_at": "2023-02-15T14:00:00Z",
    "updated_at": "2024-05-28T09:00:00Z",
    "build_settings": {
      "repo_url": "https://github.com/your-username/another-project",
      "repo_branch": "dev"
    }
  }
]

Using JavaScript (Node.js)

For programmatic access, you can use JavaScript with Node.js. Install a library like node-fetch if you're not in a browser environment:

const fetch = require('node-fetch');

const accessToken = 'YOUR_ACCESS_TOKEN';

async function listNetlifySites() {
  try {
    const response = await fetch('https://api.netlify.com/api/v1/sites', {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      }
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log('Your Netlify Sites:', data);
  } catch (error) {
    console.error('Error fetching Netlify sites:', error);
  }
}

listNetlifySites();

Remember to replace YOUR_ACCESS_TOKEN with your actual token. This script will log a JSON array of your sites to the console.

Using Go (via SDK)

Netlify provides an official Go SDK for interacting with its API. First, install the SDK:

go get github.com/netlify/open-api/go/porcelain

Then, use it in your Go application:

package main

import (
	"context"
	"fmt"
	"log"

	netlify "github.com/netlify/open-api/go/porcelain"
)

func main() {
	accessToken := "YOUR_ACCESS_TOKEN"
	
	config := netlify.NewConfiguration()
	config.AddDefaultHeader("Authorization", "Bearer "+accessToken)
	
	client := netlify.NewAPIClient(config)
	
	sites, _, err := client.DefaultApi.ListSites(context.Background(), nil)
	if err != nil {
		log.Fatalf("Error listing sites: %v", err)
	}
	
	fmt.Println("Your Netlify Sites:")
	for _, site := range sites {
		fmt.Printf("- ID: %s, Name: %s, URL: %s\n", site.Id, site.Name, site.Url)
	}
}

This Go example demonstrates how to initialize the Netlify API client with your access token and then call the ListSites method to retrieve information about your deployed sites. This approach abstracts away the HTTP request details, providing a more idiomatic way to interact with the API for Go developers.

Common next steps

After successfully making your first API call, you can explore various functionalities offered by the Netlify API. Common next steps include:

• Deploying a site: You can programmatically initiate deployments, upload files, and manage deploy keys. This is particularly useful for custom CI/CD setups or uploading static assets from a non-Git source. The Netlify API deploy site documentation provides details on creating new deployments.
• Managing environment variables: Environment variables can be set and updated via the API, allowing for dynamic configuration of your Netlify sites and functions without manual intervention in the Netlify UI.
• Configuring custom domains: Automate the process of adding and verifying custom domains for your sites, simplifying domain management at scale.
• Interacting with Netlify Functions: Deploy, update, and manage serverless functions, enabling dynamic backend logic for your applications.
• Setting up webhooks: Use the API to configure webhooks that trigger external services or custom scripts in response to Netlify events, such as new deploys or form submissions. This enables powerful integrations with other platforms, as discussed in best practices for Twilio's webhook security guide.
• Monitoring build status: Retrieve information about your site builds, including their status, logs, and associated deploy IDs, enabling automated reporting or notifications.

Refer to the Netlify OpenAPI reference for a complete list of endpoints and their capabilities, including request and response schemas, to plan your further integrations.

Troubleshooting the first call

If your first API call does not return the expected results, consider the following common issues:

• Incorrect Access Token: Double-check that you have copied the entire Personal Access Token correctly. Even a single missing character can lead to authentication failures. Ensure there are no leading or trailing spaces.
• Missing or Malformed Authorization Header: The Authorization header must be in the format Bearer YOUR_ACCESS_TOKEN. A common mistake is omitting "Bearer " or using an incorrect capitalization.
• Network Connectivity: Verify your internet connection. Proxy settings or firewall rules might also prevent your requests from reaching the Netlify API endpoints.
• API Endpoint URL: Ensure you are using the correct base URL for the Netlify API: https://api.netlify.com/api/v1/. Incorrect paths or versions will result in 404 Not Found errors.
• Rate Limiting: While unlikely for a first call, repeated failed attempts or a large number of requests in a short period could trigger rate limiting, resulting in 429 Too Many Requests responses. The Netlify API enforces rate limits to ensure fair usage across all clients Netlify API rate limits information.
• Token Permissions: Although a newly generated Personal Access Token typically has full access, if you are using a token obtained via OAuth or an older, restricted token, it might lack the necessary scopes for the requested operation. Check the token's permissions in your Netlify settings.
• Server-Side Errors: If you receive a 5xx error, it indicates a problem on Netlify's end. These are rare but can occur. In such cases, checking the Netlify status page for any ongoing incidents is advisable.

When troubleshooting, examine the HTTP status code and the response body. Netlify API error responses often include a message field that provides specific details about what went wrong, which can be invaluable for diagnosing issues.