source.unsplash.com Is Gone: The Post-Mortem and Every Way to Replace It

A stock photo service turned off a subdomain, and two years later it is still breaking documentation sites, login screens, course exercises and freshly generated code. This is a post-mortem of a URL — what it did, what killed it, and what to put in its place — plus a measured look at the stranger part of the story: the machines that write our code have not noticed it is gone.

The HTTP responses, the two changelog entries quoted word for word, the API limits, the issue trackers of the projects that broke and the counts from GitHub, npm and Stack Overflow all come from primary sources, with the method for each one in the footnotes. If you only want the fix, jump to the migration table.

What you get today, if you still request it

One command, no key, reproducible from any machine:

curl -I https://source.unsplash.com/random

HTTP/2 503
cache-control: no-cache, no-store
content-type: text/html; charset=utf-8
server: Heroku
via: 2.0 heroku-router
# body: an iframe pointing at herokucdn.com/error-pages/application-error.html

Nothing here is a DNS failure. source.unsplash.com still resolves — it is a CNAME to a herokudns.com host — so the request is answered, just not by an application. That detail matters more than it sounds: a browser that gets a fast 503 with an HTML body renders a broken image placeholder, and any code that reads response.ok or an onerror handler you never wrote takes the failure path you never tested.

Swipe the table sideways to see every column →

Checked individually with curl -o /dev/null -w "%{http_code}". The search feature was wound down first, as announced; today the whole application is off, so the distinction no longer exists.

Three years between “deprecated” and “off”

Both announcements are still readable, in one place, at unsplash.com/documentation/changelog. Quoted in full, because the wording is the whole story:

25 November 2021 — “Unsplash Source being deprecated”
“Unsplash Source is being deprecated. Existing uses will continue to work, however for new projects use the full Unsplash API.”

11 June 2024 — “Unsplash Source sunset”
“Unsplash Source has been officially unsupported since its deprecation in 2021. As part of the final sunsetting, we will first wind down by disabling the search feature, and in the coming weeks turn off the application entirely. Existing uses of Source — particularly production-level ones — should migrate as soon as possible to the full Unsplash API.”

Read them in sequence and the failure mode is obvious. The 2021 notice contained a promise (existing uses will continue to work) and no date. A developer who read it in 2021 had every reason to leave working code alone; a developer who joined in 2022 never read it at all. The 2024 notice gave “the coming weeks”, three years later, on a page nobody had bookmarked.

Unsplash does publish a deprecation policy, and it is a reasonable one — the documentation states that for publicly documented fields and endpoints, changes are announced on the changelog with at least 3 weeks of notice, and endpoints return a Warning header during the deprecation period. The same paragraph contains the sentence that explains why none of it protected Source: “For any non-publicly documented fields or endpoints, we may make changes to these with no warning.” Source was never an endpoint of the documented API. It sat outside the policy that would have covered it.

• The practical lesson is not “Unsplash was careless”. It is that a URL you can use without reading any documentation is a URL whose deprecation policy you have also not read.
• Breakage preceded the announcement. A Drupal issue filed on 28 November 2022 already reports “I get always a Heroku application error”, eighteen months before the sunset entry. Intermittent failure is how these services die: slowly, then in an announcement you never see.

The announcement is harder to find than the outage

The 2021 deprecation was published on changelog.unsplash.com, and that is the URL every contemporaneous bug report links to — including the Drupal one above. Three measurements:

1. The HTTPS endpoint is broken. openssl s_client -connect changelog.unsplash.com:443 returns tlsv1 alert internal error — the handshake fails before any certificate is presented. Every 2021-era link, which was https://, is therefore dead in a browser.
2. Over plain HTTP it redirects, but not usefully. Following http://changelog.unsplash.com/deprecations/2021/11/25/source-deprecation.html ends, two hops later, on a 400 at unsplash.com/@documentation/changelog/deprecations/2021/11/25/source-deprecation/html — the path has been swallowed by the site's username route.
3. The archive has a hole where the sunset is. The Wayback Machine's last successful capture of the old changelog is 24 March 2024; its first capture of the new one is 23 August 2024. The sunset was announced on 11 June 2024 — inside that five-month gap.

