Posts
Link previews
link-preview-service
The card of a link: what a page says of itself, read by this installation, with its picture kept here. Optional: an installation may not run it (link-previews.md).
The preview of a link, for another service
/internal/link-previewsInside the installation only: activitypub-service asks it for the card of a link in a post that came from another server. The gateway sends nobody from outside here.
The preview as it is kept, the key of its picture included, which the public route does not give out. A request that came through the gateway is answered 404.
Who: Anyone, signed in or not. Inside the installation only.
Parameters
urlstringrequiredin queryThe link: an http or https address. At most 2000 characters.
Answers
- 200OKPreview application/json
- 204there is nothing to show
- 400the request is not well formed, or a value in it is not one it may be
- 404it came through the gateway
- 429the services have asked for too many lately
Request
curl "https://api.example.org/internal/link-previews?url=<url>"
const response = await fetch('https://api.example.org/internal/link-previews?url=<url>', {
method: 'GET',
});
const answer = await response.json();
import requests
response = requests.get(
"https://api.example.org/internal/link-previews?url=<url>",
)
answer = response.json()
Answer · 200
{
"description": "string",
"final_url": "https://example.org/",
"image_key": "string",
"site_name": "string",
"status": "string",
"title": "string",
"url": "https://example.org/"
}
The preview of a link
/link-previewsRead from the page by this installation when no fresh preview is kept, so that nobody's browser asks the other site. For the composer, while a post is written.
Who: Somebody signed in
Parameters
urlstringrequiredin queryThe link: an http or https address. At most 2000 characters.
Answers
- 200OKlinkpreview.PreviewResponse application/json
- 204there is nothing to show: the page could not be read, is not a page, or says nothing of itself
- 400the request is not well formed, or a value in it is not one it may be
- 401no token, or one that has expired
- 429the viewer has asked for too many lately
Request
curl "https://api.example.org/link-previews?url=<url>" \
-H "Authorization: Bearer $TOKEN"
const response = await fetch('https://api.example.org/link-previews?url=<url>', {
method: 'GET',
headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();
import requests
response = requests.get(
"https://api.example.org/link-previews?url=<url>",
headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()
Answer · 200
{
"description": "string",
"image": "string",
"site_name": "string",
"title": "string",
"url": "https://example.org/"
}
The preview of a link
/link-previews/Read from the page by this installation when no fresh preview is kept, so that nobody's browser asks the other site. For the composer, while a post is written.
Who: Somebody signed in
Parameters
urlstringrequiredin queryThe link: an http or https address. At most 2000 characters.
Answers
- 200OKlinkpreview.PreviewResponse application/json
- 204there is nothing to show: the page could not be read, is not a page, or says nothing of itself
- 400the request is not well formed, or a value in it is not one it may be
- 401no token, or one that has expired
- 429the viewer has asked for too many lately
Request
curl "https://api.example.org/link-previews/?url=<url>" \
-H "Authorization: Bearer $TOKEN"
const response = await fetch('https://api.example.org/link-previews/?url=<url>', {
method: 'GET',
headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();
import requests
response = requests.get(
"https://api.example.org/link-previews/?url=<url>",
headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()
Answer · 200
{
"description": "string",
"image": "string",
"site_name": "string",
"title": "string",
"url": "https://example.org/"
}
A preview's picture
/link-previews/image/{name}A redirect to the picture in storage, at an address good for a short while.
Who: Anyone, signed in or not
Parameters
namestringrequiredin pathThe picture's name, as a preview'simagegives it: the hash of the picture and its kind (<64 hex>.jpg).
Answers
- 302the picture is at the address in Location
- 404there is no such picture
Request
curl "https://api.example.org/link-previews/image/<name>"
const response = await fetch('https://api.example.org/link-previews/image/<name>', {
method: 'GET',
});
const answer = await response.json();
import requests
response = requests.get(
"https://api.example.org/link-previews/image/<name>",
)
answer = response.json()
Written by Claude, reviewed by Rastin Mehr · About this