Unclear Documentation on Using GraphQL in Hubspot Cards with Version >= 2025.2

[KLawrence94]

The primary documentation that Hubspot has for using GraphQL with Hubspot Cards is this article, which was published on September 6, 2023 and tells the user to use Serverless functions. However, since version 2025.2 of Hubspot Apps (where-in Hubspot Cards are located), Serverless functions are no longer support as described here.

Similarly, the article the SDK for UI Extensions merely mentions that GraphQL queries can be done in Hubspot Cards, but doesn't give any examples of how it can be done within a Hubspot Card (particularly on the new version >= 2025.2).

So can GraphQL queries be done in the latest version of Hubspot Cards or not? If so, how are those requests authenticated? Do I have to fetch the API key from a 3rd party server?

[MichaelMa · Accepted solution]

I haven't updated my custom cards to 2025.2 because of the lack of serverless functions. Please note is that it's not that serverless functions is no longer supported (aka, it's deprecated) but rather it's not supported yet (on the road map).

In my current crm card incarnations, I use serverless functions to basically run an API request against /collector/graphql (easiest way I found so far) and since the serverless are hosted in hubspot, it saves me from hosting an API endpoint. 

From what I remember, if you wanted to go to 2025.2, you would need a third party server (added to the allowed URLs list) that you API into that replaces the serverless functions . Basically, it's the same thing but rather than HubSpot hosting the api endpoint (aka serverless function), you have to host it yourself. 

Eg,

https://github.com/HubSpot/ui-extensions-examples/blob/83df2915f346a8d2ca5f5c929c5c623e1339fcc4/data...

So no, there isn't any reason why you couldn't use fetch and post against the graphQL endpoint to be processed in the card itself.

This is a generic function I use in my serverless function to post a graphQL request in my serverless. 

/*
const payload = {
	"operationName": "getData",
	"query": "query",
	"variables": data
}
*/

async function getGraphQL(payload) {
  // Fetch associated IDs
  console.log("Payload", payload);
  try {
	const response = await hubspotClient.apiRequest({
		method: 'POST',
		path: '/collector/graphql',
		body: payload
	});
	const json = await response.json()
    return json.data
  } catch (e) {
    console.log(e)
  }
}

[MichaelMa · Accepted solution]

To be clear, with Serverless functions:

Card -> serverless function request -> HubSpot Client to API for data -> returns data to serverless function -> returns data to card

In 2025.2, you replace serverless function (hosted on hubspot) with an external server to execute what you need. You can have your external API also use the HubSpot client or just normal post requests.

You can just run all the API requests in the card file itself, probably, but it won't be as optimized and clean as it could be. 

The article you linked is talking about GraphQL being native to the HubSpot SDK (hubspotClient in my code example) which is native to the cards.

[KLawrence94]

Thanks Michael, I'm feeling dense, but want to make sure I'm understanding it correctly when you say, "The article you linked is talking about GraphQL being native to the HubSpot SDK (hubspotClient in my code example) which is native to the cards." Are you saying that the 2025.2 cards should be able to run the hubspotClient code without fetching the API key to authenticate the request from any serverless functions? If so, how? I can't get that to work. The closest I get is a 400 error, because I don't have a way of getting the API key in my card without using a Serverless function to fetch the API key from an external server or doing the very bad practice of writing the API key in the Hubspot card itself.

[MichaelMa · Accepted solution]

You know, I'm reconsidering what they consider "native" now that you mention it. It seems without serverless functions, HubSpot client can't be used anywhere.

I had thought that fetch could be used against HubSpot API but apparently for some people it doesn't work? In simple test on my side, it seems to work although I did have to hard-code the access_token into my app for testing:
https://community.hubspot.com/t5/CMS-Development/Unclear-Documentation-on-Using-GraphQL-in-Hubspot-C...

If you're doing a fetch against an external service, you should be storing the API key as an environmental variable/secret over there not passing it along. You might need to generate an private app access token for it since when I looked, it doesn't seem like the new project-based version generates an access_token for you to use.

This guide they provided has that issue listed under "Common Gotchas and Solutions":

https://developers.hubspot.com/blog/navigating-serverless-functions-on-hubspots-new-developer-platfo...

According this post: Serverless is coming back in 2025.3 in March next year.

https://community.hubspot.com/t5/Developer-Announcements/Upcoming-Deprecation-HubSpot-Projects-v2025...

Unfortunately, I feel like the mix and match documentation between 2025.1 and 2025.2 is a pain to figure out what's supported and what's not.

[KLawrence94]

Ah, I didn't get to the "Common Gotchas and Solutions" part, but that actually describes the problem, and yes, the documentation around GraphQL being "native" to cards seems to not realy be applicable for 2025.2. In any case, I'm just going to use 2025.1 and then migrate to 2025.3 so that I won't have to offload all the serverless functions at any point.

[MichaelMa · Accepted solution]

I haven't updated my custom cards to 2025.2 because of the lack of serverless functions. Please note is that it's not that serverless functions is no longer supported (aka, it's deprecated) but rather it's not supported yet (on the road map).

In my current crm card incarnations, I use serverless functions to basically run an API request against /collector/graphql (easiest way I found so far) and since the serverless are hosted in hubspot, it saves me from hosting an API endpoint. 

From what I remember, if you wanted to go to 2025.2, you would need a third party server (added to the allowed URLs list) that you API into that replaces the serverless functions . Basically, it's the same thing but rather than HubSpot hosting the api endpoint (aka serverless function), you have to host it yourself. 

Eg,

https://github.com/HubSpot/ui-extensions-examples/blob/83df2915f346a8d2ca5f5c929c5c623e1339fcc4/data...

So no, there isn't any reason why you couldn't use fetch and post against the graphQL endpoint to be processed in the card itself.

This is a generic function I use in my serverless function to post a graphQL request in my serverless. 

/*
const payload = {
	"operationName": "getData",
	"query": "query",
	"variables": data
}
*/

async function getGraphQL(payload) {
  // Fetch associated IDs
  console.log("Payload", payload);
  try {
	const response = await hubspotClient.apiRequest({
		method: 'POST',
		path: '/collector/graphql',
		body: payload
	});
	const json = await response.json()
    return json.data
  } catch (e) {
    console.log(e)
  }
}

[KLawrence94]

Ah, I didn't realize about the severless functions being on the roadmap. Super helpful to know for planning! Although that's a weird implementation to have them go away, then come back the next year (at least in terms of using the latest version of the buidler).

I guess what I'm confused about is how this article talks about GraphQL requests as if it's a native function of Hubspot Cards (witout Serverless Functions), whereas, it sounds like you're saying (and from my experience), you have to have a third-party server to make a fetch request to in order to get an authorization key to do the GraphQL query in the card right?

[MichaelMa · Accepted solution]

To be clear, with Serverless functions:

Card -> serverless function request -> HubSpot Client to API for data -> returns data to serverless function -> returns data to card

In 2025.2, you replace serverless function (hosted on hubspot) with an external server to execute what you need. You can have your external API also use the HubSpot client or just normal post requests.

You can just run all the API requests in the card file itself, probably, but it won't be as optimized and clean as it could be. 

The article you linked is talking about GraphQL being native to the HubSpot SDK (hubspotClient in my code example) which is native to the cards.