Plan my cook day

API reference.

Base URL: https://api.nomstash.com/v1

Get an API key Download the OpenAPI spec

The basics

Every label has its own code that no other label has. Make labels in sets, attach each one to something in your app by your own {type, id}, and look a label up by its code when someone scans or types it.

Authenticate with an API key from API keys in the Nomstash app (app.nomstash.com/developers/api-keys), sent as Authorization: Bearer nsk_…. A test key (nsk_test_…) and a live key (nsk_live_…) each act for their own account, so test labels never mix with live ones.

Every POST needs an Idempotency-Key header. Send the same key on a retry and you get the first answer back, so a retry never makes a second set. A key is kept for 24 hours. Errors are {"error": {"code", "message"}}.

Make a set of labels

POST /label-sets

Makes 1 to 24 labels (one A4 sheet), each with its own code, in order.

Parameters

Idempotency-Key header, required
Up to 128 characters, unique per request. Send the same one on a retry.

Body

count required
1 to 24.
origin optional
What the set was made for, in your app. Kept with the labels.
{
  "count": 24
}

Responses

201
The set, with its labels in order.
400
Something in the request needs changing. The error's message says what.
401
No key was sent, or the key is unknown or revoked.
403
The key isn't allowed to do this.
409
It clashes with the label as it is now, or a request with the same Idempotency-Key is still being handled.
422
That Idempotency-Key was already used for a different request.

Get a set of labels

GET /label-sets/{labelSetId}

Parameters

labelSetId path, required

Responses

200
The set, with its labels in order.
404
Nothing with that code or id in this key's account.

Print a set of labels

GET /label-sets/{labelSetId}/sheet

The set as one A4 sheet to print at home, as an SVG: 24 labels, 3 across and 8 down, each 63.5 × 33.9 mm. Each label has a QR code and its full code beside it. Print it on A4 sticker paper, 24 per sheet: choose A4, print at actual size (100%) and turn off "fit to page". Labels made with a test key say TEST.

Parameters

labelSetId path, required
link query
Where a scan goes: an https link with {code} in it, such as https://example.com/l/{code}. Without one, the QR holds just the code.
start query
The first free label on a part-used sheet, 1 to 24, across then down.

Responses

200
The sheet.
400
Something in the request needs changing. The error's message says what.
404
Nothing with that code or id in this key's account.

Make a label with your own code

POST /labels

For codes you write by hand or print yourself. Choose 4 characters and the label gets your account's prefix in front, such as 3KTA-K4QA. It scans and looks up the same as a label we made. Codes use only ACDEFHJKLMNPQRSTUVWXYZ234579, so 0 and O, 1 and I, 8 and B, or 6 and G can't be mixed up. Each code can be used once in an account.

Parameters

Idempotency-Key header, required
Up to 128 characters, unique per request. Send the same one on a retry.

Body

shortCode required
The 4 characters, in any case.
{
  "shortCode": "K4QA"
}

Responses

201
The new label.
400
Something in the request needs changing. The error's message says what.
409
It clashes with the label as it is now, or a request with the same Idempotency-Key is still being handled.
422
That Idempotency-Key was already used for a different request.

Find a label by its code

GET /labels/{code}

Takes the full code, such as 3KTA-4K7Q, or just its last 4 characters. A label in another account is not found.

Parameters

code path, required
The full code, such as 3KTA-4K7Q, or its last 4 characters.

Responses

200
The label, and what it's on.
404
Nothing with that code or id in this key's account.

Put a label on something

POST /labels/{code}/attach

Attaches the label to something in your app. A label is on one thing at a time; take it off first to move it.

Parameters

code path, required
The full code, such as 3KTA-4K7Q, or its last 4 characters.
Idempotency-Key header, required
Up to 128 characters, unique per request. Send the same one on a retry.

Body

subject required
Something in your app, by your own type and id. We store it and hand it back; we never read it.
{
  "subject": {
    "type": "acme.box",
    "id": "box_123"
  }
}

Responses

200
The label, now on the subject.
400
Something in the request needs changing. The error's message says what.
404
Nothing with that code or id in this key's account.
409
It clashes with the label as it is now, or a request with the same Idempotency-Key is still being handled.

Take a label off

POST /labels/{code}/detach

Parameters

code path, required
The full code, such as 3KTA-4K7Q, or its last 4 characters.
Idempotency-Key header, required
Up to 128 characters, unique per request. Send the same one on a retry.

Responses

200
The label, now on nothing.
404
Nothing with that code or id in this key's account.