HTTP API

The same metadata behind an HTTP endpoint.

Fetch metadata#

The endpoint is https://api.linkoi.dev and requires an API key. Send it from your server in an Authorization: Bearer header. Never put the key in browser code.

curl --get "https://api.linkoi.dev/" \
  --data-urlencode "url=https://example.com" \
  -H "Authorization: Bearer $LINKOI_API_KEY"

json

{
  "status": "success",
  "data": { "url": "https://example.com/", "title": "Example", "...": "other Metadata fields" },
  "cache": "miss"
}

The response above is abbreviated. The data object has the full Metadata shape.

Query parameters#

Parameter	Behaviour
url	Required target URL.
fresh=true	Skip cache reads and update the cache with a new extraction.
fallback=false	Deprecated and ignored since 0.1.1. All extraction uses Linkoi’s own parser.

Cache states#

Value	Meaning
hit	Fresh cached result.
stale	Cached result returned while background revalidation runs.
miss	No cached result; extraction performed.
bypass	Cache read skipped with fresh=true.

Other routes#

DELETE /?url=... invalidates one cache key. GET /health returns { "ok": true }.

Authentication and errors#

When API_KEY is set, every route requires a bearer token. Without it, all routes, including invalidation, are public. Rate limiting and per-customer quotas are not included.

Missing or unsafe URLs return 400. Failed authentication returns 401. Fetch failures can return 400, 429, or 502; unexpected extraction failures return 500. Read the error body rather than assuming success.