Get avatar

The one endpoint. Resolves a LinkedIn URL or username, then 302-redirects to the CDN-cached profile photo. On a miss, returns a deterministic SVG fallback at the size you requested.

GEThttps://avtrz.dev/v1/avatar

Query parameters

Name	Type		Description
key	string	Required	Your publishable (`pk_`) or secret (`sk_`) API key. May also be sent via the `x-api-key` header.
linkedin_url	string	Optional	Full LinkedIn profile URL (with or without scheme). One of `linkedin_url` or `username` is required.
username	string	Optional	LinkedIn handle (the path segment after `/in/`).
size	enum	Optional	One of `32`, `64`, `128`, `256`, `512`. Defaults to `128`.

Response

Successful lookups return a 302 Found with a Location header pointing at a CDN-cached image (WEBP or PNG, depending on the source). The redirect ships Cache-Control: public, max-age=86400, so browsers, proxies, and your CDN reuse it for 24 hours.

When no profile resolves, the endpoint streams a deterministic SVG fallback at the size you requested with Cache-Control: no-store, so a transient miss can't poison your cache.

Status codes

302

Profile resolved. Location header points at the CDN image.

200

No profile resolved. SVG fallback returned in the body.

304

If-None-Match matched the CDN image. No body, no billing.

401

Missing or invalid API key.

403

Plan quota exceeded, or domain not on the key's allow-list.

429

Rate-limited. Honor Retry-After and back off.

Response headers

Name	Type		Description
Cache-Control	header	Optional	`public, max-age=86400` on a 302 redirect. `no-store` on SVG fallbacks and error responses.
Location	header	Optional	Present on a 302. The CDN URL for the resolved image. Safe to hand back to the browser.
Retry-After	header	Optional	Present on 429. Seconds to wait before retrying.

Putting it together

A small Next.js route handler that proxies the avatar from your server. Keeps the secret key off the client, lets the browser follow the final redirect, and revalidates per the upstream cache headers.

TypeScriptapp/avatar/route.ts

import { NextResponse } from "next/server";

export async function GET(req: Request) {
  const linkedin_url = new URL(req.url).searchParams.get("linkedin_url");

  const upstream = await fetch(
    `https://avtrz.dev/v1/avatar?linkedin_url=${encodeURIComponent(linkedin_url!)}&size=128`,
    {
      headers: { "x-api-key": process.env.AVTRZ_SECRET! },
      redirect: "manual",
    }
  );

  const cdnUrl = upstream.headers.get("location");
  if (!cdnUrl) return NextResponse.json({ found: false });
  return NextResponse.redirect(cdnUrl, 302);
}

proxies upstream 302 · CDN-cached · 1 request billed

Ready to ship?

Head back to the quickstart for the copy-paste path, or open the console to grab a publishable key.

How it works