Skip to content

Add tags to an asset

POST
/assets/{id}/tags

Adds one or more tags to an asset. Send them as the tags array; tags the asset already has stay as they are, so sending the same request again changes nothing.

Each tag is trimmed of surrounding spaces, blank tags are dropped and repeats within the request count once. Tags match exactly, including case, so “Sky” and “sky” are two different tags. The declared length of 1 to 64 characters per tag isn’t checked by the server. A new tag is recorded as a manual tag; a tag the asset already has keeps its existing record, such as one added by AI tagging or an import.

Changing tags doesn’t update the asset’s similarity results (GET /assets/{id}/similar), which are based on its title and tags as they were when that data was last computed.

You need to be signed in, and any account can tag any asset that isn’t in the trash: ownership and edit rights aren’t checked. A missing or empty tags array gets the JSON 400; an array of only blank tags succeeds and adds nothing. Tags are added one at a time, so if a server error stops the request partway, the earlier ones stay added. A body that isn’t valid JSON, or an id that isn’t a UUID, gets a plain-text 400, and server errors a plain-text 500, not the JSON shown.

id
required
string format: uuid

The asset’s id.

object
tags
required

The tags to add. Surrounding spaces are trimmed and blank entries are ignored.

Array<string>

Done. New tags were added; tags already on the asset and blank entries changed nothing.

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