Verso
Centralized MARC search service — OAI-PMH harvest, PostgreSQL staging, and OpenSearch-backed retrieval.
Service
| Base URL | https://verso.service.nexuslib.xyz |
|---|---|
| OpenAPI document | /openapi/v1.json |
Authentication
API clients send their per-library key on every request:
X-API-Key: <library-api-key>
- Keys are issued per library — shown once on create / reset in the Admin UI and stored as a SHA-256 hash.
- Missing, unknown, or inactive-library keys get
401 Unauthorized. - Operators sign in at /admin-ui/login with an operator account.
Public endpoints
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/v1/health |
None | Liveness + index/store reachability. |
| POST | /api/v1/search |
X-API-Key |
JSON SearchRequest (query, filters, sort, paging) →
SearchResponse.
|
| GET | /api/v1/record/{id} |
X-API-Key |
Single record by ID (404 on miss). |
| GET | /api/v1/suggest?q=har |
X-API-Key |
Keystroke autocomplete (title/author/subject, explicit
field=isbn) → texts with top-hit record ids.
|
Rate limits
Fixed 1-minute window. Exceeding a limit returns
429 Too Many Requests (application/problem+json).
| Surface | Limit | Keyed by |
|---|---|---|
Public API (/api/v1/search, /record, /suggest) |
100 / min | X-API-Key, else client IP |
Admin login (/admin-ui/login) |
10 / min | Client IP |
Configurable via Verso:RateLimit:PublicApi /
Verso:RateLimit:Login. The health probe is not rate-limited.