homechevron_rightDocschevron_rightGuides & Tutorialschevron_rightUsing the Notehub API

Using the Notehub API

The Notehub API allows you to perform a variety of actions on your Notehub projects without having to use the Notehub UI.

In this tutorial you'll learn how the Notehub API works by performing a handful of requests, including retrieving project devices and events, sending a Note to one of your project's Notecards, and creating and updating a Notehub fleet. But before performing any Notehub API request you must first retrieve an authentication token.

note

Before starting this guide make sure you've created a Notehub account and created a Notehub project.

Authenticating

All Notehub API requests require an authentication token. The easiest way to get started is by creating a Personal Access Token, a user-level authentication token that can be created and managed through the Notehub user interface.

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. The Personal Access Token menu in Notehub

  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. Dialog for creating new personal access tokens in Notehub

  5. In the next dialog, use the Copy button to copy the token to your clipboard and store it somewhere safe. Copying a personal access token in Notehub

    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.

Now that you have an authentication token, let's look at how to send other Notehub API requests.

Retrieving Devices and Events

As a first set of requests, let's look at how to retrieve a list of devices and events from your Notehub project.

Retrieving Devices

To get a list of devices from your Notehub project you can use the Notehub API's /projects/<projectUID>/devices endpoint, where <projectUID> is your project's ProjectUID. For authorization, you'll need to include the personal access token you created in the previous step as part of a Authorization header.

If you're comfortable using the curl command, you can run the request using the syntax shown below, replacing <projectUID> with your project's ProjectUID and <your_token> with your personal access token.

curl -X GET
     -L 'https://api.notefile.net/v1/projects/<projectUID>/devices'
     -H 'Authorization: Bearer <your_token>'

An example of using curl to retrieve devices

If you're not comfortable with curl there are a variety of other tools you can use to send HTTP requests. For example, the screenshot below shows how to use Postman to send a GET request to the /projects/<projectUID>/devices endpoint.

An example of using Postman to retrieve devices

note

There are a variety of options you can use to retrieve devices from Notehub projects. Refer to the Device API for more information on the different requests and arguments you can use.

Retrieving Events

Next let's look at how to retrieve events from your Notehub project. The easiest way to get a list of events is by sending a GET request to the API's /projects/<projectUID>/events endpoint. Here's what that looks like with curl using a personal access token:

curl -X GET
     -L 'https://api.notefile.net/v1/projects/<projectUID>/events'
     -H 'Authorization: Bearer <your_token>'

An example of using curl to retrieve events

And here's what that looks like in Postman.

An example of using Postman to retrieve events

note

As with devices, there are a variety of ways you can retrieve events from Notehub projects. Refer to the Event API for more information on the different requests and arguments you can use.

Adding Notes

Next, let's look at how you can use the Notehub API to send a Note to a device. To complete this step, you must have a device associated with your Notehub project (e.g. it has already synced with the project).

Once you have a device on your project, you can send a POST to the API's /projects/<projectUID>/devices/<deviceUID>/notes/<file> endpoint, where projectUID is your ProjectUID, deviceUID is the DeviceUID of a device in your Notehub project, and <file> is the name of the Notefile you'd like to use (e.g. data.qi).

Here's an example of how to send that request with curl using a personal access token:

curl -X POST
     -L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>/notes/<file>'
     -H 'Authorization: Bearer <your_token>'
     -d '{"body": {"temp": 72.22 }}'

An example of how to send a note using curl

And here's that same example in Postman.

An example of how to send a note using Postman

Once you've sent your Note you can view it immediately on your Notehub project's event list.

A look at the new event in Notehub

note

You can retrieve inbound Notes on a Notecard by using the Notecard API's note.get request.

Managing Fleets

Finally, let's look at a few Notehub APIs to manage fleets, which are groupings of one or more devices.

To use fleets you must first create one, which you can do by sending a POST to the Notehub API's /projects/<projectUID>/fleets endpoint, and including {"label":"Name of your fleet"} in the request body.

curl -X POST
     -L 'https://api.notefile.net/v1/projects/<projectUID>/fleets'
     -H 'Authorization: Bearer <your_token>'
     -d '{"label":"My new fleet"}'

Here's what that looks like in action.

An example of how to use curl to create a fleet

An example of how to use Postman to create a fleet

Make note of your FleetUID (the uid in the /projects/<projectUID>/fleets response), as you'll need it for the next request.

Once you have a fleet, you can use the Notehub API to add and remove devices from a fleet using the API's /projects/<projectUID>/devices/<deviceUID>/fleets endpoint. You can send a PUT request when you'd like to add devices to a fleet, and a DELETE request when you'd like to remove devices from a fleet.

For this tutorial let's look at how to add a device to a fleet, which you can do by sending a PUT to /projects/<projectUID>/devices/<deviceUID>/fleets, and by including {"fleet_uids":[<fleet_uids>]} (where {fleet_uids} is an array of all FleetUIDs to add) in the request body.

curl -X PUT
     -L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>/fleets'
     -H 'Authorization: Bearer <your_token>'
     -d '{"fleet_uids":[<fleet_uids>]}'

Here's what that looks like in action.

An example of how to use curl to add a device to a fleet

An example of how to use Postman to add a device to a fleet

note

There are a number of additional APIs available to help you manage Notehub device fleets. For more information, check out the Project API.

Additional Resources

Overall, the Notehub API provides a variety of ways to perform Notehub actions without using the Notehub UI. Check out the following resources to learn more.