# A label of its own for everything your app tracks

Nomstash Labels gives every container, box or jar a code no other label has, and finds the right thing when one is scanned. Make a test key and have your first labels in minutes.

## Every label is one of a kind

Most printing is built to repeat one design many times. Labels that each carry a different code are harder to get right: the codes mustn't clash, they have to be easy to read and type, and a scan has to land on the right thing.

That's the part we do. You ask for labels, and each one comes with its own code. You tell us what it's on, and a scan finds it again.

- **Codes that never clash.** Every code is unique and is never handed out twice.
- **Easy to read.** Short codes such as `HKT4-4K7Q`, made to be typed by hand as well as scanned. The last 4 characters are enough to find a label.
- **Scans back to your thing.** Attach a code to something in your app by your own type and id. We store the reference, not your data.
- **Safe to retry.** Every request takes an idempotency key, so a retry never makes the same labels twice.

## Your first labels in minutes

Labels made with a test key are kept apart from live ones, so trying things out never touches real labels.

1. Sign in to Nomstash, or make an account, and open [API keys](https://app.nomstash.com/developers/api-keys). Make a test key. There's no form to fill in and nobody to wait for.
2. Make as many labels as you need, up to 1000 at a time, each with its own code.
3. Attach a code to something in your app, then look it up by its code, as a scan would.
4. When it works, make a live key and swap it in. Nothing else changes.

## Three ways to get labels on things

Codes are only half of it. The other half is getting them onto things, and you can offer all three.

- **Print at home, as you need them.** Send any labels with a format, such as an A4 sheet of 24 or a roll for a label printer, and get a PDF to print, with each QR code linking to your own app. Or queue labels for a printer, and your own agent beside it fetches each job as a PDF, prints it and tells us. A ready-made agent is coming soon. [How to print labels](https://nomstash.com/developers/api#createPrintFile).
- **Printed and posted for you.** We print sheets of unique labels and post them, so nobody needs a printer. Email [hello@nomstash.com](mailto:hello@nomstash.com) to set it up.
- **Write or print your own codes.** Choose 4 characters, register them as a label, and a scan or a typed code finds the right thing, the same as for a label we made. [How to register a code](https://nomstash.com/developers/api#createLabels).

## Made for building with AI

Point your coding assistant at [nomstash.com/llms.txt](https://nomstash.com/llms.txt), or give it the [OpenAPI spec](https://nomstash.com/developers/openapi.yaml). Every developer page is also there as plain Markdown, so the assistant reads the same facts you do.

An MCP server for builders is coming, so an assistant can make and print labels for you. [See what it will do](https://nomstash.com/developers/mcp).

## Nomstash runs on it

Every container in [Nomstash](https://nomstash.com/how-it-works), the batch-cooking planner, gets its code and its label from this platform. Households print sheets at home, print as they go on a label printer, or write codes by hand, and every scan finds the right container.

## Try it

Make a test key at https://app.nomstash.com/developers/api-keys, then:

```sh
# Make 30 labels, each with its own code
curl https://api.nomstash.com/v1/labels \
  -H "Authorization: Bearer $NOMSTASH_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"count": 30}'

# Print any of them as a PDF: here on A4 sheets of 24, each QR linking to your app.
# Use "roll-62x29" instead for a label printer.
curl https://api.nomstash.com/v1/print-files \
  -H "Authorization: Bearer $NOMSTASH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format": "a4-sheet", "link": "https://example.com/l/{code}",
       "labels": [{"code": "3KTA-4K7Q"}, {"code": "3KTA-K4QA"}]}' \
  -o labels.pdf

# Say what one is on
curl https://api.nomstash.com/v1/labels/3KTA-4K7Q/attach \
  -H "Authorization: Bearer $NOMSTASH_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"subject": {"type": "acme.box", "id": "box_123"}}'

# Look it up, as a scan would: the full code or its last 4 characters
curl https://api.nomstash.com/v1/labels/4K7Q \
  -H "Authorization: Bearer $NOMSTASH_KEY"
```

Every route is in the OpenAPI spec: https://nomstash.com/developers/openapi.yaml

## Questions

### Can I use the API today?

Yes. Make a test key in [API keys](https://app.nomstash.com/developers/api-keys) in the Nomstash app and call it straight away. Making, attaching and looking up labels work now.

### What's the difference between a test key and a live key?

Each one has its own labels. Labels made with a test key never mix or clash with live ones, so you can try anything without touching real labels.

### Can you print the labels and post them?

Yes. We print sheets of unique labels and post them, so you and the people using your app don't need a printer. Email [hello@nomstash.com](mailto:hello@nomstash.com) to set it up.

### Can I use labels I already have?

If their codes are 4 characters from our set, yes: register each one and a scan works the same as for a label we made. Codes in any other format, such as barcodes you already use, aren't supported yet.

### Can I use OAuth instead of a key?

Yes. Trade your key for an access token that lasts an hour with the OAuth client credentials grant: your key's client id (shown in [API keys](https://app.nomstash.com/developers/api-keys)) and the key itself, sent to `POST /v1/oauth/token`. The token works the same as the key, with the scopes you asked for, and stops when the key is revoked. [See the reference](https://nomstash.com/developers/api).

### What do you store about my app's things?

Only the reference you give us, such as `{"type": "acme.box", "id": "box_123"}`. We never read it or copy your data, so a lookup hands the reference back and your app does the rest.

### Does it work with AI coding assistants?

Yes. [llms.txt](https://nomstash.com/llms.txt) lists every developer page as plain Markdown, and the [OpenAPI spec](https://nomstash.com/developers/openapi.yaml) describes every route. An [MCP server](https://nomstash.com/developers/mcp) is coming soon.

Source: https://nomstash.com/developers