Unfurl
Unfurl turns one URL into the preview a message would show for it, as an array of embed objects. It fetches the URL again on every call.
The route is user-only, so a bot token or OAuth2 bearer credential gets 403 ACCESS_DENIED.
Supported sites
Section titled “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 |
| Klipy1 | klipy.com and www.klipy.com |
| Tenor | tenor.com |
| xkcd | xkcd.com |
| YouTube1 | 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 |
1 Needs an API key for this site on the instance. Without one, the URL gets the generic preview.
Resolve URL embeds
Section titled “Resolve URL embeds”POST/v1/unfurlReturns 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
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| url | string | The HTTP or HTTPS URL to preview (1-2048 characters) |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | array[embed object] | Resolution finished, possibly with no embed |
| 403 | error response | ACCESS_DENIED for a bot token or OAuth2 bearer credential |
| 502 | error response | BAD_GATEWAY when the unfurl service returns an error |
| 503 | error response | SERVICE_UNAVAILABLE when no unfurl service is answering |
| 504 | error response | GATEWAY_TIMEOUT when the unfurl service doesn't answer within 12 seconds |
The rate limit is 10 requests per minute, on the unfurl:debug bucket.
ActivityPub actor
Section titled “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 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
Section titled “Get the ActivityPub actor”GET/activitypub/actorReturns 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
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | ActivityPub actor document | Request signing is on |
| 404 | error response | NOT_FOUND when request signing is off |
| 503 | error response | SERVICE_UNAVAILABLE when no unfurl service is answering |
Get the ActivityPub outbox
Section titled “Get the ActivityPub outbox”GET/activitypub/actor/outboxReturns the actor's outbox as an empty OrderedCollection.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | ActivityPub collection document | Request signing is on |
| 404 | error response | NOT_FOUND when request signing is off |
| 503 | error response | SERVICE_UNAVAILABLE when no unfurl service is answering |
Post to the ActivityPub inbox
Section titled “Post to the ActivityPub inbox”POST/activitypub/actor/inboxAccepts any activity and discards it.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 202 | empty | Request signing is on |
| 404 | error response | NOT_FOUND when request signing is off |
| 503 | error response | SERVICE_UNAVAILABLE when no unfurl service is answering |
Look up the actor with WebFinger
Section titled “Look up the actor with WebFinger”GET/.well-known/webfingerReturns 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
Section titled “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:chat.example.com@chat.example.com.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | WebFinger document | resource is the actor |
| 404 | error response | NOT_FOUND when request signing is off or resource is anything else |
| 503 | error response | SERVICE_UNAVAILABLE when no unfurl service is answering |