Product REST APIs
Async events API
Fetch API


You can use requestGraph to make a request to the Atlassian platform GraphQL API, from within your Forge app. This is suitable for Atlassian products that expose GraphQL API endpoints, such as Compass.

The client includes an Authorization header based on the context-bound fetch call.

To use requestGraph, import the Forge API package in your app:

import api, { route } from '@forge/api';

To check the status of a request, use status as shown below:

const result = await api
      query, variables, headers
const status = result.status;

Method signature

// Only authenticated calls are permitted
api.[asApp | asUser]().requestGraph(query, variables, headers) => Promise<Response>

When making an authenticated API call, you can specify whether to use the app (asApp) or its user (asUser) as the context:


Use this method to call an Atlassian API as the app, using the app user. If your app has all the required permissions, the request will work regardless of who uses the app.

When using asApp, you can use the Authorize API to verify user permissions before making the request.


Use this method to call an Atlassian API as the user of the app.

If the user initiating the request has not granted permission to the app, the request is made without a valid Authorization header.

If the API returns a 401 and there isn't a valid Authorization header, then an Error is thrown.

  • If this error isn't caught, the user is prompted to grant access to the app.
  • If the user grants access, the app is re-initialized.

Experimental endpoints

In the GraphQL API reference, some endpoints may still be experimental. The queries and mutations for these fields are documented with a Field Lifecycle section that includes the following notice:

This field is in the 'EXPERIMENTAL' lifecycle stage 

The Field Lifecycle section will include specific instructions on how to query the field. In particular, any requests to experimental Compass endpoints need to include the X-ExperimentalApi: compass-beta header.



The GraphQL query or mutation.


Variables to be used in the GraphQL query.


HTTP headers to be included in the request.

Authenticated example

Fetch the name of the current user:

import api from '@forge/api';
import ForgeUI, { useEffect, useState } from '@forge/ui';

const [result, setResult] = useState(null);
const query = "query { me { user { name } } }";
const variables = { "key1": "value1", "key2": "value2" };
const headers = { "key1": "value1", "key2": "value2" };

useEffect(async () => {
  const request = await api.asApp().requestGraph(query, variables, headers);
}, []);

if(result) {
    console.log( ? : "No data");
    console.log(result.errors ? result.errors : "No errors");

Successful queries return their result in the data object. Any errors are returned as an array in the errors object.

Rate this page: