A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.
---
# SPDX-License-Identifier: AGPL-3.0-or-later
title: Unfurl
description: Resolve a public URL into embed previews.
---
import RouteHeader from '@/components/RouteHeader.astro';
Unfurl turns one URL into the preview a message would show for it, as an array of [embed](/http-api/messages/#embed-object) objects. It fetches the URL again on every call.
The route is user-only. A bot token or OAuth2 bearer credential gets 403 `ACCESS_DENIED`.
## Supported sites
The sites below get a dedicated preview. Any other URL gets a preview from its page metadata, or a media embed when it points to an image, video or audio file.
| Site | Matched URL |
| --- | --- |
| Hacker News | `news.ycombinator.com/item` with an `id` query parameter |
| Klipy<sup>1</sup> | `klipy.com` and `www.klipy.com` |
| Tenor | `tenor.com` |
| xkcd | `xkcd.com` |
| YouTube<sup>1</sup> | `youtube.com` and its `www`, `m` and `music` hosts, `youtube-nocookie.com` and `www.youtube-nocookie.com`, and `youtu.be` |
| Wikipedia | `wikipedia.org` and its `www`, `en`, `de`, `fr`, `es`, `it`, `ja`, `ru` and `zh` hosts, under `/wiki/` |
| Bluesky | Post and profile URLs on `bsky.app` |
| FxTwitter | `fxtwitter.com`, `fixupx.com`, `twittpr.com`, `xfixup.com` and their subdomains |
<sup>1</sup> Needs an API key for this site on the instance. Without one, the URL gets the generic preview.
## Resolve URL embeds
<RouteHeader method="POST" path="/v1/unfurl" />
Returns the embeds for `url`. Fluxer only fetches public HTTP and HTTPS addresses, and a fetch fails after five redirects or on a document larger than 8 MiB.
### JSON body
| Field | Type | Description |
| --- | --- | --- |
| url | string | The HTTP or HTTPS URL to preview (1-2048 characters) |
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | array[[embed](/http-api/messages/#embed-object) object] | Resolution finished, possibly with no embed |
| 403 | [error response](/http-api/#error-response) | `ACCESS_DENIED` for a bot token or OAuth2 bearer credential |
| 502 | [error response](/http-api/#error-response) | `BAD_GATEWAY` when the unfurl service returns an error |
| 503 | [error response](/http-api/#error-response) | `SERVICE_UNAVAILABLE` when no unfurl service is responding |
| 504 | [error response](/http-api/#error-response) | `GATEWAY_TIMEOUT` when the unfurl service doesn't respond within 12 seconds |
The rate limit is 10 requests per minute, on the `unfurl:debug` bucket.
## ActivityPub actor
To preview a fediverse post, the unfurl service fetches the post's ActivityPub object. With `FLUXER_ACTIVITYPUB_SIGNING_KEY_BASE64` set, it signs those fetches as the instance actor, and the server it fetches from checks the signature against the actor's public key. Without the key, each actor route returns 404 `NOT_FOUND`.
The actor's ID is the `api_public` [endpoint](/http-api/instance/#instance-endpoints-object) followed by `/activitypub/actor`. Its key ID is the actor ID followed by `#main-key`.
These routes share a rate limit of 60 requests per minute, on the `activity_pub:document` bucket.
## Get the ActivityPub actor
<RouteHeader method="GET" path="/activitypub/actor" unauthenticated />
Returns the instance actor as an `application/activity+json` document of type `Application`, with its public key in PEM form. Its `preferredUsername` is the hostname of the `api_public` endpoint. Responses may be cached for 5 minutes.
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | ActivityPub actor document | Request signing is on |
| 404 | [error response](/http-api/#error-response) | `NOT_FOUND` when request signing is off |
| 503 | [error response](/http-api/#error-response) | `SERVICE_UNAVAILABLE` when no unfurl service is responding |
## Get the ActivityPub outbox
<RouteHeader method="GET" path="/activitypub/actor/outbox" unauthenticated />
Returns the actor's outbox as an empty `OrderedCollection`.
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | ActivityPub collection document | Request signing is on |
| 404 | [error response](/http-api/#error-response) | `NOT_FOUND` when request signing is off |
| 503 | [error response](/http-api/#error-response) | `SERVICE_UNAVAILABLE` when no unfurl service is responding |
## Post to the ActivityPub inbox
<RouteHeader method="POST" path="/activitypub/actor/inbox" unauthenticated />
Accepts any activity and discards it.
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 202 | empty | Request signing is on |
| 404 | [error response](/http-api/#error-response) | `NOT_FOUND` when request signing is off |
| 503 | [error response](/http-api/#error-response) | `SERVICE_UNAVAILABLE` when no unfurl service is responding |
## Look up the actor with WebFinger
<RouteHeader method="GET" path="/.well-known/webfinger" unauthenticated />
Returns an `application/jrd+json` document whose `self` link points to the actor. The edge serves this path at the root of the public origin. Responses may be cached for 5 minutes.
### Query parameters
| Field | Type | Description |
| --- | --- | --- |
| resource | string | The actor ID, or `acct:{hostname}@{host}` for the `api_public` endpoint |
For an `api_public` endpoint of `https://chat.example.com/api`, the account is `acct:[email protected]`.
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | WebFinger document | `resource` is the actor |
| 404 | [error response](/http-api/#error-response) | `NOT_FOUND` when request signing is off or `resource` is anything else |
| 503 | [error response](/http-api/#error-response) | `SERVICE_UNAVAILABLE` when no unfurl service is responding |