# Wanderlog API

> Every Wanderlog 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/wanderlog

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)

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

- Base URL: `https://cotlet.dev/api/v1/wanderlog`
- Connects with: Your own Wanderlog account (trips you own or can edit)
- Integration page: https://cotlet.dev/integrations/wanderlog-api-mcp-server

## Endpoints

| Endpoint | Access | Description |
|---|---|---|
| `list_trips` | read | Your trips and trips shared with you, with destination, dates and tripmates. |
| `get_trip` | read | Full itinerary: days, places with times and notes, hotels, reservations, lists and checklists. |
| `search_places` | read | Find attractions, restaurants and hotels near the trip destination, with rating and address. |
| `list_expenses` | read | Trip expenses with amount, currency, category and date, plus totals by category. |
| `get_trip_forwarding_email` | read | The address to forward flight, hotel and car confirmations to for this trip. |
| `create_trip` | write | New trip plan for a destination and date range. Private until you invite someone. |
| `add_place` | write | Add a place to a day of the itinerary or to a list such as "Places to visit". |
| `remove_place` | write | Remove a place from a day or list. |
| `add_hotel` | write | Add lodging with check-in and check-out dates and an optional confirmation number. |
| `add_note` | write | Free-text note on a day or the trip: transit tips, opening hours, booking details. |
| `add_checklist` | write | Checklist for packing, to-dos or shopping, for the whole trip or one day. |
| `add_expense` | write | Log an expense in the currency you paid in, optionally split between tripmates. |
| `optimize_day_route` | write | Reorder the places of one day for a shorter route, as the app's route optimization does. |
| `invite_tripmate` | write | Invite someone by email to collaborate on the trip. |

## List trips

`POST https://cotlet.dev/api/v1/wanderlog/list_trips`

Access: read.

Returns trips you own and trips shared with you, soonest first. Use trip_id from each item in the other tools. Tripmates are listed by name and ID.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `when` | enum | no | upcoming, past or all. Default: upcoming. |
| `limit` | integer | no | 1 to 50. Default: 20. |

### Request

**cURL**

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

**Python**

```python
result = client.call("wanderlog", "list_trips")
```

**Node.js**

```js
const result = await cotlet.call('wanderlog', 'list_trips');
```

**CLI**

```bash
cotlet call wanderlog list_trips
```

### Example response

```json
{
  "trips": [
    {
      "trip_id": "tr_8kQ2mZ",
      "title": "Portugal 2027",
      "destination": "Portugal",
      "start_date": "2027-05-12",
      "end_date": "2027-05-19",
      "tripmates": [
        {
          "tripmate_id": "tm_41a",
          "name": "Maya Novak"
        }
      ],
      "url": "https://wanderlog.com/plan/tr_8kQ2mZ"
    }
  ]
}
```

## Get trip

`POST https://cotlet.dev/api/v1/wanderlog/get_trip`

Access: read.

