---
title: Notehub API
description: This API reference contains an overview of all requests relevant to interacting with Notehub.io to optimize working with fleets of Notecards over Cellular, Satellite, LoRa, or WiFi. Each section details request and response parameters, along with example curl requests and JSON responses.
source_url: https://dev.blues.io/api-reference/notehub-api/
canonical_url: https://dev.blues.io/api-reference/notehub-api/
markdown_url: https://dev.blues.io/api-reference/notehub-api.md
---

# Notehub API

This API reference contains an overview of all requests relevant to interacting with [Notehub.io](https://notehub.io/). Each section details request parameters, response members, example cURL requests, and JSON responses.

> **Tip:**
>
> - New to the Notehub API?
>   - Check out [Using the Notehub API](https://dev.blues.io/guides-and-tutorials/using-the-notehub-api.md), our tutorial which walks you through running your first few requests.
> - Want to access the Notehub API in JavaScript or Python apps?
>   - Try our [Notehub JS](https://dev.blues.io/tools-and-sdks/notehub-sdks/notehub-js-library.md) and [Notehub Py](https://dev.blues.io/tools-and-sdks/notehub-sdks/notehub-py-library.md) libraries, available on [npm](https://www.npmjs.com/package/@blues-inc/notehub-js) and [PyPI](https://pypi.org/project/notehub-py/), respectively.
> - Are you a Postman user?
>   - We provide a [Postman Collection](https://dev.blues.io/tools-and-sdks/notehub-sdks/notehub-api-postman-collection.md) for easy access to all Notehub API requests.

**On this page:**

- [Authentication](#authentication)
- [Usage Limits](#usage-limits)
- [Using Array Arguments](#using-array-arguments)
- [Request Listing](#request-listing)

## 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](#authentication-with-personal-access-tokens) (recommended)
- [Oauth Bearer Tokens](#authentication-with-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](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.

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

![Expiring a personal access token in Notehub](https://dev.blues.io/images/notehub/api/personal-access-token-expiration.png?v=bd4cd73f)

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.

![Personal access token action menu](https://dev.blues.io/images/notehub/api/personal-access-token-action-menu.png?v=78c9f3f2)

### Authentication with OAuth Bearer Tokens

> **Warning:**
>
> OAuth Bearer Tokens are no longer the recommended way to authenticate with the Notehub API. New integrations should use [Personal Access Tokens](#authentication-with-personal-access-tokens) instead, which offer simpler setup, configurable expiration, and the ability to suspend or revoke individual tokens without affecting other integrations.

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 create an OAuth Client for your Notehub project using the steps below.

#### Creating an OAuth Client

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

2. Scroll to the **OAuth** section, and click the **Create OAuth Client** button. ![creating an OAuth client for a Notehub project](https://dev.blues.io/images/notehub/api-oauth.png?v=39b3b197)

3. In the resulting dialog, copy both your **Client ID** and **Client secret** to safe location, and then click **Save**. ![client id and client secret](https://dev.blues.io/images/notehub/api-oauth-client.png?v=32d08fcf)

#### Creating Bearer Tokens

With your client id and secret, you can now use the Notehub API's [`/oauth2/token` endpoint](https://dev.blues.io/api-reference/notehub-api/authorization-api.md#generate-oauth-token) 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`.

```bash
curl -X POST
 -L 'https://api.notefile.net/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.

```json
{
  "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:**
>
> You can remove an existing OAuth Client from your project using the **Remove Client** button that appears after creating a client.
>
> ![removing client application access in Notehub](https://dev.blues.io/images/notehub/remove-client-application.png?v=a4716197)

## 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](https://dev.blues.io/notehub/notehub-walkthrough.md#running-batch-jobs) instead.

> **Note:**
>
> Higher API usage limits are available through Notehub Enterprise plans. See [Blues pricing](https://blues.com/pricing) or [contact Blues sales](https://blues.com/contact-sales/) for more information.

## Using Array Arguments

Many Notehub API request arguments accept arrays as values. For example, the [Get Project Devices](https://dev.blues.io/api-reference/notehub-api/device-api.md#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:

```plaintext
/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:

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

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

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

If you're [using the Notehub API in Postman](https://dev.blues.io/tools-and-sdks/notehub-sdks/notehub-api-postman-collection.md), the screenshot below shows how you can provide array arguments.

![Using array arguments in Postman](https://dev.blues.io/images/notehub/postman-array-arguments.png?v=949ce476)

## Request Listing

### [Authorization API](https://dev.blues.io/api-reference/notehub-api/authorization-api.md)

[Generate an OAuth bearer token for authenticating Notehub API requests.](https://dev.blues.io/api-reference/notehub-api/authorization-api.md)

[View reference](https://dev.blues.io/api-reference/notehub-api/authorization-api.md)

### [Billing Account API](https://dev.blues.io/api-reference/notehub-api/billing-account-api.md)

[Deprecated. Use the Organization API instead to retrieve data related to Notehub organizations.](https://dev.blues.io/api-reference/notehub-api/billing-account-api.md)

[View reference](https://dev.blues.io/api-reference/notehub-api/billing-account-api.md)

### [Device API](https://dev.blues.io/api-reference/notehub-api/device-api.md)

[GET, POST, and DELETE data related to the devices in a Notehub project.](https://dev.blues.io/api-reference/notehub-api/device-api.md)

[View reference](https://dev.blues.io/api-reference/notehub-api/device-api.md)

### [Event API](https://dev.blues.io/api-reference/notehub-api/event-api.md)

[Retrieve the event data your devices have synced to Notehub.](https://dev.blues.io/api-reference/notehub-api/event-api.md)

[View reference](https://dev.blues.io/api-reference/notehub-api/event-api.md)

### [Jobs API](https://dev.blues.io/api-reference/notehub-api/jobs-api.md)

[Create and manage the batch jobs that operate across a Notehub project.](https://dev.blues.io/api-reference/notehub-api/jobs-api.md)

[View reference](https://dev.blues.io/api-reference/notehub-api/jobs-api.md)

### [Monitor API](https://dev.blues.io/api-reference/notehub-api/monitor-api.md)

[Manage the alerts that notify you when your project needs attention.](https://dev.blues.io/api-reference/notehub-api/monitor-api.md)

[View reference](https://dev.blues.io/api-reference/notehub-api/monitor-api.md)

### [Organization API](https://dev.blues.io/api-reference/notehub-api/organization-api.md)

[Retrieve data related to Notehub organizations, including their projects and billing.](https://dev.blues.io/api-reference/notehub-api/organization-api.md)

[View reference](https://dev.blues.io/api-reference/notehub-api/organization-api.md)

### [Project API](https://dev.blues.io/api-reference/notehub-api/project-api.md)

[Retrieve and manage project-level data, including fleets and environment variables.](https://dev.blues.io/api-reference/notehub-api/project-api.md)

[View reference](https://dev.blues.io/api-reference/notehub-api/project-api.md)

### [Route API](https://dev.blues.io/api-reference/notehub-api/route-api.md)

[GET, POST, PUT, and DELETE the routes that forward Notehub events to your cloud.](https://dev.blues.io/api-reference/notehub-api/route-api.md)

[View reference](https://dev.blues.io/api-reference/notehub-api/route-api.md)

### [Usage API](https://dev.blues.io/api-reference/notehub-api/usage-api.md)

[Retrieve usage data and metrics for data, events, route logs, and sessions.](https://dev.blues.io/api-reference/notehub-api/usage-api.md)

[View reference](https://dev.blues.io/api-reference/notehub-api/usage-api.md)

[Authorization API](https://dev.blues.io/api-reference/notehub-api/authorization-api.md "Authorization API")