--- title: Using the Notehub API description: A short tutorial on how to use the Notehub API to manage your IoT devices and applications remotely. source_url: https://dev.blues.io/guides-and-tutorials/using-the-notehub-api/ canonical_url: https://dev.blues.io/guides-and-tutorials/using-the-notehub-api/ markdown_url: https://dev.blues.io/guides-and-tutorials/using-the-notehub-api.md --- # 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](https://dev.blues.io/notehub/notehub-walkthrough.md#create-a-notehub-account) and [created a Notehub project](https://dev.blues.io/notehub/notehub-walkthrough.md#create-a-new-project). **Ask Your Product Questions in Plain Language** Try Notehub IQ, our new intelligence layer for Notehub that you can use from your own AI agent. [Learn more about Notehub IQ →](https://dev.blues.io/notehub/notehub-walkthrough.md#notehub-iq) [Video: Using the Notehub API](https://www.youtube-nocookie.com/embed/dRq3BuDcP6M) ## 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](https://notehub.io) 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](https://dev.blues.io/images/notehub/api/personal-access-token-menu.png?v=ab898151) 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](https://dev.blues.io/images/notehub/api/personal-access-token-dialog.png?v=9b7be80e) 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](https://dev.blues.io/images/notehub/api/personal-access-token-copy.png?v=33a0e275) > **Warning:** > > Personal access tokens have the same permissions as your Notehub user account. When storing personal access tokens, use the same caution as you would with a password or other sensitive material. You'll provide this token on every Notehub API request by passing it in an `Authorization: Bearer ` HTTP header, sent to the API's base URL of `https://api.notefile.net`. You'll see this header used in each request throughout the rest of this tutorial. 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//devices` endpoint, where `` is your project's [ProjectUID](https://dev.blues.io/api-reference/glossary.md#projectuid). For authorization, you'll need to include the personal access token you created in the previous step as part of an `Authorization` header. If you're comfortable using the `curl` command, you can run the request using the syntax shown below, replacing `` with your project's ProjectUID and `` with your personal access token. ```bash curl -X GET -L 'https://api.notefile.net/v1/projects//devices' -H 'Authorization: Bearer ' ``` ![An example of using curl to retrieve devices](https://dev.blues.io/images/guides/notehub-api/curl-devices.png?v=2b0eaf81) 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](https://www.postman.com/) to send a `GET` request to the `/projects//devices` endpoint. ![An example of using Postman to retrieve devices](https://dev.blues.io/images/guides/notehub-api/postman-devices.png?v=b3e423ae) > **Note:** > > There are a variety of options you can use to retrieve devices from Notehub projects. Refer to the [Device API](https://dev.blues.io/api-reference/notehub-api/device-api.md) 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//events` endpoint. Here's what that looks like with `curl` using a personal access token: ```bash curl -X GET -L 'https://api.notefile.net/v1/projects//events' -H 'Authorization: Bearer ' ``` ![An example of using curl to retrieve events](https://dev.blues.io/images/guides/notehub-api/curl-events.png?v=ea373f10) And here's what that looks like in Postman. ![An example of using Postman to retrieve events](https://dev.blues.io/images/guides/notehub-api/postman-events.png?v=c77ef476) > **Note:** > > As with devices, there are a variety of ways you can retrieve events from Notehub projects. Refer to the [Event API](https://dev.blues.io/api-reference/notehub-api/event-api.md) for more information on the different requests and arguments you can use. > **Note:** > > Both the devices and events endpoints return **paginated** results. By default each request returns up to 50 records; use the `pageSize` (maximum `10000`) and `pageNum` query parameters to page through larger result sets. The events endpoint also accepts `startDate`/`endDate` (Unix timestamp) filters, and a cursor-based `/projects//events-cursor` endpoint that is more efficient for iterating over very large event histories. ## Adding Notes Next, let's look at how you can use the Notehub API to send a [Note](https://dev.blues.io/api-reference/glossary.md#note) to a [device](https://dev.blues.io/api-reference/glossary.md#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//devices//notes/` endpoint, where `projectUID` is your [ProjectUID](https://dev.blues.io/api-reference/glossary.md#projectuid), `deviceUID` is the DeviceUID of a device in your Notehub project, and `` 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: ```bash curl -X POST -L 'https://api.notefile.net/v1/projects//devices//notes/data.qi' -H 'Authorization: Bearer ' -d '{"body": {"temp": 72.22 }}' ``` ![An example of how to send a note using curl](https://dev.blues.io/images/guides/notehub-api/curl-note-add.png?v=2dafe54d) And here's that same example in Postman. ![An example of how to send a note using Postman](https://dev.blues.io/images/guides/notehub-api/postman-note-add.png?v=726cce34) 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](https://dev.blues.io/images/guides/notehub-api/notehub-events.png?v=31d9737d) > **Note:** > > To retrieve inbound Notes on a Notecard, first use [`hub.sync`](https://dev.blues.io/api-reference/notecard-api/hub-requests.md#hub-sync) to sync the all inbound changes (or wait until your Notecard’s next inbound interval). After the sync completes, use [the `note.get` request](https://dev.blues.io/api-reference/notecard-api/note-requests.md#note-get) to retrieve the Note. ## 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//fleets` endpoint, and including `{"label":"Name of your fleet"}` in the request body. ```bash curl -X POST -L 'https://api.notefile.net/v1/projects//fleets' -H 'Authorization: Bearer ' -d '{"label":"My new fleet"}' ``` Here's what that looks like in action. ![An example of how to use curl to create a fleet](https://dev.blues.io/images/guides/notehub-api/curl-create-fleet.png?v=974fa871) ![An example of how to use Postman to create a fleet](https://dev.blues.io/images/guides/notehub-api/postman-create-fleet.png?v=647e90ca) Make note of your FleetUID (the `uid` in the `/projects//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//devices//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//devices//fleets`, and by including `{"fleet_uids":[]}` (where `{fleet_uids}` is an array of all FleetUIDs to add) in the request body. ```bash curl -X PUT -L 'https://api.notefile.net/v1/projects//devices//fleets' -H 'Authorization: Bearer ' -d '{"fleet_uids":[]}' ``` Here's what that looks like in action. ![An example of how to use curl to add a device to a fleet](https://dev.blues.io/images/guides/notehub-api/curl-add-device-to-fleet.png?v=033de7cf) ![An example of how to use Postman to add a device to a fleet](https://dev.blues.io/images/guides/notehub-api/postman-add-device-to-fleet.png?v=d103dd24) > **Note:** > > There are a number of additional APIs available to help you manage Notehub device fleets. For more information, check out the [Project API](https://dev.blues.io/api-reference/notehub-api/project-api.md). ## 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. - [Notehub API Reference](https://dev.blues.io/api-reference/notehub-api.md): A full listing of all Notehub API requests and examples on how to use them. - [Blues community forum](https://discuss.blues.com/): A great place to reach out for help if you get stuck using the Notehub API.