# list_media

Photos of a guide with their owner rows.

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

Every photo with URL, thumbUrl (the ~640 px variant; made on the server for API uploads, usually within seconds), caption, alt, credit, dimensions, focal point, provenance and review fields, and the row it belongs to (spot, product, collection or listing). Uploading is a plain HTTP request, see whoami.endpoints.upload (one file) or whoami.endpoints.uploadBatch (up to 10 with a JSON manifest) and the authoring guide.

## Path parameters

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

## Query parameters

- `marketingOnly` (boolean, optional): true returns only product- and listing-owned photos (sales page candidates).

## Returns

200.

- `productId` (string, required): The guide's id.
- `media` (array of Photo, required): Every photo of the guide in order.
  Fields of Photo: https://developers.sceniq.earth/fields/photo.md

## Examples

### Every photo of a guide, with its owner row

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

MCP `tools/call`:

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

Response 200:

```json
{
  "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
  "media": [
    {
      "mediaId": "kg71s3d5f7g9h1j3k5k7z9x1c3v5b7n9",
      "url": "https://quiet-heron-512.convex.cloud/api/storage/grand-prismatic-overlook.webp",
      "thumbUrl": "https://quiet-heron-512.convex.cloud/api/storage/grand-prismatic-overlook-640.webp",
      "ownerType": "spot",
      "ownerId": "k1709e2vj4sk8q6x0d3m5r7t9w1y3b5c",
      "caption": "Grand Prismatic Spring from the overlook, mid morning",
      "alt": "A deep blue pool ringed with orange and yellow, steam drifting over the boardwalk below",
      "credit": "Mara Lindgren",
      "width": 2048,
      "height": 1365,
      "order": 1024,
      "focalX": 0.52,
      "focalY": 0.46,
      "sourcePageUrl": null,
      "licence": null,
      "creditUrl": null,
      "shows": {
        "kind": "spot"
      },
      "takenAt": {
        "lat": 44.5199,
        "lon": -110.8406,
        "precision": "gps"
      },
      "locationVerifiedBy": "geotag",
      "capturedOn": "2026-09-14",
      "reviewNotes": null
    },
    {
      "mediaId": "kg7q8w6e4r2t0y8v6j4p2p0a8s6d4f2g",
      "url": "https://quiet-heron-512.convex.cloud/api/storage/hero-grand-prismatic.webp",
      "thumbUrl": "https://quiet-heron-512.convex.cloud/api/storage/hero-grand-prismatic-640.webp",
      "ownerType": "product",
      "ownerId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
      "caption": "Grand Prismatic Spring from the overlook",
      "alt": "A deep blue pool ringed with orange and yellow, steam drifting over the boardwalk below",
      "credit": "Mara Lindgren",
      "width": 2048,
      "height": 1365,
      "order": 1024,
      "focalX": 0.52,
      "focalY": 0.46,
      "sourcePageUrl": null,
      "licence": null,
      "creditUrl": null,
      "shows": {
        "kind": "spot"
      },
      "takenAt": null,
      "locationVerifiedBy": null,
      "capturedOn": null,
      "reviewNotes": null
    },
    {
      "mediaId": "kg7p2p4j6v8y0t2r4e6w8q0a2s4d6f8g",
      "url": "https://quiet-heron-512.convex.cloud/api/storage/grand-prismatic-aerial.webp",
      "thumbUrl": "https://quiet-heron-512.convex.cloud/api/storage/grand-prismatic-aerial-640.webp",
      "ownerType": "spot",
      "ownerId": "k1709e2vj4sk8q6x0d3m5r7t9w1y3b5c",
      "caption": "Grand Prismatic Spring and Midway Geyser Basin from above",
      "alt": "An aerial view of a deep blue hot spring ringed in orange and yellow, with steam, the boardwalk and the Firehole River beside it",
      "credit": "Brocken Inaglory",
      "width": 2048,
      "height": 1365,
      "order": 2048,
      "focalX": null,
      "focalY": null,
      "sourcePageUrl": "https://commons.wikimedia.org/wiki/File:Grand_Prismatic_Spring_and_Midway_Geyser_Basin_from_above.jpg",
      "licence": "CC BY-SA 3.0",
      "creditUrl": "http://commons.wikimedia.org/wiki/User:Brocken_Inaglory",
      "shows": {
        "kind": "spot",
        "label": "From above"
      },
      "takenAt": null,
      "locationVerifiedBy": "photographer_caption",
      "capturedOn": "2008-07-30",
      "reviewNotes": null
    }
  ]
}
```

