SceniqDevelopers

list_media

Photos of a guide with their owner rows.

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

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.

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

Path parameters

Query parameters

  • marketingOnlybooleanoptional

    true returns only product- and listing-owned photos (sales page candidates).

Returns

200 OK with this object.

  • productIdstring · guide idrequired

    The guide's id.

  • mediaarray of Photorequired

    Every photo of the guide in order.

    Show 21 fieldsof Photo
    • mediaIdstring · photo idrequired

      The photo's id.

    • urlstringrequired

      The stored photo (at most 2048 px on the long side).

    • thumbUrlstring or nullrequired

      The ~640 px variant, or null until it is made.

    • ownerTypestringrequired

      What the photo belongs to.

      spotproductcollectionlisting
    • ownerIdstringrequired

      The owner row's id.

    • captionstring or nullrequired

      Caption.

    • altstring or nullrequired

      Alt text.

    • creditstring or nullrequired

      Photographer credit.

    • widthnumber or nullrequired

      Width in pixels.

    • heightnumber or nullrequired

      Height in pixels.

    • ordernumberrequired

      Position in the owner's gallery (ascending, fractional).

    • focalXnumber or nullrequired

      Focal point from 0 (left) to 1 (right).

    • focalYnumber or nullrequired

      Focal point from 0 (top) to 1 (bottom).

    • sourcePageUrlstring or nullrequired

      The page the photo was licensed from.

    • licencestring or nullrequired

      Licence name.

    • creditUrlstring or nullrequired

      The photographer's profile page.

    • showsPhotoShows or nullrequired

      What the photo shows.

      Show 2 fieldsof PhotoShows
      • kindstringrequired

        spot (the place itself), view_from_spot (the view from it), nearby (a sight near the spot; readiness then skips its distance check), approach (the way there), detail or other.

        spotview_from_spotnearbyapproachdetailother
      • labelstringoptional

        What exactly it shows, at most 80 characters (the north face from the lake).

    • takenAtPhotoTakenAt or nullrequired

      Where it was taken.

      Show 3 fieldsof PhotoTakenAt
      • latnumberrequired

        Latitude in decimal degrees (-90 to 90).

      • lonnumberrequired

        Longitude in decimal degrees (-180 to 180).

      • precisionstringrequired

        gps (a camera or phone fix), geocode (looked up from a place name, often coarse on stock sites) or none (an estimate; readiness lists it as resting on judgement).

        gpsgeocodenone
    • locationVerifiedBystring or nullrequired

      How the location was confirmed.

      geotaglandmarkphotographer_captioncreatorother
    • capturedOnstring or nullrequired

      Capture date (YYYY-MM-DD).

    • reviewNotesstring or nullrequired

      Notes for the creator's review, never shown to buyers.

Response 200
{
  "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
    }
  ]
}

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.