# list_properties

Custom spot property definitions of a guide.

`GET /v1/guides/{productId}/properties` · MCP tool `list_properties` · scope `read` · stable · since 2026-09-17

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.

## Path parameters

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

## Returns

200.

- `productId` (string, required): The guide's id.
- `schemaVersion` (number or null, required): The guide's property schema version.
- `properties` (array of Property, required): Every property definition, archived ones included.
  Fields of Property: https://developers.sceniq.earth/fields/property.md

## Examples

### List a guide's properties with their option ids

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

MCP `tools/call`:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_properties",
    "arguments": {
      "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2"
    }
  }
}
```

Response 200:

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

- `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).
- `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.
- `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.
- `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/list_properties