SceniqDevelopers

list_properties

Custom spot property definitions of a guide.

GET/v1/guides/{productId}/properties
MCP tool list_propertiesScope: readStableSince 2026-09-17
Markdown

The creator-defined schema every spot's customValues is validated against: key, kind (shortLabel, longSection, number, date, checkbox, singleSelect), required, options with their immutable ids.

curl "https://sceniq.earth/api/v1/guides/j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2/properties" \
  -H "Authorization: Bearer $SCENIQ_API_KEY"

Path parameters

Returns

200 OK with this object.

  • productIdstring · guide idrequired

    The guide's id.

  • schemaVersionnumber or nullrequired

    The guide's property schema version.

  • propertiesarray of Propertyrequired

    Every property definition, archived ones included.

    Show 12 fieldsof Property
    • propertyDefIdstring · property idrequired

      The property's id.

    • keystringrequired

      The immutable key spots use in customValues.

    • labelstringrequired

      The label buyers see.

    • kindstringrequired

      The kind; it decides the value's type and whether buyers can filter by it.

      shortLabellongSectionnumberdatecheckboxsingleSelect
    • ordernumberrequired

      Display order (ascending).

    • requiredbooleanoptional

      true when every spot must carry a value. Absent means false.

    • filterablebooleanrequired

      Whether buyers can filter by it (number, date, checkbox and singleSelect).

    • placeholderstring or nullrequired

      Editor placeholder text.

    • numUnitstring or nullrequired

      Unit label for number properties.

    • optionsarray of objectsrequired

      Options of checkbox and singleSelect properties.

      Show 4 fields
      • idstringrequired

        The option's immutable id: the value spots store.

      • labelstringrequired

        The option's label.

      • ordernumberrequired

        Display order (ascending).

      • archivedbooleanrequired

        true when the option is retired; stored values stay.

    • archivedbooleanrequired

      true when the property is archived; stored values stay.

    • schemaVersionnumberrequired

      The guide's property schema version after the last change.

Response 200
{
  "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
  "schemaVersion": 6,
  "properties": [
    {
      "propertyDefId": "kh75t2w9q4r6y8v0j1p3p5a7s9d1f3g5",
      "key": "best_time",
      "label": "Best time",
      "kind": "singleSelect",
      "order": 0,
      "required": false,
      "filterable": true,
      "placeholder": null,
      "numUnit": null,
      "options": [
        {
          "id": "sunrise",
          "label": "Sunrise",
          "order": 0,
          "archived": false
        },
        {
          "id": "morning",
          "label": "Morning",
          "order": 1,
          "archived": false
        },
        {
          "id": "midday",
          "label": "Midday",
          "order": 2,
          "archived": false
        },
        {
          "id": "sunset",
          "label": "Sunset",
          "order": 3,
          "archived": false
        }
      ],
      "archived": false,
      "schemaVersion": 2
    },
    {
      "propertyDefId": "kh7b3n5m7q9w1e3r5t7y9v1j3p5p7a9s",
      "key": "crowds",
      "label": "Crowds",
      "kind": "singleSelect",
      "order": 1,
      "required": false,
      "filterable": true,
      "placeholder": null,
      "numUnit": null,
      "options": [
        {
          "id": "quiet",
          "label": "Quiet",
          "order": 0,
          "archived": false
        },
        {
          "id": "busy",
          "label": "Busy",
          "order": 1,
          "archived": false
        },
        {
          "id": "packed",
          "label": "Packed",
          "order": 2,
          "archived": false
        }
      ],
      "archived": false,
      "schemaVersion": 3
    },
    {
      "propertyDefId": "kh75b789hrwaq3kafenm0xbb6v34gh06",
      "key": "photo_notes",
      "label": "Photo notes",
      "kind": "longSection",
      "order": 2,
      "required": false,
      "filterable": false,
      "placeholder": "Lens, framing, where to stand",
      "numUnit": null,
      "options": [],
      "archived": false,
      "schemaVersion": 4
    },
    {
      "propertyDefId": "kh7v7h8st8cr913jb2kzb839yxjtpkdf",
      "key": "lens",
      "label": "Lens",
      "kind": "shortLabel",
      "order": 3,
      "required": false,
      "filterable": false,
      "placeholder": "16-35 mm",
      "numUnit": null,
      "options": [],
      "archived": true,
      "schemaVersion": 6
    }
  ]
}

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).
  • 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.
  • 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.
  • 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.