Check out and check in library items via FOLIO Okapi circulation REST API
domain: dev.folio.org · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Authenticate to the FOLIO Okapi gateway by POSTing username and password to /authn/login to receive an x-okapi-token header value
Include the x-okapi-token and x-okapi-tenant headers on all subsequent requests to route them through Okapi to the correct module
POST /circulation/check-out-by-barcode with a JSON body containing itemBarcode, userBarcode, and servicePointId to check out the item to the patron
Note the returned loan object's id, dueDate, and item details for confirmation and receipt generation
When the item is returned, POST /circulation/check-in-by-barcode with itemBarcode, servicePointId, and returnDate to check in the item
GET /loan-storage/loans?query=userId=={userId} to retrieve a patron's full loan history for account review or overdue processing
Known gotchas
FOLIO is a microservices platform — the specific module versions installed on a tenant determine which API endpoints are available; an endpoint present in the FOLIO reference environment may not exist on an older institutional deployment
Okapi enforces module permission checks: the authenticated user must have the correct FOLIO permissions (e.g., circulation.loans.item.post) or the request returns 403, not 404
Barcode values in FOLIO are case-sensitive and must exactly match the physical barcode or user barcode enrolled in the system — a mismatch returns a 422 validation error, not a 404
Give your agent this knowledge — and 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?