REST API reference

Polarsteps API

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
Polarsteps
Polarsteps 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

read

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

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

Parameters: list_trips
NameTypeDescription
status enum all, planned, ongoing or past. Default: all.
limit integer 1 to 100. Default: 50.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/polarsteps/list_trips \
  -H "Authorization: Bearer $COTLET_API_KEY"
Python
result = client.call("polarsteps", "list_trips")
Node.js
const result = await cotlet.call('polarsteps', 'list_trips');
CLI
cotlet call polarsteps list_trips

Example response

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

read

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

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

Parameters: get_trip
NameTypeDescription
trip_id required string Trip ID from list_trips.

Request

cURL
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
result = client.call("polarsteps", "get_trip", {"trip_id":"trip_8c41d2"})
Node.js
const result = await cotlet.call('polarsteps', 'get_trip', {"trip_id":"trip_8c41d2"});
CLI
cotlet call polarsteps get_trip --data '{"trip_id":"trip_8c41d2"}'

Example response

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

read

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

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

Parameters: list_steps
NameTypeDescription
trip_id required string Trip ID from list_trips.
since date Only steps on or after this date.

Request

cURL
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
result = client.call("polarsteps", "list_steps", {"trip_id":"trip_8c41d2"})
Node.js
const result = await cotlet.call('polarsteps', 'list_steps', {"trip_id":"trip_8c41d2"});
CLI
cotlet call polarsteps list_steps --data '{"trip_id":"trip_8c41d2"}'

Example response

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

read

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

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

Parameters: get_step
NameTypeDescription
step_id required string Step ID from list_steps.

Request

cURL
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
result = client.call("polarsteps", "get_step", {"step_id":"231908554"})
Node.js
const result = await cotlet.call('polarsteps', 'get_step', {"step_id":"231908554"});
CLI
cotlet call polarsteps get_step --data '{"step_id":"231908554"}'

Example response

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

read

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

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

Parameters: list_step_comments
NameTypeDescription
step_id required string Step ID from list_steps.

Request

cURL
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
result = client.call("polarsteps", "list_step_comments", {"step_id":"step_8c41d2"})
Node.js
const result = await cotlet.call('polarsteps', 'list_step_comments', {"step_id":"step_8c41d2"});
CLI
cotlet call polarsteps list_step_comments --data '{"step_id":"step_8c41d2"}'

Example response

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

read

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

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
curl -X POST https://cotlet.dev/api/v1/polarsteps/get_travel_stats \
  -H "Authorization: Bearer $COTLET_API_KEY"
Python
result = client.call("polarsteps", "get_travel_stats")
Node.js
const result = await cotlet.call('polarsteps', 'get_travel_stats');
CLI
cotlet call polarsteps get_travel_stats

Example response

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

Export trip

read

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

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

Parameters: export_trip
NameTypeDescription
trip_id required string Trip ID from list_trips.
format enum json, gpx or markdown. Default: json.
include_media boolean Add a zip of full-size photos and videos. Default: false.

Request

cURL
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
result = client.call("polarsteps", "export_trip", {"trip_id":"16720458","format":"gpx","include_media":False})
Node.js
const result = await cotlet.call('polarsteps', 'export_trip', {"trip_id":"16720458","format":"gpx","include_media":false});
CLI
cotlet call polarsteps export_trip --data '{"trip_id":"16720458","format":"gpx","include_media":false}'

Example response

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

write Confirm

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

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

Parameters: create_trip
NameTypeDescription
name required string Trip name.
start_date required date First day of the trip. Can be in the past.
end_date date Last day. Leave empty for an ongoing trip.
summary string Short trip description.
privacy enum only_me, followers or everyone. Default: only_me.

Request

cURL
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
result = client.call("polarsteps", "create_trip", {"name":"Jane Doe","start_date":"2026-10-01"})
Node.js
const result = await cotlet.call('polarsteps', 'create_trip', {"name":"Jane Doe","start_date":"2026-10-01"});
CLI
cotlet call polarsteps create_trip --data '{"name":"Jane Doe","start_date":"2026-10-01"}'

Example response

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

Add step

write Confirm

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

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

Parameters: add_step
NameTypeDescription
trip_id required string Trip ID from list_trips.
place required string Place name or "lat,lon".
date required datetime ISO 8601 with time zone.
title string Step title. Default: the place name.
story string Step text.
photo_urls string[] Photo or video URLs to attach.

Request

cURL
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
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
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
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

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

write Confirm

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

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

Parameters: import_steps
NameTypeDescription
trip_id required string Trip ID from list_trips.
steps required object[] Up to 50 items of { place, date, title, story, photo_urls }. place and date are required.

Request

cURL
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
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
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
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

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

write Confirm

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

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

Parameters: update_step
NameTypeDescription
step_id required string Step ID from list_steps.
fields required object Any of title, story, place, date.

Request

cURL
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
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
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
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

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

Add step photos

write Confirm

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

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

Parameters: add_step_photos
NameTypeDescription
step_id required string Step ID from list_steps.
photo_urls required string[] Photo or video URLs.

Request

cURL
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
result = client.call("polarsteps", "add_step_photos", {"step_id":"step_8c41d2","photo_urls":["https://example.com"]})
Node.js
const result = await cotlet.call('polarsteps', 'add_step_photos', {"step_id":"step_8c41d2","photo_urls":["https://example.com"]});
CLI
cotlet call polarsteps add_step_photos --data '{"step_id":"step_8c41d2","photo_urls":["https://example.com"]}'

Example response

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

Reply to step comment

write Confirm

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

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

Parameters: reply_to_step_comment
NameTypeDescription
step_id required string Step ID from list_steps.
comment_id required string Comment ID from list_step_comments.
body required string Reply text.

Request

cURL
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
result = client.call("polarsteps", "reply_to_step_comment", {"step_id":"step_8c41d2","comment_id":"comment_8c41d2","body":"body"})
Node.js
const result = await cotlet.call('polarsteps', 'reply_to_step_comment', {"step_id":"step_8c41d2","comment_id":"comment_8c41d2","body":"body"});
CLI
cotlet call polarsteps reply_to_step_comment --data '{"step_id":"step_8c41d2","comment_id":"comment_8c41d2","body":"body"}'

Example response

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

Set trip privacy

write Confirm

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

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

Parameters: set_trip_privacy
NameTypeDescription
trip_id required string Trip ID from list_trips.
privacy required enum only_me, followers or everyone.

Request

cURL
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
result = client.call("polarsteps", "set_trip_privacy", {"trip_id":"trip_8c41d2","privacy":"only_me"})
Node.js
const result = await cotlet.call('polarsteps', 'set_trip_privacy', {"trip_id":"trip_8c41d2","privacy":"only_me"});
CLI
cotlet call polarsteps set_trip_privacy --data '{"trip_id":"trip_8c41d2","privacy":"only_me"}'

Example response

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