Scaling an IoT deployment? Join our webinar on May 28th where we dive into real-world scaling pain points and how to overcome them.

Blues Developers
What’s New
Resources
Blog
Technical articles for developers
Newsletter
The monthly Blues developer newsletter
Terminal
Connect to a Notecard in your browser
Developer Certification
Get certified on wireless connectivity with Blues
Webinars
Listing of Blues technical webinars
Blues.comNotehub.io
Shop
Docs
Button IconHelp
Notehub StatusVisit our Forum
Button IconSign In
Sign In
Sign In
Docs Home
What’s New
Resources
Blog
Technical articles for developers
Newsletter
The monthly Blues developer newsletter
Terminal
Connect to a Notecard in your browser
Developer Certification
Get certified on wireless connectivity with Blues
Webinars
Listing of Blues technical webinars
Blues.comNotehub.io
Shop
Docs
Notecard
Notecard API Reference
Notecard Guides
Notecard Firmware Releases
Notecard Walkthrough
Overview
Notecard Product Family
Notecard Requests & Responses
JSON Fundamentals
Notecard Interfaces
Essential Requests
Time & Location Requests
Inbound Requests & Shared Data
Web Transactions
Low Power Design
Low Bandwidth Design
Working with the Notecard AUX Pins
Updating Notecard Firmware
Advanced Notecard Configuration
Notecard Error and Status Codes
Notecard Certifications
homechevron_rightDocschevron_rightNotecardchevron_rightNotecard Walkthroughchevron_rightNotecard Requests & Responses

Notecard Requests & Responses

The Notecard was designed with simplicity and ease of use as a fundamental goal. As such, the Notecard API exclusively consists of JSON requests to the Notecard and JSON responses from the Notecard. Notecard requests must be valid JSON. The argument list will vary by request type and usage.

{
  "req": "<category.request>",
  "argument-one": "value-one",
  "argument-two": "value-two",
  "argument-n": "value-n"
}

Format

Although usually allowed by JSON, newline characters (\n) are not allowed within a JSON request object because the Notecard API is based on newline-delimited JSON (ndjson ). In this documentation, JSON will be shown with extra (invalid) newlines for human readability. When sending the request, to the Notecard, it must be formatted with only a single \n termination:

{"req":"<category.request>","argument-one":"value-one","argument-n":"value-n"} \n

Requests

For each request, the req field specifies the category (for example, hub), and request (for example, set). For example, a hub.set request is formatted as:

"req":"hub.set"
note

Before you send a subsequent request to the Notecard, you must wait to receive the response from the previous request. It is unsafe to send a second request without waiting for the first to complete.

Responses

API responses from the Notecard (also valid-formatted JSON) vary by request and are detailed for each request in the Notecard API Reference. For all responses, an err field may be present in the returned object. If the err object is not present in the Notecard response then no error has ocurred. Otherwise, the string value will indicate the reason for the error.

warning

The err string is for developer consumption and is not intended for display to end-users. For future-proof programmatic error handling, brace-delimited keywords should be checked, for example, by searching for the string "{connection-failure}" within the err field in this sample response:

{
 "err": "sync: unable to check for changes: {connection-failure} service disconnect"
}
Notecard Product Family JSON Fundamentals
Can we improve this page? Send us feedback
© 2025 Blues Inc.
© 2025 Blues Inc.
TermsPrivacy
Notecard Disconnected
Having trouble connecting?

Try changing your USB cable as some cables do not support transferring data. If that does not solve your problem, contact us at support@blues.com and we will get you set up with another tool to communicate with the Notecard.

Advanced Usage

The help command gives more info.

Connect a Notecard
Use USB to connect and start issuing requests from the browser.
Try Notecard Simulator
Experiment with Notecard's latest firmware on a Simulator assigned to your free Notehub account.

Don't have an account? Sign up