Or, if using TypeScript with CommonJS output, add a loader or use a bundler (esbuild, Rollup) that handles ES module interop.

Public API

NetlifyAPI

class NetlifyAPI {
  constructor(accessToken?: string, opts?: {
    userAgent?: string
    scheme?: string
    host?: string
    pathPrefix?: string
    accessToken?: string
    globalParams?: Record<string, unknown>
    agent?: unknown // e.g. HttpsProxyAgent
  })
  constructor(opts: { accessToken?: string; [key: string]: unknown })

  get accessToken(): string | null
  set accessToken(token: string | null)

  get basePath(): string

  async getAccessToken(
    ticket: { id: string },
    opts?: { poll?: number; timeout?: number }
  ): Promise<string>

  // Dynamically generated per OpenAPI operationId, e.g.:
  [operationId: string]: (
    params?: Record<string, unknown>,
    opts?: RequestInit
  ) => Promise<unknown>
}

The main entry point. Instantiate once per access token and reuse across all API calls. The constructor is variadic: pass a token string alone, an options object alone, or both.

getOperations

function getOperations(): Array<{
  operationId: string
  verb: string
  path: string
  parameters: {
    path: Record<string, unknown>
    query: Record<string, unknown>
    body: Record<string, unknown>
  }
  [key: string]: unknown
}>

Returns the full list of parsed OpenAPI operations. Useful for introspection, testing, or building tooling on top of the spec without instantiating a client.

getMethods

function getMethods(opts: {
  basePath: string
  defaultHeaders: Record<string, string>
  agent?: unknown
  globalParams?: Record<string, unknown>
}): Record<string, (params?: unknown, opts?: unknown) => Promise<unknown>>

Generates and returns the map of operationId → async function from the parsed operations. Called internally by NetlifyAPI but can be used standalone if you need a bare method map without the class wrapper.

Working examples

Scenario - List and filter sites

Authenticate with a token, retrieve all sites belonging to the account, and log their names and URLs.

import { NetlifyAPI } from './src/netlify-client/index.js'

const client = new NetlifyAPI(process.env.NETLIFY_ACCESS_TOKEN)

const sites = await client.listSites({ filter: 'all' })

for (const site of sites) {
  console.log(site.name, site.ssl_url)
}

Scenario - Create a site and trigger a deploy

Create a new site with a custom subdomain, then deploy a local build directory using a readable stream.

import { NetlifyAPI } from './src/netlify-client/index.js'
import fs from 'fs'

const client = new NetlifyAPI(process.env.NETLIFY_ACCESS_TOKEN)

// Create the site
const site = await client.createSite({
  body: {
    name: 'my-automated-site',
    custom_domain: null,
  },
})

console.log('Created site:', site.id)

// Upload a deploy (binary body via stream)
const deploy = await client.createSiteDeploy(
  {
    site_id: site.id,
    body: () => fs.createReadStream('./dist/build.zip'),
  },
)

console.log('Deploy id:', deploy.id, 'state:', deploy.state)

Scenario - Swap the access token at runtime and delete a site

Demonstrates the accessToken setter for multi-tenant scenarios, then deletes a site by ID.

import { NetlifyAPI } from './src/netlify-client/index.js'

// Start with no token
const client = new NetlifyAPI({ globalParams: {} })

// Swap in the token later (e.g. after OAuth flow)
client.accessToken = process.env.NETLIFY_ACCESS_TOKEN

const siteId = 'abcd-1234-efgh-5678'

await client.deleteSite({ site_id: siteId })

console.log('Site deleted. basePath was:', client.basePath)

// Clear the token
client.accessToken = null
console.log('Token cleared:', client.accessToken) // null

File walkthrough

• index.js — Defines and exports NetlifyAPI. Handles constructor overloading, default headers, basePath construction, the accessToken getter/setter, and the getAccessToken OAuth polling helper.
• open_api.js — Uses createRequire to load the @netlify/open-api JSON spec in an ESM context and re-exports it as openApiSpec.
• operations.js — Exports getOperations, which flattens openApiSpec.paths into an array of operation objects, merging path-level and operation-level parameters into typed buckets (path, query, body).
• operations.test.js.md — Not a runtime module; documents expected operation shapes for testing reference.
• methods/index.js — Exports getMethods. Calls getOperations, maps each to an async function, and merges them into a plain object. Also owns the fetch-and-retry loop.
• methods/body.js — Handles serialisation of params.body to a JSON string or passes through streams for binary uploads.
• methods/params.js — Exports getRequestParams to extract and validate parameters against an OpenAPI parameter definition map.
• methods/response.js — Exports parseResponse (deserialises JSON/text body) and getFetchError (builds a descriptive error from a failed response).
• methods/retry.js — Exports shouldRetry, waitForRetry, and MAX_RETRY; implements retry logic for transient network and 5xx errors.
• methods/url.js — Exports getUrl; interpolates path parameters into the URL template and appends query string via qs.

Common pitfalls and fixes

• ESM in a CJS project: The source uses import/export. In a CommonJS project use a bundler (esbuild, Rollup) or set "type": "module" and use .mjs extensions as needed.
• @netlify/open-api not found: open_api.js calls require('@netlify/open-api') — ensure this package is installed; it is a mandatory runtime dependency even though it looks like a dev tool.
• node-fetch v3 vs v2 ESM interop: node-fetch v3 is ESM-only. If your bundler targets CJS, pin node-fetch to ^2.6.x and update the import, or configure your bundler for ESM output.
• params.body as a function: For retried requests the body factory pattern (body: () => fs.createReadStream(...)) is required; a consumed stream cannot be re-read on retry.
• Token not set before first call: The accessToken setter writes to defaultHeaders; calls made before setting the token will be unauthenticated and return 401. Set the token in the constructor or immediately after instantiation.
• globalParams leaking between tenants: globalParams is merged into every request. In multi-tenant use cases, create a separate NetlifyAPI instance per user rather than mutating globalParams on a shared instance.

Vibe-coding prompt template

I have a Netlify API client block located at `source/` in my project.
The integration guide is in `USAGE.md` (also in this context).
The upstream package is `user@example.com`.

Please help me integrate this client into my project step by step:

1. Read `USAGE.md` and `source/index.js` to understand the exported API.
2. Install all required npm dependencies listed in USAGE.md.
3. Create a singleton client module that reads NETLIFY_ACCESS_TOKEN from
   environment variables and exports a ready-to-use `NetlifyAPI` instance.
4. Add a helper function that lists all sites and returns their IDs and names.
5. Add a helper that creates a site given a name string and returns the site object.
6. Ensure all code is TypeScript-compatible and uses async/await.
7. Show me where to place each file relative to my project root.
8. Point out any ESM/CJS issues given my current `package.json` settings.

License and credit

The upstream source is published as netlify (version 12.0.1) by the Netlify team. The license is MIT; see source/LICENSE if present, or refer to the upstream repository for the authoritative license text.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

TypeScript OIDC Client for Browser Applications

Automation, Utilities & Developer Tools

Free