None of that is a conspiracy; it is an ordinary CMS migration. But the consequence is real, and it is the reason this article quotes both entries in full: the primary record of a deprecation should outlive the thing it deprecated, and here it very nearly did not.

What actually broke

Not side projects. The failures below are public issue-tracker entries; the titles, dates and states come from the GitHub and drupal.org APIs.

Swipe the table sideways to see every column →

Read that last row again, because it is the one worth internalising. A decorative image next to a login form — the most obviously non-critical asset on the page — degraded into an authentication outage, because a slow third-party request sat in front of the CAPTCHA the login form needed. Nobody wrote it that way. It emerged from the order in which a browser loads things.

Your coding assistant did not get the memo

Here is the part that turns a 2024 outage into a 2026 problem. source.unsplash.com was documented, blogged, taught and copied for roughly eight years. All of that text is in the training data of the models that now write our starter code — and text does not expire. Three counts:

Swipe the table sideways to see every column →

The most direct evidence is not in application code at all — it is in prompts. The top result for that search is a library of GPT system prompts containing the line “please use unsplash API( https://source.unsplash.com/1280x720/?<PUT YOUR QUERY HERE>”. That instruction is still being copied into new assistants today. The model does not verify the URL; it was told to use it, and every example it ever saw agreed.

So the generated-code failure has two independent causes, and fixing one does not fix the other: stale training data, and stale instructions written by humans on top of it. Either way, the symptom is the same family of images that never load:

source.unsplash.com/random/1200x800   # 503 since mid-2024 — never comes back
images.unsplash.com/photo-…           # real CDN, but memorised IDs may not exist
via.placeholder.com/400               # grey rectangle, shipped to production
placehold.co/800x600                  # grey rectangle, on purpose
picsum.photos/800/600                 # a real photo, unrelated to your page
/placeholder.png                      # a file that was never added to the repo

A footnote on the second line of that list: while writing this, via.placeholder.com would not complete a TLS handshake from our test network either, and answered 403 over plain HTTP. Check it from your own network before trusting it — the fallback these tools reach for may have an outage story of its own.

Only the first one is broken. The others are worse in a subtler way: they load, the layout looks finished, and nobody notices that the page is illustrated with nothing in particular. And none of this is specific to images — it is the general shape of the problem. A model's picture of the web is a snapshot, and endpoints, CLI flags, package names and free tiers keep moving after the shutter closes.

The migration table

There are exactly three destinations, and the honest way to present them is by what you give up. Pick the column first, then read your row.

Swipe the table sideways to see every column →

Option A is the one most people actually want. If the image was decorative — a hero, a login side panel, a card background — you never needed a different photo on every request. Choose one, keep the CDN URL, and the page stops depending on anything random:

<img src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=1600&h=900&fit=crop&auto=format"
     width="1600" height="900" alt="…">
# Officially supported params: w, h, crop, fit, fm, auto=format, q, dpr.
# Keep any ixid parameter the API gave you — it is what reports the view.

Option B is the official path, and it moves the call server-side, because a Client-ID in front-end JavaScript is a published credential. Note the two rules that trip people up: collections/topics cannot be combined with query in the same request, and count (max 30) changes the response shape to an array even when it is 1.

curl "https://api.unsplash.com/photos/random?query=nature&orientation=landscape" \
  -H "Authorization: Client-ID YOUR_ACCESS_KEY" \
  -H "Accept-Version: v1"

# → JSON. The image lives at .urls.regular / .urls.raw (add w/h/fit yourself).
# → X-Ratelimit-Limit: 1000   X-Ratelimit-Remaining: 999

Option C: rebuild Source, in about forty lines

If what you lost was genuinely the behaviour — a keyless URL that returns a different photo each time, usable straight from an <img> tag, in a CMS field, or in a static site where there is no server — then you have to run that endpoint yourself. It is one small worker in front of the API, and the three things that make it survive contact with production are the cache, the referrer check, and passing the rest of the query string through to the CDN.

// Cloudflare Workers. Elsewhere (Deno Deploy, Val Town…) the shape is the same,
// but open a named cache with caches.open() instead of caches.default.
// UNSPLASH_KEY stays server-side. Callers never see it.
const ALLOWED = ["example.com", "www.example.com"];   // your domains only
const API_PARAMS = ["query", "collections", "topics", "username", "orientation"];
const TTL = 60;                                       // seconds — protects the hourly quota

const host = (value) => { try { return new URL(value).hostname; } catch { return null; } };

export default {
  async fetch(req, env, ctx) {
    // 0. GET only: the Cache API refuses to store anything else, and an image
    //    endpoint has no other verb to answer.
    if (req.method !== "GET")
      return new Response("Method not allowed", { status: 405 });
    const url = new URL(req.url);

    // 1. Only your own pages may embed it — a public random-photo endpoint
    //    on the open internet is someone else's rate limit to burn.
    const ref = req.headers.get("referer");       // absent on plenty of legit clients
    if (ref && !ALLOWED.includes(host(ref)))
      return new Response("Forbidden", { status: 403 });

    // 2. Cache per parameter combination, so a page with 12 images
    //    costs one API call per minute instead of twelve per render.
    const cache = caches.default;
    const hit = await cache.match(req);
    if (hit) return hit;

    // 3. Ask the official API for a random photo.
    const api = new URL("https://api.unsplash.com/photos/random");
    for (const p of API_PARAMS)
      if (url.searchParams.has(p)) api.searchParams.set(p, url.searchParams.get(p));

    const r = await fetch(api, { headers: {
      Authorization: "Client-ID " + env.UNSPLASH_KEY,
      "Accept-Version": "v1",
    }});
    // 403 here usually means the hourly quota, not a bad key — raise TTL, not panic.
    if (!r.ok) return new Response("Upstream " + r.status, { status: 502 });
    const photo = await r.json();

    // 4. Rebuild the image URL: keep ixid, append the caller's sizing params.
    const img = new URL(photo.urls.raw);          // .raw already carries ixid
    for (const [k, v] of url.searchParams)
      if (!API_PARAMS.includes(k)) img.searchParams.set(k, v);  // w, h, fit, q…

    const res = new Response(null, { status: 302, headers: {
      Location: img.toString(),
      "Cache-Control": "public, max-age=" + TTL,
      // Credit travels with the redirect; header values must be ASCII, hence the encoding.
      "X-Photo-Credit": encodeURIComponent(photo.user.name + " on Unsplash"),
      "X-Photo-Link": photo.links.html,
    }});
    ctx.waitUntil(cache.put(req, res.clone()));
    return res;
  },
};

Migrating a URL is then a search-and-replace, which is exactly what makes this option worth the twenty minutes:

- https://source.unsplash.com/collection/67920491/1600x900
+ https://img.example.com/?collections=67920491&w=1600&h=900&fit=crop

Two design notes, both of which cost someone a bad afternoon before they were written down. The redirect (302) rather than proxying the bytes keeps you off the hook for bandwidth and keeps the view counted on Unsplash's CDN, which is what the guidelines ask for. And the Referer check is deliberately permissive when the header is absent — plenty of legitimate clients strip it — while still stopping the obvious case where your endpoint becomes somebody else's free image API.

The rules you inherit the moment you use the API

Source had no rules because it had no account. The API has five that change how you architect the thing, all from the current documentation:

• Rate limits are per hour, and small at first. 50 requests/hour in demo mode; 1,000/hour after your application is approved for production. Only calls to api.unsplash.com count — image requests to images.unsplash.com do not. Read X-Ratelimit-Remaining on every response.
• Hotlinking is mandatory, not merely allowed. Unsplash requires that the image URLs the API returns be embedded directly, so photo views can be attributed to the photographer. Mirroring the file onto your own CDN is the one optimisation you are not free to make.
• Keep the ixid parameter. Resizing and cropping the returned URL is expected; stripping the parameter that identifies your application is not.
• Attribution and download tracking are part of the deal — the photographer and Unsplash get credited, and a “download” is reported through the photo's download endpoint when a user takes the file, which is an event you have to fire yourself.
• Distributed products need dynamic client registration. If you ship a plugin, a theme or a self-hosted CMS, one shared key is both a policy violation and a single point of failure; the API has a registration flow for exactly that case.

This is the moment to be honest about scope: if you are wiring up an API and a key anyway, the choice of which image API is suddenly open, and it is worth spending five minutes on before you write the client. We compared the free ones — quotas, rules, search behaviour and response shapes — in the free stock photo API comparison.

If you only wanted a placeholder, say so

A large share of Source usage was never about Unsplash. It was “put something image-shaped here while I build the layout”. For that, keyless services still exist and are the correct answer:

Swipe the table sideways to see every column →

The distinction that matters: a placeholder is temporary by definition. If the image survives to production, it is not a placeholder any more — it is an illustration that nobody chose, and the reader can tell.

One key instead of three

Here is the part of the migration nobody plans for: people leaving Source rarely land on one API. A page needs a hero, two section images and something for a card grid, and the honest answer is usually Unsplash plus Pexels plus Pixabay — three registrations, three auth schemes, three JSON shapes, three pagination models and three sets of attribution rules, all to fill the same <img> tags. That integration work is the real bill for a keyless URL going away, and it lands weeks after the outage that caused it.

Collapsing that into one integration is what we built Pexafy for: a single key over 9 free-licence libraries in one schema, with sentence-level semantic search — so a full description like “a cracked phone screen on a wooden desk, shot from above” returns ranked results instead of nothing. Two limits, stated plainly, because this whole article is about not being surprised twice: it needs a key, so it does not restore what Source was — it belongs in the same category as the official Unsplash API above; and it carries free-licence photography, not editorial or brand imagery.

The piece that is genuinely new is aimed at the assistants above: an MCP server at mcp.pexafy.com/mcp means a model that would otherwise recite an image URL from memory can search a real catalogue and return a photo that exists, with its credit line attached. That is a better answer to machine-written dead URLs than any lint rule, and the reasoning is written up in image search infrastructure for AI agents.

Audit your estate in ten minutes

Whatever you migrate to, do this part first — you cannot fix URLs you have not found. Source is just today's example; the same three steps apply to every external asset you embed.

# 1. Everything in the repo, including docs, tests, fixtures and READMEs.
grep -rn --binary-files=without-match \
  -e "source.unsplash.com" -e "via.placeholder.com" -e "/placeholder.png" .

# 2. Everything the database holds — CMS bodies are where these hide longest.
psql -c "SELECT id FROM posts WHERE body LIKE '%source.unsplash.com%'"

# 3. Everything the built site actually requests: crawl it and list the failures.
#    Match the attribute, not a file extension — image URLs rarely end in .jpg.
grep -rhoE 'src="[^"]+"' dist/ \
  | cut -d'"' -f2 | grep -E '^https?://' | sort -u \
  | xargs -P8 -I{} curl -s -o /dev/null -w "%{http_code} {}\n" {} \
  | grep -v "^200"

# 503 https://source.unsplash.com/random/1200x800   ← what you are looking for

Then decide, once, how much external images are allowed to cost you. Four rules that survive the next shutdown, whoever causes it:

1. Fetch at build time, not at request time. An image resolved during the build fails in CI, in front of a developer, instead of at 3 a.m. in front of a user.
2. Never let a decorative asset block a critical path. Preload nothing external above a login form; give every third-party <img> an onerror fallback and explicit width/height so a failure costs a blank box, not a layout shift or a stalled script.
3. Add the check to CI. Step 3 above, run on your built output, turns “someone eventually noticed” into a red build. It is the only step that prevents recurrence.
4. Budget your external dependencies like any other. Write down which hosts your pages are allowed to depend on and what happens when each one is down. A URL you did not have to register for is still a dependency — Source proved that it is simply one nobody owns.

References & footnotes