REST API

The Librario REST API lets you integrate and automate your library processes programmatically. It exposes the functions of Librario that matter for your existing IT infrastructure and your workflows.

Two API versions

There are currently two versions of the API. They are reachable independently of one another and differ in both their data model and their sign-in.

v3 clears out the legacy of v2: dedicated endpoints for nested resources, dedicated DELETE endpoints instead of _destroy markers, and a unified PATCH /users/:id. The details are in the changelog entry API v3 available as a preview.

Reaching the API

The API is available at:

https://<your-company>.mylibrar.io/api, for example: https://app.mylibrar.io/api

If you have been assigned your own subdomain, use it in the URL.

The complete reference

The full API documentation is available in two formats:

1. Swagger UI: An interactive web interface for exploring the API

   • Available at https://<your-company>.mylibrar.io/api
   • Lets you call endpoints directly
   • Shows example requests and responses
   • Offers the OpenAPI specification as swagger.yaml for download

2. OpenAPI specification (swagger.yaml): A machine-readable description of the API

   • The basis for generating API clients automatically
   • Can be imported into API development tools
   • Useful with AI tools such as ChatGPT or Claude

Authentication

The two API versions sign in differently.

v3: OAuth 2.1

v3 accepts OAuth 2.1 with the authorization code flow and nothing else. There is no sign-in with a username and password. An access token is valid for one hour and comes with a refresh token that renews itself on every use.

Every token is valid for exactly one target resource, namely https://<your-company>.mylibrar.io/api/v3. You pass that address in the resource parameter when authorising. For a self-registered client without the parameter, the authorization server answers error=invalid_target, because a token with no fixed target resource could be replayed against a different interface. The exception is a client registered with no scope beyond library:read and assets:read. This includes a registration with no scope at all, which Librario stores as those two. If such a client omits resource, Librario binds the token to the MCP server. /api/v3 refuses that token with 401. The WWW-Authenticate header then carries error="invalid_token" and error_description="audience mismatch". So always send resource in scripts for the REST API. For a client an administrator issued, Librario fills in the surface chosen at creation. When you redeem the code, the token inherits the target resource of the authorization; if you send resource there anyway, it has to match.

Public and confidential clients

A client is public when it does not authenticate itself at the token endpoint, and confidential when it does, with a client secret. Librario issues both. Which one you get is decided on one of two paths.

Self-registration (Dynamic Client Registration). Your program registers itself at POST /oauth/clients. The token_endpoint_auth_method field decides the type: the value none yields a public client with no secret. Leave the field out and RFC 7591’s default client_secret_basic applies, so you get a confidential client with a secret. The supported methods are none, client_secret_basic, and client_secret_post. The client_secret appears in the registration response and nowhere else; it is never handed out a second time.

Issued by an administrator. If the client should belong to the account rather than to the person who registered it, an administrator issues a client for the REST API surface. The client, with its registration, client secret, rotation and revocation, belongs to the account and stays in place when people come and go. Each connection belongs to the person who signed in and runs with their roles. When that person leaves the team, someone else signs in once and the integration carries on with the same client. The same applies to connectors that ask for a client ID and client secret up front. Administrators see the client in the account administration, rotate its client secret with a changeover window, and end every connection at once by revoking it. Those clients are always confidential; they authenticate with client_secret_basic or client_secret_post. With client_secret_basic, send the client ID and client secret as HTTP Basic authentication to POST /oauth/token; code and code_verifier go in the request body as for a public client. The client secret is shown exactly once, and at most two are valid at a time so a rotation runs without interruption. Creating, rotating and revoking are described on OAuth clients for integrations. This path is part of advanced AI controls and is open only on plans that include them; self-registration is not affected.

Librario requires PKCE (method S256) from every self-registered client, public or confidential. For a client an administrator issues, PKCE is a choice at creation and is on by default; turn it off only when the connector sends no code_challenge. If a tool registers itself and sends no code_challenge, support can lift the requirement for the confidential clients of your account. For public clients PKCE always stands.

v3: Permissions

A token carries the intersection of the requested permissions, what the client registered for, and what the person signing in released on the consent screen.

If a token is missing a permission, the API answers 403 InsufficientScope and names the missing scope in the WWW-Authenticate header. Tokens issued before assets:read and assets:write existed received those permissions automatically wherever they carried library:read or library:write.

v2: Basic authentication or session cookie

v2 knows two methods:

1. Basic authentication with the usual Librario credentials.
2. Session cookie (_library_session), when the call comes from a browser session that is already signed in.

In both cases the permissions match the roles configured in the application.

Examples for v2 are not documented here. The complete description is in the OpenAPI specification at https://<your-company>.mylibrar.io/api/v2/swagger.yaml.

Data format

The API exchanges data as JSON, a format that every common programming language handles easily.

Pagination

List endpoints return 25 entries per page, 50 at most. To retrieve every record, request the pages one after another.

Two response headers help you navigate:

• X-Total: the total number of available entries
• Link: URLs for the first, previous, next, and last page

Best practices

Request rate

Please limit automated access to roughly 60 requests per minute, use pagination for list queries, and process large volumes in smaller batches.

Error handling

The API uses the following HTTP status codes:

• 200: request succeeded
• 401: not authorised, for example because the token has expired
• 403: access denied or permission missing (InsufficientScope)
• 404: resource not found. When creating or updating a publication, also when an id for a contributor, category or organization does not exist in your account (category and organization in API v3 only)
• 422: input could not be processed
• 429: too many requests
• 500: internal server error

Error responses carry additional detail as JSON:

{
  "error": {
    "code": "RecordNotFound",
    "message": "Requested record not found"
  }
}