Civitatis API

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

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 -X POST https://cotlet.dev/api/v1/civitatis/list_activities \
  -H "Authorization: Bearer $COTLET_API_KEY"

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

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

cotlet call civitatis list_activities

Example response

{
  "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"
    }
  ]
}

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

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

Request

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"}'

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

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

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

Example response

{
  "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
}

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

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

Request

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"}'

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

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

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

Example response

{
  "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"
  }
}

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

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

Request

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"}'

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

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

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

Example response

{
  "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": []
    }
  ]
}

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

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

Request

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

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

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

cotlet call civitatis list_messages

Example response

{
  "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"
    }
  ]
}

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

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

Request

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

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

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

cotlet call civitatis list_reviews

Example response

{
  "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"
    }
  ]
}

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

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

Request

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

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

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

cotlet call civitatis list_invoices

Example response

{
  "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"
    }
  ]
}

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

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

Request

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

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

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

cotlet call civitatis list_payments

Example response

{
  "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"
    }
  ]
}

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

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

Request

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"]}'

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

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"]});

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

{
  "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
}

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

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

Request

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"}'

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

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

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

Example response

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

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

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

Request

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}'

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

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

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

Example response

{
  "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"
      ]
    }
  ]
}

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

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

Request

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."}'

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."})

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."});

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

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

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

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

Request

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"}'

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

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

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

Example response

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