Serverless functions reference (projects)

​

Project structure

hs project create --name <name> --dest <folder> --project-base app --distribution private --auth static --platform-version 2026.09 --features app-function-endpoint

project-folder/
├── hsproject.json
└── src/
    └── app/
        ├── app-hsmeta.json
        └── functions/
            ├── fetch-quote-hsmeta.json
            ├── fetch-quote.js
            ├── events-update-hsmeta.json
            ├── update.js
            └── package.json

​

Function configuration

{
  "uid": "fetch_quote_function",
  "type": "app-function",
  "config": {
    "entrypoint": "/app/functions/fetch-quote.js",
    "secretKeys": [],
    "endpoint": {
      "path": "fetch-quote",
      "methods": ["GET"]
    }
  }
}

​

Function file

const axios = require('axios');

exports.main = async (context) => {
  try {
    // Make a GET request to the Zen Quotes API
    const response = await axios.get('https://zenquotes.io/api/random');

    // Extract the quote data (first item in the array)
    const quoteData = response.data[0];

    // Return the response with a status code, body, and headers
    return {
      statusCode: 200,
      body: quoteData,
      headers: {
        'Content-Type': 'application/json',
      },
    };
  } catch (error) {
    // Log the error, and return a generic message to the caller
    console.error('Error fetching quote:', error.message);

    return {
      statusCode: 500,
      body: { error: 'Failed to fetch quote' },
      headers: {
        'Content-Type': 'application/json',
      },
    };
  }
};

• Catch every error. If a function throws, it returns a 500 response whose body includes the raw error message, which anyone who calls the endpoint can see. Log the details and return a generic message instead.
• Await all work before you return. Work that’s still running when the function returns may never finish, including follow-up requests whose result the caller doesn’t need.
• Don’t log secrets. Anyone with access to the app can read its logs.

​

Responses

exports.main = async (context) => {
  return {
    statusCode: 301,
    headers: {
      Location: 'https://www.example.com',
    },
  };
};

​

package.json

npm install axios

{
  "name": "zen-quote-function",
  "version": "0.1.0",
  "dependencies": {
    "axios": "^1.13.6"
  }
}

​

Endpoints

​

Authentication

• App access token: every function can read process.env.PRIVATE_APP_ACCESS_TOKEN to call HubSpot APIs. The token has the scopes listed in the app’s requiredScopes in app-hsmeta.json. Don’t add it to secretKeys. Calls made with the token count against your API call limits.
• Secrets: store other credentials, such as third-party API keys, as secrets with hs secret add <NAME>, then list each secret’s name in the function’s config.secretKeys array. Learn more about managing secrets.

const axios = require('axios');

exports.main = async (context) => {
  try {
    const response = await axios.get(
      'https://api.hubapi.com/cms/v3/hubdb/tables/109906251/rows?sort=random()&limit=1',
      {
        headers: {
          Authorization: `Bearer ${process.env.PRIVATE_APP_ACCESS_TOKEN}`,
          'Content-Type': 'application/json',
        },
      }
    );
    return { statusCode: 200, body: response.data.results };
  } catch (error) {
    console.error(error.message);
    return { statusCode: 500, body: { error: 'Request failed' } };
  }
};

const axios = require('axios');

exports.main = async (context) => {
  try {
    const response = await axios.get(
      'https://api.hubapi.com/cms/v3/hubdb/tables/109906251/rows?sort=random()&limit=1',
      {
        headers: {
          Authorization: `Bearer ${process.env.MY_SECRET}`,
          'Content-Type': 'application/json',
        },
      }
    );
    return { statusCode: 200, body: response.data.results };
  } catch (error) {
    console.error(error.message);
    return { statusCode: 500, body: { error: 'Request failed' } };
  }
};

​

Context object

​

Headers

​

Logs

​

Limits

• Each function has a maximum of 15 seconds of execution time. Give every retry or polling loop a limit, so a function doesn’t run until it times out.
• Functions that exceed the account’s execution limits return a 429 response. There’s no field in context that reports how close you are to the limits, so handle 429 responses in the code that calls the function, for example by retrying after a delay.
• Functions may experience cold starts after periods of inactivity. To reduce their impact, keep functions lightweight and minimize the number of external API calls.
• Requests with a body must use a content type of application/json. Form posts (application/x-www-form-urlencoded) return a 415 response, so send form data as JSON.
• Only privately distributed apps with static auth can include serverless functions.

​

Related resources

• Get started with serverless functions
• Developer platform serverless functions reference
• Migrate design manager serverless functions to developer projects
• Developer platform versioning