{"openapi":"3.1.0","info":{"title":"InstaFetch Public & Developer API","version":"1.0.0","description":"High-performance REST API for resolving public Instagram posts, reels, stories, highlights, profile DPs, and carousels with expiring signed streaming links."},"servers":[{"url":"/api/v1","description":"API v1 Gateway"}],"paths":{"/health":{"get":{"summary":"Gateway Health Check","description":"Returns operational status of the API Gateway, KV cache, D1 database, and Extractor service.","responses":{"200":{"description":"Gateway is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"timestamp":{"type":"string","format":"date-time"},"version":{"type":"string","example":"1.0.0"}}}}}}}}},"/resolve":{"post":{"summary":"Resolve Instagram URL or Username","description":"Parses an Instagram link, validates DMCA blocklists, checks KV cache, and resolves media metadata with signed download tokens.","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Developer API key for programmatic usage."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"Instagram URL or @username (e.g. https://www.instagram.com/reel/C8AbCdEfGhI/)","example":"https://www.instagram.com/p/C7g-e31uP_M/"},"turnstileToken":{"type":"string","description":"Cloudflare Turnstile token from web client (optional if using X-API-Key)."}}}}}},"responses":{"200":{"description":"Media successfully resolved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"type":{"type":"string","example":"post"},"id":{"type":"string","example":"C7g-e31uP_M"},"owner":{"type":"object","properties":{"username":{"type":"string","example":"instagram"},"fullName":{"type":"string"},"profilePicUrl":{"type":"string"}}},"caption":{"type":"string"},"itemCount":{"type":"number","example":1},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["image","video","audio"]},"downloadUrl":{"type":"string","description":"Expiring signed download URL"},"thumbnail":{"type":"string"},"filename":{"type":"string"}}}},"isCarousel":{"type":"boolean"},"zipDownloadUrl":{"type":"string"}}}}}}}},"400":{"description":"Invalid Instagram URL"},"403":{"description":"Content is private or DMCA blocked"},"404":{"description":"Instagram media not found"},"429":{"description":"Rate limit or monthly quota exceeded"},"503":{"description":"Extractor service temporarily unavailable"}}}},"/download":{"get":{"summary":"Stream Media File","description":"Streams media securely from Instagram CDNs using an HMAC-signed expiring token with proper Content-Disposition and Range support.","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string"},"description":"Expiring HMAC-signed download token returned from /resolve"}],"responses":{"200":{"description":"Direct binary stream of image or video"},"206":{"description":"Partial content stream for HTTP Range requests"},"401":{"description":"Invalid or expired token"},"403":{"description":"Hostname not permitted by SSRF allowlist"}}}},"/zip":{"get":{"summary":"Stream Carousel ZIP Archive","description":"Streams a ZIP archive containing all carousel images and videos.","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string"},"description":"Expiring HMAC-signed ZIP token returned from /resolve"}],"responses":{"200":{"description":"Streaming application/zip file"}}}},"/dmca":{"post":{"summary":"Submit DMCA Copyright Takedown Notice","description":"Records a formal copyright takedown request. Content will be reviewed and placed on the resolution blocklist.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reporterName","reporterEmail","targetUrl","copyrightWorkDescription","jurisdictionConfirmation","signature"],"properties":{"reporterName":{"type":"string"},"reporterEmail":{"type":"string","format":"email"},"targetUrl":{"type":"string"},"copyrightWorkDescription":{"type":"string"},"jurisdictionConfirmation":{"type":"boolean"},"signature":{"type":"string"}}}}}},"responses":{"200":{"description":"Takedown notice received","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"noticeId":{"type":"string"}}}}}}}}}}}