homechevron_rightDocschevron_rightAPI Referencechevron_rightNotehub APIchevron_rightNotehub API Introduction

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, or view accelerator projects that feature usage of the Notehub API.

note

For web apps, check out our Notehub JS and Notehub Python libraries

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 with OAuth Bearer Tokens

All requests to the Notehub API are authorized via OAuth bearer tokens. Each bearer token is unique based on the Notehub user and Notehub project, and can be obtained via a request to the /oauth2/token endpoint.

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 client_id and client_secret values can be obtained from the Settings of a Notehub project, under Programmatic API access:

generate programmatic api access in notehub

client id and client secret

note

Tokens automatically expire after 30 minutes, as reflected by the expires_in property (in seconds), which is returned alongside the access_token.

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

Authentication with Session Tokens (Deprecated)

deprecated

This authentication method is officially deprecated in favor of the OAuth workflow documented above.

All requests to the Notehub API require an authentication token in the form of an X-SESSION-TOKEN header. This token can be obtained via a request to the /auth/login endpoint using a Notehub username and password in the body of the request.

curl -X POST
     -L 'https://api.notefile.net/auth/login'
     -d '{"username":"you@youremail.com", "password": "your_password"}'

note

Accounts using GitHub Authentication

If an account was created by using "Sign in with GitHub", by default there is no password available for API authentication purposes. Therefore, users will need to set a password in the Account settings panel in Notehub.io. This password will only be used when generating an authentication token.

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.

Set baseUrl variable in Postman

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).

Create empty apiKey secret value in a new Postman environment

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.

Entering your credentials in Postman

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);

Set code snippet in tests tab to dynamically set X-Session-Token for Notehub API requests

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.

Set environment for Notehub API requests to environment with the apiKey secret

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.

Using array arguments in Postman

Authorization API