API and embeddable widget

Plus plans (and every trial) can read the database list as JSON or drop a ready-made widget into an existing website. Both use a token from API & widget in the admin. Only databases patrons can already see are ever returned.

The widget

Paste this where the list should appear:

<div data-refbytes-az data-token="az_…"></div>
<script src="https://yourlibrary.az.refbytes.com/widget.js" defer></script>

It renders a search box, subject/type/access filters, and the cards in your brand color, with every link going through the same tracked redirect as the main page so clicks still count. Optional attributes: data-subject="genealogy" locks a subject, data-list="spanish-resources" shows one of your lists (by its handle, in the list's order), data-limit="12" caps the list, data-hide-filters="true" shows search only.

If you set allowed origins on the token, the widget only works on those sites.

Searches patrons settle on in the widget (a pause in typing, or Enter) show in Patron searches alongside the public page's, under the same rules: nothing identifies who searched, and searches that look like an email address or a card or phone number are never kept. Searching in the widget sets no cookies and stores nothing in the patron's browser.

The API

GET /api/v1/library
GET /api/v1/databases?q=&subject=&type=&access=&audience=&featured=1&per_page=100
GET /api/v1/databases/{handle}
GET /api/v1/subjects
GET /api/v1/types
GET /api/v1/lists
GET /api/v1/lists/{handle}
GET /api/v1/librarians
GET /api/v1/librarians/{handle}
POST /api/v1/searches

The full interactive reference, with every parameter and example responses, is at /api/docs (OpenAPI JSON at /api/docs.json).

Send the token as Authorization: Bearer az_… or ?token=az_…. Responses are JSON with a data key; list endpoints are paginated. Each IP address can make 300 requests a minute per token, so patrons using the widget each have their own allowance (a campus lab behind one address shares one); every response carries X-RateLimit-Limit and X-RateLimit-Remaining, and past the limit you get a 429 with Retry-After. Each database includes its vendor, links.open (tracked, proxied), links.direct (the proxied vendor URL itself; clicks on it aren't counted in your usage reports), and links.details.

/lists returns your published lists; an unlisted list can still be fetched by its handle. Get a list's databases, in its order, with /databases?list={handle}. /librarians returns the librarians shown on your public site, with their subjects and the contact details on their profiles.

POST /searches is how the widget logs a search a patron settled on. Searches your own code makes through /databases?q= are never logged, so they don't appear in Patron searches.