Netlify Sites & Deploys
Lets an agent monitor Netlify sites: list sites, check deploy and build status per site and branch, trigger a new build, and read form submissions collected by Netlify Forms. Curated from Netlify's official OpenAPI specification.
Connect this API to an AI agent Browse all specs
What you can do with Netlify Sites & Deploys via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /user |
getCurrentUser | Get the Netlify user that owns the token |
| GET | /sites |
listSites | List sites, optionally filtered by name |
| GET | /sites/{site_id} |
getSite | Get a site's URL, repo settings and published deploy |
| GET | /sites/{site_id}/deploys |
listSiteDeploys | List a site's deploys, newest first |
| GET | /sites/{site_id}/deploys/{deploy_id} |
getSiteDeploy | Get a site deploy's state, branch and error message |
| GET | /deploys/{deploy_id} |
getDeploy | Get any deploy by id |
| GET | /sites/{site_id}/deployed-branches |
listSiteDeployedBranches | List branches that have branch deploys |
| GET | /sites/{site_id}/builds |
listSiteBuilds | List a site's builds and whether they are done |
| POST | /sites/{site_id}/builds |
triggerSiteBuild | Start a new build and deploy of a site |
| GET | /sites/{site_id}/forms |
listSiteForms | List the forms Netlify detected on a site |
| GET | /sites/{site_id}/submissions |
listSiteSubmissions | List form submissions across a site |
| GET | /forms/{form_id}/submissions |
listFormSubmissions | List submissions for one form |
| GET | /submissions/{submission_id} |
getFormSubmission | Get one form submission |
Authentication
netlifyToken
API key — sent as the Authorization header
Netlify personal access token, sent as Authorization: Bearer <token>.
How to get a credential
- Sign in to app.netlify.com and open User settings > Applications > Personal access tokens.
- Click New access token, add a description (e.g.
VX Agents) and choose an expiration. - Copy the token (it is shown only once).
- Enter the credential value as
Bearer <your-token>(with the wordBearerand a space).
Permissions used
Personal access tokens are not scoped per endpoint: they act as you, on every team you belong to.
| Access | Operations |
|---|---|
| User (read) | getCurrentUser |
| Sites (read) | listSites, getSite, listSiteDeployedBranches |
| Deploys (read) | listSiteDeploys, getSiteDeploy, getDeploy, listSiteBuilds |
| Builds (write) | triggerSiteBuild |
| Forms (read) | listSiteForms, listSiteSubmissions, listFormSubmissions, getFormSubmission |
Common errors
- 401 Unauthorized: token missing, expired, or entered without the
Bearerprefix. Re-enter it asBearer <token>. - 403 Forbidden: you are not a member of the team that owns the site.
- 404 Not Found: wrong
site_id/deploy_id, or the site belongs to a team the token cannot see. - 400 Bad Request: invalid parameter value (e.g.
per_pageabove 100). - 429 Too Many Requests: about 500 requests/minute; wait for the
X-RateLimit-Resettime and retry.
Store the token as a VX Agents credential so it is never pasted into chat.
Usage guide
Setup
- Add a Netlify personal access token (User settings > Applications) as the credential, entered as
Bearer <token>. - If the agent works on one site, preset
site_id(Site configuration > General > Site ID, or theidfromlistSites). The site's name (e.g.my-site.netlify.app) also works assite_id.
Check deploy status
getCurrentUserto confirm the token works.listSiteswithnameto find the site and itsid,urlandpublished_deploy.listSiteDeployswithsite_id(filter withbranch,production=trueorstate=error;per_pageup to 100).getSiteDeploy(orgetDeploywith only a deploy id) forstate,branch,commit_ref,deploy_ssl_urlanderror_message.listSiteDeployedBranchesto see which branches have their own branch-deploy URL.
Rebuild a site
- Tell the user which site and branch will be rebuilt (a production rebuild replaces the live site once it succeeds) and wait for confirmation.
triggerSiteBuildwithsite_id, plusbranchfor a branch deploy andclear_cache=trueonly if the user asks for a clean build.- Poll
listSiteBuildsorlistSiteDeploysevery 30-60 seconds untildoneis true or the deploystateisreadyorerror.
Read form submissions
listSiteFormswithsite_idto get the form ids and names.listFormSubmissionswithform_id(orlistSiteSubmissionsfor every form) to list entries. Submissions contain customer personal data, so share only what the user needs.getFormSubmissionfor one entry's fulldata.
Good to know
- Deploy
stategoesnew→building→uploading→processing→ready(orerror). - Times are ISO 8601 UTC (e.g.
2026-10-14T08:30:00.000Z). - Lists use
pageandper_page(max 100). Stop when a page returns fewer items thanper_page. - This spec cannot delete sites, deploys or submissions and cannot change site settings.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Netlify Sites & Deploys” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.