Runtimes
Web triggers
Async functions
Product REST APIs
Fetch APIs

This section describes a Forge preview feature. Preview features are deemed stable; however, they remain under active development and may be subject to shorter deprecation windows. Preview features are suitable for early adopters in production environments.

We release preview features so partners and developers can study, test, and integrate them prior to General Availability (GA). For more information, see Forge release phases: EAP, Preview, and GA.

Invoke Remote API

The invokeRemote method enables apps to integrate with remote backends from within Forge functions.

To use the invokeRemote method, you need to define a remote for your backend in the manifest.yml file.

Additionally, you must include compute in the remote definition's operations array, to allow backend functions to invoke the remote.

Function signature

1
2
import { RequestInit, Response } from 'node-fetch';

type InvokeRemoteOptions = {
  path: string;
};

type APIResponse = Pick<Response, 'json' | 'text' | 'arrayBuffer' | 'ok' | 'status' | 'statusText' | 'headers'>

export async function invokeRemote(
  remoteKey: string,
  options: RequestInit & InvokeRemoteOptions
): Promise<APIResponse>;

Arguments

Returns

Promise<Response>, see node-fetch's Response.

Example

Making a POST request to a remote endpoint:

1
2
import { invokeRemote } from "@forge/api";

const res = await invokeRemote('my-remote-key', {
  path: `/tasks/`,
  method: 'POST',
  headers: {
    x-header-key: 'x-header-value'
  },
  body: JSON.stringify({
    department: 'Ecosystem',
    team: 'Forge',
    description: 'Write docs'
  })
});

if (!res.ok) {
  throw new Error(`invokeRemote failed: ${res.status}`);
}

const json = await res.json();
console.log(`Created task: ${JSON.stringify(json.task)}`);

Making a GET request to a remote endpoint:

1
2
import { invokeRemote } from "@forge/api";

const res = await invokeRemote('my-remote-key', {
  path: `/tasks/?team=Forge`,
  method: 'GET'
});

if (!res.ok) {
  throw new Error(`invokeRemote failed: ${res.status}`);
}

const json = await res.json();
console.log(`Tasks: ${JSON.stringify(json)}`);

Context and security

No context will automatically be passed to invokeRemote when called from a backend Forge function, unlike the context shown on Forge remote essentials, which is only provided to frontend invocations of invokeRemote.

Context should only be pulled from the FCT token in your backend function, otherwise it could be untrusted user input.

Because the context will be passed to the backend through GET params or POST body, it is possible for a frontend user to spoof these parameters and make a call directly to the backend with altered values.

Rate this page: