Skip to main content
This article provides reference information for configuring serverless functions on version 2026.03 of the developer platform.
Using serverless functions with 2026.03 apps requires that you’re on the latest version of the HubSpot CLI. You’ll need to be using v8.3.0 or above.You can check the version you’re using by running hs --version.

​
Project structure

To add serverless function support to an existing project, run the following command: 
hs project add --features app-function
This command will create the following directory and files in your project: 
project-folder/
└── src/
    └── app/
        ├── app-hsmeta.json
        ...
        └── functions/
            └── private-function-hsmeta.json
            └── NewFunction.js
            └── package.json

​
Function configuration

The src/app/functions/private-function-hsmeta.json file provides the main configuration for your serverless functions, while the code for your serverless function is defined in the NewFunction.js file. These boilerplate files are meant as a starting point for your app, which can be adapted to fit your app’s needs. 
{
  "uid": "app_function_private",
  "type": "app-function",
  "config": {
    "entrypoint": "/app/functions/NewFunction.js",
    "secretKeys": []
  }
}
The table below provides details on each of the available properties you can configure in your function-hsmeta.json file:
FieldTypeDescription
uid StringA unique identifier for the app function component. This can be any string, but should meaningfully identify the app function. HubSpot will identify the function by this ID.
type StringThe type of component, which should be app-function in this case.
config ObjectAn object containing configuration details, which includes the entrypoint, endpoint, and secretKeys properties, detailed below.
entrypoint StringA sub-property of the config object, which is the path to your serverless function JavaScript file.
endpointObjectAn object that defines a publicly accessible endpoint (without authentication), which requires Content Hub Enterprise. This object includes the following properties:
  • path: The URL path for the public endpoint.
  • method: the HTTP method for the endpoint (e.g., "POST", "GET").
secretKeysArrayArray of secret names to inject as environment variables.

​
Manage multiple serverless functions

2026.03 apps support multiple serverless functions, added via sets of .js and *-hsmeta.json files. For example, to define another serverless function, you could create two new files, ‘SecondFunction.js’ and second-function-hsmeta.json in the src/app/functions/ directory: 
project-folder/
└── src/
    └── app/
        ├── app-hsmeta.json
        ...
        └── functions/
            └── private-function-hsmeta.json
            └── NewFunction.js
            └── second-private-function-hsmeta.json
            └── SecondFunction.js
            └── package.json
Then, you’d edit the newly added files to ensure the second-private-function-hsmeta.json file references the path to SecondFunction.js, and it has a uid that’s distinct from the uid of any other function. 
{
  "uid": "second_app_function_private",
  "type": "app-function",
  "config": {
    "entrypoint": "/app/functions/SecondFunction.js",
    "secretKeys": []
  }
}

​
Managing and referencing secrets

Secrets provide secure storage for any API keys, tokens, or other sensitive data your serverless function might need to use when making an external request. By default, a reserved secret named PRIVATE_APP_ACCESS_TOKEN is accessible by default in every private serverless function to make HubSpot API requests on behalf of your app, but you can add new secrets if your serverless function needs to make other external requests. To add a secret, use the hs secret add command. The example below would add a secret with a name of THIRD_PARTY_ACCESS_TOKEN: 
hs secret add THIRD_PARTY_ACCESS_TOKEN
You’d then be prompted to enter or paste in the value of the secret (which will not appear in the terminal). You should then add the secret name to the secretKeys array in the corresponding private-function-hsmeta.json file: 
{
  "uid": "app_function_private",
  "type": "app-function",
  "config": {
    "entrypoint": "/app/functions/NewFunction.js",
    "secretKeys": ["THIRD_PARTY_ACCESS_TOKEN"]
  }
}
The secret is then injected as an environment variable in your serverless function: 
    exports.main = async (context) => {
    // ...

    // Get third-party access token
    const accessToken = process.env.THIRD_PARTY_ACCESS_TOKEN;

    // ...
    };
After adding a secret, you may need to run hs project upload to ensure your secret can be correctly referenced in a deployed UI extension.
Learn more about managing secrets using the HubSpot CLI.

​
Calling serverless functions

The way you invoke your serverless function depends on whether you configured a private function to run in a UI extension or whether you configured a publicly accessible endpoint.

​
Private functions in UI extensions

To execute your serverless function from one of your UI extensions (e.g., an app card, app home, or app settings page), use the hubspot.serverless() API, as demonstrated in the code block below: 
import { hubspot } from '@hubspot/ui-extensions';

// In your React component (App Card, App Home, App Settings, etc.)
const handleSubmit = async () => {
  try {
    const result = await hubspot.serverless('app_function_private', {
      parameters: {
        customParam: 'value'
      },
      propertiesToSend: ['firstname', 'lastname', 'email']
    });

    console.log('Function result:', result);
  } catch (error) {
    console.error('Function error:', error);
  }
};
Learn more about how to use serverless functions in an app card.

​
Endpoint functions via public HTTP request

Please note: public endpoints require Content Hub Enterprise, and are accessible without authentication. Only add endpoint configuration if you intentionally need to create a public API. Consider implementing your own authentication logic (API keys, tokens, etc.) within the function if you need to restrict access.
If you configured a public endpoint, you can make HTTP requests to the endpoint that you specified by the config.endpoint.path property in your function-hsmeta.json file. The cURL example below demonstrates how to make a request to a function with a path of https://your-domain.com/hs/serverless/api/app_function_endpoint: 
curl -X POST https://your-domain.com/hs/serverless/api/app_function_endpoint \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

​
Function context

Serverless functions are passed a context object, which contains metadata based on whether you configure your function to be private or public.

​
Private function

When your function is called from a UI extension (e.g., an app card, app home, or app settings page), the context object can be deconstructed to reference the properties shown below: 
  exports.main = async (context) => {
    const {
      accountId, userId, userEmail, // User and account information
      parameters, // Parameters passed from your frontend code
      propertiesToSend // CRM properties
    } = context;

    // ...
  };
The propertiesToSend field is only available when your function is invoked from a CRM record context (like an App Card on a contact record). It will not be present when called from App Homes or App Settings.
Learn more about using context in the UI extensions SDK reference.

​
Public function

If your serverless function is a publicly accessible endpoint, the context object contains the following fields:
FieldTypeDescription
accountIdNumberThe HubSpot account ID (if authenticated)
methodStringThe HTTP request method.
bodyObjectRequest body, if provided.
queryObjectRequest query parameters, if provided.
headersObjectRequest headers.

​
Add NPM packages

Serverless functions support custom NPM dependencies. You can add them by running npm install <package-name> in the src/app/functions/ directory. For example, if you wanted to add axios as a dependency, you’d run npm install axios in the src/app/functions/ directory, which would install axios and update the package.json file in the functions/ directory automatically: 
{
  "name": "example-function",
  "version": "0.1.0",
  "dependencies": {
    "axios": "^1.13.6"
  }
}

​
Limitations

Keep the following limits in mind as you develop and test your function:
  • Functions have a 15 second execution timeout
  • Functions may experience “cold starts” after periods of inactivity.
  • Only privately distributed apps with static auth are currently supported. Apps using OAuth for authentication cannot use 2026.03 serverless functions.
To help mitigate both limitations above, keep your functions lightweight, minimize the number of external API calls, and assign variables within functions instead of at the module level.

​
Troubleshooting

The table below outlines common errors you might encounter while you develop and test your serverless function:
ErrorDetails
Function "[name]" not foundOccurs when the uid in your functions/*-hsmeta.json file doesn’t match the function name. Double-check that the uid matches, then check for any errors when running hs project upload.
Function execution timed outThe function didn’t complete within 15 seconds. Try reducing any unnecessary external API calls, breaking larger functions into separate functions, or cache results from your requests.
Build failed: invalid configurationResults from project configuration issues. Run the hs project validate command to identify any schema errors, then address any missing fields in your project’s *-hsmeta.json files. You should also confirm that all uid values are unique across all functions.
Check out the following resources as you develop your app:
Last modified on March 30, 2026