Public search links

A public search link is a revocable URL that lets anyone run a read-only inventory search limited to one location (and, optionally, one category). Libraries and workshops can share it with visitors without giving them an account or a workspace.

Scope and safety

• The link is bound to one location. Results include that location and, by default, its descendants. An optional category narrows results further.

• Public requests are GET only. They cannot create, edit, move, delete, import, or export anything, and they never see other locations, tokens, membership, or holding notes.

• The URL carries an unguessable random secret. It is a capability URL: treat it like a password. It is returned only to workspace members and is never shown in the link list.

• A link can be given an expiry and can be revoked at any time. Rotating the secret invalidates the previous URL (and any QR that encodes it) immediately.

• Public search is rate limited (default 60/min per client IP, configurable with PUBLIC_SEARCH_THROTTLE_RATE).

• Each successful request updates the link’s last_used_at and use_count for a lightweight access log.

Managing links (workspace members)

Signed-in members have a Public links page (/app/{slug}/public-links/) to create, rotate, and revoke links and to view or download each link’s QR. The full URL is shown once, as a flash message, when a link is created or its secret is rotated.

Method & path	Who	Purpose
GET /api/workspaces/{workspace}/public-search-links/	any member	list links (no working URL)
POST /api/workspaces/{workspace}/public-search-links/	writers	create a link, returns the URL once
GET /api/workspaces/{workspace}/public-search-links/{id}/	any member	inspect one link
DELETE /api/workspaces/{workspace}/public-search-links/{id}/	writers	revoke the link
POST /api/workspaces/{workspace}/public-search-links/{id}/rotate/	writers	new secret, returns the new URL once
GET /api/workspaces/{workspace}/public-search-links/{id}/qr/	any member	QR code for the public URL

Create request body:

{
  "name": "Front desk catalog",
  "location_key": "reading-room",
  "include_descendants": true,
  "category": "book",
  "expires_at": "2027-01-01T00:00:00Z"
}

category and expires_at are optional. The response includes url, the full public link. Save it: the list endpoint returns link metadata but never the URL or secret.

QR codes

GET /api/workspaces/{workspace}/public-search-links/{id}/qr/ renders a QR code that encodes only the public URL — never inventory data, tokens, or session credentials.

• ?format=svg (default) or ?format=png for the bare code.

• ?label=true returns a printable SVG that adds the link’s scope name under the code.

• A revoked or expired link returns 404; rotating the secret changes the URL, so any previously printed QR stops working.

Using a link (public visitor)

GET /api/public/search/{secret}/?q=cordless%20drill&page=1&page_size=20

q is optional; an empty query lists everything in scope. Pagination is bounded (page_size up to 50). A revoked, expired, or unknown secret returns 404.

The response uses a dedicated read-only serializer:

{
  "scope": "Front desk catalog",
  "query": "cordless drill",
  "count": 1,
  "truncated": false,
  "pagination": { "count": 1, "page": 1, "page_size": 20, "total_pages": 1, "next": null, "previous": null },
  "results": [
    {
      "item_name": "Cordless drill",
      "item_category": "power-tools",
      "item_description": "18V, two batteries",
      "item_aliases": ["taladro"],
      "item_attributes": {},
      "quantity": "1.000000",
      "approximate": false,
      "unit": "unit",
      "location_name": "Reading room",
      "location_path": [{ "key": "library", "name": "Library" }, { "key": "reading-room", "name": "Reading room" }],
      "search": { "score": 100.0, "matched_terms": ["cordless", "drill"], "match_type": "complete" }
    }
  ]
}