A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Netlify API is how an app or AI agent works with a Netlify account: listing and creating sites, starting builds, publishing and restoring deploys, reading form submissions, and managing DNS records and environment variables. Access is granted through a personal access token or an OAuth token sent in an Authorization header, and that token carries the full access of the user who issued it rather than a narrowed set of permissions. Netlify can also push site events, like a deploy being created or a form being submitted, to a notification hook instead of being polled.
How an app or AI agent connects to Netlify determines what it can reach. There are a few routes, each governed by the token behind it, and a Netlify token carries the full access of the account that issued it.
The REST API answers at https://api.netlify.com/api/v1/ over HTTPS only. A token is sent in an Authorization Bearer header, and Netlify asks that requests also carry a User-Agent that identifies the caller.
Netlify's official MCP server lets an agent manage sites, deploys, extensions, and configuration through the Model Context Protocol. The remote server runs at https://netlify-mcp.netlify.app/mcp, and a local server runs through the npx @netlify/mcp package. Netlify recommends the remote server.
A notification hook posts the relevant object to a chosen URL when a site event fires, such as a deploy being created or failing, or a form submission arriving. Hooks are managed through the hooks endpoint.
A personal access token is generated in Netlify user settings, with a chosen expiry, and sent as a Bearer token. It carries the full access of the user who created it, and resetting that user's password invalidates every token issued before the reset.
OAuth 2.0 lets a public integration connect a Netlify user without handling their password. The user authorizes at https://app.netlify.com/authorize, and the resulting token, like a personal access token, carries the user's full account access rather than a narrowed set of permissions.
The Netlify API is split into areas an agent can act on, such as sites, deploys, builds, forms, DNS, environment variables, and notification hooks. Each area has its own methods, and a single token reaches all of them.
List sites, read a single site, create a site, update its settings, and delete it.
List a site's deploys, read one, start a new deploy, restore a previous one, and lock or unlock the published deploy.
List a site's builds and start a new build of the connected repository.
List a site's forms, read submitted form data, delete a form, and delete a single submission.
List DNS zones, create a zone, read a zone's records, create a record, and delete a record.
Read an account's environment variables, create them, update one by key, and delete one.
Create a build hook that triggers deploys by URL, and list, create, or delete notification hooks that fire on site events.
List a site's injected code snippets and add a new one.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
SitesList sites, read a single site, create a site, update its settings, and delete it.5 | ||||||
| GET | /sites | List all sites the token can reach. | read | — | Current | |
Netlify tokens carry the full access of the issuing user, so there is no per-endpoint scope to grant. The token returns every site the account can see. Acts onsite Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /sites/{site_id} | Get a single site's details. | read | — | Current | |
No per-endpoint scope; the token reaches any site on the account. Acts onsite Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /sites | Create a new site. | write | — | Current | |
No per-endpoint scope; any valid token can create sites on the account. Acts onsite Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /sites/{site_id} | Update a site's settings. | write | — | Current | |
No per-endpoint scope; the token can change settings on any site it reaches. Acts onsite Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /sites/{site_id} | Delete a site. | write | — | Current | |
No per-endpoint scope. Deletion is permanent and removes the site and its deploys. Acts onsite Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DeploysList a site's deploys, read one, start a new deploy, restore a previous one, and lock or unlock the published deploy.6 | ||||||
| GET | /sites/{site_id}/deploys | List a site's deploys. | read | — | Current | |
No per-endpoint scope; the token reaches the deploys of any site on the account. Acts ondeploy Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /deploys/{deploy_id} | Get a single deploy's details. | read | — | Current | |
No per-endpoint scope. Acts ondeploy Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /sites/{site_id}/deploys | Start a new deploy for a site. | write | — | Current | |
No per-endpoint scope. Creating deploys is held to a stricter ceiling than general calls. Acts ondeploy Permission (capability)None required VersionAvailable since the API’s base version Webhook event deploy_createdRate limit3 deploys per minute, 100 per day SourceOfficial documentation ↗ | ||||||
| POST | /sites/{site_id}/deploys/{deploy_id}/restore | Restore an earlier deploy as the published one. | write | — | Current | |
No per-endpoint scope. Restoring changes which deploy serves the live site. Acts ondeploy Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /deploys/{deploy_id}/lock | Lock the published deploy so it is not replaced automatically. | write | — | Current | |
No per-endpoint scope. Locking stops auto publishing until the deploy is unlocked. Acts ondeploy Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /deploys/{deploy_id}/unlock | Unlock the published deploy so auto publishing resumes. | write | — | Current | |
No per-endpoint scope. Acts ondeploy Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
BuildsList a site's builds and start a new build of the connected repository.2 | ||||||
| GET | /sites/{site_id}/builds | List a site's builds. | read | — | Current | |
No per-endpoint scope. Acts onbuild Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /sites/{site_id}/builds | Start a new build of a site. | write | — | Current | |
No per-endpoint scope. A build runs the site's build command and can publish a new deploy. Acts onbuild Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Forms & submissionsList a site's forms, read submitted form data, delete a form, and delete a single submission.4 | ||||||
| GET | /sites/{site_id}/forms | List the forms on a site. | read | — | Current | |
No per-endpoint scope. Acts onform Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /sites/{site_id}/submissions | List the form submissions for a site. | read | — | Current | |
Submissions return the data visitors entered, which can include names, email addresses, and message content. Acts onsubmission Permission (capability)None required VersionAvailable since the API’s base version Webhook event submission_createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /sites/{site_id}/forms/{form_id} | Delete a form from a site. | write | — | Current | |
No per-endpoint scope. After deletion, future submissions to the form return a 404. Acts onform Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /submissions/{submission_id} | Delete a single form submission. | write | — | Current | |
No per-endpoint scope. Deletion permanently removes the submitted data. Acts onsubmission Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DNSList DNS zones, create a zone, read a zone's records, create a record, and delete a record.5 | ||||||
| GET | /dns_zones | List the DNS zones the token can reach. | read | — | Current | |
No per-endpoint scope. Acts ondns zone Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /dns_zones | Create a DNS zone. | write | — | Current | |
No per-endpoint scope. A zone controls how a domain resolves. Acts ondns zone Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /dns_zones/{zone_id}/records | List the records in a DNS zone. | read | — | Current | |
No per-endpoint scope. Acts ondns record Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /dns_zones/{zone_id}/records | Create a DNS record in a zone. | write | — | Current | |
No per-endpoint scope. Records decide where a domain or subdomain points. Acts ondns record Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /dns_zones/{zone_id}/records/{record_id} | Delete a DNS record from a zone. | write | — | Current | |
No per-endpoint scope. Removing a record can stop a domain from resolving. Acts ondns record Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Environment variablesRead an account's environment variables, create them, update one by key, and delete one.4 | ||||||
| GET | /accounts/{account_id}/env | List an account's environment variables. | read | — | Current | |
Environment variables often hold secrets that builds and functions read. The list is scoped to the account, not a single site. Acts onenvironment variable Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /accounts/{account_id}/env | Create one or more environment variables for an account. | write | — | Current | |
No per-endpoint scope. Values set here are available to the account's builds and functions. Acts onenvironment variable Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /accounts/{account_id}/env/{key} | Update an environment variable by key. | write | — | Current | |
No per-endpoint scope. Acts onenvironment variable Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /accounts/{account_id}/env/{key} | Delete an environment variable by key. | write | — | Current | |
No per-endpoint scope. Removing a variable a build relies on can break later builds. Acts onenvironment variable Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Hooks & notificationsCreate a build hook that triggers deploys by URL, and list, create, or delete notification hooks that fire on site events.4 | ||||||
| POST | /sites/{site_id}/build_hooks | Create a build hook, a unique URL that triggers a deploy when called. | write | — | Current | |
A build hook URL needs no token of its own; anyone who holds the URL can trigger a deploy of the site. Acts onbuild hook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /hooks?site_id={site_id} | List the notification hooks for a site. | read | — | Current | |
No per-endpoint scope. The site is passed as a query parameter. Acts onhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /hooks | Create a notification hook that fires on a site event, sending to a URL or email. | write | — | Current | |
The hook body sets the event and a type such as url or email, and the site_id it belongs to. Acts onhook Permission (capability)None required VersionAvailable since the API’s base version Webhook event deploy_createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /hooks/{hook_id} | Delete a notification hook. | write | — | Current | |
No per-endpoint scope. For outgoing webhook hooks, returning a 410 Gone from the receiving URL also deletes the hook. Acts onhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SnippetsList a site's injected code snippets and add a new one.2 | ||||||
| GET | /sites/{site_id}/snippets | List the code snippets injected into a site. | read | — | Current | |
No per-endpoint scope. Acts onsnippet Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /sites/{site_id}/snippets | Add a code snippet to a site. | write | — | Current | |
No per-endpoint scope. A snippet injects code into every page the site serves to visitors. Acts onsnippet Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Netlify can notify an app or AI agent when something happens on a site, instead of the app repeatedly asking. A notification hook is registered for an event, and Netlify posts the relevant object to the chosen URL when that event fires.
| Event | What it signals | Triggered by |
|---|---|---|
deploy_created | Fires when a new deploy finishes and is published to the Netlify CDN. | /sites/{site_id}/deploys/hooks |
deploy_failed | Fires when a deploy does not complete because the build failed. | In-app only |
submission_created | Fires when a visitor submits a form on the site, carrying the submitted data. | /sites/{site_id}/submissions |
Netlify limits how fast an app or AI agent can call, through a per-minute request quota with stricter ceilings on deploys. Going over returns a rate-limit response with headers that say when the window resets.
Netlify allows up to 500 requests per minute for most requests, and certain operations have stricter ceilings. Creating deploys is capped at 3 per minute and 100 per day. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers that report the current window and when it resets, and Netlify asks teams that need higher limits to get in touch. A separate timeout terminates any single request that runs longer than 30 seconds, so large deploys use an async option instead.
List endpoints page through results with the page and per_page query parameters. The default page size is 100 items, and per_page tops out at 100.
Requests and responses are JSON over HTTPS. There is no single documented payload size limit across the whole API, and large deploys are uploaded as a new immutable set of files rather than edited file by file, with an async option for deploys that would otherwise exceed the 30 second request timeout.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | Unauthorized | The token is missing, invalid, or expired. A password reset on the issuing user invalidates every token created before it. | Send a valid Bearer token in the Authorization header, and reissue tokens that were invalidated by a password reset. |
| 404 | Not Found | The resource does not exist or the token cannot reach it. A form that has been deleted also returns 404 on future submissions. | Confirm the identifier and that the token's account has access to the resource. |
| 422 | Unprocessable Entity | The request was understood but a field is missing or invalid. | Correct the named field in the request body and resend. |
| 429 | Too Many Requests | A rate limit was exceeded, either the general per-minute quota or the stricter deploy ceilings. | Wait for the window in the X-RateLimit-Reset header before retrying, and contact Netlify if higher limits are needed. |
Netlify serves a single, stable version of its API, marked v1 in the request path. Backward-incompatible changes would ship under a new version marker while the old paths stay supported.
Netlify serves a single stable version of its REST API, marked v1 in the request path at https://api.netlify.com/api/v1/. Netlify states that a backward-incompatible change would ship under a new version marker while the old paths keep stable support, so the API is not versioned by date and an integration does not pin a version.
Netlify released its official MCP server during Agent Week, giving AI agents direct access to the Netlify API and CLI through the Model Context Protocol. Agents can create projects, deploy, manage extensions and configuration, and read deploy logs in natural language. It was announced on 3 June 2025.
From 2 April 2025, the default deploy retention period changed from 90 days to 30 days for Free and Starter accounts, which affects how far back the deploys an agent can list and restore reach on those plans.
An integration calls the v1 paths and does not need to pin or negotiate a version.
Netlify changelog ↗Bollard AI sits between a team's AI agents and Netlify. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.