# Polarsteps API

> Every Polarsteps 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/polarsteps

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 Polarsteps. Each one is a POST with a JSON body, called with your API key.

- Base URL: `https://cotlet.dev/api/v1/polarsteps`
- Connects with: Your own Polarsteps account
- Integration page: https://cotlet.dev/integrations/polarsteps-api-mcp-server

## Endpoints

| Endpoint | Access | Description |
|---|---|---|
| `list_trips` | read | Your trips, newest first, with dates, privacy level, distance and step count. |
| `get_trip` | read | One trip: name, summary, dates, privacy, Travel Buddies, distance and countries. |
| `list_steps` | read | Steps of a trip in order, with place, country, date, title and photo count. |
| `get_step` | read | Full step: story text, place and coordinates, date, photo and video links. |
| `list_step_comments` | read | Comments your followers left on a step, with author and date. |
| `get_travel_stats` | read | Countries visited, total kilometers, number of trips and steps on your profile. |
| `export_trip` | read | One trip as a download link, valid for 1 hour: route, steps and photo links. |
| `create_trip` | write | New trip, past or upcoming, with the privacy level you pick. |
| `add_step` | write | Add a step to a trip with a story and photos. People who can see the trip see it. |
| `import_steps` | write | Add many steps at once, e.g. a past trip from a CSV, sorted by date. |
| `update_step` | write | Change the title, story, place or date of a step. |
| `add_step_photos` | write | Add photos or videos to an existing step. |
| `reply_to_step_comment` | write | Reply to a follower comment on one of your steps, as you. |
| `set_trip_privacy` | write | Choose who can see a trip: only you, your followers or everyone. |

## List trips

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

Access: read.

Returns the trips on your own account, newest first. Filter by status to see only planned, ongoing or past trips. Use trip_id from each item in the other endpoints.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `status` | enum | no | all, planned, ongoing or past. Default: all. |
| `limit` | integer | no | 1 to 100. Default: 50. |

### Request

**cURL**

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

**Python**

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

**Node.js**

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

**CLI**

```bash
cotlet call polarsteps list_trips
```

### Example response

```json
{
  "trips": [
    {
      "trip_id": "18452237",
      "name": "Portugal by train",
      "start_date": "2026-10-01",
      "end_date": null,
      "privacy": "followers",
      "steps": 9,
      "distance_km": 612
    },
    {
      "trip_id": "16720458",
      "name": "Patagonia",
      "start_date": "2025-12-04",
      "end_date": "2026-01-19",
      "privacy": "everyone",
      "steps": 41,
      "distance_km": 3870
    }
  ]
}
```

## Get trip

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

Access: read.

Returns one trip with its summary, start and end dates, privacy level and the Travel Buddies on it. Trip dates are separate from the dates of its steps.

### 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/polarsteps/get_trip \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trip_id":"trip_8c41d2"}'
```

**Python**

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

**Node.js**

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

**CLI**

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

### Example response

```json
{
  "trip_id": "18452237",
  "name": "Portugal by train",
  "summary": "Two weeks from Porto to Faro on regional trains.",
  "start_date": "2026-10-01",
  "end_date": null,
  "privacy": "followers",
  "travel_buddies": [
    "Marta Silva"
  ],
  "distance_km": 612,
  "countries": [
    "Portugal"
  ]
}
```

## List steps

`POST https://cotlet.dev/api/v1/polarsteps/list_steps`

Access: read.

Lists the steps of one trip in the order of the trip. Story is a short preview; get_step returns the full text, coordinates and photo links. Pass since to see only steps from a given date.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Trip ID from list_trips. |
| `since` | date | no | Only steps on or after this date. |

### Request

**cURL**

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

**Python**

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

**Node.js**

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

**CLI**

```bash
cotlet call polarsteps list_steps --data '{"trip_id":"trip_8c41d2"}'
```

### Example response

```json
{
  "steps": [
    {
      "step_id": "231908554",
      "title": "Fado night in Alfama",
      "place": "Lisbon",
      "country": "Portugal",
      "date": "2026-10-09T19:30:00+01:00",
      "photos": 2,
      "comments": 1
    },
    {
      "step_id": "231544107",
      "title": "Tram 28 to Graça",
      "place": "Lisbon",
      "country": "Portugal",
      "date": "2026-10-09T11:10:00+01:00",
      "photos": 3,
      "comments": 0
    }
  ]
}
```

## Get step

`POST https://cotlet.dev/api/v1/polarsteps/get_step`

Access: read.

