API reference

Quickstart

1. Create a key

   Sign in, open Account, and create a key. A picture key is for spreadsheets. An All routes key is for your own code.

2. Look up a value

   Send the value. The answer names the barcode type and the address of its picture, without drawing it.

   curl -H "Authorization: Bearer $BEEPABLE_KEY" \
     "https://beepable.app/b/auto.json?v=4006381333931"

   {
     "ok": true,
     "symbology": "ean13",
     "digitalLink": false,
     "imageUrl": "https://beepable.app/b/ean13.png?v=4006381333931",
     "print": {
       "minMm": 29.832,
       "targetMm": 37.29,
       "maxMm": 74.58,
       "note": "EAN-13 nominal size is 37.29 × 25.93 mm at 100%. Magnification is 80–200%."
     }
   }

   const response = await fetch("https://beepable.app/b/auto.json?v=4006381333931", {
     headers: { Authorization: `Bearer ${process.env.BEEPABLE_KEY}` },
   });
   const result = await response.json();
   if (result.ok) console.log(result.symbology, result.imageUrl);
   else console.log(result.error.code, result.error.message);

   import os, requests
   
   response = requests.get(
       "https://beepable.app/b/auto.json",
       params={"v": "4006381333931"},
       headers={"Authorization": f"Bearer {os.environ['BEEPABLE_KEY']}"},
   )
   result = response.json()
   print(result["imageUrl"] if result["ok"] else result["error"]["message"])

3. Show the picture

   Add a picture key as k and use the address anywhere an image goes.

   <img src="https://beepable.app/b/ean13.png?v=4006381333931&k=PICTURE_KEY" alt="EAN-13 4006381333931">

   =IMAGE("https://beepable.app/i/auto.png?v="&ENCODEURL(A2)&"&k="&$Z$1)

Keys

Create keys under Account. A key is shown once. A revoked key stops working on the next request.

• Never put an All routes key in an image address. The address is public, and a CDN may keep it for a year.
• A picture key on a route that needs an All routes key is HTTP 403: This key can only draw pictures.
• A pictureKey or pk that adds a key to the addresses must be a picture key of the same account. An All routes key there is HTTP 400: Use a picture key, not an All routes key, in image addresses.
• A missing or unknown key is HTTP 401: This request needs an API key. A revoked key is: This API key has been revoked. On a picture route for a sheet, both are a PNG card instead.
• A request with k can be cached publicly when it succeeds. A request with only Authorization is private, no-store.

Endpoints

Open an endpoint to see its parameters and responses. Choose Authorize, paste a key, and use Try it out to call it from this page. The key stays in this browser tab: it is not saved, and it is gone when you reload.

Symbology names

Automatic mode accepts a valid GTIN-8, GTIN-12, GTIN-13, or GTIN-14, or an http or https URL. A 14-digit value with a leading zero stays ITF-14. An ISBN-13 stays EAN-13. A named retail symbology that does not fit is an error. The service does not switch to another symbology.

A Digital Link is two neighbouring path segments, on any host, after any prefix. The match uses the decoded segments. /8003/00952012345678 is a GRAI. /8003/10952012345678 is not, so that URL stays a QR code. Query-string keys stay a QR code. A bad check digit inside a pasted link is bad_check_digit_in_link. Build a link from a GTIN at /digital-link.

Errors

These sentences are exact. A JSON failure uses the code and the sentence. A text or file route sends the sentence as the whole body. A picture route for a sheet draws the sentence on a PNG card. Show the message to the person who entered the value. Two codes, wrong_length and bad_check_digit, are also used by the Digital Link builder with its own sentence, so branch on the code and display the message you received.

Label and file sentences

Any method other than GET on a /b/ or /i/ route is HTTP 405. The renderer draws at most 32 pictures at a time. Up to 10,000 further misses wait. A miss that cannot enter that queue, or that has waited 60 seconds, is HTTP 429 with rate_limited. There is no per-address cap.

Limits

Limits are buckets that refill over time, so a short burst is fine. Pictures, decisions, and uploads are counted per account, never per network address, because Excel and Google Sheets fetch pictures from shared addresses. Only a picture that has to be drawn counts. A picture served from the cache is free, so reloading a sheet costs nothing.

Rate limits

A limited request is HTTP 429 with Retry-After in seconds and Cache-Control: no-store. It also carries RateLimit-Policy and RateLimit from the IETF draft, for example RateLimit-Policy: "render";q=20000;w=67 and RateLimit: "render";r=0;t=67. A successful upload carries the same two fields. Wait for Retry-After before you try again.

Size limits

These sentences are exact. A body over the limit is refused before it is read. A form error is HTTP 400. A body over the limit is HTTP 413. An address over the limit is HTTP 414.

Account and sign-in

These apply to the Account pages, not to API calls.

One account keeps 20 sessions. A new sign-in deletes the oldest. The server closes a slow connection after 10 seconds for headers, 30 seconds for the whole request, and 5 seconds of idle keep-alive. The process keeps at most 10,000 successful responses and at most 256 MB of them, and drops the oldest. Those four have no sentence.

Retries

Uploads run at most two at a time per account. Send files one after another rather than in parallel.

Caching and CORS

Successful JSON and PNG responses with k in the address use Cache-Control: public, max-age=31536000, immutable. Without k, they are private, no-store. Errors, the batch, the CSV, and formula failures use no-store. This process also keeps the last 10,000 successful responses. GET https://beepable.app/api lists the paths, and GET https://beepable.app/openapi.json describes them.

A browser on another origin can call these routes. Access-Control-Allow-Origin is *. An OPTIONS preflight is HTTP 204.

Stability

The routes, parameters, response fields, and error codes on this page are stable. New fields and new routes may be added, so ignore fields you do not know. A field, a route, or an error code will not be removed or renamed without notice on this page and in /openapi.json, whose version number changes with every published change. The same notice applies to an error sentence. In your code, branch on the error code and show the sentence to people.

Questions