# 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**](https://mobile-calendar.gitbook.io/v1/overview/authentication).

## 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**](https://mobile-calendar.gitbook.io/v1/webhooks/introduction).

### 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://mobile-calendar.gitbook.io/v1/overview/introduction.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.