# Civitatis API

> Every Civitatis endpoint on Cotlet: inputs, JSON Schema, cURL, Python and Node.js examples and an example response for each call.

Source: https://cotlet.dev/docs/api/civitatis

Docs sections: [Get started](https://cotlet.dev/docs.md) · [REST API](https://cotlet.dev/docs/api.md) · [MCP](https://cotlet.dev/docs/mcp.md) · [SDKs & CLI](https://cotlet.dev/docs/sdks.md) · [Integrations](https://cotlet.dev/docs/integrations.md)

13 endpoints for Civitatis. Each one is a POST with a JSON body, called with your API key.

- Base URL: `https://cotlet.dev/api/v1/civitatis`
- Connects with: Your Civitatis provider panel account (username and password)
- Integration page: https://cotlet.dev/integrations/civitatis-api-mcp-server

## Endpoints

| Endpoint | Access | Description |
|---|---|---|
| `list_activities` | read | Your activities on Civitatis with destination and status. |
| `list_bookings` | read | Bookings by activity date, with activity, time, number of people and status. |
| `get_booking` | read | One booking: reference, activity, date and time, people, price and lead traveler contact. |
| `get_availability` | read | Calendar of an activity: open and closed dates and the quota per day and time. |
| `list_messages` | read | Messages with customers and the Civitatis booking department, newest first. |
| `list_reviews` | read | Customer reviews of your activities with rating, text and date. |
| `list_invoices` | read | Commission invoices from Civitatis with period, amount and a download link. |
| `list_payments` | read | Monthly settlements: services rendered, commission, net amount and payment status. |
| `close_dates` | write | Stop sales of an activity on a date range, all day or for chosen times. |
| `open_dates` | write | Reopen sales of an activity on dates you closed before. |
| `set_quota` | write | Limit the places sold for an activity on given days and times. |
| `send_message` | write | Write to a customer about a booking, or to the Civitatis booking department. |
| `request_payment` | write | Request payment for services rendered in the previous month, net of commission. |

## List activities

`POST https://cotlet.dev/api/v1/civitatis/list_activities`

Access: read.

Returns every activity your provider account sells, with its destination and status. Use activity_id from each item in the other tools.

### Parameters

No parameters.

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/civitatis/list_activities \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("civitatis", "list_activities")
```

**Node.js**

```js
const result = await cotlet.call('civitatis', 'list_activities');
```

**CLI**

```bash
cotlet call civitatis list_activities
```

### Example response

```json
{
  "activities": [
    {
      "activity_id": "act_48213",
      "name": "Bike tour of the old town",
      "destination": "Madrid",
      "status": "active"
    },
    {
      "activity_id": "act_51907",
      "name": "Sunset cruise",
      "destination": "Madrid",
      "status": "active"
    }
  ]
}
```

## List bookings

`POST https://cotlet.dev/api/v1/civitatis/list_bookings`

Access: read.

Lists bookings by activity date, in start time order, with the activity, time, number of people and status. By default it returns confirmed bookings for the next 7 days. Pass next_cursor back as cursor for the next page. Use booking_id with get_booking for the price and contact.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `from` | date | no | First activity date. Default: today. |
| `to` | date | no | Last activity date. Default: 7 days from today. |
| `activity_id` | string | no | Only bookings for this activity. |
| `status` | enum | no | confirmed, cancelled or all. Default: confirmed. |
| `cursor` | string | no | Next page cursor from the previous call. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/civitatis/list_bookings \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"2026-10-14","to":"2026-10-14","activity_id":"act_48213","status":"confirmed"}'
```

**Python**

```python
result = client.call("civitatis", "list_bookings", {"from":"2026-10-14","to":"2026-10-14","activity_id":"act_48213","status":"confirmed"})
```

**Node.js**

```js
const result = await cotlet.call('civitatis', 'list_bookings', {"from":"2026-10-14","to":"2026-10-14","activity_id":"act_48213","status":"confirmed"});
```

**CLI**

```bash
cotlet call civitatis list_bookings --data '{"from":"2026-10-14","to":"2026-10-14","activity_id":"act_48213","status":"confirmed"}'
```

### Example response

```json
{
  "bookings": [
    {
      "booking_id": "bk_702154",
      "activity_id": "act_48213",
      "activity": "Bike tour of the old town",
      "date": "2026-10-12",
      "time": "10:00",
      "people": 3,
      "status": "confirmed"
    },
    {
      "booking_id": "bk_702160",
      "activity_id": "act_48213",
      "activity": "Bike tour of the old town",
      "date": "2026-10-12",
      "time": "10:00",
      "people": 2,
      "status": "confirmed"
    }
  ],
  "next_cursor": null
}
```

## Get booking

`POST https://cotlet.dev/api/v1/civitatis/get_booking`