Returns the itinerary day by day, with places in the order they appear. Each place has a block_id for remove_place. Pass day to return one day only.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Trip ID from list_trips. |
| `day` | date | no | Return only this day. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/wanderlog/get_trip \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trip_id":"trip_8c41d2"}'
```

**Python**

```python
result = client.call("wanderlog", "get_trip", {"trip_id":"trip_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('wanderlog', 'get_trip', {"trip_id":"trip_8c41d2"});
```

**CLI**

```bash
cotlet call wanderlog get_trip --data '{"trip_id":"trip_8c41d2"}'
```

### Example response

```json
{
  "trip_id": "tr_8kQ2mZ",
  "title": "Portugal 2027",
  "days": [
    {
      "date": "2027-05-12",
      "places": [
        {
          "block_id": "blk_1a20",
          "name": "Belem Tower",
          "start_time": "10:00",
          "note": "Buy tickets online"
        },
        {
          "block_id": "blk_1a21",
          "name": "Pasteis de Belem",
          "start_time": "12:30",
          "note": null
        }
      ]
    }
  ],
  "hotels": [],
  "checklists": []
}
```

## Search places

`POST https://cotlet.dev/api/v1/wanderlog/search_places`

Access: read.

Searches near the trip destination and returns up to the limit, best match first, with a place_id for add_place and add_hotel. Nothing is added to the trip.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Trip ID from list_trips. |
| `query` | string | yes | What to find, e.g. "seafood restaurant" or "Belem Tower". |
| `limit` | integer | no | 1 to 20. Default: 10. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/wanderlog/search_places \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trip_id":"trip_8c41d2","query":"seafood restaurant"}'
```

**Python**

```python
result = client.call("wanderlog", "search_places", {"trip_id":"trip_8c41d2","query":"seafood restaurant"})
```

**Node.js**

```js
const result = await cotlet.call('wanderlog', 'search_places', {"trip_id":"trip_8c41d2","query":"seafood restaurant"});
```

**CLI**

```bash
cotlet call wanderlog search_places --data '{"trip_id":"trip_8c41d2","query":"seafood restaurant"}'
```

### Example response

```json
{
  "places": [
    {
      "place_id": "pl_91c0",
      "name": "Time Out Market Lisboa",
      "category": "restaurant",
      "rating": 4.4,
      "address": "Av. 24 de Julho 49, Lisboa"
    }
  ]
}
```

## List expenses

`POST https://cotlet.dev/api/v1/wanderlog/list_expenses`

Access: read.

Returns the expenses logged on the trip, newest first, with the currency each was paid in. Totals by category are in the trip's home currency, as the app shows them.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Trip ID from list_trips. |
| `category` | string | no | Only this category, e.g. food or lodging. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/wanderlog/list_expenses \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trip_id":"trip_8c41d2"}'
```

**Python**

```python
result = client.call("wanderlog", "list_expenses", {"trip_id":"trip_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('wanderlog', 'list_expenses', {"trip_id":"trip_8c41d2"});
```

**CLI**

```bash
cotlet call wanderlog list_expenses --data '{"trip_id":"trip_8c41d2"}'
```

### Example response

```json
{
  "expenses": [
    {
      "expense_id": "ex_72d1",
      "amount": "64.50",
      "currency": "EUR",
      "category": "food",
      "description": "Dinner at Time Out Market",
      "date": "2027-05-13"
    }
  ],
  "totals_by_category": [
    {
      "category": "food",
      "amount": "64.50",
      "currency": "EUR"
    }
  ]
}
```

## Get booking import address

`POST https://cotlet.dev/api/v1/wanderlog/get_trip_forwarding_email`

Access: read.

Returns the address Wanderlog shows for forwarding confirmation emails to this trip. Forward a confirmation from your mail client and Wanderlog fills in dates and times. Cotlet does not read your mailbox.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Trip ID from list_trips. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/wanderlog/get_trip_forwarding_email \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trip_id":"trip_8c41d2"}'
```

**Python**

```python
result = client.call("wanderlog", "get_trip_forwarding_email", {"trip_id":"trip_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('wanderlog', 'get_trip_forwarding_email', {"trip_id":"trip_8c41d2"});
```

**CLI**

```bash
cotlet call wanderlog get_trip_forwarding_email --data '{"trip_id":"trip_8c41d2"}'
```

### Example response

```json
{
  "trip_id": "tr_8kQ2mZ",
  "forwarding_email": "<your trip's forwarding address>"
}
```

## Create trip

`POST https://cotlet.dev/api/v1/wanderlog/create_trip`

Access: write.

Creates a trip with one day per date between start and end. The trip is visible only to you until invite_tripmate. It reaches no one and you can delete it in the app, so it runs without asking.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `destination` | string | yes | City, region or country. |
| `start_date` | date | yes | First day of the trip. |
| `end_date` | date | yes | Last day of the trip. |
| `title` | string | no | Trip name. Default: "Trip to {destination}". |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/wanderlog/create_trip \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"destination":"Lisbon, Portugal","start_date":"2027-05-12","end_date":"2027-05-15","title":"Lisbon long weekend"}'
```

**Python**

```python
result = client.call("wanderlog", "create_trip", {"destination":"Lisbon, Portugal","start_date":"2027-05-12","end_date":"2027-05-15","title":"Lisbon long weekend"})
```

**Node.js**

```js
const result = await cotlet.call('wanderlog', 'create_trip', {"destination":"Lisbon, Portugal","start_date":"2027-05-12","end_date":"2027-05-15","title":"Lisbon long weekend"});
```

**CLI**

```bash
cotlet call wanderlog create_trip --data '{"destination":"Lisbon, Portugal","start_date":"2027-05-12","end_date":"2027-05-15","title":"Lisbon long weekend"}'
```

### Example response

```json
{
  "trip_id": "tr_5nT7pL",
  "title": "Lisbon long weekend",
  "destination": "Lisbon, Portugal",
  "start_date": "2027-05-12",
  "end_date": "2027-05-15",
  "days": 4,
  "url": "https://wanderlog.com/plan/tr_5nT7pL"
}
```

## Add place

`POST https://cotlet.dev/api/v1/wanderlog/add_place`

Access: write.

Adds the place at the end of the day, or of the list when no day is given. On a shared trip, tripmates see it as the app syncs in real time. It runs without asking, because it is undone with remove_place.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Trip ID from list_trips. |
| `place` | string | yes | Place ID from search_places, or a name to look up. |
| `day` | date | no | Day of the trip. Omit to use the trip-level list or notes instead. |
| `list` | string | no | List heading when no day is given. Default: Places to visit. |
| `start_time` | string | no | HH:MM, local time. |
| `note` | string | no | Note shown under the place. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/wanderlog/add_place \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trip_id":"trip_8c41d2","place":"place"}'
```

**Python**

```python
result = client.call("wanderlog", "add_place", {"trip_id":"trip_8c41d2","place":"place"})
```

**Node.js**

```js
const result = await cotlet.call('wanderlog', 'add_place', {"trip_id":"trip_8c41d2","place":"place"});
```

**CLI**

```bash
cotlet call wanderlog add_place --data '{"trip_id":"trip_8c41d2","place":"place"}'
```

### Example response

```json
{
  "block_id": "blk_2c07",
  "trip_id": "tr_8kQ2mZ",
  "name": "Castelo de S. Jorge",
  "day": "2027-05-13",
  "start_time": "10:00"
}
```

## Remove place

`POST https://cotlet.dev/api/v1/wanderlog/remove_place`

Access: write.

Removes one entry from the itinerary. Use block_id from get_trip. It runs without asking, because add_place puts it back.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Trip ID from list_trips. |
| `block_id` | string | yes | Place entry ID from get_trip. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/wanderlog/remove_place \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trip_id":"trip_8c41d2","block_id":"block_8c41d2"}'
```

**Python**

```python
result = client.call("wanderlog", "remove_place", {"trip_id":"trip_8c41d2","block_id":"block_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('wanderlog', 'remove_place', {"trip_id":"trip_8c41d2","block_id":"block_8c41d2"});
```

**CLI**

```bash
cotlet call wanderlog remove_place --data '{"trip_id":"trip_8c41d2","block_id":"block_8c41d2"}'
```

### Example response

```json
{
  "block_id": "blk_2c07",
  "status": "removed"
}
```

## Add hotel

`POST https://cotlet.dev/api/v1/wanderlog/add_hotel`

Access: write.

Adds a lodging entry with the dates you pass and returns the number of nights. It runs without asking, because it reaches no one outside the trip and is removed with remove_place.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Trip ID from list_trips. |
| `place` | string | yes | Hotel place ID or name. |
| `check_in` | date | yes | Check-in date. |
| `check_out` | date | yes | Check-out date. |
| `confirmation` | string | no | Booking confirmation number. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/wanderlog/add_hotel \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trip_id":"tr_8kQ2mZ","place":"Hotel Infante Sagres, Porto","check_in":"2027-05-16","check_out":"2027-05-19","confirmation":"HB-4471902"}'
```

**Python**

```python
result = client.call("wanderlog", "add_hotel", {"trip_id":"tr_8kQ2mZ","place":"Hotel Infante Sagres, Porto","check_in":"2027-05-16","check_out":"2027-05-19","confirmation":"HB-4471902"})
```

**Node.js**

```js
const result = await cotlet.call('wanderlog', 'add_hotel', {"trip_id":"tr_8kQ2mZ","place":"Hotel Infante Sagres, Porto","check_in":"2027-05-16","check_out":"2027-05-19","confirmation":"HB-4471902"});
```

**CLI**

```bash
cotlet call wanderlog add_hotel --data '{"trip_id":"tr_8kQ2mZ","place":"Hotel Infante Sagres, Porto","check_in":"2027-05-16","check_out":"2027-05-19","confirmation":"HB-4471902"}'
```

### Example response

```json
{
  "block_id": "blk_31f9a0",
  "trip_id": "tr_8kQ2mZ",
  "type": "hotel",
  "name": "Hotel Infante Sagres",
  "check_in": "2027-05-16",
  "check_out": "2027-05-19",
  "nights": 3,
  "url": "https://wanderlog.com/plan/tr_8kQ2mZ"
}
```

## Add note

`POST https://cotlet.dev/api/v1/wanderlog/add_note`

Access: write.

Adds a note to the day you name, or to the trip when no day is given. It runs without asking, because it reaches no one outside the trip and is removed with remove_place.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Trip ID from list_trips. |
| `text` | string | yes | Note text. |
| `day` | date | no | Day of the trip. Omit to use the trip-level list or notes instead. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/wanderlog/add_note \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trip_id":"trip_8c41d2","text":"text"}'
```

**Python**

```python
result = client.call("wanderlog", "add_note", {"trip_id":"trip_8c41d2","text":"text"})
```

**Node.js**

```js
const result = await cotlet.call('wanderlog', 'add_note', {"trip_id":"trip_8c41d2","text":"text"});
```

**CLI**

```bash
cotlet call wanderlog add_note --data '{"trip_id":"trip_8c41d2","text":"text"}'
```

### Example response

```json
{
  "block_id": "blk_4b12",
  "trip_id": "tr_8kQ2mZ",
  "status": "added"
}
```

## Add checklist

`POST https://cotlet.dev/api/v1/wanderlog/add_checklist`

Access: write.

Creates a checklist with the items you pass, all unchecked. It runs without asking, because it reaches no one outside the trip and you can delete it in the app.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Trip ID from list_trips. |
| `title` | string | yes | Checklist heading, e.g. Packing. |
| `items` | string[] | yes | Checklist items, unchecked. |
| `day` | date | no | Day of the trip. Omit to use the trip-level list or notes instead. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/wanderlog/add_checklist \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trip_id":"trip_8c41d2","title":"title","items":["items"]}'
```

**Python**

```python
result = client.call("wanderlog", "add_checklist", {"trip_id":"trip_8c41d2","title":"title","items":["items"]})
```

**Node.js**

```js
const result = await cotlet.call('wanderlog', 'add_checklist', {"trip_id":"trip_8c41d2","title":"title","items":["items"]});
```

**CLI**

```bash
cotlet call wanderlog add_checklist --data '{"trip_id":"trip_8c41d2","title":"title","items":["items"]}'
```

### Example response

```json
{
  "checklist_id": "cl_66e2",
  "trip_id": "tr_8kQ2mZ",
  "title": "Packing",
  "items": 4,
  "checked": 0
}
```

## Add expense

`POST https://cotlet.dev/api/v1/wanderlog/add_expense`

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

Logs the expense with its category and date (today by default). With split_with, the app shows who owes whom, so this reaches tripmates. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Trip ID from list_trips. |
| `amount` | string | yes | Decimal amount, e.g. "64.50". |
| `currency` | string | yes | ISO 4217 code, e.g. EUR. |
| `category` | string | yes | Expense category, e.g. food or lodging. |
| `description` | string | no | What it was. |
| `date` | date | no | Default: today. |
| `split_with` | string[] | no | Tripmate IDs from list_trips. Default: not split. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/wanderlog/add_expense \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trip_id":"tr_8kQ2mZ","amount":"86.40","currency":"EUR","category":"food","description":"Dinner at Cervejaria Ramiro","date":"2027-05-13","split_with":["tm_41a","tm_52c"]}'
```

**Python**

```python
result = client.call("wanderlog", "add_expense", {"trip_id":"tr_8kQ2mZ","amount":"86.40","currency":"EUR","category":"food","description":"Dinner at Cervejaria Ramiro","date":"2027-05-13","split_with":["tm_41a","tm_52c"]})
```

**Node.js**

```js
const result = await cotlet.call('wanderlog', 'add_expense', {"trip_id":"tr_8kQ2mZ","amount":"86.40","currency":"EUR","category":"food","description":"Dinner at Cervejaria Ramiro","date":"2027-05-13","split_with":["tm_41a","tm_52c"]});
```

**CLI**

```bash
cotlet call wanderlog add_expense --data '{"trip_id":"tr_8kQ2mZ","amount":"86.40","currency":"EUR","category":"food","description":"Dinner at Cervejaria Ramiro","date":"2027-05-13","split_with":["tm_41a","tm_52c"]}'
```

### Example response

```json
{
  "expense_id": "ex_72d1",
  "trip_id": "tr_8kQ2mZ",
  "amount": "64.50",
  "currency": "EUR",
  "category": "food",
  "date": "2027-05-13",
  "split_with": []
}
```

## Optimize day route

`POST https://cotlet.dev/api/v1/wanderlog/optimize_day_route`

Access: write.

Reorders the places of one day and returns the new order. It runs without asking, because the old order is in the response and you can restore it with remove_place and add_place.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Trip ID from list_trips. |
| `day` | date | yes | Day to reorder. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/wanderlog/optimize_day_route \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trip_id":"trip_8c41d2","day":"2026-10-01"}'
```

**Python**

```python
result = client.call("wanderlog", "optimize_day_route", {"trip_id":"trip_8c41d2","day":"2026-10-01"})
```

**Node.js**

```js
const result = await cotlet.call('wanderlog', 'optimize_day_route', {"trip_id":"trip_8c41d2","day":"2026-10-01"});
```

**CLI**

```bash
cotlet call wanderlog optimize_day_route --data '{"trip_id":"trip_8c41d2","day":"2026-10-01"}'
```

### Example response

```json
{
  "trip_id": "tr_8kQ2mZ",
  "day": "2027-05-14",
  "order": [
    "Castelo de S. Jorge",
    "Alfama walk",
    "Time Out Market Lisboa"
  ]
}
```

## Invite tripmate

`POST https://cotlet.dev/api/v1/wanderlog/invite_tripmate`

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

Sends the invitation for the trip to the email you pass. The person sees the itinerary once they accept. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Trip ID from list_trips. |
| `email` | string | yes | Their email. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/wanderlog/invite_tripmate \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trip_id":"trip_8c41d2","email":"jane@example.com"}'
```

**Python**

```python
result = client.call("wanderlog", "invite_tripmate", {"trip_id":"trip_8c41d2","email":"jane@example.com"})
```

**Node.js**

```js
const result = await cotlet.call('wanderlog', 'invite_tripmate', {"trip_id":"trip_8c41d2","email":"jane@example.com"});
```

**CLI**

```bash
cotlet call wanderlog invite_tripmate --data '{"trip_id":"trip_8c41d2","email":"jane@example.com"}'
```

### Example response

```json
{
  "trip_id": "tr_8kQ2mZ",
  "email": "friend@example.com",
  "status": "invited"
}
```