Skip to content
Netlify SDK Docs Netlify SDK Docs 1.38.2

Get started with API Handlers

This page will help you get started with creating an integration that uses API Handlers. It describes how to generate the boilerplate code for an integration with an API handler, what the required files and basic scaffolding are, and how to build your code.

Prerequisites

Windows users should run the Netlify SDK through WSL 2

Support for using the Netlify SDK on Windows is currently only available through WSL 2.

Create your API handler

  1. To get started, run the following command to create a new integration:

    npm create @netlify/sdk@latest

  2. Then, follow the prompts to add the Build Event Handler or Integration UI boilerplate.

    The Netlify SDK will scaffold the basic structure needed for your integration which includes these required files:

    • src/index.ts
    • package.json

    The src/index.ts file is the entrypoint for your integration and is listed in the main property of your package.json.

  3. Inside the src/index.ts file, declare an instance of NetlifyIntegration and call the method addApiHandler to create your first API handler.

    src/index.ts
    import { NetlifyIntegration } from "@netlify/sdk";
    

    const integration = new NetlifyIntegration();
    

    integration.addApiHandler("cool-function", async (event, context) => {
      const { client } = context;
      // Do something cool here
    

      return {
        statusCode: 200,
      };
    });

Develop your API handler

Now that you’ve added an API Handlers component to your integration, you can tailor it to fit your needs.

If your API handler makes calls to a third-party API that requires authentication, you can configure your integration to allow users to authenticate through an OAuth identity provider. Once a user authenticates, you can access the OAuth token and use it to make requests on the user’s behalf.

Synchronous serverless functions only

API handlers do not support Scheduled Functions or Background Functions.

Build your API handler

Once you’re done developing your API handler, you can compile your code by using the following Netlify SDK utility tools command:

pnpm run build

The code is compiled to the folder .ntli. These functions are deployed and hosted by Netlify when you publish your integration, you don’t need to deploy these functions separately once they’re built.

Next steps