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.

View accelerator projects that feature usage of the Notehub API.

Authenticating

All Notehub API requests require an authentication token, and you can retrieve one by sending a POST request to the API's /oauth2/token endpoint. If you're comfortable using the curl command, you can do so by running the command below in your terminal, replacing your-client-id and your-client-secret with the values from the Programmatic API access section of a Notehub project's Settings.

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

An example of using curl to get an authentication token

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 POST to /oauth2/token and generate a bearer token.

An example of using Postman to get an authentication token

Once you have a bearer token, let's look at how to send other Notehub API requests.

Retrieving Devices and Events

You can retrieve a project's devices by sending a GET request to the Notehub API's /projects/<projectUID>/devices endpoint, where <projectUID> is your ProjectUID. For authentication, you must also include a bearer token in an Authorization header. You can perform the request with cURL or Postman using the syntax below.

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

An example of using curl to retrieve devices

And as with your earlier authentication request, you can send the /projects/<projectUID>/devices request using any tool you'd like. For example, the screenshot below shows how to retrieve devices in Postman.

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.

Similarly, the easiest way to retrieve a list of Notehub events is by sending a GET to the API's /projects/<projectUID>/events endpoint. Here's what that looks like with curl.

curl -X GET
     -L 'https://api.notefile.net/v1/projects/<projectUID>/events'
     -H 'Authorization: Bearer <access_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.

curl -X POST
     -L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>/notes/<file>'
     -H 'Authorization: Bearer <access_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 <access_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 <access_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.