Media Proxy

GET/api/v1/idap/media/{media_id}

Overview

Proxies binary media files from SpiderIQ's storage (SeaweedFS). Returns files with correct Content-Type headers. Used for screenshots, business photos, HTML bundles, and other media captured by SpiderLanding and SpiderMapsEnrich workers.

Supports conditional requests for efficient caching — your app can cache media aggressively since media rarely changes after creation.

Path Parameters

media_idstringrequired

The media identifier. This is the ID portion of an idap://media/{media_id} reference.

Example: screenshot-456, photo-abc123

Query Parameters

thumbbooleandefault: false

Return a thumbnail (max 400px) instead of the full-resolution image.

downloadbooleandefault: false

Set Content-Disposition: attachment header to force the browser to download the file instead of displaying it.

Response Headers

Header	Description
Content-Type	MIME type of the file (e.g., image/png, image/jpeg, text/html)
Content-Length	File size in bytes
ETag	Entity tag for conditional request caching
Last-Modified	Last modification timestamp
Content-Disposition	Only present when download=true — triggers file download

Conditional Requests (Caching)

The media proxy supports HTTP conditional requests for efficient caching:

Request Header	Description	Response
If-None-Match: "<etag>"	Send the ETag from a previous response	304 Not Modified if unchanged
If-Modified-Since: <date>	Send the Last-Modified from a previous response	304 Not Modified if unchanged

When a 304 is returned, no body is sent — your app uses its cached copy.

Example Request

cURL

# Fetch full image
curl "https://spideriq.ai/api/v1/idap/media/screenshot-456" \
  -H "Authorization: Bearer <your_token>" \
  --output screenshot.png

# Fetch thumbnail
curl "https://spideriq.ai/api/v1/idap/media/screenshot-456?thumb=true" \
  -H "Authorization: Bearer <your_token>" \
  --output thumb.png

# Download with filename
curl "https://spideriq.ai/api/v1/idap/media/screenshot-456?download=true" \
  -H "Authorization: Bearer <your_token>" \
  -OJ

# Conditional request (cache validation)
curl "https://spideriq.ai/api/v1/idap/media/screenshot-456" \
  -H "Authorization: Bearer <your_token>" \
  -H "If-None-Match: \"abc123etag\"" \
  -w "\nHTTP Status: %{http_code}\n"
# Returns 304 if unchanged, 200 with new content if changed

Python

import httpx

# Fetch media
response = httpx.get(
    "https://spideriq.ai/api/v1/idap/media/screenshot-456",
    headers={"Authorization": "Bearer <your_token>"},
)

# Save the file
with open("screenshot.png", "wb") as f:
    f.write(response.content)

# Store cache headers for next request
etag = response.headers.get("ETag")
last_modified = response.headers.get("Last-Modified")

# Later: conditional request
response = httpx.get(
    "https://spideriq.ai/api/v1/idap/media/screenshot-456",
    headers={
        "Authorization": "Bearer <your_token>",
        "If-None-Match": etag,
    },
)
if response.status_code == 304:
    print("Not modified — use cached version")
else:
    print("New content received")

Response Example

[Binary file content with headers:]
Content-Type: image/png
Content-Length: 145832
ETag: "a1b2c3d4e5f6"
Last-Modified: Sat, 10 Apr 2026 08:00:00 GMT

[No body — use cached copy]

{
  "detail": "media_not_found"
}

Notes

• Media resources cannot be fetched via the Batch Fetch endpoint — use this endpoint directly for each media file.
• Flags, Search, and Stats are not supported on media resources.
• Media files rarely change after creation — cache aggressively using the ETag and Last-Modified headers.