The barcode network

Scanning a barcode works out of the box for groceries, books and music, because open databases cover those and any install can read them for free. Electronics, toys, hardware, tools and craft supplies 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.

Joining

1. Make an account at account.cobblr.xyz. It asks for a name and an email and has you confirm the address.
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, with nothing to edit afterwards.
   • 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, and it stays inert until COBBLR_BIDB_URL is set.
• Skip the key in the builder and the two lines are written commented out with instructions, so joining later never means regenerating anything.

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.

What the account is for, and what it is not

Confirming your email address 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.

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.

What you get, and what you send

• You get per-lookup answers built from open data plus corrections contributed by people on the network. Facts, one barcode at a time.
• You send a correction you made: 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.
• There is no read-only tier. You cannot take without giving. It is one switch, not two.
• 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.
• It is never a dependency. If the service is slow, throttled, or down, your install falls back to its own providers and carries on. When the network does not know a barcode, the lookup falls through to whatever else you have configured instead of stopping there.

Why there is no read-only tier, and why a lookup can come back short

A corpus everyone reads and nobody corrects decays, and the corrections are the entire reason coverage improves.

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.

Losing the network degrades your scanning, it does not break it. That is a design property rather than a reassurance.

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. That is the one usage pattern with a stated consequence.

Why enumeration is the line

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.

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.

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.