# create_hike

Add a hike.

`POST /v1/guides/{productId}/hikes` · MCP tool `create_hike` · scope `write` · beta · since 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.

## Path parameters

- `productId` (string, required): Id of the guide (a product of type map). From list_guides or create_guide.

## Body parameters

- `descentM` (number or null, optional): Descent in meters, 0 or more. Never derived from gainM: give it when the source does.
- `description` (string, optional): The hike in the creator's words, shown on the hike card. Empty string clears.
- `difficulty` (string or null, optional): 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. One of `easy`, `moderate`, `hard`, `expert`.
- `distanceKm` (number or null, optional): Distance in kilometers, 0 or more.
- `durationMin` (number or null, optional): Walking time in minutes, 0 or more, as the creator or the trail page gives it.
- `equipment` (array of strings or null, optional): Gear, at most 50 items; [] means explicitly no special gear (shown as None), absent means unknown.
- `gainM` (number or null, optional): Elevation gain in meters, 0 or more.
- `grade` (string, optional): 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.
- `name` (string, optional): 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.
- `sources` (array of strings, optional): 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.
- `spotKeys` (array of strings, optional): 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.
- `start` (string, optional): Trailhead or starting point in words. Empty string clears.
- `startMapsUrl` (string, optional): Map link to the trailhead: https on Google Maps, Apple Maps, Swisstopo, OpenStreetMap or SchweizMobil, or a geo: URI. Empty string clears.
- `track` (HikeTrack or null, optional): 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.
  Fields of HikeTrack: https://developers.sceniq.earth/fields/hike-track.md
- `transit` (array of TransitNote, optional): 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.
  Fields of TransitNote: https://developers.sceniq.earth/fields/transit-note.md

## Returns

201: Hike.

- `hikeId` (string, required): The hike's id.
- `name` (string or null, required): The hike's name.
- `difficulty` (string or null, required): easy, moderate, hard or expert; null when unset. One of `easy`, `moderate`, `hard`, `expert`.
- `grade` (string or null, required): The grade as written (T3, K2, Class 3); null when unset.
- `durationMin` (number or null, required): Walking time in minutes.
- `gainM` (number or null, required): Elevation gain in meters.
- `descentM` (number or null, required): Descent in meters.
- `distanceKm` (number or null, required): Distance in kilometers.
- `start` (string or null, required): The trailhead in words.
- `startMapsUrl` (string or null, required): Map link to the trailhead.
- `transit` (array of TransitNote, required): Transit notes per mode.
  Fields of TransitNote: https://developers.sceniq.earth/fields/transit-note.md
- `description` (string or null, required): The hike in the creator's words.
- `equipment` (array of strings or null, required): Gear; [] means explicitly none, null means unknown.
- `sources` (array of strings, required): Where the facts come from.
- `track` (HikeTrack or null, required): The hike's line.
  Fields of HikeTrack: https://developers.sceniq.earth/fields/hike-track.md
- `createdAt` (number, required): When the row was created (Unix time in milliseconds).
- `updatedAt` (number, required): When the row last changed (Unix time in milliseconds).
- `spots` (array of objects, required): The spots the hike goes to, in order.
  - `spotKey` (string, required): The spot's key.
  - `order` (number, required): Position on the hike.
- `facilities` (array of objects, required): The places the hike uses, in order.
  - `facilityId` (string, required): The place's id: its helper pin's spot id (a place written before helpers keeps answering to its old id).
  - `order` (number, required): Position on the hike.

## Examples

### Add a day hike with its difficulty, grade, figures, sources and GPX line, linked to its spot

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