Access: read.

Returns one booking with its reference, activity, date and time, number of people, price and the lead traveler contact as shown in the provider panel. Personal data is returned as the panel shows it and is not stored by Cotlet.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `booking_id` | string | yes | Booking ID from list_bookings. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/civitatis/get_booking \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"booking_id":"booking_8c41d2"}'
```

**Python**

```python
result = client.call("civitatis", "get_booking", {"booking_id":"booking_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('civitatis', 'get_booking', {"booking_id":"booking_8c41d2"});
```

**CLI**

```bash
cotlet call civitatis get_booking --data '{"booking_id":"booking_8c41d2"}'
```

### Example response

```json
{
  "booking_id": "bk_702154",
  "reference": "CIV-702154",
  "activity": "Bike tour of the old town",
  "date": "2026-10-12",
  "time": "10:00",
  "people": 3,
  "price": {
    "amount": 87,
    "currency": "EUR"
  },
  "status": "confirmed",
  "lead_traveler": {
    "name": "Sample Traveler",
    "email": "traveler@example.com",
    "phone": "+34 600 000 000"
  }
}
```

## Get availability

`POST https://cotlet.dev/api/v1/civitatis/get_availability`

Access: read.

Returns the calendar of one activity for a date range: whether each date is open or closed, and the quota for each start time. Use it before and after close_dates or set_quota to check the result. The default range is the next 30 days.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `activity_id` | string | yes | Activity ID from list_activities. |
| `from` | date | no | First date. Default: today. |
| `to` | date | no | Last date. Default: 30 days from today. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/civitatis/get_availability \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"activity_id":"activity_8c41d2"}'
```

**Python**

```python
result = client.call("civitatis", "get_availability", {"activity_id":"activity_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('civitatis', 'get_availability', {"activity_id":"activity_8c41d2"});
```

**CLI**

```bash
cotlet call civitatis get_availability --data '{"activity_id":"activity_8c41d2"}'
```

### Example response

```json
{
  "activity_id": "act_51907",
  "days": [
    {
      "date": "2026-11-07",
      "status": "open",
      "slots": [
        {
          "time": "18:00",
          "quota": 12
        }
      ]
    },
    {
      "date": "2026-11-08",
      "status": "open",
      "slots": [
        {
          "time": "18:00",
          "quota": 20
        }
      ]
    },
    {
      "date": "2026-11-09",
      "status": "closed",
      "slots": []
    }
  ]
}
```

## List messages

`POST https://cotlet.dev/api/v1/civitatis/list_messages`

Access: read.

Lists message threads with customers and with the Civitatis booking department, newest first, with the booking each one is about and the last message. Set unread_only to see only what needs an answer.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `unread_only` | boolean | no | Only unread threads. Default: false. |
| `booking_id` | string | no | Only messages about this booking. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/civitatis/list_messages \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("civitatis", "list_messages")
```

**Node.js**

```js
const result = await cotlet.call('civitatis', 'list_messages');
```

**CLI**

```bash
cotlet call civitatis list_messages
```

### Example response

```json
{
  "threads": [
    {
      "booking_id": "bk_702154",
      "with": "customer",
      "unread": true,
      "last_message": "Where do we meet, and does the tour run in the rain?",
      "received_at": "2026-10-11T08:12:00+02:00"
    }
  ]
}
```

## List reviews

`POST https://cotlet.dev/api/v1/civitatis/list_reviews`

Access: read.

Returns customer reviews of your activities with the rating, text and date, as the provider panel shows them. Filter by activity or by start date. Reviews are read only: Cotlet has no tool to answer or report them.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `activity_id` | string | no | Only reviews of this activity. |
| `since` | date | no | Only reviews on or after this date. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/civitatis/list_reviews \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("civitatis", "list_reviews")
```

**Node.js**

```js
const result = await cotlet.call('civitatis', 'list_reviews');
```

**CLI**

```bash
cotlet call civitatis list_reviews
```

### Example response

```json
{
  "reviews": [
    {
      "activity_id": "act_48213",
      "rating": 5,
      "text": "Great guide, easy route.",
      "date": "2026-09-21"
    },
    {
      "activity_id": "act_48213",
      "rating": 3,
      "text": "Meeting point was hard to find.",
      "date": "2026-09-14"
    }
  ]
}
```

## List invoices

`POST https://cotlet.dev/api/v1/civitatis/list_invoices`

Access: read.

Lists the invoices Civitatis issues to you, which are commission invoices, with the period, amount and a download link. The default is the current year.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `year` | integer | no | Invoice year. Default: current year. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/civitatis/list_invoices \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("civitatis", "list_invoices")
```

**Node.js**

```js
const result = await cotlet.call('civitatis', 'list_invoices');
```

**CLI**

```bash
cotlet call civitatis list_invoices
```

### Example response

```json
{
  "invoices": [
    {
      "invoice_id": "inv_2026_09",
      "period": "2026-09",
      "amount": {
        "value": 620,
        "currency": "EUR"
      },
      "download_url": "https://www.civitatis.com/example/invoice/inv_2026_09.pdf"
    }
  ]
}
```

## List payments

`POST https://cotlet.dev/api/v1/civitatis/list_payments`

Access: read.

Lists monthly settlements with the services rendered, the Civitatis commission, the net amount and the payment status. Use it before request_payment to see which months are still open. The default is the current year.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `year` | integer | no | Settlement year. Default: current year. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/civitatis/list_payments \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("civitatis", "list_payments")
```

**Node.js**

```js
const result = await cotlet.call('civitatis', 'list_payments');
```

**CLI**

```bash
cotlet call civitatis list_payments
```

### Example response

```json
{
  "payments": [
    {
      "month": "2026-09",
      "services": {
        "value": 3100,
        "currency": "EUR"
      },
      "commission": {
        "value": 620,
        "currency": "EUR"
      },
      "net": {
        "value": 2480,
        "currency": "EUR"
      },
      "status": "not_requested"
    },
    {
      "month": "2026-08",
      "services": {
        "value": 2750,
        "currency": "EUR"
      },
      "commission": {
        "value": 550,
        "currency": "EUR"
      },
      "net": {
        "value": 2200,
        "currency": "EUR"
      },
      "status": "paid"
    }
  ]
}
```

## Close dates

`POST https://cotlet.dev/api/v1/civitatis/close_dates`

Access: write.

Closes an activity for a date range, for all start times or only the ones you list. It stops new sales only; bookings already made stay, and bookings_on_closed_slots tells you how many. close_dates runs without asking first: it messages no one and open_dates undoes it in one call.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `activity_id` | string | yes | Activity ID from list_activities. |
| `from` | date | yes | First date to close. |
| `to` | date | yes | Last date to close. |
| `times` | string[] | no | Start times to close, e.g. ["10:00"]. Default: all times. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/civitatis/close_dates \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"activity_id":"act_48213","from":"2026-10-20","to":"2026-10-22","times":["10:00","16:00"]}'
```

**Python**

```python
result = client.call("civitatis", "close_dates", {"activity_id":"act_48213","from":"2026-10-20","to":"2026-10-22","times":["10:00","16:00"]})
```

**Node.js**

```js
const result = await cotlet.call('civitatis', 'close_dates', {"activity_id":"act_48213","from":"2026-10-20","to":"2026-10-22","times":["10:00","16:00"]});
```

**CLI**

```bash
cotlet call civitatis close_dates --data '{"activity_id":"act_48213","from":"2026-10-20","to":"2026-10-22","times":["10:00","16:00"]}'
```

### Example response

```json
{
  "activity_id": "act_48213",
  "activity": "Bike tour of the old town",
  "closed": [
    {
      "date": "2026-10-20",
      "times": [
        "10:00",
        "16:00"
      ]
    },
    {
      "date": "2026-10-21",
      "times": [
        "10:00",
        "16:00"
      ]
    },
    {
      "date": "2026-10-22",
      "times": [
        "10:00",
        "16:00"
      ]
    }
  ],
  "bookings_on_closed_slots": 0
}
```

## Open dates

`POST https://cotlet.dev/api/v1/civitatis/open_dates`

Access: write.

Reopens an activity on dates you closed before, for all start times or only the ones you list. open_dates runs without asking first: it messages no one and close_dates undoes it in one call.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `activity_id` | string | yes | Activity ID from list_activities. |
| `from` | date | yes | First date to open. |
| `to` | date | yes | Last date to open. |
| `times` | string[] | no | Start times to open. Default: all times. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/civitatis/open_dates \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"activity_id":"activity_8c41d2","from":"2026-10-01","to":"2026-10-01"}'
```

**Python**

```python
result = client.call("civitatis", "open_dates", {"activity_id":"activity_8c41d2","from":"2026-10-01","to":"2026-10-01"})
```

**Node.js**

```js
const result = await cotlet.call('civitatis', 'open_dates', {"activity_id":"activity_8c41d2","from":"2026-10-01","to":"2026-10-01"});
```

**CLI**

```bash
cotlet call civitatis open_dates --data '{"activity_id":"activity_8c41d2","from":"2026-10-01","to":"2026-10-01"}'
```

### Example response

```json
{
  "activity_id": "act_48213",
  "activity": "Bike tour of the old town",
  "opened": [
    {
      "date": "2026-10-22",
      "times": [
        "10:00",
        "16:00"
      ]
    }
  ]
}
```

## Set quota

`POST https://cotlet.dev/api/v1/civitatis/set_quota`

Access: write.

Sets the maximum number of places sold per slot for a date range, optionally only on some weekdays and start times. places counts per slot, not per day. set_quota runs without asking first: it messages no one and another call restores the old limit.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `activity_id` | string | yes | Activity ID from list_activities. |
| `from` | date | yes | First date. |
| `to` | date | yes | Last date. |
| `places` | integer | yes | Maximum places per slot. |
| `weekdays` | string[] | no | Only these days, e.g. ["sat", "sun"]. Default: every day. |
| `times` | string[] | no | Only these start times. Default: all times. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/civitatis/set_quota \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"activity_id":"activity_8c41d2","from":"2026-10-01","to":"2026-10-01","places":1}'
```

**Python**

```python
result = client.call("civitatis", "set_quota", {"activity_id":"activity_8c41d2","from":"2026-10-01","to":"2026-10-01","places":1})
```

**Node.js**

```js
const result = await cotlet.call('civitatis', 'set_quota', {"activity_id":"activity_8c41d2","from":"2026-10-01","to":"2026-10-01","places":1});
```

**CLI**

```bash
cotlet call civitatis set_quota --data '{"activity_id":"activity_8c41d2","from":"2026-10-01","to":"2026-10-01","places":1}'
```

### Example response

```json
{
  "activity_id": "act_51907",
  "activity": "Sunset cruise",
  "places": 12,
  "updated": [
    {
      "date": "2026-11-07",
      "times": [
        "18:00"
      ]
    },
    {
      "date": "2026-11-14",
      "times": [
        "18:00"
      ]
    },
    {
      "date": "2026-11-21",
      "times": [
        "18:00"
      ]
    },
    {
      "date": "2026-11-28",
      "times": [
        "18:00"
      ]
    }
  ]
}
```

## Send message

`POST https://cotlet.dev/api/v1/civitatis/send_message`

Access: write. Confirm: waits for the user's OK before it runs.

Sends a message about one booking, to the customer or to the Civitatis booking department. It appears in the same thread as in the provider panel. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `booking_id` | string | yes | Booking ID from list_bookings. |
| `to` | enum | no | customer or civitatis. Default: customer. |
| `body` | string | yes | Message text. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/civitatis/send_message \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"booking_id":"bk_702154","to":"customer","body":"Hi Sofia, we meet at the fountain in Plaza Mayor at 9:50. Your guide Marta will hold a blue umbrella."}'
```

**Python**

```python
result = client.call("civitatis", "send_message", {"booking_id":"bk_702154","to":"customer","body":"Hi Sofia, we meet at the fountain in Plaza Mayor at 9:50. Your guide Marta will hold a blue umbrella."})
```

**Node.js**

```js
const result = await cotlet.call('civitatis', 'send_message', {"booking_id":"bk_702154","to":"customer","body":"Hi Sofia, we meet at the fountain in Plaza Mayor at 9:50. Your guide Marta will hold a blue umbrella."});
```

**CLI**

```bash
cotlet call civitatis send_message --data '{"booking_id":"bk_702154","to":"customer","body":"Hi Sofia, we meet at the fountain in Plaza Mayor at 9:50. Your guide Marta will hold a blue umbrella."}'
```

### Example response

```json
{
  "booking_id": "bk_702154",
  "to": "customer",
  "status": "sent",
  "sent_at": "2026-10-11T09:05:00+02:00"
}
```

## Request payment

`POST https://cotlet.dev/api/v1/civitatis/request_payment`

Access: write. Confirm: waits for the user's OK before it runs.

Requests payment for the services of one past month, net of the Civitatis commission, the same request you make online in the control panel. Civitatis opens requests from the first day of the following month. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `month` | string | yes | Month to settle, YYYY-MM. Must be a past month. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/civitatis/request_payment \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"month":"2026-09"}'
```

**Python**

```python
result = client.call("civitatis", "request_payment", {"month":"2026-09"})
```

**Node.js**

```js
const result = await cotlet.call('civitatis', 'request_payment', {"month":"2026-09"});
```

**CLI**

```bash
cotlet call civitatis request_payment --data '{"month":"2026-09"}'
```

### Example response

```json
{
  "month": "2026-09",
  "status": "requested",
  "net": {
    "value": 2480,
    "currency": "EUR"
  },
  "requested_at": "2026-10-01T09:00:00+02:00"
}
```