Notehub API Introduction

This API reference contains an overview of all requests relevant to interacting with Notehub.io. Each section details request parameters, response members, example cURL requests, and JSON responses.

note

New to the Notehub API? Check out Using the Notehub API, our tutorial which walks you through running your first few requests.

If you want to access the Notehub API in a JavaScript or Python-based application, consider our Notehub JS and Notehub Py libraries available on npm and PyPI. They're our official JavaScript and Python-based SDKs to connect to and interact with the Notehub API.

Authentication

All Notehub API requests require authentication tokens. The two types of tokens Notehub supports are Personal Access Tokens and OAuth bearer tokens.

Personal access tokens are tied to your user account and allow any action your Notehub account can perform. OAuth bearer tokens, on the other hand, are tied to a project and allow any project-level changes. See the sections below for details on using each approach.

• Personal Access Tokens
• Oauth Bearer Tokens

Authentication with Personal Access Tokens

Personal access tokens are user-level authentication tokens for authorizing Notehub API requests. They can be created and managed directly from the Notehub user interface.

Creating a Personal Access Token

Complete the following steps to create a new personal access token.

1. Navigate to Notehub and sign into your account.

2. From the user menu in the top-right corner, select the API Access option.

3. On the next screen, click the Create New Token button.

4. In the resulting dialog, give your token a Token Name, an optional Description and an Expiration, and then click Create.

5. In the next dialog, use the Copy button to copy the token to your clipboard and store it somewhere safe.

   warning

   Personal access tokens have the same permissions as your Notehub user account. When storing personal acccess tokens, use the same caution as you would with a password or other sensitive material.

Using a Personal Access Token

After you create a personal access token, you can use that token to authorize subsequent Notehub API requests. All Notehub API requests accept a Authorization: Bearer <your_token> header for authorization.

Suspending and Deleting Personal Access Tokens

Personal access tokens expire according to the interval you selected when you created the token. You can view the expiration date and time at any point in the Personal Access Tokens section of the Notehub user interface.

If you wish to deactivate your token before its expiration date, you can use the action menu on the right-hand side of the personal access menu table (see image below). A suspended token cannot be used authorize Notehub API requests, and a deleted token is removed from Notehub entirely.

Authentication with OAuth Bearer Tokens

OAuth bearer tokens are project-level autentication tokens that can be used to authorize Notehub API requests. To generate a bearer token you must first enable programmatic API access to your Notehub project using the steps below.

Enabling Programmatic API Access

1. Navigate to your Notehub project and open its Settings.

2. Scroll to the Programmatic API access section, and click the Generate programmatic access button.

3. In the resulting dialog, copy both your Client ID and Client secret to safe location, and then click Save.

Creating Bearer Tokens

With your client id and secret, you can now use the Notehub API's /oauth2/token endpoint to generate an authentication token. The request to /oauth2/token must be sent as a POST request, must include a content-type: application/x-www-form-urlencoded header, and must include a grant_type, client_id, and client_secret in its body.

The code below shows an example of invoking the endpoint using curl.

curl -X POST
 -L 'https://notehub.io/oauth2/token'
 -H 'content-type: application/x-www-form-urlencoded'
 -d grant_type=client_credentials
 -d client_id=your_client_id
 -d client_secret=your_client_secret

The response of the request takes the following form.

{
  "access_token": "lXF80vkqKn...",
  "expires_in": 1799,
  "scope": "",
  "token_type": "bearer"
}

The access_token in the response is your authentication token. You can use this value to authorize subsequent Notehub API requests by providing a Authorization: Bearer <access_token> header.

OAuth bearer tokens automatically expire after 30 minutes. The expires_in property returned by the /oauth2/token request indicates the number of seconds until the token expires.

note

Tokens can also be manually revoked at any time using the Remove Client Application button that appears after enabling programmatic API access.

Usage Limits

You may perform 7 Notehub API requests per minute (up to 10,200/day), per billing account, free of charge.

If you exceed this threshold you may receive a 429 HTTP response code from subsequent Notehub API calls, indicating you've exceeded the free threshold. For high-volume or "bulk" operations, you may be able to utilize a Batch Job instead.

note

Higher API usage limits are available through Notehub Enterprise plans. See Blues pricing or contact Blues sales for more information.

Postman Collection for Notehub API

Want to use the Postman API platform to test your Notehub API calls? Download our Postman Collection and get started now.

After you've imported the data file into Postman, click on the top level folder of the Notehub API collection, and confirm if the baseUrl variable's initial value and current value are set. If not, set them to https://api.notefile.net.

Next, click the eyeball/page icon in the upper right hand corner of Postman to create a new environment (this will hold our secret X-Session-Token value to authenicate with the Notehub API). Select Add on the Environment section, rename the new environment to something like "Notehub API Env" and make a new variable named apiKey, set its type to secret, and hit the Save button in the upper right corner (no need to add any values here, we'll do it dynamically in the next step).

After that, select the "Notehub API Env" option (or whatever you named your new environment) from the Environment dropdown in the top-right corner, open the login request inside of the Notehub API folder, and add your username and password for your Notehub account in the Body tab.

Finally, open the Scripts tab, select Post-res, and add the following code snippet:

var jsonData = JSON.parse(responseBody);
pm.environment.set("apiKey", jsonData.session_token);

This code will set the environment variable apiKey to the generated X-Session-Token value that every other Notehub API request needs. As long as the environment with the apiKey value is selected, any subsequent Notehub API requests you make should work.

Using Array Arguments

Many Notehub API request arguments accept arrays as values. For example, the Get Project Devices request offers a tag argument that allows you to filter devices by their associated tags.

When array arguments are accepted by GET requests, the Notehub API expects them to be passed in the following format:

/endpoint-name?argumentName=value1&argumentName=value2

For example, to use the Get Project Devices endpoint to get devices with a single tag, you could use the following request:

/projects/{projectOrProductUID}/devices?tag=tag1

And to get devices with multiple tags, you could use the following request:

/projects/{projectOrProductUID}/devices?tag=tag1&tag=tag2

If you're using the Notehub API in Postman, the screenshot below shows how you can provide array arguments.