Hep.gg

Serving and embeds

How uploaded files are served (GET /:ID), custom domains and *.hep.gg hosts, social-media OpenGraph embeds, and the oEmbed companion document.

Serving and embeds

Once a file or shortlink is stored, it is served back from your account's host with no authentication. This page covers the public serve route, where it can be hosted, and how social platforms render rich embeds.

GEThttps://i.hep.gg/:IDPublic
Stream a stored file, redirect a shortlink, or return an embed page to social crawlers.

Fully public, no token required. The :ID slug is matched (with or without a file extension) against your stored uploads.

  • File rows stream the stored object with its content type.
  • Shortlink rows issue a 302 redirect to the target URL.
  • Social crawlers may receive an HTML embed page instead of raw bytes (see Social embeds).
Path and query
ID
stringrequired
The content ID, with or without its file extension. For example both abc123 and abc123.png resolve to the same upload.
embed
stringoptional
Optional query value. ?embed=raw forces the raw bytes and bypasses the social-embed HTML path. Crawlers fetch this variant to get the actual media for a preview.
curl
# Stream the file
curl -L https://i.hep.gg/abc123.png --output out.png
 
# Force raw bytes (skip any embed HTML)
curl -L "https://i.hep.gg/abc123.png?embed=raw" --output out.png

Each successful serve records a best-effort analytics view (IP, referrer, accept-language, user-agent) and increments the upload's view count. If the slug does not resolve, or the request host is not authorized for the owner, the request falls through to the catch-all rather than returning a JSON 404: on hep.gg it renders the standard 404 page, and on custom domains it redirects to the home page.

Hosts and custom domains

A file is served only on hosts that are authorized for its owner. The candidate hosts are:

  • i.hep.gg - the default serve host for every account.
  • Your *.hep.gg subdomain slot - always allowed for your own uploads.
  • Registered custom CDN domains - a domain is allowed if it is public, or premium-and-the-owner-is-premium, or owned by the uploader.

Add and verify custom domains from the uploader Domains subpage in the dashboard. Custom domains exist only to serve GET /:ID: a request to a custom domain's root path is redirected to https://hep.gg/.

Social embeds

When a known social or messaging crawler requests a file, and the owner has the embed proxy enabled, and the file is an image or video, the serve route returns an HTML page with OpenGraph and Twitter meta tags instead of the raw bytes. This is what produces rich link previews in chat apps. Regular browsers (and crawlers when the embed proxy is off) always get the file itself.

The embed proxy is opt-in and configured from the dashboard. When it is on:

  • The response is text/html with Cache-Control: private, no-store.
  • og:image points back at the same URL with ?embed=raw so the crawler fetches the real media.
  • Video files additionally get og:video and a Twitter player card; images get summary_large_image.
  • Title, description, and theme color come from your embed settings.

Crawlers detected for this path include Discord, Twitter/X, Slack, Telegram, Facebook, LinkedIn, Skype, WhatsApp, Google, Bing, Yandex, and Pinterest.

oEmbed companion

GEThttps://i.hep.gg/:ID/oembed.jsonPublic
oEmbed document Discord and other oembed-aware crawlers fetch to fill the author and provider slots.

The embed HTML links to an oEmbed document at /:ID/oembed.json. Discord and other oembed-aware crawlers fetch it to populate the author line and provider footer of a rich embed. It only returns data when the upload is a file, the owner has the embed proxy enabled, the request host is authorized for that owner, and the file is an image or video. Otherwise the request passes through with no JSON.

curl
curl https://i.hep.gg/abc123/oembed.json
{
  "version": "1.0",
  "type": "photo",
  "author_name": "@username",
  "author_url": "https://i.hep.gg",
  "provider_name": "Powered by Hep.gg",
  "provider_url": "https://hep.gg"
}
Response fields
version
stringoptional
Always "1.0".
type
stringoptional
"photo" for images, "video" for video files.
author_name
stringoptional
@<username> of the uploader, or anonymous if the account has no username.
author_url
stringoptional
https://<request-host>, the host the embed was served from.
provider_name
stringoptional
"Powered by Hep.gg".
provider_url
stringoptional
"https://hep.gg".

Lifetime upload counter

GEThttps://hep.gg/uploadCounterPublic
Public lifetime upload count across all of Hep.gg.

A legacy, unauthenticated endpoint that returns the lifetime number of uploads across Hep.gg (current uploads plus lifetime hard-deletes). It is kept for older integrations and intentionally returns a raw shape outside the standard envelope.

curl
curl https://hep.gg/uploadCounter
{
  "count": 1048576
}

On failure it returns 500 with { "error": "<message>" }.