create_hike

Add a hike.

POST/v1/guides/{productId}/hikes

MCP tool create_hikeScope: writeBetaSince 2026-10-06.8

A hike is its own row: facts the creator vouches for (difficulty, an optional grade, walking time, gain, descent, distance, trailhead, transit per mode, equipment with [] meaning explicitly none, sources) and the line from the creator's GPX or KML. spotKeys links it to the spots it goes to in the same write; a hike can go to several spots, or to none (one stage of a multi-day hike). A multi-day hike is an itinerary: one day per stage, each with a hike stop and an overnight at a hut. The reply is the stored hike.

curl -X POST "https://sceniq.earth/api/v1/guides/j57h3k5m7p9r1t3v5x7z9b1d3f5h7k9m/hikes" \
  -H "Authorization: Bearer $SCENIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Oeschinensee panorama loop",
  "difficulty": "moderate",
  "grade": "T2",
  "durationMin": 165,
  "distanceKm": 7.4,
  "gainM": 420,
  "descentM": 420,
  "start": "Oeschinen gondola top station above Kandersteg",
  "startMapsUrl": "https://www.google.com/maps/search/?api=1&query=46.4978,7.6985",
  "description": "Up from the gondola to the Heuberg balcony with the whole lake below, then a steep zigzag down to the shore and back along the water. Start early in July and August, before the day visitors.",
  "transit": [
    {
      "mode": "train",
      "note": "Kandersteg is on the Lötschberg line; the gondola valley station is a 15 minute walk from the train station."
    },
    {
      "mode": "cable_car",
      "note": "The gondola from Kandersteg runs from late May to October. Check the last ride down before you set off."
    }
  ],
  "equipment": [
    "Hiking boots with grip for the steep descent",
    "Rain jacket"
  ],
  "sources": [
    "https://www.oeschinensee.ch",
    "GPX recorded by Mara Lindgren on 2026-07-18"
  ],
  "track": {
    "coordinates": [
      [
        7.6985,
        46.4978,
        1682
      ],
      [
        7.7071,
        46.5002,
        1771
      ],
      [
        7.7163,
        46.5021,
        1902
      ],
      [
        7.7215,
        46.5026,
        1940
      ],
      [
        7.7268,
        46.5003,
        1712
      ],
      [
        7.7243,
        46.4983,
        1580
      ],
      [
        7.7104,
        46.4972,
        1610
      ],
      [
        7.6985,
        46.4978,
        1682
      ]
    ],
    "source": "gpx",
    "fileName": "oeschinensee-panorama-2026-07-18.gpx"
  },
  "spotKeys": [
    "01M3B7K2D5F8H1J4L7N0Q3S6V9"
  ]
}'

Path parameters

productIdstring · guide idrequired
Id of the guide (a product of type map). From list_guides or create_guide.

Body parameters

