Skip to content

Create an asset

POST
/assets

Creates an asset: a record with a title, tags and other details, usually for an uploaded file. To link a file, upload it with POST /storage/objects first and send the hash it returns as file_hash; without one, the asset has no file.

Any signed-in account can create assets. The new asset belongs to you, is created with public sensitivity, and is active unless you send another status, so once its processing has finished anonymous visitors can see it if the instance lets them browse. Creating an asset doesn’t create a post; posts are made separately and can include assets.

Your account can link the same file to only one live asset. If you already have one, you get that asset back instead: 200 with duplicate_warning, or 409 when the instance blocks duplicates. Nothing you sent is applied to it.

file_extension decides whether the file needs processing. Images, video, audio, 3D models, PDFs, fonts, EPUB books, comics, .txt files and archives start as pending and have preview jobs queued; anything else is ready at once. Queuing can fail without failing the request, and a pending asset with no file_hash is never processed.

The 201 body is the new record as stored, without the preview flags, tag_details, card fields or owner. Get the asset with GET /assets/{id} for those.

object
title
required

The asset’s name. Surrounding spaces are trimmed, and an empty title gets 400.

string
>= 1 characters <= 500 characters
description
string
asset_type
required

The asset type ref, such as 1 for an image or 5 for a 3D model. An unknown ref gets 400. A 1 or 2 is replaced by the type that matches the file extension, if there is one.

integer format: int64
status

active is the default. draft and archived hide the asset from anonymous visitors, but not from other signed-in accounts.

string
default: active
Allowed values: draft active archived
mature

Send true to rate the work as mature. It’s refused with 400 when the instance doesn’t allow mature content; false is always accepted. The rating controls who has chosen to see such work, which is separate from who is allowed to see it.

boolean
ai_provenance

The maker’s statement about generative AI in this work: none, assisted or generated. Leave it out when nobody has said, and the work stays undeclared. Don’t send none as a default: it’s a claim that no AI was used. Accepted on every instance.

string
nullable
Allowed values: none assisted generated
file_hash

The SHA-256 that POST /storage/objects returned for your upload. Leave it out, or send null or "", for an asset with no file. Any other value is trimmed and lowercased and must then name a stored object the server has a record of, or you get 400 (so does a value of only spaces). The check is against the record, not the stored bytes.

After the asset is saved, the bytes are recorded as held by the asset and your account’s hold from the upload is dropped. Both steps are separate from the save, and a failure in either is only logged.

string
nullable
file_extension

The file’s extension, such as png or .glb. It decides whether the file is processed and can change a generic asset_type.

string
nullable
tags

Tags for the asset. Each is trimmed, and empty ones and repeats are dropped. Tags are case-sensitive.

Array<string>
metadata

Any JSON object you want stored with the asset.

object
key
additional properties
any
state_id

Optional workflow state id. The server checks only that the state exists, not that it belongs to this asset type’s workflow. Leave it out and the asset has no state.

string format: uuid
nullable
team_id

Optional team for the asset. You can choose a team you’re a member of, one you hold a team-scoped assets.admin grant for (including teams below it), or any team if you have system.admin. Any other team, or a deleted one, gets 404, the same as a team that doesn’t exist.

The team decides whose team-scoped grants apply to the asset; it doesn’t limit who can see it. It can’t be changed later.

string format: uuid
nullable

You already have a live asset with this file, so that asset is returned instead of a new one. Nothing from your request was applied.

The existing asset, plus duplicate_warning. It has fewer fields than GET /assets/{id}: no tags, mature, ai_provenance, team_id, state_id, card_fields or owner.

object
id
required
string format: uuid
restricted
required

true when this is a placeholder for an asset you can’t open. Always present, so check it before reading anything else.

boolean
owner_display_name

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.

string
title
string
description
string
asset_type
integer format: int64
owner_user_ref
integer format: int64
nullable
status

Anonymous visitors see only active assets. draft and archived don’t hide an asset from other signed-in accounts.

string
Allowed values: draft active archived
mature

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.

boolean
ai_provenance

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.

string
nullable
Allowed values: none assisted generated
file_hash

The SHA-256 of the linked file, as used by GET /storage/objects/{hash}. Absent when no file is linked.

string
nullable
file_extension
string
nullable
file_size_bytes

The file’s size in bytes, when recorded. Assets created with POST /assets don’t record it.

integer format: int64
nullable
tags

The asset’s tags, as plain strings. tag_details has the same tags with where each one came from.

Array<string>
tag_details

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.

Array<object>

One tag and where it came from.

object
value
required

The tag.

string
source
required

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.

string
Allowed values: manual ai import
confidence

For AI tags, the provider’s confidence from 0 to 1. Absent for other tags.

number format: double
nullable
created_by_provider

For AI tags, the provider that suggested it, such as openai or ollama.

string
nullable
created_by_model

For AI tags, the model that suggested it.

string
nullable
metadata

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
key
additional properties
any
state_id

The asset’s workflow state, if it has one.

string format: uuid
nullable
team_id

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.

string format: uuid
nullable
processing_status

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.

string
Allowed values: pending ready failed
preview_available

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.

boolean
ladder_available

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.

boolean
scrub_available

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.

boolean
anonymously_visible

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.

boolean
thumbhash

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.

string
nullable
pixel_width

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.

integer format: int32
nullable
pixel_height

The height to go with pixel_width.

integer format: int32
nullable
created_at
string format: date-time
updated_at

When the asset last changed, including changes made by background processing. Send it as if_unchanged_since when you update.

string format: date-time
deleted_at