Returns one step with its full story, the place and its coordinates, the date and time, and links to every photo and video. Use it before editing a step or turning it into a post.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `step_id` | string | yes | Step ID from list_steps. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/polarsteps/get_step \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"step_id":"231908554"}'
```

**Python**

```python
result = client.call("polarsteps", "get_step", {"step_id":"231908554"})
```

**Node.js**

```js
const result = await cotlet.call('polarsteps', 'get_step', {"step_id":"231908554"});
```

**CLI**

```bash
cotlet call polarsteps get_step --data '{"step_id":"231908554"}'
```

### Example response

```json
{
  "step_id": "231908554",
  "trip_id": "18452237",
  "title": "Fado night in Alfama",
  "story": "Got lost in the old town, then found a tiny fado bar with six tables.",
  "place": "Alfama, Lisbon, Portugal",
  "coordinates": {
    "lat": 38.711,
    "lon": -9.1304
  },
  "date": "2026-10-09T19:30:00+01:00",
  "media": [
    "https://example.com/photos/alfama-1.jpg",
    "https://example.com/photos/alfama-2.jpg"
  ]
}
```

## List step comments

`POST https://cotlet.dev/api/v1/polarsteps/list_step_comments`

Access: read.

Returns the comments on one step, oldest first, with author and date. Replies from you are included under the comment they answer. Use comment_id with reply_to_step_comment.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `step_id` | string | yes | Step ID from list_steps. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/polarsteps/list_step_comments \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"step_id":"step_8c41d2"}'
```

**Python**

```python
result = client.call("polarsteps", "list_step_comments", {"step_id":"step_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('polarsteps', 'list_step_comments', {"step_id":"step_8c41d2"});
```

**CLI**

```bash
cotlet call polarsteps list_step_comments --data '{"step_id":"step_8c41d2"}'
```

### Example response

```json
{
  "comments": [
    {
      "comment_id": "cm_4821",
      "author": "Eva Novak",
      "body": "That fado bar looks amazing!",
      "created_at": "2026-10-09T21:05:00+01:00",
      "replies": []
    }
  ]
}
```

## Get travel stats

`POST https://cotlet.dev/api/v1/polarsteps/get_travel_stats`

Access: read.

Returns the figures from the Travel stats on your profile: countries visited, kilometers, trips and steps. Countries are counted from the steps you add.

### Parameters

No parameters.

### Request

**cURL**

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

**Python**

```python
result = client.call("polarsteps", "get_travel_stats")
```

**Node.js**

```js
const result = await cotlet.call('polarsteps', 'get_travel_stats');
```

**CLI**

```bash
cotlet call polarsteps get_travel_stats
```

### Example response

```json
{
  "countries": 14,
  "distance_km": 28640,
  "trips": 6,
  "steps": 187
}
```

## Export trip

`POST https://cotlet.dev/api/v1/polarsteps/export_trip`

Access: read.

Exports one trip as json, gpx or markdown and returns a download link valid for 1 hour. gpx holds the route, markdown holds the step stories. Set include_media for a zip of the full-size photos and videos. It only reads, so it never asks for your OK.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Trip ID from list_trips. |
| `format` | enum | no | json, gpx or markdown. Default: json. |
| `include_media` | boolean | no | Add a zip of full-size photos and videos. Default: false. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/polarsteps/export_trip \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trip_id":"16720458","format":"gpx","include_media":false}'
```

**Python**

```python
result = client.call("polarsteps", "export_trip", {"trip_id":"16720458","format":"gpx","include_media":False})
```

**Node.js**

```js
const result = await cotlet.call('polarsteps', 'export_trip', {"trip_id":"16720458","format":"gpx","include_media":false});
```

**CLI**

```bash
cotlet call polarsteps export_trip --data '{"trip_id":"16720458","format":"gpx","include_media":false}'
```

### Example response

```json
{
  "trip_id": "16720458",
  "format": "gpx",
  "download_url": "https://example.com/exports/16720458.gpx",
  "expires_at": "2026-10-11T15:00:00+02:00",
  "steps": 41
}
```

## Create trip

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

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

Creates a trip with a name and start date. The start date can be in the past, for a trip from before you used Polarsteps. Privacy is Only me (only_me) unless you set followers or everyone, so nothing is shared by accident. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | Trip name. |
| `start_date` | date | yes | First day of the trip. Can be in the past. |
| `end_date` | date | no | Last day. Leave empty for an ongoing trip. |
| `summary` | string | no | Short trip description. |
| `privacy` | enum | no | only_me, followers or everyone. Default: only_me. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/polarsteps/create_trip \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Doe","start_date":"2026-10-01"}'
```

**Python**

```python
result = client.call("polarsteps", "create_trip", {"name":"Jane Doe","start_date":"2026-10-01"})
```

**Node.js**

```js
const result = await cotlet.call('polarsteps', 'create_trip', {"name":"Jane Doe","start_date":"2026-10-01"});
```

**CLI**

```bash
cotlet call polarsteps create_trip --data '{"name":"Jane Doe","start_date":"2026-10-01"}'
```

### Example response

```json
{
  "trip_id": "20931176",
  "name": "Vietnam 2019",
  "start_date": "2019-03-02",
  "end_date": "2019-03-20",
  "privacy": "only_me",
  "steps": 0
}
```

## Add step

`POST https://cotlet.dev/api/v1/polarsteps/add_step`

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

Adds one step to a trip at a place and time, with an optional title, story and photos by URL. The date and place set where the step sits on the route. Everyone who can see the trip, by its privacy level, sees the step. 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. |
| `place` | string | yes | Place name or "lat,lon". |
| `date` | datetime | yes | ISO 8601 with time zone. |
| `title` | string | no | Step title. Default: the place name. |
| `story` | string | no | Step text. |
| `photo_urls` | string[] | no | Photo or video URLs to attach. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/polarsteps/add_step \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trip_id":"18452237","place":"Alfama, Lisbon, Portugal","date":"2026-10-09T19:30:00+01:00","title":"Fado night in Alfama","story":"Got lost in the old town, then found a tiny fado bar with six tables.","photo_urls":["https://example.com/photos/alfama-1.jpg","https://example.com/photos/alfama-2.jpg"]}'
```

**Python**

```python
result = client.call("polarsteps", "add_step", {"trip_id":"18452237","place":"Alfama, Lisbon, Portugal","date":"2026-10-09T19:30:00+01:00","title":"Fado night in Alfama","story":"Got lost in the old town, then found a tiny fado bar with six tables.","photo_urls":["https://example.com/photos/alfama-1.jpg","https://example.com/photos/alfama-2.jpg"]})
```

**Node.js**

```js
const result = await cotlet.call('polarsteps', 'add_step', {"trip_id":"18452237","place":"Alfama, Lisbon, Portugal","date":"2026-10-09T19:30:00+01:00","title":"Fado night in Alfama","story":"Got lost in the old town, then found a tiny fado bar with six tables.","photo_urls":["https://example.com/photos/alfama-1.jpg","https://example.com/photos/alfama-2.jpg"]});
```

**CLI**

```bash
cotlet call polarsteps add_step --data '{"trip_id":"18452237","place":"Alfama, Lisbon, Portugal","date":"2026-10-09T19:30:00+01:00","title":"Fado night in Alfama","story":"Got lost in the old town, then found a tiny fado bar with six tables.","photo_urls":["https://example.com/photos/alfama-1.jpg","https://example.com/photos/alfama-2.jpg"]}'
```

### Example response

```json
{
  "step_id": "231908554",
  "trip_id": "18452237",
  "title": "Fado night in Alfama",
  "place": "Lisbon, Portugal",
  "date": "2026-10-09T19:30:00+01:00",
  "photos": 2
}
```

## Import steps

`POST https://cotlet.dev/api/v1/polarsteps/import_steps`

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

Adds up to 50 steps to one trip in a single call and sorts them by date, so the route draws in travel order. Each step needs a place and a date. The OK covers the whole batch. 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. |
| `steps` | object[] | yes | Up to 50 items of { place, date, title, story, photo_urls }. place and date are required. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/polarsteps/import_steps \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trip_id":"20931176","steps":[{"place":"Hanoi, Vietnam","date":"2019-03-02T09:00:00+07:00","title":"Arrival in Hanoi"},{"place":"Ha Long Bay, Vietnam","date":"2019-03-05T08:00:00+07:00","title":"Boat to Ha Long Bay"}]}'
```

**Python**

```python
result = client.call("polarsteps", "import_steps", {"trip_id":"20931176","steps":[{"place":"Hanoi, Vietnam","date":"2019-03-02T09:00:00+07:00","title":"Arrival in Hanoi"},{"place":"Ha Long Bay, Vietnam","date":"2019-03-05T08:00:00+07:00","title":"Boat to Ha Long Bay"}]})
```

**Node.js**

```js
const result = await cotlet.call('polarsteps', 'import_steps', {"trip_id":"20931176","steps":[{"place":"Hanoi, Vietnam","date":"2019-03-02T09:00:00+07:00","title":"Arrival in Hanoi"},{"place":"Ha Long Bay, Vietnam","date":"2019-03-05T08:00:00+07:00","title":"Boat to Ha Long Bay"}]});
```

**CLI**

```bash
cotlet call polarsteps import_steps --data '{"trip_id":"20931176","steps":[{"place":"Hanoi, Vietnam","date":"2019-03-02T09:00:00+07:00","title":"Arrival in Hanoi"},{"place":"Ha Long Bay, Vietnam","date":"2019-03-05T08:00:00+07:00","title":"Boat to Ha Long Bay"}]}'
```

### Example response

```json
{
  "trip_id": "20931176",
  "added": 2,
  "steps": [
    {
      "step_id": "301440018",
      "title": "Arrival in Hanoi",
      "date": "2019-03-02T09:00:00+07:00"
    },
    {
      "step_id": "301440019",
      "title": "Boat to Ha Long Bay",
      "date": "2019-03-05T08:00:00+07:00"
    }
  ]
}
```

## Update step

`POST https://cotlet.dev/api/v1/polarsteps/update_step`

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

Changes the fields you send and leaves the rest of the step as it is. Changing the place or date moves the step on the route. Trip start and end dates are not changed. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `step_id` | string | yes | Step ID from list_steps. |
| `fields` | object | yes | Any of title, story, place, date. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/polarsteps/update_step \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"step_id":"231908554","fields":{"story":"Got lost in the old town, then found a tiny fado bar with six tables."}}'
```

**Python**

```python
result = client.call("polarsteps", "update_step", {"step_id":"231908554","fields":{"story":"Got lost in the old town, then found a tiny fado bar with six tables."}})
```

**Node.js**

```js
const result = await cotlet.call('polarsteps', 'update_step', {"step_id":"231908554","fields":{"story":"Got lost in the old town, then found a tiny fado bar with six tables."}});
```

**CLI**

```bash
cotlet call polarsteps update_step --data '{"step_id":"231908554","fields":{"story":"Got lost in the old town, then found a tiny fado bar with six tables."}}'
```

### Example response

```json
{
  "step_id": "231908554",
  "updated": [
    "story"
  ],
  "date": "2026-10-09T19:30:00+01:00"
}
```

## Add step photos

`POST https://cotlet.dev/api/v1/polarsteps/add_step_photos`

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

Attaches photos or videos by URL to a step that already exists. People who can see the trip see them. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `step_id` | string | yes | Step ID from list_steps. |
| `photo_urls` | string[] | yes | Photo or video URLs. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/polarsteps/add_step_photos \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"step_id":"step_8c41d2","photo_urls":["https://example.com"]}'
```

**Python**

```python
result = client.call("polarsteps", "add_step_photos", {"step_id":"step_8c41d2","photo_urls":["https://example.com"]})
```

**Node.js**

```js
const result = await cotlet.call('polarsteps', 'add_step_photos', {"step_id":"step_8c41d2","photo_urls":["https://example.com"]});
```

**CLI**

```bash
cotlet call polarsteps add_step_photos --data '{"step_id":"step_8c41d2","photo_urls":["https://example.com"]}'
```

### Example response

```json
{
  "step_id": "231908554",
  "added": 2,
  "photos_total": 4
}
```

## Reply to step comment

`POST https://cotlet.dev/api/v1/polarsteps/reply_to_step_comment`

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

