API Documentation

Base URL: https://linkpeek-api.linkpeek.workers.dev

Authentication

All preview endpoints require an API key. Pass it via any of:

Query parameter: ?key=YOUR_KEY
Header: X-API-Key: YOUR_KEY
Header: Authorization: Bearer YOUR_KEY

Endpoints

POST /v1/register

Create a free API key.

Request body (JSON):

{ "email": "you@example.com" }

Response:

{
  "api_key": "lp_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345",
  "plan": "free",
  "daily_limit": 100,
  "message": "Save your API key - it cannot be recovered."
}

Rate limit: 5 registrations per IP per hour.

GET /v1/preview

Extract metadata from a URL.

Parameter	Type	Description
url	string (required)	The URL to preview
key	string (required)	Your API key

Response:

{
  "url": "https://github.com",
  "title": "GitHub: Let's build from here",
  "description": "GitHub is where over 100 million developers...",
  "image": "https://github.githubassets.com/assets/social.png",
  "site_name": "GitHub",
  "favicon": "https://github.githubassets.com/favicons/favicon.svg",
  "type": "website"
}

Response headers:

Header	Description
X-Cache	HIT or MISS
X-RateLimit-Limit	Your daily request limit
X-RateLimit-Remaining	Requests remaining today
X-RateLimit-Reset	When the limit resets (ISO 8601)

GET /v1/preview/image

Generate an SVG preview card from a URL.

Parameter	Type	Description
url	string (required)	The URL to preview
key	string (required)	Your API key

Response: SVG image (Content-Type: image/svg+xml)

Embed directly:

<img src="https://linkpeek-api.linkpeek.workers.dev/v1/preview/image?url=https://github.com&key=YOUR_KEY" />

GET /v1/usage

Check your usage statistics.

{
  "plan": "free",
  "daily_limit": 100,
  "today": 42,
  "total": 1337
}

GET /health

Health check endpoint. No authentication required.

Error Codes

Status	Meaning
400	Bad request (missing or invalid parameters)
401	API key not provided
403	Invalid API key
429	Rate limit exceeded
502	Failed to fetch target URL

Rate Limits

Plan	Requests/day	Price
Free	100	$0
Pro	5,000	$9/mo
Business	50,000	$29/mo