### Only the photos a sales page may use (product and listing photos)

```bash
curl "https://sceniq.earth/api/v1/guides/j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2/media?marketingOnly=true" \
  -H "Authorization: Bearer $SCENIQ_API_KEY"
```

MCP `tools/call`:

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

Response 200:

```json
{
  "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
  "media": [
    {
      "mediaId": "kg7q8w6e4r2t0y8v6j4p2p0a8s6d4f2g",
      "url": "https://quiet-heron-512.convex.cloud/api/storage/hero-grand-prismatic.webp",
      "thumbUrl": "https://quiet-heron-512.convex.cloud/api/storage/hero-grand-prismatic-640.webp",
      "ownerType": "product",
      "ownerId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
      "caption": "Grand Prismatic Spring from the overlook",
      "alt": "A deep blue pool ringed with orange and yellow, steam drifting over the boardwalk below",
      "credit": "Mara Lindgren",
      "width": 2048,
      "height": 1365,
      "order": 1024,
      "focalX": 0.52,
      "focalY": 0.46,
      "sourcePageUrl": null,
      "licence": null,
      "creditUrl": null,
      "shows": {
        "kind": "spot"
      },
      "takenAt": null,
      "locationVerifiedBy": null,
      "capturedOn": null,
      "reviewNotes": null
    },
    {
      "mediaId": "kg7b4n6m8q0w2e4r6t8y0v2j4p6p8a0s",
      "url": "https://quiet-heron-512.convex.cloud/api/storage/guide-map-yellowstone.webp",
      "thumbUrl": "https://quiet-heron-512.convex.cloud/api/storage/guide-map-yellowstone-640.webp",
      "ownerType": "listing",
      "ownerId": "kr7w1e3r5t7y9v1j3p5p7a9s1d3f5g7h",
      "caption": "The guide's map of Yellowstone in the Sceniq app",
      "alt": "A phone showing a map of Yellowstone with pins for viewpoints, trailheads and parking",
      "credit": null,
      "width": 1638,
      "height": 2048,
      "order": 1024,
      "focalX": null,
      "focalY": null,
      "sourcePageUrl": null,
      "licence": null,
      "creditUrl": null,
      "shows": null,
      "takenAt": null,
      "locationVerifiedBy": null,
      "capturedOn": null,
      "reviewNotes": null
    },
    {
      "mediaId": "kg7t5y7v9j1p3p5a7s9d1f3g5h7j9k1k",
      "url": "https://quiet-heron-512.convex.cloud/api/storage/tunnel-view-first-light.webp",
      "thumbUrl": "https://quiet-heron-512.convex.cloud/api/storage/tunnel-view-first-light-640.webp",
      "ownerType": "product",
      "ownerId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
      "caption": "Tunnel View at first light",
      "alt": "Yosemite Valley at sunrise: El Capitan on the left, Half Dome ahead, Bridalveil Fall on the right",
      "credit": "Mara Lindgren",
      "width": 2048,
      "height": 1365,
      "order": 2048,
      "focalX": null,
      "focalY": null,
      "sourcePageUrl": null,
      "licence": null,
      "creditUrl": null,
      "shows": {
        "kind": "view_from_spot"
      },
      "takenAt": null,
      "locationVerifiedBy": null,
      "capturedOn": null,
      "reviewNotes": null
    }
  ]
}
```

## 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_media