Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/vufind-org/vufind/llms.txt

Use this file to discover all available pages before exploring further.

The VuFind REST API exposes library catalog search and record retrieval functionality over HTTP. All responses are returned as JSON, making it straightforward to integrate catalog data into external applications, harvesters, or custom frontends. The API follows OpenAPI 3 conventions and ships with an interactive Swagger UI for exploration.

​
Base URL

All API v1 endpoints are served under /api/v1/: 
https://your-vufind-instance.example.org/api/v1/
Visiting /api or /api/v1/ without query parameters redirects you to the Swagger UI. To retrieve the raw OpenAPI specification as JSON, append ?openapi to the URL: 
https://your-vufind-instance.example.org/api?openapi

​
Authentication

VuFind supports three API key modes, configured in config.ini under [API_Keys]:
ModeBehavior
disabledAPI keys are not used. All requests are permitted (subject to permissions). This is the default.
optionalUsers may create and use API keys, but keys are not required.
enforcedEvery request must include a valid API key. Requests without a key receive a 401 Unauthorized response.
When API keys are enabled or enforced, pass your key in the X-API-KEY request header (the header name is configurable via header_field in config.ini): 
curl -H "X-API-KEY: your-api-key" \
  "https://your-vufind-instance.example.org/api/v1/search?lookfor=geology"
Users can manage their API keys through the VuFind developer settings interface. Administrators control whether keys are optional or enforced, and can set a per-user key limit (default: 5).

​
Swagger UI

An interactive Swagger UI is available at: 
https://your-vufind-instance.example.org/swagger-ui/?url=...
Visiting /api in a browser will redirect you there automatically. The Swagger UI lets you explore all available endpoints, inspect parameters and response schemas, and issue live test requests directly from your browser.

​
Available endpoints

Search

Search the primary bibliographic index. Supports faceted filtering, sorting, and cursor-based pagination.

Records

Retrieve one or more bibliographic records by their unique identifiers.

Authority

Search and retrieve records from the authority index (persons, corporate bodies, subjects).
Additional endpoints registered in the API:
EndpointMethodDescription
GET /api/v1/searchGET, POSTSearch the primary bibliographic index
GET /api/v1/recordGET, POSTRetrieve one or more bibliographic records
GET /api/v1/index2/searchGET, POSTSearch the secondary index (Search2)
GET /api/v1/index2/recordGET, POSTRetrieve records from the secondary index
GET /api/v1/authority/searchGET, POSTSearch the authority index
GET /api/v1/authority/recordGET, POSTRetrieve authority records
GET /api/v1/web/searchGET, POSTSearch the website index
GET /api/v1/web/recordGET, POSTRetrieve website index records
DELETE /api/v1/admin/cacheDELETEClear application caches (requires admin permission)

​
Response format

All successful responses return JSON with the following top-level envelope: 
{
  "status": "OK",
  "resultCount": 42,
  "records": [ ... ],
  "facets": { ... }
}
Error responses use the same envelope with a non-OK status and an HTTP error code: 
{
  "status": "ERROR",
  "statusMessage": "Missing id"
}
​
status
string
required
"OK" on success, "ERROR" on failure, or "UNAUTHORIZED" when a required API key is absent.
​
statusMessage
string
Human-readable description of the error. Present only when status is not "OK".
​
resultCount
integer
Total number of results matching the query. Present on search and record endpoints.
​
records
array
Array of record objects. Present when records are returned.
​
facets
object
Facet data keyed by facet field name. Present on search responses when facets were requested.

​
HTTP status codes

CodeMeaning
200 OKRequest succeeded.
204 No ContentOPTIONS preflight request handled (CORS).
400 Bad RequestInvalid parameter (e.g., missing id, limit out of range, invalid search syntax, expired resumption token).
401 UnauthorizedAPI key required but not provided.
403 ForbiddenThe caller does not have the required permission (e.g., access.api.Search).
500 Internal Server ErrorAn unexpected server error occurred.

​
CORS

All API responses include Access-Control-Allow-Origin: *, allowing cross-origin requests from any domain. The API accepts GET, POST, and OPTIONS methods.

​
Output options

Two optional query parameters are available on all endpoints:
​
prettyPrint
boolean
default:"false"
When true, the JSON response is formatted with indentation for human readability.
​
callback
string
When provided, the response is wrapped as a JSONP callback instead of plain JSON. The value must be the name of the JavaScript function to call.

​
Access control

API access is governed by VuFind’s permission system. The relevant permissions are defined in permissions.ini:
PermissionControls access to
access.api.SearchGET /api/v1/search
access.api.RecordGET /api/v1/record
access.api.admin.cacheDELETE /api/v1/admin/cache
By default, these permissions are open to all users. Administrators can restrict access by IP range or role by uncommenting and editing the example blocks in permissions.ini.
If you expose VuFind publicly and want to limit API use to trusted clients, enable IP-range restrictions in permissions.ini and set [API_Keys] mode = enforced in config.ini.

Build docs developers (and LLMs) love

Get started for freeTalk to us