> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trycarhub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Permanent assets

> Store reusable logos, plate artwork, banners, files, and custom backgrounds.

Upload artwork once and reuse it from the dashboard or the CarHub API. Assets
belong to your organization and remain available until you delete them. CarHub
stores them in private storage and returns short-lived signed download links.

## Choose a category

| Category | Contents | Accepted files |
| - | - | - |
| `background` | Custom Studio scene, including its layers and YAML | Complete Studio package |
| `license_plate` | Artwork placed over license plates | PNG, JPEG, WebP |
| `banner` | Top or bottom banner | PNG, JPEG, WebP |
| `logo` | Reusable brand logo | PNG, JPEG, WebP |
| `misc` | Other files you want to keep | Any file type |

Flat files have a 25 MiB upload limit. Banners also require `banner_placement`
set to `top` or `bottom`. Use the specialized Studio flow for background
packages; uploading one image does not create a complete background scene.

## Upload and list assets

Grant your API key `assets:write` to upload and delete assets. It includes
`assets:read`, which permits listing and downloading. Asset access does not
grant permission to submit inference jobs; grant each destination endpoint
separately.

```bash theme={null}
curl https://api.trycarhub.com/v1/assets \
  -H "Authorization: Bearer $CARHUB_API_KEY" \
  -F category=logo \
  -F name="Dealer logo" \
  -F file=@dealer-logo.png
```

The response includes a UUID `id`, `category`, legacy `kind`, name, content
type, `size_bytes`, `total_size_bytes`, `state`, creation timestamp, and signed
links. Scene sizes include every image layer and the generated YAML. The
legacy `kind` field remains supported for uploads and responses. If you send
both `category` and `kind`, they must match.

```bash theme={null}
curl "https://api.trycarhub.com/v1/assets?category=logo&limit=20" \
  -H "Authorization: Bearer $CARHUB_API_KEY"
```

Read `data`, `has_more`, and `next_cursor` from the list response. Pass the
returned UUID cursor as `cursor` for the next page. The maximum `limit` is 100.
Use `GET /v1/assets/{id}` to refresh an asset's metadata and signed links.
Files in `misc` use `download_url` with an attachment disposition so browsers
download them. Fetch signed links without forwarding your API key.

For an available background scene, the detail response also includes `files`.
Each entry contains its relative `path`, `size_bytes`, and signed `download_url`.
Download every entry to preserve the complete scene package. The dashboard
packages these files as a ZIP download.

For a background package, `POST /v1/assets` accepts `category=background`,
`name`, `interior_id`, generated `yaml`, and the files `image`,
`non_floor_rgba`, `floor_rgba`, and `to_ignore_mask`. You can also send `brands`
as a JSON-encoded array. Existing Studio routes remain supported.

## Select an asset for rendering

For `render.plate`, send a `license_plate` or `logo` asset UUID as
`logo_asset_id` with `mode=logo`:

```json theme={null}
{
  "input_refs": ["upl_7Qm2hV9tXbLd"],
  "mode": "logo",
  "logo_asset_id": "a451e393-e0a6-4d60-9bf6-940a276163be"
}
```

Do not combine `logo_asset_id` with `logo` or the legacy `logo_ref`. The API
checks ownership, category, and availability before resolving the private
file for the worker.

Custom background scenes keep their historical numeric `background_id` in
addition to their asset UUID. Continue using `background: "custom--<ID>"`
with `render.background`. Existing logo and banner asset selectors remain
supported.

The preview `render.video` contract accepts a `logo` asset through
`branding.logo_asset_id`. Do not combine it with `branding.logo`,
`branding.logo_url`, or `branding.logo_ref`. This contract does not change
the video endpoint's availability or enable its rendering engine.

## Quota and deletion

Permanent assets and inference inputs share your organization's existing
storage quota. CarHub reserves space before uploading. Use
`GET /v1/uploads/usage` to inspect the total `stored_bytes`, `reserved_bytes`,
and `available_bytes`. `asset_bytes` and `asset_reserved_bytes` show the asset
portion of those totals. Input retention and output accounting remain unchanged.

```bash theme={null}
curl -X DELETE https://api.trycarhub.com/v1/assets/ASSET_UUID \
  -H "Authorization: Bearer $CARHUB_API_KEY"
```

Deletion immediately blocks new jobs from selecting the asset. Existing jobs
finish before CarHub removes its files. The response reports `deleted: true`
and `state: "deleting"`; this confirms the request, while physical deletion
may still be pending. Metadata remains visible without signed links while
deletion is pending. CarHub retries `delete_failed` assets, and releases quota
only after storage confirms removal. After deletion completes, retrieving the
asset returns `404`.

Input retention, input deletion, and input space-recovery operations never
select permanent assets. Failed uploads also keep their reservation until
their partial files have been removed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.