Reference

Social sharing

When a dropfast.dev/s/<slug>/ link is pasted into Slack, X, LinkedIn, or iMessage, it renders a preview card — a title, description, and a 1200×630 image. DropFast gives every site a branded card by default and lets you replace the image three ways. The card metadata (og:* + twitter:card) is injected into the served index page automatically; you never edit HTML.

The default: an auto-generated card

Publish anything and the link already has a card — no setup. DropFast renders a 1200×630 PNG with the site's title, a short excerpt, and the site URL, in the DropFast brand style. It's served from:

GET https://dropfast.dev/api/og/<slug>

The card is regenerated whenever the site's content or settings change, and its URL carries a ?v=<timestamp> cache-buster so social crawlers always fetch the current version.

Access mirrors the site exactly. A private, password, or restricted site's card returns 404 to anyone who can't already view the site — no title or excerpt leaks to an anonymous crawler. (It's a 404, not a 403, so a card request can't even confirm that a private site exists.)

Three ways to set a custom image

1. A URL

Point the card at any absolute https:// image, or a path on your own site:

# REST
curl -X PATCH https://dropfast.dev/api/v1/sites/<slug> \
  -H "Authorization: Bearer df_sk_..." \
  -H "content-type: application/json" \
  -d '{"ogImageUrl":"https://cdn.example.com/card.png"}'
 
# CLI
dropfast sites set <slug> --og-image https://cdn.example.com/card.png

2. Upload an image

Upload a PNG, JPEG, or WebP (≤ 5 MB) and DropFast hosts it for you, content-addressed and immutable:

# REST — multipart with an `image` field
curl -X POST https://dropfast.dev/api/v1/sites/<slug>/og-image \
  -H "Authorization: Bearer df_sk_..." \
  -F "image=@card.png"
 
# CLI — a local file path is detected and uploaded automatically
dropfast sites set <slug> --og-image ./card.png

The response returns both the stored setting and the effective URL:

{ "success": true,
  "data": { "ogImageUrl": "/api/og/file/<sha256>.<ext>",
            "ogImage": "https://dropfast.dev/api/og/file/<sha256>.<ext>" } }

(<ext> is png, jpg, or webp — the extension is derived from the image's actual bytes, so a JPEG uploads as .jpg regardless of its filename.)

In the dashboard, the site's Social preview block has a live card preview, a URL field, an Upload image button, and Reset to auto card.

3. The zip convention

Drop a file named og_image.png (or .jpg / .jpeg / .webp / .gif) at the root of an uploaded zip and DropFast uses it as the card automatically — no flag needed. This is the zero-config path for agents and the CLI: bundle the image and publish.

site.zip
├── index.html
├── og_image.png   ← auto-detected as the social card
└── styles.css

An explicit ogImageUrl on the request always wins over the convention. The convention is also self-healing: if a later re-upload drops the og_image.* file, the card resets to the auto card. A custom URL or uploaded image you set explicitly is never touched by a file re-upload.

Every response carries two fields

Across REST, MCP, and the CLI, a site object exposes:

• ogImageUrl — the stored setting: null (auto card), an https URL, or a single-leading-slash path (/og_image.png, /api/og/file/<sha>.png).
• ogImage — the effective absolute URL of the card the served page advertises. Use this to preview or embed the card.

On an existing site, send ogImageUrl: null (via PATCH) or --og-image none (CLI) to clear a custom image back to the auto card. On create, there's no null — just omit ogImageUrl for the auto card.

What gets injected, and where

DropFast injects og:title, og:description, og:image (+ og:image:width/height), og:url, og:type, and twitter:card=summary_large_image into the served HTML — but only:

• on the site's index page (sub-pages aren't the share target), and
• for the current version (a ?v=<n> pinned URL serves immutable content, so no mutable meta is added), and
• when your HTML doesn't already declare an og:image — if you ship your own, DropFast leaves it untouched.

Notes and limits

• Site-relative images and gated sites. A site-relative image (including the zip convention's /og_image.png) only renders a preview for public sites — a crawler can't fetch it for a private site. Use an uploaded image or the auto card for gated sites.
• CDN staleness on an access flip. Flipping a site from public to private can leave the old public card URL cached at the CDN edge for up to 24h — the same accepted behavior as the site's own HTML.
• URLs are validated for shape, not reachability. A custom ogImageUrl must be an https:// URL or a single-leading-slash path; http://, protocol-relative //, data:, and javascript: are rejected with INVALID_OG_IMAGE_URL. The dashboard preview gives you visual feedback.