MCP `tools/call`:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_hike",
    "arguments": {
      "productId": "j57h3k5m7p9r1t3v5x7z9b1d3f5h7k9m",
      "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:

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

### One stage of a multi-day hike: a hike on no spot, the night at the hut follows in the itinerary

```bash
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 to the Blüemlisalp hut",
  "difficulty": "hard",
  "grade": "T3",
  "durationMin": 270,
  "distanceKm": 7.8,
  "gainM": 1220,
  "descentM": 50,
  "start": "Oeschinensee, west shore",
  "description": "Pasture paths to Oberbärgli, then the long stepped climb to the Hohtürli pass and the hut just above it."
}'
```

MCP `tools/call`:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_hike",
    "arguments": {
      "productId": "j57h3k5m7p9r1t3v5x7z9b1d3f5h7k9m",
      "name": "Oeschinensee to the Blüemlisalp hut",
      "difficulty": "hard",
      "grade": "T3",
      "durationMin": 270,
      "distanceKm": 7.8,
      "gainM": 1220,
      "descentM": 50,
      "start": "Oeschinensee, west shore",
      "description": "Pasture paths to Oberbärgli, then the long stepped climb to the Hohtürli pass and the hut just above it."
    }
  }
}
```

Response 201:

```json
{
  "hikeId": "kx7b4d6f8h0j2k4m6p8r0t2v4x6z8c0e",
  "name": "Oeschinensee to the Blüemlisalp hut",
  "difficulty": "hard",
  "grade": "T3",
  "durationMin": 270,
  "gainM": 1220,
  "descentM": 50,
  "distanceKm": 7.8,
  "start": "Oeschinensee, west shore",
  "startMapsUrl": null,
  "transit": [],
  "description": "Pasture paths to Oberbärgli, then the long stepped climb to the Hohtürli pass and the hut just above it.",
  "equipment": null,
  "sources": [],
  "track": null,
  "createdAt": 1790673240000,
  "updatedAt": 1790673240000,
  "spots": [],
  "facilities": []
}
```

### A short walk with only the basics: everything else comes back null or empty

```bash
curl -X POST "https://sceniq.earth/api/v1/guides/j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2/hikes" \
  -H "Authorization: Bearer $SCENIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Bridalveil Fall trail",
  "difficulty": "easy",
  "durationMin": 20,
  "distanceKm": 0.8
}'
```

MCP `tools/call`:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_hike",
    "arguments": {
      "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
      "name": "Bridalveil Fall trail",
      "difficulty": "easy",
      "durationMin": 20,
      "distanceKm": 0.8
    }
  }
}
```

Response 201:

```json
{
  "hikeId": "kx7c5v7b9n1m3q5w7e9r1t3y5v7j9p1p",
  "name": "Bridalveil Fall trail",
  "difficulty": "easy",
  "grade": null,
  "durationMin": 20,
  "gainM": null,
  "descentM": null,
  "distanceKm": 0.8,
  "start": null,
  "startMapsUrl": null,
  "transit": [],
  "description": null,
  "equipment": null,
  "sources": [],
  "track": null,
  "createdAt": 1790673240000,
  "updatedAt": 1790673240000,
  "spots": [],
  "facilities": []
}
```

## Errors

- `invalid_argument` (400): A 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).
- `invalid_request` (400): A 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.
- `unauthenticated` (401): The request carries no key. Send it as Authorization: Bearer sk_sceniq_... (or X-Api-Key).
- `invalid_api_key` (401): The key is unknown, revoked or expired.
- `api_scope_required` (403): A read-only key called a write operation, or a key without the publish option called publish_changes.
- `forbidden` (403): The key belongs to a creator account that is no longer active.
- `not_found` (404): The id does not exist or belongs to another creator. The two answers are identical on purpose, so ids never reveal what exists.
- `payload_too_large` (413): A JSON body over 2 MB, an image over 6 MB, a batch upload over 19 MB, or an MCP message over 2 MB.
- `rate_limited` (429): Over a limit: requests per key per minute, per creator per hour, uploads per key per minute, or check_links per guide per hour.
- `internal_error` (500): An unexpected failure. The message is hidden on purpose.

Reference: https://developers.sceniq.earth/reference/create_hike