Adds a reply under a comment on your step. The reply appears under your name for people who can see the trip. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `step_id` | string | yes | Step ID from list_steps. |
| `comment_id` | string | yes | Comment ID from list_step_comments. |
| `body` | string | yes | Reply text. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/polarsteps/reply_to_step_comment \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"step_id":"step_8c41d2","comment_id":"comment_8c41d2","body":"body"}'
```

**Python**

```python
result = client.call("polarsteps", "reply_to_step_comment", {"step_id":"step_8c41d2","comment_id":"comment_8c41d2","body":"body"})
```

**Node.js**

```js
const result = await cotlet.call('polarsteps', 'reply_to_step_comment', {"step_id":"step_8c41d2","comment_id":"comment_8c41d2","body":"body"});
```

**CLI**

```bash
cotlet call polarsteps reply_to_step_comment --data '{"step_id":"step_8c41d2","comment_id":"comment_8c41d2","body":"body"}'
```

### Example response

```json
{
  "comment_id": "cm_4822",
  "parent_comment_id": "cm_4821",
  "step_id": "231908554",
  "status": "published"
}
```

## Set trip privacy

`POST https://cotlet.dev/api/v1/polarsteps/set_trip_privacy`

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

Sets the privacy level of one trip to Only me, Followers or Everyone. It applies to the trip with all its steps. Followers can also see the trip through the secret link. 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. |
| `privacy` | enum | yes | only_me, followers or everyone. |

### Request

**cURL**

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

**Python**

```python
result = client.call("polarsteps", "set_trip_privacy", {"trip_id":"trip_8c41d2","privacy":"only_me"})
```

**Node.js**

```js
const result = await cotlet.call('polarsteps', 'set_trip_privacy', {"trip_id":"trip_8c41d2","privacy":"only_me"});
```

**CLI**

```bash
cotlet call polarsteps set_trip_privacy --data '{"trip_id":"trip_8c41d2","privacy":"only_me"}'
```

### Example response

```json
{
  "trip_id": "18452237",
  "privacy": "everyone"
}
```