Snipe IT Integration

Snipe-IT Integration

Print asset tag labels from Snipe-IT.

Status: design specification. Implementation tracked in issue #16.

How it works — pull only

Snipe-IT does not offer outbound webhooks for asset events or label-print actions. Integration is therefore pull-mode only — you operate from inside the hub UI:

1. Open the hub (e.g. on your phone)
2. Switch to the Snipe-IT tab on a printer
3. Search for an asset by tag, name, serial, or category — the hub queries Snipe-IT's REST API
4. (Or scan an asset's existing barcode if the asset already has one)
5. Pick the asset from the results
6. Choose a layout from the dropdown (see layouts below) and the tape size if not auto-set
7. Hit Print → label prints

You / phone                  Hub                           Snipe-IT
─────────────                ─────                         ─────────
1. Open hub UI         ─────►
2. Switch to Snipe-IT tab
3. Scan / search       ─────► /api/lookup/snipeit/search?q=…
                                                  ─────► GET /api/v1/hardware
                                                  ◄───── matching assets
                              ◄────── search results
4. Click the asset       ─────► /api/lookup/snipeit/<id>
                                                  ─────► GET /api/v1/hardware/bytag/<tag>
                                                  ◄───── full asset detail
                              ◄────── LabelData
5. Choose layout
   Click Print          ─────► /api/print/<printer>?layout_id=<id>
                              ──► PrintQueue worker → printer
                              ◄── live status via SSE

There is no automatic / triggered printing in Snipe-IT integration. If you need that, file a feature request in Snipe-IT upstream — the hub would happily consume a webhook if Snipe-IT adds one.

Layouts

Per ADR 0012, every label is rendered through a layout — a saved recipe describing what the printed label looks like. You can:

• Use a seeded default (e.g. snipeit-asset-12mm)
• Save your own custom layout for Snipe-IT (e.g. "asset tag + serial + category icon")
• Pick which layout to use for each print job
• Set a different default per (integration, tape_mm) combination

Available Snipe-IT fields you can put on a layout (extends as Snipe-IT API evolves):

Field path	Example value
title	"MacBook Pro 16" (resolved from name, falls back to model.name)
primary_id	"ASSET-12345" (the asset_tag)
qr_payload	https://<your-host>/asset/ASSET-12345
secondary[0]	serial number (if printable)
secondary[1]	category name (e.g. "Laptops")
secondary[2]	manufacturer (e.g. "Apple")
extras.location	assigned location name
extras.assigned_to	assignee name
extras.purchase_date	purchase date

Seed layouts shipped:

• snipeit-asset-12mm (default for 12mm tape) — QR + asset_tag + short title
• snipeit-asset-24mm (default for 24mm tape) — QR + title + asset_tag
• snipeit-asset-with-serial-24mm — QR + title + asset_tag + serial

Create your own via POST /api/layouts — see the API reference at /redoc on a running hub.

Setup

1. Create a Snipe-IT API token

In your Snipe-IT instance:

1. Profile → Manage API Keys → Create New Token
2. Name it (e.g. label-printer-hub)
3. Copy the token immediately — it isn't shown again

The hub only reads from Snipe-IT, so a read-only token is sufficient. At minimum the token needs view permission for the asset categories you want to print labels for.

2. Configure the hub

In your .env (or your secret manager):

SNIPEIT_URL=https://snipeit.example.com
SNIPEIT_API_TOKEN=<your-token>

Restart the backend container so the new variables are picked up:

docker compose restart backend

3. Verify

Open the hub UI → switch to the Snipe-IT tab on a printer → search for a known asset tag or name. Matching results appear in 1-2 s.

Tape size recommendations

• 12mm: minimum tape that fits a useful Snipe-IT label. Tight — only QR + asset_tag + short title fit
• 24mm (recommended): more room for asset name + serial; recommended default for most assets
• larger sizes (38mm or 62mm with QL printers): full asset detail card with location, model, owner

Limitations

• Pull-only — Snipe-IT can't trigger an automatic print (no webhook from Snipe-IT in 2026)
• Bulk-print mode (e.g. "print labels for all uncategorised assets") is not in MVP — track in a future issue
• The hub doesn't write back to Snipe-IT (no "marked as labelled" status). Read-only by design.

Troubleshooting

Symptom	Likely cause	Fix
401 from Snipe-IT API	Token expired or invalid	Regenerate in Snipe-IT and update SNIPEIT_API_TOKEN
404 on asset lookup	Wrong tag, asset deleted, or token lacks permission for this asset's category	Check tag in Snipe-IT directly; check token permissions
Search returns nothing	Wrong field queried, or pagination issue	Try a different search term (name, tag, serial); the hub respects Snipe-IT's API filters
Hub UI shows asset but print fails	Printer not reachable, tape mismatch	Check printer status page; ensure tape size matches layout
Preview shows "title truncated"	Asset name longer than tape allows	Pick a wider tape, or pick / create a different layout

See also

• Snipe-IT API docs
• ADR 0012 — label-layout management
• Architecture: Pull-mode flow
• Issue #16 — AppLookupService design
• Issue #17 — visual layout editor (post-MVP)