descentMnumber or nulloptional
Descent in meters, 0 or more. Never derived from gainM: give it when the source does.
descriptionstringoptional
The hike in the creator's words, shown on the hike card. Empty string clears.
difficultystring or nulloptional
One of four words: easy, moderate, hard or expert. Buyers read it before the grade (Moderate · T2), and the easiest hike of a spot fills its Accessibility. null clears.
easymoderatehardexpert
distanceKmnumber or nulloptional
Distance in kilometers, 0 or more.
durationMinnumber or nulloptional
Walking time in minutes, 0 or more, as the creator or the trail page gives it.
equipmentarray of strings or nulloptional
Gear, at most 50 items; [] means explicitly no special gear (shown as None), absent means unknown.
gainMnumber or nulloptional
Elevation gain in meters, 0 or more.
gradestringoptional
The technical grade as the creator or the trail page writes it, at most 24 characters: T2 (SAC hiking), K3 (via ferrata), Class 3 (US), EE (Italy). Optional; empty string clears.
namestringoptional
Hike name, e.g. Oeschinensee panorama loop or Fairy Falls trail. Without one the apps show Hike from <start>, or Hike N when there is no start either. Empty string clears.
sourcesarray of stringsoptional
Where the facts come from, full replacement ([] clears), at most 25 entries: links to official trail pages or plain text (the creator's GPX). Buyers see them under Sources, links by their host.
spotKeysarray of stringsoptional
The spots the hike goes to, in order (spotKey from list_spots), each once, at most 200. Optional; set_hike_spots replaces the list later.
startstringoptional
Trailhead or starting point in words. Empty string clears.
startMapsUrlstringoptional
Map link to the trailhead: https on Google Maps, Apple Maps, Swisstopo, OpenStreetMap or SchweizMobil, or a geo: URI. Empty string clears.
trackHikeTrack or nulloptional
The hike's line from the creator's GPX or KML: { coordinates: [[lon, lat] or [lon, lat, ele]], source: gpx|kml, fileName }. 2 to 1,000 points; simplify long recordings first.
Show 3 fieldsHide fieldsof HikeTrack
- coordinatesarray of array of numbersrequired
  Positions as [lon, lat] or [lon, lat, ele] (ele in meters), 2 to 1,000. Stored rounded to 6 decimals and whole meters.
- sourcestringoptional
  The file type the line came from: gpx or kml. Other values are dropped.
- fileNamestringoptional
  The imported file's name, cut to 200 characters.
transitarray of TransitNoteoptional
Transit notes shown under Transit on the hike card, full replacement ([] clears), at most 20: [{ mode: train|bus|cable_car|car|boat|ferry|plane, note }]. Rows with an empty note are dropped.
Show 2 fieldsHide fieldsof TransitNote
- modestringrequired
  train, bus, cable_car, car, boat, ferry or plane (shown as Flight).
  trainbuscable_carcarboatferryplane
- notestringrequired
  The note in words: the connection, where to change, the last departure.

Returns

201 Created with Hike: A hike with its facts and its spot and place links.

hikeIdstring · hike idrequired
The hike's id.
namestring or nullrequired
The hike's name.
difficultystring or nullrequired
easy, moderate, hard or expert; null when unset.
easymoderatehardexpert
gradestring or nullrequired
The grade as written (T3, K2, Class 3); null when unset.
durationMinnumber or nullrequired
Walking time in minutes.
gainMnumber or nullrequired
Elevation gain in meters.
descentMnumber or nullrequired
Descent in meters.
distanceKmnumber or nullrequired
Distance in kilometers.
startstring or nullrequired
The trailhead in words.
startMapsUrlstring or nullrequired
Map link to the trailhead.
transitarray of TransitNoterequired
Transit notes per mode.
Show 2 fieldsHide fieldsof TransitNote
- modestringrequired
  train, bus, cable_car, car, boat, ferry or plane (shown as Flight).
  trainbuscable_carcarboatferryplane
- notestringrequired
  The note in words: the connection, where to change, the last departure.
descriptionstring or nullrequired
The hike in the creator's words.
equipmentarray of strings or nullrequired
Gear; [] means explicitly none, null means unknown.
sourcesarray of stringsrequired
Where the facts come from.
trackHikeTrack or nullrequired
The hike's line.
Show 3 fieldsHide fieldsof HikeTrack
- coordinatesarray of array of numbersrequired
  Positions as [lon, lat] or [lon, lat, ele] (ele in meters), 2 to 1,000. Stored rounded to 6 decimals and whole meters.
- sourcestringoptional
  The file type the line came from: gpx or kml. Other values are dropped.
- fileNamestringoptional
  The imported file's name, cut to 200 characters.
createdAtnumberrequired
When the row was created (Unix time in milliseconds).
updatedAtnumberrequired
When the row last changed (Unix time in milliseconds).
spotsarray of objectsrequired
The spots the hike goes to, in order.
Show 2 fieldsHide fields
- spotKeystringrequired
  The spot's key.
- ordernumberrequired
  Position on the hike.
facilitiesarray of objectsrequired
The places the hike uses, in order.
Show 2 fieldsHide fields
- facilityIdstringrequired
  The place's id: its helper pin's spot id (a place written before helpers keeps answering to its old id).
- ordernumberrequired
  Position on the hike.

Response 201

{
  "hikeId": "kx7q3e5s7c9h1n3m5e7r9s1t3v5w7y9a",
  "name": "Oeschinensee panorama loop",
  "difficulty": "moderate",
  "grade": "T2",
  "durationMin": 165,
  "gainM": 420,
  "descentM": 420,
  "distanceKm": 7.4,
  "start": "Oeschinen gondola top station above Kandersteg",
  "startMapsUrl": "https://www.google.com/maps/search/?api=1&query=46.4978,7.6985",
  "transit": [
    {
      "mode": "train",
      "note": "Kandersteg is on the Lötschberg line; the gondola valley station is a 15 minute walk from the train station."
    },
    {
      "mode": "cable_car",
      "note": "The gondola from Kandersteg runs from late May to October. Check the last ride down before you set off."
    }
  ],
  "description": "Up from the gondola to the Heuberg balcony with the whole lake below, then a steep zigzag down to the shore and back along the water. Start early in July and August, before the day visitors.",
  "equipment": [
    "Hiking boots with grip for the steep descent",
    "Rain jacket"
  ],
  "sources": [
    "https://www.oeschinensee.ch",
    "GPX recorded by Mara Lindgren on 2026-07-18"
  ],
  "track": {
    "coordinates": [
      [
        7.6985,
        46.4978,
        1682
      ],
      [
        7.7071,
        46.5002,
        1771
      ],
      [
        7.7163,
        46.5021,
        1902
      ],
      [
        7.7215,
        46.5026,
        1940
      ],
      [
        7.7268,
        46.5003,
        1712
      ],
      [
        7.7243,
        46.4983,
        1580
      ],
      [
        7.7104,
        46.4972,
        1610
      ],
      [
        7.6985,
        46.4978,
        1682
      ]
    ],
    "source": "gpx",
    "fileName": "oeschinensee-panorama-2026-07-18.gpx"
  },
  "createdAt": 1789895640000,
  "updatedAt": 1789895640000,
  "spots": [
    {
      "spotKey": "01M3B7K2D5F8H1J4L7N0Q3S6V9",
      "order": 1024
    }
  ],
  "facilities": []
}

Errors

Every error is { error: { code, message } }. Act on the code.

400invalid_argumentA required field is missing, a field is unknown, or a value does not match its type (the Convex validator's path and value are in the message).
400invalid_requestA writer refused a value: a map link on a host that is not allowed, a title that is too long, a date that does not exist, too many items in a list. The message is the writer's own sentence.
401unauthenticatedThe request carries no key. Send it as Authorization: Bearer sk_sceniq_... (or X-Api-Key).
401invalid_api_keyThe key is unknown, revoked or expired.
403api_scope_requiredA read-only key called a write operation, or a key without the publish option called publish_changes.
403forbiddenThe key belongs to a creator account that is no longer active.
404not_foundThe id does not exist or belongs to another creator. The two answers are identical on purpose, so ids never reveal what exists.
413payload_too_largeA JSON body over 2 MB, an image over 6 MB, a batch upload over 19 MB, or an MCP message over 2 MB.
429rate_limitedOver a limit: requests per key per minute, per creator per hour, uploads per key per minute, or check_links per guide per hour.
500internal_errorAn unexpected failure. The message is hidden on purpose.

curl -X POST "https://sceniq.earth/api/v1/guides/j57h3k5m7p9r1t3v5x7z9b1d3f5h7k9m/hikes" \
  -H "Authorization: Bearer $SCENIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Oeschinensee panorama loop",
  "difficulty": "moderate",
  "grade": "T2",
  "durationMin": 165,
  "distanceKm": 7.4,
  "gainM": 420,
  "descentM": 420,
  "start": "Oeschinen gondola top station above Kandersteg",
  "startMapsUrl": "https://www.google.com/maps/search/?api=1&query=46.4978,7.6985",
  "description": "Up from the gondola to the Heuberg balcony with the whole lake below, then a steep zigzag down to the shore and back along the water. Start early in July and August, before the day visitors.",
  "transit": [
    {
      "mode": "train",
      "note": "Kandersteg is on the Lötschberg line; the gondola valley station is a 15 minute walk from the train station."
    },
    {
      "mode": "cable_car",
      "note": "The gondola from Kandersteg runs from late May to October. Check the last ride down before you set off."
    }
  ],
  "equipment": [
    "Hiking boots with grip for the steep descent",
    "Rain jacket"
  ],
  "sources": [
    "https://www.oeschinensee.ch",
    "GPX recorded by Mara Lindgren on 2026-07-18"
  ],
  "track": {
    "coordinates": [
      [
        7.6985,
        46.4978,
        1682
      ],
      [
        7.7071,
        46.5002,
        1771
      ],
      [
        7.7163,
        46.5021,
        1902
      ],
      [
        7.7215,
        46.5026,
        1940
      ],
      [
        7.7268,
        46.5003,
        1712
      ],
      [
        7.7243,
        46.4983,
        1580
      ],
      [
        7.7104,
        46.4972,
        1610
      ],
      [
        7.6985,
        46.4978,
        1682
      ]
    ],
    "source": "gpx",
    "fileName": "oeschinensee-panorama-2026-07-18.gpx"
  },
  "spotKeys": [
    "01M3B7K2D5F8H1J4L7N0Q3S6V9"
  ]
}'

Response 201

{
  "hikeId": "kx7q3e5s7c9h1n3m5e7r9s1t3v5w7y9a",
  "name": "Oeschinensee panorama loop",
  "difficulty": "moderate",
  "grade": "T2",
  "durationMin": 165,
  "gainM": 420,
  "descentM": 420,
  "distanceKm": 7.4,
  "start": "Oeschinen gondola top station above Kandersteg",
  "startMapsUrl": "https://www.google.com/maps/search/?api=1&query=46.4978,7.6985",
  "transit": [
    {
      "mode": "train",
      "note": "Kandersteg is on the Lötschberg line; the gondola valley station is a 15 minute walk from the train station."
    },
    {
      "mode": "cable_car",
      "note": "The gondola from Kandersteg runs from late May to October. Check the last ride down before you set off."
    }
  ],
  "description": "Up from the gondola to the Heuberg balcony with the whole lake below, then a steep zigzag down to the shore and back along the water. Start early in July and August, before the day visitors.",
  "equipment": [
    "Hiking boots with grip for the steep descent",
    "Rain jacket"
  ],
  "sources": [
    "https://www.oeschinensee.ch",
    "GPX recorded by Mara Lindgren on 2026-07-18"
  ],
  "track": {
    "coordinates": [
      [
        7.6985,
        46.4978,
        1682
      ],
      [
        7.7071,
        46.5002,
        1771
      ],
      [
        7.7163,
        46.5021,
        1902
      ],
      [
        7.7215,
        46.5026,
        1940
      ],
      [
        7.7268,
        46.5003,
        1712
      ],
      [
        7.7243,
        46.4983,
        1580
      ],
      [
        7.7104,
        46.4972,
        1610
      ],
      [
        7.6985,
        46.4978,
        1682
      ]
    ],
    "source": "gpx",
    "fileName": "oeschinensee-panorama-2026-07-18.gpx"
  },
  "createdAt": 1789895640000,
  "updatedAt": 1789895640000,
  "spots": [
    {
      "spotKey": "01M3B7K2D5F8H1J4L7N0Q3S6V9",
      "order": 1024
    }
  ],
  "facilities": []
}