FAQ content

API: Overview of the LibCal API

In this article

What is an API?

API stands for Application Programming Interface and it allows you to display and process your LibCal content outside of your system. The LibCal API offers more flexibility than widgets, but they also require more extensive coding knowledge and are more complicated than just copying and pasting.

To think of this in another way, widgets are kind of like a frozen dinner - what you see is what you get. APIs are like individual ingredients. Think of all the different meals a cook can create from the same set of ingredients! APIs offer you the same opportunity to mix & match. The possibilities are almost endless!


To access the API, go to Admin > API.

Navigating to the API page

API v1.1 endpoints

The v1.1 endpoints include requests that allow you to get data from your system. In order to request data from the API, you must first set up an application in LibCal. This will provide you with a unique Client ID and Client Secret, which you will need in order to obtain an access token. A valid token is required for LibCal to return data to your app. If you do not include an access token, or the token is expired, an error message will be returned.

API Authentication

Your existing applications will be displayed under the API Authentication tab. If you need to create a new one:

  1. Under the API Authentication tab, click on the Create New Application button. 
The Create New Application button
  1. In the Create Application window, give your application a name. This is only used to help you organize your applications, so you know which ID/Secret pairs you're using with your different apps.
  2. Optionally, you can add a Description to provide more info about how you're using this application.
  3. For the Scope, select the checkbox for each module you want this application to have access to.
    • Calendars - Read: this will give the application read-only access to calendar information, including calendar names, owner, URLs, and visibility.
    • Events - Read: this will give the application read-only access to a calendar's events, including information about the event (such as dates, times, location, and categories).
    • Events - Write: this will give your application the ability to create and cancel event registrations using the /events/:id/register and /events/:event_id/cancel/:booking_id endpoints.
    • Appointments - Read: this will give the application read-only access to a user's appointments, with information such as appointment dates and times.
    • Rooms - Read: if you are using the legacy Room Bookings module (not Spaces), this will give your application read-only access to information about rooms, room availability times, and bookings.
    • Equipment - Read: this will give your application read-only access to information about your equipment bookings, such as locations, categories, bookings, and fines.
    • Equipment - Write: this will give your application the ability to create and cancel equipment bookings using the /equipment/reserve and /equipment/cancel endpoints.
    • Spaces - Read: this will give your application read-only access to information about your space/seat bookings, such as locations, categories, bookings, utilization, availability, filters, and searching.
    • Spaces - Write: this will give your application the ability to create and cancel space/seat bookings using the /space/reserve and /space/cancel endpoints.
    • Passes - Read: this will give your application read-only access to information about your tickets & passes bookings, such as institutions, digital passes, bookings, and availability.
    • Hours - Read: this will give your application read-only access to retrieve a list of hours for locations in your system from the Hours module.
    • Billing - Read: this will give your application read-only access to retrieve payment transactions from your system.
  4. Click the Create button to save your changes. Your Client ID and Client Secret will appear in the Applications table.
The Create Application window
  1. Your Client ID and Client Secret will appear in the Applications table.
    1. Click the eye () icon to show the complete client secret.
The Obtaining an client secret and id
Obtain access token

After creating your application, you will need to obtain an access token to be used with any v1.1 API calls.

  1. Navigate to the Endpoints v1.1 tab.
  2. Click on the link for the /1.1/oauth/token endpoint under the Access Token section.
    1. When submitting your API request, you'll need to provide that token in the Authorization header. You can find an example for your site in the Usage Guide tab.
  3. Use the information and instructions provided on the Generate an Access Token page to format your request.
    • The LibCal v1.1 API uses oAuth 2.0 for authentication and supports the Client Credentials grant type.
    • You'll find details on the payload parameters and an example request and response on the page.
Getting to the Obtaining an Access Token endpoint

Available endpoints

Full details for using each endpoint are available in LibCal under the Endpoints v1.1 tab -- just click on the endpoint's URL on that page to view its specific documentation. Below is a summary of what's available.

  • Access Token: used to retrieve the access token needed for querying other endpoints.
  • Calendars: retrieve information on one or multiple calendars.
  • Events: retrieve information on a calendar's events; create, cancel, and view event registrations; and look up event registrations for individual patrons.
  • Appointments: retrieve a list of appointments for all users or a specific user. You can also retrieve a list of Appointments users, appointment categories, and booking form questions in your system.
  • Equipment: retrieve information on locations, booking forms, categories, and items. You can also retrieve a list of overdue items and fines. In addition, you can also submit and cancel equipment bookings.
  • Spaces / Seats: retrieve information on locations, booking forms, categories, spaces, seats, custom search filters, utilization/occupancy data, search for available spaces, and bookings data. You can also submit and cancel bookings.
  • Hours: return a list of hours for locations in your system.
  • Tickets & Passes: retrieve information on institutions, digital passes, availability, and digital pass bookings.
  • Room Bookings: if you are still using the legacy Room Bookings module (not Spaces), you can retrieve information on one or more room groups or individual rooms. You can also retrieve the availability for a single room, as well as the confirmed bookings for a room group.
  • Billing: retrieve transaction details for payments and/or refunds.

API v1.0 endpoints

The v1.0 endpoints are the older version of the LibCal API but are still supported for backward compatibility. If you are currently using the v1.0 endpoints, you do not need to change your existing scripts. However, we encourage you to use the newer v1.1 endpoints for all future development.

Available endpoints

Full details for using each endpoint are available in LibCal under Admin > API > Endpoints v1.0 -- just click on the endpoint's URL on that page to view its specific documentation. Below is a summary of what's available.

  • Calendars: retrieve information on one or multiple calendars.
  • Events: retrieve information on one or multiple events. You can also search for events, as well.
  • Appointments: retrieve a list of appointments for a specific user.
  • Equipment: retrieve information on locations, booking forms, categories, and items. You can also retrieve a list of overdue items and fines.
  • Spaces / Seats: retrieve information on locations, booking forms, categories, spaces, seats, custom search filters, utilization/occupancy data, search for available spaces, and bookings data and bookings.
  • Hours: retrieve hours information for locations.
  • Tickets & Passes: retrieve information on institutions, digital passes, availability, and digital pass bookings.
  • Room Bookings: retrieve information on one or more room groups or individual rooms. You can also retrieve the availability for a single room, as well as the confirmed bookings for a room group.