API
Base URL of the hosted instance: https://index.tinkerbus.org. The API is read only (GET), answers JSON, and allows
cross-origin requests from any site. GET /openapi.json describes it as OpenAPI 3.
Endpoints
| Request | Answer |
|---|---|
GET /v1/search?q=&ets=&manufacturer=&source=&limit=&offset=&include= | {total, limit, offset, results[]} |
GET /v1/entries/{id} | One entry |
GET /v1/entries/{id}/file | The stored copy of the file |
GET /v1/entries/{id}/products | What the file contains: products and application programs |
GET /v1/entries/{id}/go | 302 redirect to the file on the manufacturer’s site |
GET /v1/manufacturers?q=&withFiles=&limit=&offset= | The registry of KNX manufacturers with the number of indexed files |
GET /v1/sources | The pages that are read and the result of the last crawl |
GET /v1/status | Counts and the last runs of the scheduled jobs |
GET /healthz | Liveness and database check |
GET /openapi.json | The OpenAPI document |
Search
| Parameter | Meaning |
|---|---|
q | Words, at most 200 characters. Every word has to match, as a prefix, the name, article or order number, product names, application names, series, version, category, file name or manufacturer id. |
ets | Only files for this ETS major version, for example 6. |
manufacturer | Manufacturer id, for example M-0083. |
source | Source id, as listed by /v1/sources. |
include=all | Also files that are gone from the manufacturer’s page or whose link is broken. |
limit | Default 20, at most 100. |
offset | Default 0. |
curl 'https://index.tinkerbus.org/v1/search?q=JAL-0410&ets=6&limit=5'
Entries
An entry has id, status, sha256, storedSize, download (the API path of the stored copy), productCount,
applicationCount, minEts and manufacturerId (taken from the file once it was read), next to what the page said
(name, version, releaseDate, fileUrl, pageUrl and so on). Other timestamps: firstSeen, lastSeen,
lastChecked, fetchedAt.
status is:
ok: the manufacturer’s page still lists the file;gone: it left the page. The entry and its copy are kept for 30 days;error: the link failed three checks in a row.
The file endpoint
/v1/entries/{id}/file serves the stored copy with ETag and X-Content-SHA256 (both are the checksum of the
content), supports Range requests, and sets X-Source-Status and X-Source-Page, which say what the manufacturer’s
page says now. It answers 404 when no copy is stored, with a message pointing to /go.
/v1/entries/{id}/go redirects to the file on the manufacturer’s site, or answers 410 if the page no longer offers
it.
Status codes
| Code | Meaning |
|---|---|
| 200, 206 | Success, partial content for Range requests |
| 302 | Redirect (/go) |
| 400 | A bad parameter |
| 404 | Unknown id, or no stored copy |
| 410 | The manufacturer’s page no longer offers the file |
| 405 | Any method other than GET, HEAD or OPTIONS |
| 429 | Rate limit exceeded. The answer carries Retry-After: 30 |
| 503 | /healthz: the database is not readable |
Rate limits
Requests are limited per client address. The default is 120 requests per minute, with a burst of half that, refilled
continuously. A file download costs five requests, and /healthz is not limited. Responses carry Cache-Control:
five minutes for most answers, a day for stored files.
Checking what you get
Tinkerbus checks the SHA-256 and size of every download against the entry, and refuses redirects to another host. If you
write your own client, do the same: compare X-Content-SHA256 with sha256 of the entry.