Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp
5.6 KB
Raw Blame
---
# 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 |