HTTP API

The same metadata behind an HTTP endpoint.

Fetch metadata#

Create an API key in the dashboard after signing in with GitHub. Copy it when it appears; Linkoi stores only its hash and cannot show it again. 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.

JavaScript client

Install @linkoi/client in your server application.

import { createClient } from '@linkoi/client'

const linkoi = createClient({ apiKey: process.env.LINKOI_API_KEY })
const { data } = await linkoi.resolve('https://example.com')
console.log(data.title)

Use { fresh: true } to refresh a result. LinkoiError exposes status and retryAfter; the client does not retry automatically.

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#

GET /health checks authentication and returns { "ok": true } without consuming a request. The hosted API does not expose cache deletion. A self-hosted Worker also supports DELETE /?url=... for cache invalidation.

Authentication and errors#

The hosted API requires a personal bearer key on every request except CORS preflight. Each account starts with 1,000 metadata requests per UTC calendar month and 60 per UTC minute, shared across up to 10 active keys. Requests admitted for extraction count, including cache hits and extraction failures. Revoke keys immediately in the dashboard. Self-hosted Workers use their own optional API_KEY setting and do not include hosted account quotas.

Responses include X-RateLimit-Limit and X-RateLimit-Remaining for monthly usage. Quota exhaustion returns 429 with Retry-After in seconds. If the account service is unavailable, requests fail closed with 503. Missing or unsafe URLs return 400. Invalid or revoked keys return 401. Fetch failures can return 400, 429, or 502; unexpected extraction failures return 500. Read the error body rather than assuming success.