Double column

Using 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.projects({})).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.

Throwing errors on request failure

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:

  • {object}

    Response object.

    • data


      The data returned as a result of your query.

      • pagination


        Data about the endpoint pagination.

        • hasNextPage

          boolean required

          Is there another page of results available?

        • cursor


          The cursor to access the next page of results.

        • count

          number required

          The number of results returned by this request.

      • rawResponse

        {object} required

        An object of node-fetch's Response class.

        • request

          {object} required

          Details of the request that you sent.

          • url

          • method

          • headers

          • body

        • error


          If your query results in an error, this object will include the error details.

          • status

            number required
          • message

            string required
          • id

          • details


      © 2022 Northflank Ltd. All rights reserved.