Find similar assets
GET /assets/{id}/similar
Lists other assets that are most similar to this one, closest first. Similarity comes from a text embedding of each asset’s title and tags, not from the image or file itself.
The comparison uses the instance’s default embedding model, and each
asset’s embedding reflects its title and tags when it was last
computed, so recent edits may not show yet. If this asset has no
embedding yet, you get an empty results list with
anchor_has_embedding set to false; every asset gets that answer
if the server has no embedding store set up.
The server takes the nearest limit assets first and then removes
the ones you can’t see, so you can get fewer results than limit,
or none, even when more visible assets exist. Each result’s asset
is a shortened record. When you can see its details, tags is null,
mature is false and ai_provenance is missing, whatever the
asset’s real values; when you can’t, it is a placeholder with only
its id, restricted set to true and, when there is one, the
owner’s name.
A 404 means the asset doesn’t exist or you can’t view it or its
content; its error is empty. You need to be signed in unless the
instance is in public mode, where visitors can use this for assets
they can view. A limit that isn’t a whole number gets a plain-text
400, and server errors, including an embedding model the server
can’t read, a plain-text 500.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The asset’s id.
Query Parameters
Section titled “Query Parameters ”How many of the nearest assets to look at before the ones you can’t see are removed. Values below 1 mean 12; values above 50 count as 50.
Responses
Section titled “ Responses ”The most similar assets you can see, closest first.
object
One similar asset and its distance from the asset you asked about.
object
An asset: a record with a title, tags and other details, and
optionally a link to one stored file. Which fields appear depends on
the endpoint, so treat everything except id and restricted as
optional.
If its sensitivity tier keeps you from opening an asset, you get a
placeholder instead: restricted is true, and apart from id
only owner_display_name can appear, so you can show whose work it
is and offer to request access. GET /assets/{id} can also attach
subtitle_tracks to a placeholder. Someone who can manage an asset
without being able to open it gets its fields, but no thumbhash,
and its preview flags are false.
object
true when this is a placeholder for an asset you can’t open.
Always present, so check it before reading anything else.
On a placeholder only: the owner’s display name. Absent when there’s no name that can be shown, for example to an anonymous visitor when the owner hides their profile from them.
Anonymous visitors see only active assets. draft and archived don’t hide an asset from other signed-in accounts.
true when the work is rated mature. The rating is about who has
chosen to see mature work; it’s separate from the sensitivity tier,
which decides who is allowed to see it.
A viewer qualifies for mature work when the instance allows it and
they’ve opted in; signed-in owners and system.admin are let
through either way. For anyone else, the browse list leaves mature
assets out and their files are refused, but GET /assets/{id} still
returns the record, so use this flag to label what you show. GET /assets reports false on every readable item, and placeholders
leave it out.
The maker’s statement about generative AI in this work: none,
assisted or generated. Absent means nobody has said, which isn’t
the same as none; show it as “not stated” or show nothing. It’s a
label people can filter by, never a reason to hide the work. GET /assets leaves it out even when it’s set.
The SHA-256 of the linked file, as used by GET /storage/objects/{hash}. Absent when no file is linked.
The file’s size in bytes, when recorded. Assets created with POST /assets don’t record it.
The asset’s tags, as plain strings. tag_details has the same tags
with where each one came from.
The same tags with their source and, for AI tags, confidence and
model. Only GET /assets/{id} includes it, and only when the asset
has tags.
One tag and where it came from.
object
The tag.
manual for tags people added, ai for AI tagging, import for
imported tags. AI tagging replaces only earlier AI tags; replacing
the tag list with PATCH /assets/{id} removes all three kinds.
For AI tags, the provider’s confidence from 0 to 1. Absent for other tags.
For AI tags, the provider that suggested it, such as openai or ollama.
For AI tags, the model that suggested it.
Free-form JSON stored with the asset. Clients can keep their own keys here, and background processing adds its own sections. Updating it replaces the whole object.
object
The asset’s workflow state, if it has one.
The team the asset is assigned to. It’s set when the asset is created and can’t be changed. Absent when there is none, and on placeholders.
Where the asset’s preview processing stands, as recorded. pending
means the preview job hasn’t finished or never started: an asset
with no linked file, or whose job couldn’t be queued, stays
pending, and its variants can return 404. ready means the
preview job finished or none was needed; other background jobs, such
as transcription, may still be running. failed means the preview
job stopped with an error. While a job runs, the value can also be
processing, which isn’t in the list below. Anonymous visitors see
only ready assets.
Like the preview flags, this is a stored marker: it doesn’t check that the file or its renditions are actually in storage.
true when a col thumbnail is recorded for the file and you may
see the asset’s pictures. When it’s false, don’t request one.
This and the other preview hints (ladder_available,
scrub_available, thumbhash) come from the server’s records, not
from storage, so a request can still fail if a stored copy is
missing. “May see the pictures” follows the sensitivity tier; on
GET /assets/{id} it doesn’t take the mature rating into account,
so a viewer who doesn’t qualify for mature work can see true and
still have the request refused.
true when every size in the instance’s preview ladder (see GET /previews) is recorded and you may see the asset’s pictures, on the
same basis as preview_available. Check it before requesting the
larger sizes; preview_available covers only the col thumbnail.
true when a sprites.vtt hover-scrub file is recorded and you may
see the asset’s pictures, on the same basis as preview_available.
Whether an anonymous visitor would be shown this asset: it’s live,
active, public and processed. The answer is the same for
everyone, so it says nothing about what you can see. It doesn’t take
the mature rating or the instance’s anonymous-browsing setting into
account. Useful when choosing a cover for something public.
A small encoded blur of the image (a base64 thumbhash) to show while
it loads. Absent when there isn’t one or you may not see the asset’s
pictures, on the same basis as preview_available.
The width in pixels of the image the previews are made from, when it
has been recorded. For files without pixels, such as 3D models,
fonts or audio, it’s the size of the image their preview is drawn
from. Photos are measured after their EXIF rotation. pixel_width
and pixel_height always come together or not at all.
The height to go with pixel_width.
When the asset last changed, including changes made by background processing. Send it as if_unchanged_since when you update.
When the asset was deleted. Only soft-deleted assets in GET /assets?include_deleted=true results have it.
The reason given when it was deleted, if any. Appears with deleted_at.
Subtitle and caption tracks for the asset. Only GET /assets/{id}
includes them, and only when there are some.
One subtitle or caption track. An asset has at most one per language; uploading another for the same language replaces it.
object
The track’s language tag, such as en or fr-CA. und means the
language couldn’t be worked out from the file name.
A display name, such as English (US) or Forced. Empty when none
was given.
The SHA-256 of the stored WebVTT file.
The format the track was uploaded in. It’s stored as WebVTT whatever the source format.
How reliable the conversion to WebVTT is, from 0 to 1. Every format accepted today converts from text and gives 1; image-based subtitles, such as DVD IDX files, aren’t accepted yet.
Field values to show on a card, already formatted and in the order the operator set. Absent when there are none and on placeholders. Only fields without a read restriction can appear.
One field value to show on a card.
object
The field’s code.
The field’s name, for a caption.
The value as one line of text. Never empty: a field with no value is left out instead.
The federated instance this asset came from. Absent for local assets.
object
The owner’s name and avatar, for showing on a card. Absent when the owner can’t be shown, for example to an anonymous visitor when the owner hides their profile from them, and on placeholders.
object
The handle. Also the profile link target
(/users/by-username/{username}).
The name to show, never empty: the profile’s display name, then the
account’s full name, then the username, and as a last resort user
followed by the account number. For readers who aren’t signed in,
the account’s full name is skipped; the display name and username
are still used.
The avatar URL stored on the user’s profile, if there is one; left out when none is stored.
Cosine distance between the two embeddings: 0 when they point the same way, 2 when they point in opposite directions. Lower means more similar. No cutoff is applied.
false when the asset you asked about has no embedding yet, or the
server has no embedding store, so an empty results means there was
nothing to compare rather than nothing similar.
Authentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Resource not found
object
Human-readable error summary
Example
the request could not be completed