Skip to content
Artbucket

What an asset is and may be used for

GET
/api/v1/assets/{id}/description
curl --request GET \
  --url http://localhost:3000/api/v1/assets/example/description \
  --header 'Authorization: Bearer <token>'

Title, credit, tags, effective field values, rights, provenance, what supersedes it, its URLs, the transforms it allows and ready-made rendition URLs. Whether a particular use is allowed: POST /api/v1/check.

Scope: read.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

Asset id

Responses

Section titled “Responses”

200

Section titled “200”

The description

Media typeapplication/json
object
id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
filename
required
string
mime
required
string
size
required
integer
>= -9007199254740991 <= 9007199254740991
width
required
Any of:
integer
>= -9007199254740991 <= 9007199254740991
height
required
Any of:
integer
>= -9007199254740991 <= 9007199254740991
sha256
required
string
status
required
string
Allowed values: draft proposed active archived rejected
state
required

Only active is served at /a/{id} to anyone; expired and archived answer 410

string
Allowed values: draft proposed active expired archived rejected deleted
version
required
Any of:
integer
>= -9007199254740991 <= 9007199254740991
current
required

The version to use: its stack’s current one, or the only one

boolean
proposedBy
required
string | null
reviewNote
required
string | null
title
required
string | null
description
required
string | null
creator
required
string | null
copyright
required
string | null
focus
required
Any of:
object
x
required
number
y
required
number
tags
required
Array<string>
fields
required

Effective values: own over inherited

object
key
additional properties
string | number | boolean
collections
required
Array<string>
rights
required
Any of:
object
license
required
string | null
territories
required

ISO 3166-1 alpha-2; empty: anywhere

Array<string>
channels
required

Empty: any use

Array<string>
embargo
required
Any of:
string format: date
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$/
expires
required
Any of:
string format: date
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$/
modelRelease
required
Any of:
string
Allowed values: released missing not-needed
downloadable

Set by a person; null or missing follows the license (see downloadable on its description)

boolean | null
provenance
required
object
origin
required
Any of:
string
Allowed values: shot licensed generated
parentAssetId
required
Any of:
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
generator
required
string | null
prompt
required
string | null
c2pa
required
Any of:
object
manifests
required
integer
>= -9007199254740991 <= 9007199254740991
generator
required

The app that signed it

string | null
title
required
string | null
signedBy
required

The signing certificate’s organization, as the file claims it; not verified

string | null
actions
required
Array<string>
digitalSourceType
required

IPTC: digitalCapture, trainedAlgorithmicMedia…

string | null
softwareAgent
required

The tool the actions name, often the model

string | null
ingredients
required
integer
>= -9007199254740991 <= 9007199254740991
via
required
Any of:
string
Allowed values: agent import
supersededBy
required
Any of:
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
public
required

Its URLs work for anyone while it may be used; otherwise with a key or session, or signed (POST /api/v1/assets/{id}/signed-url)

boolean
downloadable
required

Whether people outside the project may download the file itself. False: they see it, at most 1600 px a side, and its original and ?download answer 403 to them (fonts still load on this app’s own pages). Its rights’ downloadable decides, else its license: a font only under an open one, a licensed file only under an open one, anything else yes

boolean
urls
required
object
original
required
string format: uri
download
required

The original with current metadata written in

string format: uri
rendition
required

Template: replace {transform}, e.g. w_800,f_webp

string | null
constraints
required
Any of:
object
w
required
array
>= 2 items <= 2 items
h
required
array
>= 2 items <= 2 items
sizes
required

A side snaps up to the next of these: w_801 is w_828

Array<number>
q
required

Snaps to a multiple of 5

array
>= 2 items <= 2 items
fit
required
Array<string>
Allowed values: cover contain inside outside fill
f
required
Array<string>
Allowed values: jpeg png webp avif
enlarges
required

An SVG is drawn at the size asked, up to the w and h caps; any other image never comes out larger than it is

boolean
alternatives
required

Ready-made renditions

Array<object>
object
name
required
string
url
required
string format: uri
Example
{
  "status": "draft",
  "state": "draft",
  "rights": {
    "modelRelease": "released"
  },
  "provenance": {
    "origin": "shot",
    "via": "agent"
  },
  "constraints": {
    "fit": [
      "cover"
    ],
    "f": [
      "jpeg"
    ]
  }
}

default

Section titled “default”

An error

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
detail
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "detail": "example"
  }
}