When the asset was deleted. Only soft-deleted assets in GET /assets?include_deleted=true results have it.

string format: date-time
nullable
deleted_reason

The reason given when it was deleted, if any. Appears with deleted_at.

string
nullable
subtitle_tracks

Subtitle and caption tracks for the asset. Only GET /assets/{id} includes them, and only when there are some.

Array<object>

One subtitle or caption track. An asset has at most one per language; uploading another for the same language replaces it.

object
lang
required

The track’s language tag, such as en or fr-CA. und means the language couldn’t be worked out from the file name.

string
label

A display name, such as English (US) or Forced. Empty when none was given.

string
file_hash
required

The SHA-256 of the stored WebVTT file.

string
source_format
required

The format the track was uploaded in. It’s stored as WebVTT whatever the source format.

string
Allowed values: vtt srt ssa ass sub idx
confidence
required

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.

number format: float
<= 1
created_at
string format: date-time
card_fields

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.

Array<object>

One field value to show on a card.

object
code
required

The field’s code.

string
label
required

The field’s name, for a caption.

string
value
required

The value as one line of text. Never empty: a field with no value is left out instead.

string
origin

The federated instance this asset came from. Absent for local assets.

object
peer_id
required
string format: uuid
display_name
required
string
instance_url
string
owner

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
ref
required
integer format: int64
username
required

The handle. Also the profile link target (/users/by-username/{username}).

string
display_name
required

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.

string
avatar_url

The avatar URL stored on the user’s profile, if there is one; left out when none is stored.

string
nullable
duplicate_warning
required
object
existing_asset_id
required

The existing asset’s id, the same as id.

string format: uuid
message
required

A short message you can show the user.

string

The asset was created.

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
id
required
string format: uuid
restricted
required

true when this is a placeholder for an asset you can’t open. Always present, so check it before reading anything else.

boolean
owner_display_name

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.

string
title
string
description
string
asset_type
integer format: int64
owner_user_ref
integer format: int64
nullable
status

Anonymous visitors see only active assets. draft and archived don’t hide an asset from other signed-in accounts.

string
Allowed values: draft active archived
mature

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.

boolean
ai_provenance

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.

string
nullable
Allowed values: none assisted generated
file_hash

The SHA-256 of the linked file, as used by GET /storage/objects/{hash}. Absent when no file is linked.

string
nullable
file_extension
string
nullable
file_size_bytes

The file’s size in bytes, when recorded. Assets created with POST /assets don’t record it.

integer format: int64
nullable
tags

The asset’s tags, as plain strings. tag_details has the same tags with where each one came from.

Array<string>
tag_details

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.

Array<object>

One tag and where it came from.

object
value
required

The tag.

string
source
required

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.

string
Allowed values: manual ai import
confidence

For AI tags, the provider’s confidence from 0 to 1. Absent for other tags.

number format: double
nullable
created_by_provider

For AI tags, the provider that suggested it, such as openai or ollama.

string
nullable
created_by_model

For AI tags, the model that suggested it.

string
nullable
metadata

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
key
additional properties
any
state_id

The asset’s workflow state, if it has one.

string format: uuid
nullable
team_id

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.

string format: uuid
nullable
processing_status

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.

string
Allowed values: pending ready failed
preview_available

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.

boolean
ladder_available

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.

boolean
scrub_available

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.

boolean
anonymously_visible

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.

boolean
thumbhash

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.

string
nullable
pixel_width

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.

integer format: int32
nullable
pixel_height

The height to go with pixel_width.

integer format: int32
nullable
created_at
string format: date-time
updated_at

When the asset last changed, including changes made by background processing. Send it as if_unchanged_since when you update.

string format: date-time
deleted_at

When the asset was deleted. Only soft-deleted assets in GET /assets?include_deleted=true results have it.

string format: date-time
nullable
deleted_reason

The reason given when it was deleted, if any. Appears with deleted_at.

string
nullable
subtitle_tracks

Subtitle and caption tracks for the asset. Only GET /assets/{id} includes them, and only when there are some.

Array<object>

One subtitle or caption track. An asset has at most one per language; uploading another for the same language replaces it.

object
lang
required

The track’s language tag, such as en or fr-CA. und means the language couldn’t be worked out from the file name.

string
label

A display name, such as English (US) or Forced. Empty when none was given.

string
file_hash
required

The SHA-256 of the stored WebVTT file.

string
source_format
required

The format the track was uploaded in. It’s stored as WebVTT whatever the source format.

string
Allowed values: vtt srt ssa ass sub idx
confidence
required

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.

number format: float
<= 1
created_at
string format: date-time
card_fields

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.

Array<object>

One field value to show on a card.

object
code
required

The field’s code.

string
label
required

The field’s name, for a caption.

string
value
required

The value as one line of text. Never empty: a field with no value is left out instead.

string
origin

The federated instance this asset came from. Absent for local assets.

object
peer_id
required
string format: uuid
display_name
required
string
instance_url
string
owner

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
ref
required
integer format: int64
username
required

The handle. Also the profile link target (/users/by-username/{username}).

string
display_name
required

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.

string
avatar_url

The avatar URL stored on the user’s profile, if there is one; left out when none is stored.

string
nullable

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed

You already have a live asset with this file and the instance blocks duplicates. existing_asset_id names it.

Returned with 409 from POST /assets when you already have a live asset with this file and the instance blocks duplicates.

object
error
required

A short explanation.

string
existing_asset_id
required

The id of your asset that already has this file.

string format: uuid

Unexpected server error

object
error
required

Human-readable error summary

string
Example
the request could not be completed