Skip to main content
POST
Upload permanent artwork or a Studio background package

Authorizations

Authorization
string
header
required

Short-lived JWT issued by the CarHub auth service (Better Auth), verified against its JWKS. Claims: sub (user), org_id (active organisation) and role (owner | admin | member | billing_manager). Used by the dashboard for /mgmt/v1/… only — it is never accepted on /v1/….

Body

multipart/form-data
category
enum<string>
required
Available options:
license_plate,
banner,
logo,
misc
name
string
required
Required string length: 1 - 200
file
file
required

File up to 25 MiB. Images must be PNG, JPEG, or WebP; misc accepts any type.

kind
enum<string>
deprecated

Legacy alias. If both selectors are sent, they must match.

Available options:
license_plate,
banner,
logo,
misc
banner_placement
enum<string>

Required for category banner.

Available options:
top,
bottom

Response

Asset uploaded.

Permanent organization asset. Scene size includes all image layers and YAML. Only available assets have signed links and can be selected for new jobs.

id
string<uuid>
required

Asset UUID, including for custom background scenes.

object
string
required
Allowed value: "asset"
category
enum<string>
required
Available options:
background,
license_plate,
banner,
logo,
misc
kind
enum<string>
required
deprecated

Legacy alias of category, retained for existing clients.

Available options:
background,
license_plate,
banner,
logo,
misc
name
string
required
content_type
string
required
size_bytes
integer
required

Total bytes in the asset package.

Required range: x >= 0
total_size_bytes
integer
required

Total bytes including all scene layers and YAML.

Required range: x >= 0
state
enum<string>
required
Available options:
available,
uploading,
deleting,
delete_failed,
deleted
created
integer<int64>
required

Epoch seconds, UTC.

Example:

1755300000

banner_placement
enum<string> | null
Available options:
top,
bottom,
null
background_id
integer | null

Historical numeric scene ID used in custom-- selectors.

Short-lived signed preview URL. Empty or omitted for unavailable assets; misc files use attachment downloads.

download_url
string

Short-lived signed download URL. Uses attachment Content-Disposition for misc files. Empty or omitted when unavailable.

files
object[]

Background package files returned by GET for an available scene. Includes all layers and YAML with individual signed download URLs. Omitted when unavailable.