# bins

bins is a tool for tracking what is stored in physical bins: boxes, shelves,
closets. The data model is a simple hierarchy:

- Account: a login identity (an email) that owns one or more collections.
- Collection: a place such as a house, apartment, or RV, containing areas.
- Area: a room or zone within a collection, containing bins.
- Bin: a container with a numeric label id (assigned by the server), holding items.
- Item: a thing in a bin, with a name and an optional quantity.

This file is for AI assistants and scripts helping a user import or manage their
inventory through the JSON API.

## Authentication

All endpoints are under `/api` on this same origin. Authenticate with an API key
sent as the header `Authorization: Bearer <key>`. The user creates a key by
signing in to bins, opening Settings, then API keys. The key is shown once and
looks like `bins_...`. Keys expire one year after they are created. Ask the user
to paste their key; never invent or guess one. Send
`Content-Type: application/json` on writes. All request and response bodies are
JSON.

## Endpoints

- `GET /api/collections` — list the account's collections: `[{ uuid, name, created }]`.
- `POST /api/collections` with `{ "name": "House" }` — create a collection; returns `{ collectionUuid, metadata }`.
- `GET /api/collections/{uuid}` — read a whole collection (its areas and bins).
- `PUT /api/collections/{uuid}` with `{ "name": "..." }` — rename a collection.
- `POST /api/collections/{uuid}/areas` with `{ "name": "Garage" }` — create an area; returns `{ id, name, bins }` (id is a UUID).
- `PUT`/`DELETE /api/collections/{uuid}/areas/{areaId}` — rename or delete an area.
- `POST /api/collections/{uuid}/areas/{areaId}/bins` with `{ "name": "Toolbox", "description": "" }` — create a bin; returns `{ id, name, description }` (id is the numeric bin label, assigned by the server).
- `PUT`/`DELETE /api/collections/{uuid}/bins/{binId}` — edit or delete a bin.
- `POST /api/collections/{uuid}/bins/{binId}/items` with `{ "name": "Cordless drill", "quantity": 1 }` — add an item (quantity optional).
- `PUT`/`DELETE /api/collections/{uuid}/bins/{binId}/items/{itemId}` — edit or delete an item.
- `GET /api/collections/{uuid}/search?q=term` — search items, bins, and areas (rate limited to one request per 5 seconds per account).

## Importing a spreadsheet or existing inventory

1. Decide which columns map to area, bin, and item.
2. Create the collection once.
3. For each distinct area, create it and keep its returned `id`.
4. For each bin, create it under its area and keep the returned numeric `id`.
5. For each item, post it to its bin.

Let the server assign bin label ids; they are never reused, so do not choose
your own. Create bins one at a time per collection, since writes are serialized.
A short pause between requests is fine. After importing, the user can print QR
labels for each bin from the collection screen.