Double column

Use the JavaScript client

The Northflank JavaScript client allows you to interact with Northflank via JavaScript code. The JavaScript client can be installed using either NPM or Yarn:

  • npm i @northflank/js-client, or
  • yarn add @northflank/js-client

Below is an example of basic usage: setting up the client using an API token, fetching a list of existing projects and then creating a new project.

import { ApiClient, ApiClientInMemoryContextProvider} from '@northflank/js-client';

(async () => {
  // Create context to store credentials.
  const contextProvider = new ApiClientInMemoryContextProvider();
  await contextProvider.addContext({
      name: 'test-context',
      token: '<api-token>', // Use token retrieved from Northflank web interface: Account Settings > API > Tokens > Create API token.

  // Initialize API client.
  const apiClient = new ApiClient(contextProvider);

  // Retrieve list of projects and log to console.
  const projects = (await apiClient.list.project({})).data.projects;

  // Create a new project.
  await apiClient.create.project({
    data: { name: 'test-project', region: 'europe-west', description: 'test project description' },

Calls using the JavaScript client take a combination of 3 parameters:

  • body - a payload or resource definition, usually used when creating a resource,
  • parameters - equivalent to path parameters on the API, and
  • options - equivalent to query parameters on the API

Have a look at operations such as update service deployment, list builds, and view secret for examples of the different options. You may need to switch to the 'JS client' tab on the right-hand side.

The ApiClient constructor also takes an optional second boolean argument, which if set to true will cause the client to throw an error if the request is met with a HTTP error code response.

Responses are in JSON. The response object contains the following keys:

dataThe data returned as a result of your query
paginationIf the response is paginated, details such as current page and cursoroptional
rawResponseThe raw Response object
requestDetails of the request that you sent including url, method, headers, and body
errorIf your query results in an error, this object will include the error details status, message, and optionally id and detailsoptional

© 2021 Northflank Ltd. All rights reserved.