NAV
cURL

Libro API

Welcome to the Libro API — your comprehensive toolkit for integrating restaurant reservation management into your applications.

This documentation will guide you through the process of integrating with our platform, from authentication to making your first API call and implementing advanced features.

Base URLs

Environment Base URL Purpose
Production https://api.libroreserve.com Live system integration
Staging https://api.staging.libro.app Testing and development

API Overview

The Libro API follows REST principles and provides JSON:API-compliant responses. Here's a quick overview of the main resources:

Resource Description
Restaurants Restaurant profiles, availability, and settings
Bookings Reservation creation and management
People Guest information
Reviews Customer reviews and feedback

Introduction

Welcome to the Libro API — your comprehensive toolkit for integrating restaurant reservation management into your applications. This documentation provides detailed guidance on accessing our API endpoints for booking management, restaurant information, and customer data.

API Architecture

The Libro API uses RESTful principles with JSON:API-compliant responses. All data is exchanged in JSON format, and authentication is handled through OAuth 2.0 bearer tokens.

Key Features

Documentation Conventions

Throughout this documentation, you'll find examples in multiple programming languages. Select your preferred language using the tabs at the top of each code example.

The API uses resource-oriented URLs, standard HTTP response codes, and accepts request bodies in JSON format.

Getting API Access

To begin your integration:

  1. Request API Access: Contact us at admin@libroreserve.com to be added to our partner program
  2. Obtain OAuth Credentials: You'll receive client ID and secret for authentication
  3. Set Up Your Environment: Choose between production or staging based on your development phase

Here's what is required to get API access:

Authentication

The Libro API uses OAuth 2.0 for authentication, providing secure access to resources while maintaining fine-grained control over permissions.

Authentication Methods

OAuth 2.0 Bearer Tokens

Request:

curl https://api.libroreserve.com/oauth/token \
  -X POST \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 7200
}

The Libro API uses OAuth 2.0 bearer tokens for authentication. This method is secure and allows for token rotation and management.

The response will contain your access token:

Step 1: Implement the Authorization Request

Authorization URL

HTML Button example

<a href="https://accounts.libroreserve.com/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&scope=REQUESTED_SCOPES"
  >Connect to Libro</a>

Create a “Connect” or “Link Account” button in your application that directs users to the Libro authorization URL. The URL should be structured as follows:

https://accounts.libroreserve.com/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&scope=REQUESTED_SCOPES

Replace CLIENT_ID with your client ID, REDIRECT_URI with your encoded callback URL, and REQUESTED_SCOPES with the permissions you need (e.g., bookings). For multiple scopes, separate each with a space (i.e., bookings people reviews).

User Authentication and Authorization

When users click this button, they will be redirected to Libro’s system to log in (if not already logged in) and authorize your application to access their data based on the requested scopes.

Libro Authorization Flow

Step 2: Handle the Callback

Receive the Authorization Code

After the user authorizes the connection, Libro’s system will redirect the user back to your application via the redirect_uri you provided during authentication, including an authorization_code as a URL parameter.

Example Callback URL: https://app.example.io/oauth/callback?code=AUTHORIZATION_CODE

Step 3: Exchange the Authorization Code for an Access Token

Request:

curl https://accounts.libroreserve.com/oauth/token \
  -X POST \
  -d "grant_type=authorization_code&
  client_id=CLIENT_ID&
  client_secret=CLIENT_SECRET&
  code=AUTHORIZATION_CODE&
  redirect_uri=ENCODED_REDIRECT_URI"

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IKSJFGDKJF...",
  "token_type": "Bearer",
  "expires_in": 7200
}

Libro’s system will respond with an access and refresh token that your application can use to make authenticated requests to Libro’s API on behalf of the user.

The expires_in value returned in the token response is expressed in seconds, as per the OAuth 2.0 specification.

Step 4: Make Authenticated Requests

Request:

curl https://accounts.libroreserve.com/restricted/restaurant/bookings/63873433 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Response:

{
  "data": {
    "id": "63873433",
    "type": "bookings",
    "attributes": {
      "status": "confirmed",
      "date": "2023-01-01T12:00:00Z",
      "party_size": 4
      ...
    }
  }
}

Your application can now access Libro’s API by including the access token in the Authorization header of your requests

Step 5: Handle Token Expiration

Request:

curl https://accounts.libroreserve.com/oauth/token \
  -X POST \
  -d "grant_type=refresh_token&
  client_id=CLIENT_ID&
  client_secret=CLIENT_SECRET&
  refresh_token=REFRESH_TOKEN"

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 7200
}

Access tokens expire after a period (typically 2 hours). Your application should handle token expiration and renewal:

  1. Store the expires_in value when receiving a token
  2. Implement a token refresh mechanism before expiration
  3. If you receive a 401 Unauthorized error, request a new token

Token Endpoint

Make a POST request to Libro’s token endpoint with the refresh token to obtain a new access token.

Error Handling

Ensure your application gracefully handles errors such as invalid or expired refresh tokens by prompting the user to reauthorize if necessary.

By adding these details, the guide provides a comprehensive approach to handling token refresh, ensuring continuous and secure access to Libro’s API.

Restaurants

The Restaurants API allows you to access restaurant profiles, manage availability, and retrieve detailed information about dining establishments in the Libro network.

ENDPOINTS

GET /restricted/restaurants
GET /restricted/restaurants/:id
GET /restricted/restaurants/:id/seatings

The Restaurant Object

THE RESTAURANT OBJECT

{
  "type": "restaurant",
  "id": "0000000000",
  "attributes": {
    "name": "Example Restaurant",
    "active": true,
    "code": "ZZ000000000000",
    "latitude": 45.5001,
    "longitude": -73.5665,
    "tz": "America/Montreal",
    "created-at": "2024-01-01T12:00:00.0-04:00",
    "online-booking-lead-months": 6,
    "cancelation-delay": 86400,
    "service-scopes": [
      {
          "name": "Diner",
          "startTime": "10:00",
          "endTime": "15:00"
      },
      {
          "name": "Souper",
          "startTime": "15:00",
          "endTime": "03:00"
      }
    ]
  }
}

Attributes

Get Restaurant

This endpoint retrieves a specific restaurant by its code.

Query Parameters

GET /restricted/restaurants?restaurant-code=QC01621448XXXX

REQUEST:

curl "https://api.libroreserve.com/restricted/restaurants?restaurant-code=QC016214487921" \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.libro-restricted-v2+json" \
  -H "Authorization: Bearer ACCESS_TOKEN"

RESPONSE:

{
  "data": [
    {
      "id": "0000000000",
      "type": "restaurant",
      "attributes": { /* restaurant attributes */ }
    }
  ]
}

List Restaurants

GET /restricted/restaurants

REQUEST:

curl "https://api.libroreserve.com/restricted/restaurants" \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.libro-restricted-v2+json" \
  -H "Authorization: Bearer ACCESS_TOKEN"

RESPONSE:

{
  "data": [
    {
      "id": "0000000000",
      "type": "restaurant",
      "attributes": { /* restaurant attributes */ }
    },
    {
      "id": "0000000001",
      "type": "restaurant",
      "attributes": { /* restaurant attributes */ }
    }
  ]
}

This endpoint retrieves all restaurants available to your connected account.

See Pagination for more details.

Get Restaurant Availability

GET /restricted/restaurants/seatings

REQUEST:

curl "https://api.libroreserve.com/restricted/restaurants/seatings?restaurant-code=QC01621448XXXX&date=2026-07-09&size=2" \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.libro-restricted-v2+json" \
  -H "Authorization: Bearer ACCESS_TOKEN"

RESPONSE:

# Response with experiences:
{
  "2026-07-09": {
    "2026-07-09T11:00:00": [
      {
        "id": 5211,
        "name": {
            "en": "Dinning Room",
            "fr": "Salle à manger"
        }
      }
    ],
    "2026-07-09T11:15:00": [
      {
        "id": 5211,
        "name": {
          "en": "Dinning Room",
          "fr": "Salle à manger"
        }
      }
    ]
  }
}

# Response without experiences:
{
  "2026-07-09": {
    "2026-07-09T11:00:00": true,
    "2026-07-09T11:15:00": true,
  }
}

This endpoint retrieves restaurant availabilities.

Query Parameters

Bookings

ENDPOINTS

GET /restricted/restaurant/bookings/:id
GET /restricted/restaurant/bookings
POST /restricted/restaurant/bookings
PATCH /restricted/restaurant/bookings/:id
PUT /restricted/restaurant/bookings/:id
DELETE /restricted/restaurant/bookings/:id

The Bookings API allows you to create, retrieve, and manage reservations.

The Booking Object

THE BOOKING OBJECT

{
  "type": "booking",
  "id": "0000000000",
  "attributes": {
    "size": 2,
    "status": "approved",
    "time": "2025-07-09T17:00:00.000-04:00",
    "note": "We would like to have a table near the window",
    "table-number": null,
    "private-note": null,
    "expected-leave-at": "2025-07-09T18:30:00.000-04:00",
    "source": "google",
    "read-token": "17ca6f639",
    "edit-token": "17ca6f604",
    "booking-type": "reservation",
    "locale": "en",
    "created-at": "2025-07-08T22:54:26.708-04:00",
    "arrived-at": null,
    "confirmed-at": null,
    "seated-at": null,
    "completed-at": null,
    "canceled-at": null,
    "flags": {
        "children": false,
        "reduced-mobility": false,
        "do-not-move": false
    },
    "invoice": null,
    "affiliate": null,
    "cancelation-allowed-until": null
  }
}

Booking Attributes

Booking Relationships

Booking object will be returned with the following relationships:

Get Booking

GET /restricted/restaurant/bookings/:id

REQUEST:

curl "https://api.libroreserve.com/restricted/restaurant/bookings/63873441" \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.libro-restricted-v2+json" \
  -H "Authorization: Bearer ACCESS_TOKEN"

RESPONSE:

{
  "data": {
    "id": "63873433",
    "type": "booking",
    "attributes": {
      "size": 2,
      "status": "seated",
      "time": "2025-04-30T10:45:00.000-04:00",
      "note": "",
      "table-number": null,
      "note": "Birthday party",
      "private-note": "",
      "expected-leave-at": "2025-04-30T12:15:00.000-04:00",
      "source": "dashboard",
      "read-token": "17cb72002",
      "edit-token": "17cb72018",
      "booking-type": "reservation",
      "locale": null,
      "created-at": "2025-04-30T10:51:01.730-04:00",
      "arrived-at": "2025-04-30T10:51:01.729-04:00",
      "confirmed-at": null,
      "seated-at": null,
      "completed-at": null,
      "canceled-at": "2025-05-06T17:32:19.190-04:00"
    },
    "relationships": {
      "person": {
        "data": {
          "id": "XXXXXXXXX",
          "type": "person"
        }
      },
      "restaurant": {
        "data": {
          "id": "XXXX",
          "type": "restaurant"
        }
      },
      "recommendation": {
        "data": {
          "id": "XXXXXXXXX",
          "type": "recommendation"
        }
      },
      "experience": {
        "data": {
          "id": "XXXXXXXXX",
          "type": "experience"
        }
      }
    }
  },
  "included": []
}

This endpoint retrieves a specific booking by its ID.

Path Parameters

List Bookings

GET /restricted/restaurant/bookings

REQUEST:

curl "https://api.libroreserve.com/restricted/restaurant/bookings" \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.libro-restricted-v2+json" \
  -H "Authorization: Bearer ACCESS_TOKEN"

RESPONSE:

{
  "data": [
    {
      "id": "0000000000",
      "type": "booking",
      "attributes": { /* booking attributes */ },
      "relationships": { /* booking relationships */ }
    },
    {
      "id": "0000000001",
      "type": "booking",
      "attributes": { /* booking attributes */ },
      "relationships": { /* booking relationships */ }
    }
  ]
}

This endpoint retrieves a list of bookings for the restaurant.

Query Parameters

Examples

GET https://api.libroreserve.com/restricted/restaurant/bookings?date=2025-05-30

GET https://api.libroreserve.com/restricted/restaurant/bookings?date=2025-05-30&time=13:00

GET https://api.libroreserve.com/restricted/restaurant/bookings?guest-phone=15141111111

See Pagination for more details.

Create Booking

POST /restricted/restaurant/bookings

REQUEST:

 curl "https://api.libroreserve.com/restricted/restaurant/bookings" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.libro-restricted-v2+json" \
  -H "Authorization: Bearer ACCESS_TOKEN"

REQUEST BODY WITH PERSON DATA:


{
  "restaurant-code": "0000000000",
  "data": {
    "attributes": {
      "size": 2,
      "date": "2025-05-07",
      "time": "12:00",
      "note": "Birthday party",
      "locale": "en",
      "table-number": "12"
    },
    "relationships": {
      "person": {
        "data": {
          "type": "people",
          "attributes": {
            "first_name": "John",
            "last_name": "Doe",
            "email": "john@doe.com",
            "phone": "5141111111",
            "preferred-communication-channel": "email",
            "locale": "en"
          }
        }
      }
    }
  },
  "device-infos": {
    "id": "XXXXXXXXXXX",
    "ip": "192.168.1.1"
  }
}

REQUEST BODY WITH PERSON ID:


{
  "restaurant-code": "0000000000",
  "data": {
    "attributes": {
      "size": 2,
      "date": "2025-05-07",
      "time": "12:00",
      "note": "Birthday party",
      "locale": "en",
      "table-number": "12"
    },
    "relationships": {
      "person": {
        "data": {
          "type": "people",
          "id": 1234567890
        }
      }
    }
  },
  "device-infos": {
    "id": "XXXXXXXXXXX",
    "ip": "192.168.1.1"
  }
}

RESPONSE:

{
  "data": {
    "id": "0000000000",
    "type": "booking",
    "attributes": {
      "size": 2,
      "status": "approved",
      "time": "2025-05-07T12:00:00.000-04:00",
      "table-number": "3",
      "note": "Birthday party",
      "private-note": null,
      "expected-leave-at": "2025-05-07T13:30:00.000-04:00",
      "source": "widget",
      "read-token": "17cb72339",
      "edit-token": "17cb722f3",
      "booking-type": "reservation",
      "locale": "en",
      "created-at": "2025-05-06T17:13:14.250-04:00",
      "arrived-at": null,
      "confirmed-at": null,
      "seated-at": null,
      "completed-at": null,
      "canceled-at": null
    },
    "relationships": { /* booking relationships */ }
  },
  "included": []
}

This endpoint allows you to create a new booking.

Body Parameters

Body Attributes

Relationship Person

Person Attributes

Device Infos

Update Booking

PATCH /restricted/restaurant/bookings/:id

REQUEST:

curl "https://api.libroreserve.com/restricted/restaurant/bookings/63873441" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.libro-restricted-v2+json" \
  -H "Authorization: Bearer ACCESS_TOKEN"

REQUEST BODY:

{
  "restaurant-code": "0000000000",
  "data": {
    "attributes": {
      "note": "We would like to have a table near the window",
      "locale": "en"
    }
  }
}

RESPONSE:

{
  "data": {
    "id": "63873441",
    "type": "booking",
    "attributes": { /* booking attributes */ },
    "relationships": { /* booking relationships */ }
  },
  "included": []
}

This endpoint allows you to update some attributes of a booking.

Parameters

Body Attributes

Cancel Booking

DELETE /restricted/restaurant/bookings/:id

REQUEST:

curl "https://api.libroreserve.com/restricted/restaurant/bookings/63873441" \
  -X DELETE \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.libro-restricted-v2+json" \
  -H "Authorization: Bearer ACCESS_TOKEN"

RESPONSE:

{
  "data": {
    "id": "63873441",
    "type": "booking",
    "attributes": { /* booking attributes */ },
    "relationships": { /* booking relationships */ }
  },
  "included": []
}

This endpoint allows you to cancel a booking.

Query Parameters

Example

DELETE /restricted/restaurant/bookings/63873441?restaurant-code=0000000000

Errors

Reschedule Booking

PUT /restricted/restaurant/bookings/:id/reschedule

REQUEST:

curl "https://api.libroreserve.com/restricted/restaurant/bookings/63873441/reschedule" \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.libro-restricted-v2+json" \
  -H "Authorization: Bearer ACCESS_TOKEN"

REQUEST BODY:

{
  "restaurant-code": "0000000000",
  "data": {
    "attributes": {
      "date": "2025-05-07",
      "time": "17:00",
      "booking-experience-id": 123,
      "size": 2
    }
  }
}

RESPONSE:

{
  "data": {
    "id": "63873441",
    "type": "booking",
    "attributes": { /* booking attributes */ },
    "relationships": { /* booking relationships */ }
  },
  "included": []
}

This endpoint allows you to reschedule a booking. It will be used to increase/descrease booking size, change date and time or change booking experience.

Body Parameters

Body Attributes

Examples

PUT https://api.libroreserve.com/restricted/restaurant/bookings/63873441/reschedule?restaurant-code=0000000000&date=2025-05-07&time=17:00&size=4

PUT https://api.libroreserve.com/restricted/restaurant/bookings/63873441/reschedule?restaurant-code=0000000000&date=2025-05-07&time=17:00

Person

ENDPOINTS

GET /restricted/people/:id
PATCH /restricted/people/:id

The People API allows you to retrieve and update people data.

The Person Object

THE PERSON OBJECT

{
  "id": "18476003",
  "type": "person",
  "attributes": {
    "first-name": "Johnny",
    "last-name": "Doe",
    "email": "john@gmail.com",
    "phone": "225-951-4433",
    "note": "Lorem Ipsum",
    "tags": ["vvip", "vegan"]
  }
}

Person

Person Attributes

Get Person

GET /restricted/people/:id

