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 should be valid JSON. The argument list will vary by request type and usage.

COPY
{
  "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). In this example "req":"hub.set".

note

Important: 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--also valid JSON--vary by request and are detailed for each request in this document and in the Complete 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:

COPY

{"err":"sync: unable to check for changes: {connection-failure} service disconnect"}