---
title: Notecard Requests & Responses
description: 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.
source_url: https://dev.blues.io/notecard/notecard-walkthrough/notecard-requests-and-responses/
canonical_url: https://dev.blues.io/notecard/notecard-walkthrough/notecard-requests-and-responses/
markdown_url: https://dev.blues.io/notecard/notecard-walkthrough/notecard-requests-and-responses.md
---

# 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](https://dev.blues.io/api-reference/glossary.md#request) to the Notecard and JSON [responses](https://dev.blues.io/api-reference/glossary.md#response) from the Notecard. Notecard requests must be valid JSON. The argument list will vary by request type and usage.

```json
{
  "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](https://github.com/ndjson/ndjson-spec)). 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:

```json
{"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](https://dev.blues.io/api-reference/notecard-api/hub-requests.md#hub-set) request is formatted as:

```json
{"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](https://dev.blues.io/api-reference/notecard-api.md). 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 occurred. Otherwise, the string value will indicate the reason for the error.

Many Notecard requests that perform an action but have no data to return will respond with an empty JSON object:

```json
{}
```

This is the standard Notecard success response when there are no return fields. If you receive `{}` and no `err` field is present, the request completed successfully.

> **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:
>
> ```json
> {
>  "err": "sync: unable to check for changes: {connection-failure} service disconnect"
> }
> ```

### Commands

Every Notecard request also has a `cmd` form. When you use `cmd` instead of `req`, the Notecard executes the operation but sends **no response**.

A classic example is [putting a host microcontroller to sleep](https://dev.blues.io/example-apps/samples/putting-a-host-to-sleep-between-sensor-readings.md) via [`card.attn`](https://dev.blues.io/api-reference/notecard-api/card-requests.md#card-attn). Because the host is about to lose power, it cannot receive a response, and therefore using `cmd` is appropriate:

```json
{
  "cmd": "card.attn",
  "mode": "sleep",
  "seconds": 60
}
```

Note that errors are silently discarded when using `cmd`, so only use this form when the success or failure of the operation does not affect program flow.

[The Notecard & Notehub](https://dev.blues.io/notecard/notecard-walkthrough/overview.md "The Notecard & Notehub") [JSON Fundamentals](https://dev.blues.io/notecard/notecard-walkthrough/json-fundamentals.md "JSON Fundamentals")