The barcode network

Scanning a barcode works out of the box, and it works well for groceries, books and music, because open databases cover those and any install can read them for free. Where it thins out is everything else: electronics, toys, hardware, tools, craft supplies. Those live in databases a stock install has no key for, so you scan a drill bit and get nothing.

The barcode network is the answer to that. You get everyone else's corrections, and yours go back in. Joining is optional and takes two settings.

It is never a dependency

Scanning works without it, and keeps working when it breaks. If the service is slow, throttled, or down, your install falls back to its own providers and carries on. That is a design property rather than a reassurance: losing the network degrades your scanning, it does not break it.

The same is true of a miss. When the network does not know a barcode, the lookup falls through to whatever else you have configured instead of stopping there.

Joining

1. Make an account at account.cobblr.xyz. It asks for a name and an email and has you confirm the address. That is what makes revoking a key, enforcing fair use and handling abuse possible at all, and it is the whole of what an account is for.
2. Accept the contributor terms and mint a key. Label it for the machine it is going on, like "Pi in the garage", because keys are per install.
3. Give the key to your install.

Installing for the first time? The setup builder asks for the key while you are generating your files, with joining as the suggested answer. Paste it there and it lands in your .env; there is nothing to edit afterwards. Skip it and the two lines are written commented out with instructions, so joining later never means regenerating anything.

Already running? Add both lines to your .env and restart. The portal shows this snippet with your key already in it:

COBBLR_BIDB_URL=https://barcodes.cobblr.xyz
COBBLR_BIDB_KEY=<your key>

Set both or neither. A URL with no key is refused on every lookup, which costs you a failed request per scan and buys nothing.

There is nothing to install. The client has shipped in every install for a while; it stays inert until COBBLR_BIDB_URL is set.

The key is shown once

The full key appears only at creation. After that the portal shows a masked prefix and there is no way to reveal the rest. Lose it and you revoke that key and mint another, which is a minute of work, not a disaster.

One switch, not two

You cannot take without giving: there is deliberately no read-only tier. A corpus everyone reads and nobody corrects decays, and the corrections are the entire reason coverage improves.

What travels is narrow: the corrected value, the barcode it belongs to, which field it fixed, and an opaque account id. Not your email, not your workspace, not the rest of what you scanned.

What you get, and what you do not

You get per-lookup answers built from open data plus corrections contributed by people on the network. Facts, one barcode at a time.

You do not get records that came from another database whose licence forbids passing them on. Where a human correction sits on top of one of those records, you receive the correction and nothing else. This is those licences rather than a Cobblr preference, and it is the reason a lookup sometimes returns less than you expected, or returns nothing for a barcode the network plainly knows something about.

Worth being blunt about, because the alternative is filing it as a bug: a barcode coming back empty with the network on is often not a failure. It can mean the only record for it is one that cannot be passed on.

Fair use

Keys are rate limited to 10 requests a second sustained, with a burst allowance of 60. Going over returns a throttle, which your install handles by falling back; it is never cached as "this product does not exist", so a later scan retries properly.

Automated enumeration of the barcode keyspace gets a key revoked. Individual facts are free; the compiled, corrected, continuously maintained corpus is the thing being tended, and copying it wholesale takes the work without the upkeep. That is the one usage pattern with a stated consequence.

Leaving

Turn it off by removing the two settings and restarting, revoke the key from the portal, or delete the account. Revoking takes effect on the next key sync, within a minute.

Corrections you already contributed stay contributed. They were released into the public domain, which is not something that can be recalled, and saying so plainly beats implying a recall that could not be performed.

An account is not a login

A Cobblr account at account.cobblr.xyz does one thing today: it issues barcode network keys. It is not a login for your instance and your instance does not depend on it. The accounts people use to sign in to your workspaces are local to your box, they work exactly as they did before, and nothing about them changes whether you join the network or not.

The terms

Two short documents, both readable before you sign up and served at account.cobblr.xyz/terms:

• Contributor terms cover what you grant. Corrections are released under CC0, and you warrant that each one is your own observation of the product in front of you rather than a value copied out of another database. That second clause carries real weight: data held under someone else's licence cannot be passed on, and a correction sourced that way looks like an independent fact and gets served as one.
• Corpus terms cover what you may do with what you receive: per-lookup use yes, bulk extraction no, records that cannot be passed on withheld, service is best-effort.

Read the documents themselves rather than trusting this summary of them.

Where it sits in a lookup

The network is one tier in a chain. See where a scan result comes from for the order and what each tier does.