REQUEST:

curl "https://api.libroreserve.com/restricted/people/18476003" \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.libro-restricted-v2+json" \
  -H "Authorization: Bearer ACCESS_TOKEN"

RESPONSE:

{
  "data": {
    "id": "18476003",
    "type": "person",
    "attributes": {
      "first-name": "Johnny",
      "last-name": "Doe",
      "email": "john@gmail.com",
      "phone": "225-951-4433",
      "note": "Lorem Ipsum",
      "tags": ["vvip", "vegan"]
    }
  }
}

This endpoint allows you to retrieve a person's details.

Path Parameters

Update Person

PATCH /restricted/people/:id

REQUEST:

curl "https://api.libroreserve.com/restricted/people/18476003" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.libro-restricted-v2+json" \
  -H "Authorization: Bearer ACCESS_TOKEN"

REQUEST BODY:

{
  "data": {
    "attributes": {
      "first-name": "Johnny",
      "last-name": "Doe",
      "email": "john@gmail.com",
      "phone": "225-951-4433",
      "note": "Lorem Ipsum",
      "tags": ["vvip", "vegan"]
    }
  }
}

RESPONSE:

{
  "data": {
    "id": "18476003",
    "type": "person",
    "attributes": {
      "first-name": "Johnny",
      "last-name": "Doe",
      "email": "john@gmail.com",
      "phone": "225-951-4433",
      "note": "Lorem Ipsum",
      "tags": ["vvip", "vegan"]
    }
  }
}

This endpoint allows you to update a person's details.

Path Parameters

Body Parameters

Reviews

ENDPOINTS

GET /restricted/restaurant/reviews

The Reviews API allows you to retrieve reviews.

The Review Object

THE REVIEW OBJECT

{
  "id": "1234567890",
  "type": "review",
  "attributes": {
      "rating": 5.0,
      "ambiance-rating": 4.0,
      "food-rating": 5.0,
      "service-rating": 5.0,
      "menu-rating": null,
      "presentation-rating": null,
      "custom-question-1": null,
      "custom-question-2": null,
      "description": "Perfect!",
      "reply": "Glad you enjoyed your meal!",
      "source": "libro",
      "created-at": "2024-07-08T10:40:31.660-04:00",
      "updated-at": "2024-07-12T11:50:21.615-04:00"
  }
}

Review Attributes

Review Relationships

Review object will be returned with the following relationships:

List Reviews

GET /restricted/restaurant/reviews

REQUEST:

curl "https://api.libroreserve.com/restricted/restaurant/reviews?restaurant-code=QCXXXXXXXXXX" \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.libro-restricted-v2+json" \
  -H "Authorization: Bearer ACCESS_TOKEN"

RESPONSE:

{
    "data": [
        {
            "id": "1234567890",
            "type": "review",
            "attributes": { /* review attributes */ },
            "relationships": { /* review relationships */ }
        },
        {
            "id": "1234567891",
            "type": "review",
            "attributes": { /* review attributes */ },
            "relationships": { /* review relationships */ }
        },
        {
            "id": "1234567892",
            "type": "review",
            "attributes": { /* review attributes */ },
            "relationships": { /* review relationships */ }
        }
    ],
    "included": []
}

This endpoint allows you to retrieve a list of reviews for a specific restaurant.

Query Parameters

See Pagination for more details.

Pagination

Every resource LIST endpoint returns a paginated list of records, and can use the pagination mechanics.

Retrieve the first 20 bookings:

GET restricted/restaurant/bookings?limit=20&offset=0

Retrieve the next 20 bookings:

GET restricted/restaurant/bookings?limit=20&offset=20

Retrieve 50 bookings per page:

GET restricted/restaurant/bookings?limit=50&offset=0

Query Parameters

To paginate through the payload, use the limit and offset parameters. The limit parameter controls the number of records returned in a single request, with a maximum value of 250. The offset parameter specifies the starting point for the query in terms of database records.

Common Errors

The Libro API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- The token is missing or invalid.
402 Unauthorized -- Your subscription plan does not allow API access, please contact success@libroreserve.com to subscribe the Premium Plan
403 Forbidden -- The token has expired or is invalid.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- The token does not allow access to this endpoint.
406 Not Acceptable -- You requested a format that isn't json.
409 Conflict -- The request could not be completed due to a conflict with the current state of the resource.
422 Unprocessable Entity -- The request could not be completed due to a validation error.
429 Too Many Requests -- You're requesting too many resources!
500 Internal Server Error -- We had a problem with our server. Try again later.
cURL