# Link Header API
> Parse and build RFC 8288 HTTP Link headers (Web Linking). The parse endpoint turns a Link header into a structured list — each link with its URI, its rel relation(s) and any target attributes (title, type, hreflang, media, anchor) — and also returns a handy rel→uri map, so you can grab the next, prev, first and last URLs for API pagination in a single step. It correctly handles the awkward parts: multiple comma-separated links, commas inside angle-bracketed URIs, quoted parameter values, multiple space-separated rel tokens, and RFC 8187 extended values. The build endpoint assembles a correct Link header from one or more link objects (or a single uri + rel with optional attributes), quoting values only where required. Everything is computed locally and deterministically, so it is instant and private. Ideal for paginated REST APIs and clients, hypermedia and HATEOAS, HTTP preload/prefetch hints, feed and alternate-format discovery, proxies and gateways. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This builds and parses the Link header string itself; it does not fetch a URL.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/linkheader-api/..."
```

## Pricing
- **Free** (Free) — 2,535 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 12,050 calls/Mo, 8 req/s
- **Pro** ($24/Mo) — 171,500 calls/Mo, 20 req/s
- **Mega** ($62/Mo) — 900,000 calls/Mo, 50 req/s

## Endpoints

### Link

#### `GET /v1/build` — Build a Link header

**Parameters:**
- `links` (query, optional, string) — JSON array of link objects ({uri, rel, title, …})
- `uri` (query, optional, string) — Single link URI (alternative to links) Example: `https://x.com/p?page=2`
- `rel` (query, optional, string) — Single link relation Example: `next`
- `title` (query, optional, string) — Optional title attribute
- `type` (query, optional, string) — Optional type attribute
- `hreflang` (query, optional, string) — Optional hreflang attribute

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/linkheader-api/v1/build?uri=https%3A%2F%2Fx.com%2Fp%3Fpage%3D2&rel=next"
```

**Response:**
```json
{
    "data": {
        "count": 1,
        "header": "<https://x.com/p?page=2>; rel=\"next\""
    },
    "meta": {
        "timestamp": "2026-06-03T09:25:03.609Z",
        "request_id": "de136cff-fa37-4a6e-9a0b-d85316baaabd"
    },
    "status": "ok",
    "message": "Build a Link header",
    "success": true
}
```

#### `GET /v1/parse` — Parse a Link header

**Parameters:**
- `header` (query, required, string) — A Link header value Example: `<https://api.x.com/p?page=2>; rel="next", <https://api.x.com/p?page=5>; rel="last"`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/linkheader-api/v1/parse?header=%3Chttps%3A%2F%2Fapi.x.com%2Fp%3Fpage%3D2%3E%3B+rel%3D%22next%22%2C+%3Chttps%3A%2F%2Fapi.x.com%2Fp%3Fpage%3D5%3E%3B+rel%3D%22last%22"
```

**Response:**
```json
{
    "data": {
        "count": 2,
        "links": [
            {
                "rel": "next",
                "uri": "https://api.x.com/p?page=2",
                "rel_tokens": [
                    "next"
                ]
            },
            {
                "rel": "last",
                "uri": "https://api.x.com/p?page=5",
                "rel_tokens": [
                    "last"
                ]
            }
        ],
        "by_rel": {
            "last": "https://api.x.com/p?page=5",
            "next": "https://api.x.com/p?page=2"
        }
    },
    "meta": {
        "timestamp": "2026-06-03T09:25:03.699Z",
        "request_id": "ce80d2cf-f4cf-4e31-bf43-977503ba2e33"
    },
    "status": "ok",
    "message": "Parse a Link header",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/linkheader-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "name": "Link Header API",
        "notes": "Relations with multiple values are space-separated inside one rel (rel=\"next last\"). Pagination relations are next, prev/previous, first and last. This builds and parses the Link header string — it does not fetch a URL. Nothing is stored.",
        "version": "v1",
        "endpoints": [
            {
                "path": "/v1/parse",
                "params": {
                    "header": "a Link header value (required)"
                },
                "returns": "the parsed links and a rel→uri map"
            },
            {
                "path": "/v1/build",
                "params": {
                    "rel": "single link relation",
                    "uri": "single link URI (alternative to links)",
                    "links": "a JSON array of link objects ({uri, rel, title, …})",
                    "title/type/hreflang…": "optional target attributes for the single link"
                },
                "returns": "the Link header string"
            },
            {
                "path": "/v1/meta",
                "params": [],
                "returns": "this document"
            }
        ],
        "description": "Parse and build RFC 8288 HTTP Link headers (Web Linking). The parse endpoint turns a Link header into a structured list — each link with its URI, rel relation(s) and target attributes (title, type, hreflang, media…) — plus a handy rel→uri map so you 
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/linkheader-api
OpenAPI spec: https://www.oanor.com/api/linkheader-api/openapi.json