> For the complete documentation index, see [llms.txt](https://mobile-calendar.gitbook.io/v1/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mobile-calendar.gitbook.io/v1/overview/introduction.md).

# Introduction

## Overview

The **Mobile Calendar API** provides a modern, REST-based interface for integrating external systems such as **channel managers**, **property management systems (PMS)**, **pricing tools**, and **custom applications**.\
It allows developers to **synchronize reservations, availability, pricing, clients, and room data and others** between Mobile Calendar and external platforms.

The API supports both **data retrieval and data submission** — enabling two-way communication for building deep integrations.

Common use cases include:

* Importing or exporting reservations from connected systems
* Managing room availability and restrictions
* Synchronizing pricing rules and occupancy
* Building custom dashboards or automation tools
* Receiving real-time updates through webhooks

## Standards and Architecture

The API follows **RESTful design principles**, using standard HTTP methods and status codes.\
All requests and responses use **JSON** format encoded in **UTF-8**.

* **Base URL:** `https://api.mobile-calendar.com/v1/public`
* **Content-Type:** `application/json`
* **Versioning:** Managed via the URL path (e.g., `/v1/`)
* **Rate Limiting:** 60 requests per minute per user
* **Error handling**: compliant with **RFC 7807** (`application/problem+json`)

## Authentication and Security

Authentication uses **JWT (JSON Web Token)** in the `Authorization` header.

```
Authorization: Bearer {access_token}
```

Tokens are obtained through the `/auth/login` endpoint by providing valid credentials.\
All communication must occur over **HTTPS**. Unencrypted HTTP requests are rejected.

You can read more here: [**Authentiction**](/v1/overview/authentication.md).

## HTTP Status Codes

| Code    | Meaning               | Description                              |
| ------- | --------------------- | ---------------------------------------- |
| **200** | OK                    | Successful request                       |
| **201** | Created               | Resource successfully created            |
| **204** | No Content            | Request successful, no response body     |
| **300** | Multiple Choices      | Resource has multiple representations    |
| **401** | Unauthorized          | Invalid or missing authentication        |
| **403** | Forbidden             | Access denied for the resource           |
| **404** | Not Found             | Resource not found                       |
| **409** | Conflict              | Resource already exists or invalid state |
| **422** | Unprocessable Entity  | Validation error in request body         |
| **429** | Too Many Requests     | Rate limit exceeded                      |
| **500** | Internal Server Error | Unexpected server error                  |
| **503** | Service Unavailable   | API temporarily unavailable              |
| **504** | Gateway Timeout       | API did not respond in time              |

## Response Formats

The API primarily returns **JSON** responses.

### Example Success Response (200)

{% code title="Success (200) example.json" %}

```json
{
  "data": {
    "reservationId": 12345,
    "roomId": 30268,
    "arrival": "2025-10-14",
    "departure": "2025-10-16"
    ...
  },
  "meta": {
    "ruid": "7f80f1b4-a44b-4345-b383-7d0a937b4411"
  }
}
```

{% endcode %}

### Example Error Response (`application/problem+json`)

{% code title="Error (422) example.json" %}

```json
{
  "type": "https://api.mobile-calendar.com...",
  "title": "Invalid request data",
  "status": 422,
  "detail": "The 'arrival' date cannot be in the past.",
  "instance": "/v1/reservations",
  "ruid": "7f80f1b4-a44b-4345-b383-7d0a937b4411"
}
```

{% endcode %}

## API Versioning and Rate Limits

The current API version is **v1**.\
Each major release introduces breaking changes and will be announced in advance.

**Rate limits:**

* 60 requests per minute per authenticated user
* Exceeding limits returns **429 Too Many Requests**
* Response headers include rate limit details:
  * `X-RateLimit-Limit`
  * `X-RateLimit-Remaining`
  * `X-RateLimit-Reset`

## Additional Concepts

### RUID (Request Unique ID)

Every response includes a `ruid` value for tracing requests through logs and support tools.

### Webhooks

The API supports **webhooks** for real-time data synchronization.\
You can register endpoints to receive updates when reservations, availability, or prices change.

Example Webhook events:

* `reservation.created`
* `reservation.updated`
* `reservation.cancelled`
* `availability.updated`    

You can read more here: [**Webhooks**](/v1/webhooks/introduction.md).

### Pagination

Endpoints returning lists use pagination parameters:

```
?page=1&limit=50
```

Metadata such as total items and next/previous links are included in responses.

## Getting Started

{% stepper %}
{% step %}

### Request API access

Request API access via your Mobile Calendar account.
{% endstep %}

{% step %}

### Generate your API credentials

Generate your API credentials and obtain your JWT token using `/auth/login`.
{% endstep %}

{% step %}

### Make your first request

Example:

{% code title="curl example" %}

```bash
curl -X GET https://api.mobile-calendar.com/v1/reservations \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json"
```

{% endcode %}
{% endstep %}

{% step %}

### Handle rate limits and errors

Handle rate limits (429) and other errors gracefully in your integration.
{% endstep %}

{% step %}

### Subscribe to webhooks (optional)

Subscribe to webhooks for automatic data updates.
{% endstep %}

{% step %}

### Explore the OpenAPI documentation

Explore the full OpenAPI documentation to understand all available endpoints and data models.
{% endstep %}
{% endstepper %}

## Support and Best Practices

* Always use HTTPS and short-lived tokens.
* Respect rate limits to ensure stable API access.
* Include your integration name and version in the `User-Agent` header.
* Log all requests and `ruid` values for troubleshooting.
* Contact support for partnership integrations or higher rate limits.