---
title: "Set a link's preview"
method: PATCH
path: "/links/{id}/metadata"
tags: ["Metadata"]
---

# Set a link's preview

`PATCH /links/{id}/metadata`

## Request

- Base URL: `https://fixed.link/api/v1`
- URL: `https://fixed.link/api/v1/links/{id}/metadata`
- Auth: HTTP bearer

Send null for a field to clear the override and fall back to the destination page's own tag.

## Path parameters

- `id` string, required

## Request body

- UpdateLinkPreviewRequest
  - `previewMode` 'auto' | 'custom' | 'off': "auto" unfurls with the destination's tags, "custom" with yours, "off" disables the preview page.
  - `title` string, nullable
  - `description` string, nullable
  - `imageUrl` string, uri, nullable: Absolute http(s) URL.
  - `siteName` string, nullable

## Response `200`

The updated metadata

- LinkMetadata
  - `status` 'pending' | 'fetching' | 'ok' | 'failed' | 'skipped', required: State of the background fetch of the destination page.
  - `fetched` object, required
    - `title` string, nullable, required
    - `description` string, nullable, required
    - `imageUrl` string, nullable, required
    - `iconUrl` string, nullable, required
    - `siteName` string, nullable, required
    - `author` string, nullable, required
    - `type` string, nullable, required
    - `locale` string, nullable, required
    - `canonicalUrl` string, nullable, required
  - `overrides` object, required
    - `title` string, nullable, required
    - `description` string, nullable, required
    - `imageUrl` string, nullable, required
    - `siteName` string, nullable, required
  - `previewMode` 'auto' | 'custom' | 'off', required
  - `preview` object, nullable, required
    - `title` string, nullable, required
    - `description` string, nullable, required
    - `imageUrl` string, nullable, required
    - `siteName` string, nullable, required
  - `resolvedUrl` string, nullable, required
  - `httpStatus` integer, nullable, required
  - `error` string, nullable, required
  - `fetchedAt` string, date-time, nullable, required

## Other responses

- `402`: Plan does not include custom link previews
- `404`: No such link
- `422`: Invalid preview mode or image URL

---

[API](https://skmtc.dev/fixed/apis/fixedlink-api.md) · [All operations](https://skmtc.dev/fixed/apis/fixedlink-api/llms.txt) · [OpenAPI document](https://skmtc.dev/fixed/apis/fixedlink-api/revisions/72343453b299?raw)