Netlify is a hosting service for the programmable web. It understands your documents and provides an API to handle atomic deploys of websites, manage form submissions, inject JavaScript snippets, and much more. This is a REST-style API that uses JSON for serialization and OAuth 2 for authentication.
openapi: 3.0.1
info:
title: Netlify Netlify's API documentation
description: |-
Netlify is a hosting service for the programmable web. It understands your documents and provides an API to handle atomic deploys of websites, manage form submissions, inject JavaScript snippets, and much more. This is a REST-style API that uses JSON for serialization and OAuth 2 for authentication.
This document is an OpenAPI reference for the Netlify API that you can explore. For more detailed instructions for common uses, please visit the [online documentation](https://www.netlify.com/docs/api/). Visit our Community forum to join the conversation about [understanding and using Netlify’s API](https://community.netlify.com/t/common-issue-understanding-and-using-netlifys-api/160).
Additionally, we have two API clients for your convenience:
- [Go Client](https://github.com/netlify/open-api#go-client)
- [JS Client](https://github.com/netlify/build/tree/main/packages/js-client)
termsOfService: https://www.netlify.com/legal/terms-of-use/
version: 2.33.1
x-logo:
url: netlify-logo.png
href: https://www.netlify.com/docs/
altText: Netlify
externalDocs:
description: Online documentation
url: https://www.netlify.com/docs/api/
servers:
- url: https://api.netlify.com/api/v1
security:
- netlifyAuth: []
tags:
- name: accessToken
x-displayName: Access token
- name: accountMembership
x-displayName: Accounts
- name: accountType
x-displayName: Access type
- name: Asset
x-displayName: Asset
- name: assetPublicSignature
x-displayName: Asset public signature
- name: auditLog
x-displayName: Audit log
- name: Build
x-displayName: Build
- name: buildHook
x-displayName: Build hook
- name: buildLogMsg
x-displayName: Build log message
- name: Deploy
x-displayName: Deploy
- name: deployedBranch
x-displayName: Deployed branch
- name: deployKey
x-displayName: Deploy key
- name: devServer
x-displayName: Dev server
- name: devServerHook
x-displayName: Dev server hook
- name: dnsZone
x-displayName: DNS zone
- name: environmentVariables
x-displayName: Environment variables
- name: File
x-displayName: File
- name: Form
x-displayName: Form
- name: Function
x-displayName: Function
- name: Hook
x-displayName: Hook
- name: hookType
x-displayName: Hook type
- name: Member
x-displayName: Member
- name: Metadata
x-displayName: Metadata
- name: paymentMethod
x-displayName: Payment method
- name: Purge
x-displayName: Cache purge
- name: serviceInstance
x-displayName: Service instance
- name: Site
x-displayName: Site
- name: sniCertificate
x-displayName: SNI certificate
- name: Snippet
x-displayName: Snippet
- name: splitTest
x-displayName: Split test
- name: Submission
x-displayName: Form submission
- name: Ticket
x-displayName: Ticket
- name: User
x-displayName: User
- name: X-Internal
paths:
/sites:
get:
tags:
- Site
description: "**Note:** Environment variable keys and values have moved from `build_settings.env` and `repo.env` to a new endpoint. Please use [getEnvVars](#tag/environmentVariables/operation/getEnvVars) to retrieve site environment variables."
operationId: listSites
parameters:
- name: name
in: query
schema:
type: string
- name: filter
in: query
schema:
type: string
enum:
- all
- owner
- guest
- name: page
in: query
schema:
type: integer
format: int32
- name: per_page
in: query
schema:
type: integer
format: int32
responses:
"200":
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/site'
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
post:
tags:
- Site
description: "**Note:** Environment variable keys and values have moved from `build_settings.env` and `repo.env` to a new endpoint. Please use [createEnvVars](#tag/environmentVariables/operation/createEnvVars) to create environment variables for a site."
operationId: createSite
parameters:
- name: configure_dns
in: query
schema:
type: boolean
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/siteSetup'
required: true
responses:
"201":
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/site'
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
x-codegen-request-body-name: site
/sites/{site_id}:
get:
tags:
- Site
description: "**Note:** Environment variable keys and values have moved from `build_settings.env` and `repo.env` to a new endpoint. Please use [getEnvVars](#tag/environmentVariables/operation/getEnvVars) to retrieve site environment variables."
operationId: getSite
parameters:
- name: site_id
in: path
required: true
schema:
type: string
- name: feature_flags
in: query
schema:
type: string
x-internal: true
x-internal: true
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/site'
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
delete:
tags:
- Site
operationId: deleteSite
parameters:
- name: site_id
in: path
required: true
schema:
type: string
responses:
"204":
description: Deleted
content: {}
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
patch:
tags:
- Site
description: "**Note:** Environment variable keys and values have moved from `build_settings.env` and `repo.env` to a new endpoint. Please use [updateEnvVar](#tag/environmentVariables/operation/updateEnvVar) to update a site's environment variables."
operationId: updateSite
parameters:
- name: site_id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/siteSetup'
required: true
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/site'
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
x-codegen-request-body-name: site
/sites/{site_id}/ssl:
get:
tags:
- sniCertificate
operationId: showSiteTLSCertificate
parameters:
- name: site_id
in: path
required: true
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/sniCertificate'
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
post:
tags:
- sniCertificate
operationId: provisionSiteTLSCertificate
parameters:
- name: site_id
in: path
required: true
schema:
type: string
- name: certificate
in: query
schema:
type: string
- name: key
in: query
schema:
type: string
- name: ca_certificates
in: query
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/sniCertificate'
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
/accounts/{account_id}/env:
get:
tags:
- environmentVariables
description: "Returns all environment variables for an account or site. An account corresponds to a team in the Netlify UI. To use this endpoint, your site must no longer be using the <a href=\"https://docs.netlify.com/environment-variables/classic-experience/\">classic environment variables experience</a>. Migrate now with the Netlify UI."
operationId: getEnvVars
parameters:
- name: account_id
in: path
description: Scope response to account_id
required: true
schema:
type: string
- name: context_name
in: query
description: Filter by deploy context
schema:
type: string
enum:
- all
- dev
- branch-deploy
- deploy-preview
- production
- name: scope
in: query
description: Filter by scope
schema:
type: string
enum:
- builds
- functions
- runtime
- post-processing
- name: site_id
in: query
description: "If specified, only return environment variables set on this site"
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/envVar'
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
post:
tags:
- environmentVariables
description: "Creates new environment variables. Granular scopes are available on Pro plans and above. To use this endpoint, your site must no longer be using the <a href=\"https://docs.netlify.com/environment-variables/classic-experience/\">classic environment variables experience</a>. Migrate now with the Netlify UI."
operationId: createEnvVars
parameters:
- name: account_id
in: path
description: Scope response to account_id
required: true
schema:
type: string
- name: site_id
in: query
description: "If provided, create an environment variable on the site level, not the account level"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: array
items:
type: object
properties:
key:
type: string
description: "The existing or new name of the key, if you wish to rename it (case-sensitive)"
scopes:
type: array
description: The scopes that this environment variable is set to (Pro plans and above)
items:
type: string
enum:
- builds
- functions
- runtime
- post-processing
values:
type: array
items:
$ref: '#/components/schemas/envVarValue'
is_secret:
type: boolean
description: "Secret values are only readable by code running on Netlify’s systems. With secrets, only the local development context values are readable from the UI, API, and CLI. By default, environment variable values are not secret. (Enterprise plans only)"
required: false
responses:
"201":
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/envVar'
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
x-codegen-request-body-name: env_vars
/api/v1/sites/{site_id}/env:
get:
tags:
- environmentVariables
description: Returns all environment variables for a site. This convenience method behaves the same as `getEnvVars` but doesn't require an `account_id` as input.
operationId: getSiteEnvVars
parameters:
- name: context_name
in: query
description: Filter by deploy context
schema:
type: string
enum:
- all
- dev
- branch-deploy
- deploy-preview
- production
- name: scope
in: query
description: Filter by scope
schema:
type: string
enum:
- builds
- functions
- runtime
- post_processing
- name: site_id
in: path
description: Scope response to site_id
required: true
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/envVar'
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
/accounts/{account_id}/env/{key}:
get:
tags:
- environmentVariables
description: "Returns an individual environment variable. To use this endpoint, your site must no longer be using the <a href=\"https://docs.netlify.com/environment-variables/classic-experience/\">classic environment variables experience</a>. Migrate now with the Netlify UI."
operationId: getEnvVar
parameters:
- name: account_id
in: path
description: Scope response to account_id
required: true
schema:
type: string
- name: key
in: path
description: The environment variable key (case-sensitive)
required: true
schema:
type: string
- name: site_id
in: query
description: "If provided, return the environment variable for a specific site (no merging is performed)"
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/envVar'
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
put:
tags:
- environmentVariables
description: "Updates an existing environment variable and all of its values. Existing values will be replaced by values provided. To use this endpoint, your site must no longer be using the <a href=\"https://docs.netlify.com/environment-variables/classic-experience/\">classic environment variables experience</a>. Migrate now with the Netlify UI."
operationId: updateEnvVar
parameters:
- name: account_id
in: path
description: Scope response to account_id
required: true
schema:
type: string
- name: key
in: path
description: The existing environment variable key name (case-sensitive)
required: true
schema:
type: string
- name: site_id
in: query
description: "If provided, update an environment variable set on this site"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
key:
type: string
description: "The existing or new name of the key, if you wish to rename it (case-sensitive)"
scopes:
type: array
description: The scopes that this environment variable is set to (Pro plans and above)
items:
type: string
enum:
- builds
- functions
- runtime
- post-processing
values:
type: array
items:
$ref: '#/components/schemas/envVarValue'
is_secret:
type: boolean
description: "Secret values are only readable by code running on Netlify’s systems. With secrets, only the local development context values are readable from the UI, API, and CLI. By default, environment variable values are not secret. (Enterprise plans only)"
required: false
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/envVar'
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
x-codegen-request-body-name: env_var
delete:
tags:
- environmentVariables
description: "Deletes an environment variable. To use this endpoint, your site must no longer be using the <a href=\"https://docs.netlify.com/environment-variables/classic-experience/\">classic environment variables experience</a>. Migrate now with the Netlify UI."
operationId: deleteEnvVar
parameters:
- name: account_id
in: path
description: Scope response to account_id
required: true
schema:
type: string
- name: key
in: path
description: The environment variable key (case-sensitive)
required: true
schema:
type: string
- name: site_id
in: query
description: "If provided, delete the environment variable from this site"
schema:
type: string
responses:
"204":
description: No Content (success)
content: {}
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
patch:
tags:
- environmentVariables
description: "Updates or creates a new value for an existing environment variable. To use this endpoint, your site must no longer be using the <a href=\"https://docs.netlify.com/environment-variables/classic-experience/\">classic environment variables experience</a>. Migrate now with the Netlify UI."
operationId: setEnvVarValue
parameters:
- name: account_id
in: path
description: Scope response to account_id
required: true
schema:
type: string
- name: key
in: path
description: The existing environment variable key name (case-sensitive)
required: true
schema:
type: string
- name: site_id
in: query
description: "If provided, update an environment variable set on this site"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
type: string
description: The deploy context in which this value will be used. `dev` refers to local development when running `netlify dev`. `branch` must be provided with a value in `context_parameter`.
enum:
- all
- dev
- branch-deploy
- deploy-preview
- production
- branch
context_parameter:
type: string
description: "An additional parameter for custom branches. Currently, this is used for providing a branch name when `context=branch`."
value:
type: string
description: The environment variable's unencrypted value
required: false
responses:
"201":
description: Created (success)
content:
application/json:
schema:
$ref: '#/components/schemas/envVar'
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
x-codegen-request-body-name: env_var
/accounts/{account_id}/env/{key}/value/{id}:
delete:
tags:
- environmentVariables
description: "Deletes a specific environment variable value. To use this endpoint, your site must no longer be using the <a href=\"https://docs.netlify.com/environment-variables/classic-experience/\">classic environment variables experience</a>. Migrate now with the Netlify UI."
operationId: deleteEnvVarValue
parameters:
- name: account_id
in: path
description: Scope response to account_id
required: true
schema:
type: string
- name: id
in: path
description: The environment variable value's ID
required: true
schema:
type: string
- name: key
in: path
description: The environment variable key name (case-sensitive)
required: true
schema:
type: string
- name: site_id
in: query
description: "If provided, delete the value from an environment variable on this site"
schema:
type: string
responses:
"204":
description: No Content (success)
content: {}
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
/sites/{site_id}/functions:
get:
tags:
- Function
operationId: searchSiteFunctions
parameters:
- name: site_id
in: path
required: true
schema:
type: string
- name: filter
in: query
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/siteFunction'
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
/sites/{site_id}/forms:
get:
tags:
- Form
operationId: listSiteForms
parameters:
- name: site_id
in: path
required: true
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/form'
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
/sites/{site_id}/forms/{form_id}:
delete:
tags:
- Form
operationId: deleteSiteForm
parameters:
- name: site_id
in: path
required: true
schema:
type: string
- name: form_id
in: path
required: true
schema:
type: string
responses:
"204":
description: Deleted
content: {}
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
/sites/{site_id}/submissions:
get:
tags:
- Submission
operationId: listSiteSubmissions
parameters:
- name: site_id
in: path
required: true
schema:
type: string
- name: page
in: query
schema:
type: integer
format: int32
- name: per_page
in: query
schema:
type: integer
format: int32
responses:
"200":
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/submission'
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
/sites/{site_id}/files:
get:
tags:
- File
operationId: listSiteFiles
parameters:
- name: site_id
in: path
required: true
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/file'
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
/sites/{site_id}/assets:
get:
tags:
- Asset
operationId: listSiteAssets
parameters:
- name: site_id
in: path
required: true
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/asset'
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
post:
tags:
- Asset
operationId: createSiteAsset
parameters:
- name: site_id
in: path
required: true
schema:
type: string
- name: name
in: query
required: true
schema:
type: string
- name: size
in: query
required: true
schema:
type: integer
format: int64
- name: content_type
in: query
required: true
schema:
type: string
- name: visibility
in: query
schema:
type: string
responses:
"201":
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/assetSignature'
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
/sites/{site_id}/assets/{asset_id}:
get:
tags:
- Asset
operationId: getSiteAssetInfo
parameters:
- name: site_id
in: path
required: true
schema:
type: string
- name: asset_id
in: path
required: true
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/asset'
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
put:
tags:
- Asset
operationId: updateSiteAsset
parameters:
- name: site_id
in: path
required: true
schema:
type: string
- name: asset_id
in: path
required: true
schema:
type: string
- name: state
in: query
required: true
schema:
type: string
responses:
"200":
description: Updated
content:
application/json:
schema:
$ref: '#/components/schemas/asset'
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
delete:
tags:
- Asset
operationId: deleteSiteAsset
parameters:
- name: site_id
in: path
required: true
schema:
type: string
- name: asset_id
in: path
required: true
schema:
type: string
responses:
"204":
description: Deleted
content: {}
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
/sites/{site_id}/assets/{asset_id}/public_signature:
get:
tags:
- assetPublicSignature
operationId: getSiteAssetPublicSignature
parameters:
- name: site_id
in: path
required: true
schema:
type: string
- name: asset_id
in: path
required: true
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/assetPublicSignature'
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
/sites/{site_id}/files/{file_path}:
get:
tags:
- File
operationId: getSiteFileByPathName
parameters:
- name: site_id
in: path
required: true
schema:
type: string
- name: file_path
in: path
required: true
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/file'
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
/purge:
post:
tags:
- Purge
description: Purges cached content from Netlify's CDN. Supports purging by Cache-Tag.
operationId: purgeCache
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/purge'
required: true
responses:
"202":
description: OK
content: {}
"400":
description: Invalid request parameters
content: {}
"404":
description: Site not found
content: {}
x-codegen-request-body-name:
# --- truncated at 32 KB (135 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/netlify/refs/heads/main/openapi/netlify-openapi-original.yml