# list_assets

List the background images the shooter uploaded in the theme editor: sha256, type, size, date and ref.

## What it is for

`list_assets` lists the background pictures the shooter uploaded in the app's theme editor, each with the reference a theme background uses. It is the only way an assistant learns such a reference. It returns no picture and no log photo, uploads nothing and changes nothing. Terms are on [the family page](appearance.md).

## What to know first

**The picture is named by `ref`.** Each row's `ref` is `asset:` and the picture's 64-character hash. A theme background of kind `image` takes exactly that text, from this list.

**Only theme pictures are listed.** Photos saved with logged groups are not. The tool returns a hash, a type, a size and a date for each picture, never the picture itself.

**No tool uploads one.** The shooter adds pictures in the theme editor of the app. The tool cannot fetch a picture from a web address.

**The spoken allowance is rounded.** The line says megabytes used of 105 MB, counting a million bytes to the megabyte; the app and the server's refusal call the same allowance 100 MB. `quota` is 104,857,600 bytes.

## Generated table

**Tool:** `list_assets` · **Family:** Appearance · **Scope:** any link · **Save scope:** none · **Changes:** nothing · **Runs:** no solver work in the connector

**Description** (what the connector sends to an assistant, word for word):

```text
List the background images the shooter uploaded in the theme editor: sha256, type, size, date and ref. Use a ref from it as a theme background, {kind: "image", asset: ref}. Saves nothing. Any link has it. No tool uploads an image, and none can come from a web address; photos saved with logged groups are not listed. Guide: list_assets.
```

**Inputs:** none.

## When to use it, and when not

| The shooter wants | Use | Why |
|---|---|---|
| To use a picture they uploaded as a theme background | `list_assets`, then [edit_theme](edit_theme.md), if the link has it | The list gives the reference the edit takes |
| To know how much of the picture allowance is used | `list_assets` | `used` and `quota`, in bytes |
| Themes, layouts or devices | [list_appearance](list_appearance.md) | This tool lists pictures only |
| A theme's current background | [get_theme](get_theme.md) | Its `content` holds the background |

If the list is empty, tell the shooter to upload the picture in the app's theme editor.

## The inputs

The tool has no input.

## What it returns

With no picture the line says none is uploaded and to upload in the theme editor in the app. With some, it gives the count and the megabytes used of 105 MB.

| Key | Holds |
|---|---|
| `assets` | Each picture: `sha256`, `mime` (its type), `size` (bytes), `created_at` and `ref` |
| `used` | Bytes the listed pictures take, plus the copy kept of a picture shared by link (without its place or camera details) |
| `quota` | The allowance in bytes: 104,857,600 on the server |

The pictures come oldest first, then by hash. A small picture can be spoken as `0.0 MB`, since the line gives one decimal. The tool returns no stored text. The example with no picture shows a made-up allowance of 100,000,000; the server's is 104,857,600.

## Worked examples

Every example below was run by the documentation generator against a made-up account, never a real one. Numbers are rounded to three places; generated ids and times are shown as placeholders. Two things are printed more briefly than the tool sent them, and nothing else is changed. A list of plain values stands on one line, whole up to 12 entries (a longer one, and a list of objects past 3, ends with a count of the rest). A reply that puts stored text in quotation marks also carries a note saying so, which an example leaves out and marks instead; no reply below carried it.

## When it refuses

The tool has no refusal of its own. With no picture it answers that there is none. A failure to reach the server is worded by the connector, on [the connector overview](connector.md).

## What it reads and changes

It reads the account's uploaded images. It saves nothing and sends no command. It reads no profile, no session and no theme.

## Below this page

- [edit_theme](edit_theme.md): puts a listed picture behind a theme, if the link has it.
- [get_theme](get_theme.md): a theme's background as saved.
- [list_appearance](list_appearance.md): themes, layouts and devices.
- [the connector overview](connector.md), [the family page](appearance.md)

## Worked examples

**1. One uploaded image**

Starting point: a theme at version 2, a layout, one uploaded image of 48 kB, two share links (one for the theme, and a later one for the layout that was stopped) and one phone. Link scopes: `read`.

Call:
```json
{}
```

Spoken line:
```text
You have 1 background image (0.0 MB of 105 MB used).
```

Details:
```json
{
 "assets": [
  {
   "sha256": "c07e5a1934fb268dc07e5a1934fb268dc07e5a1934fb268dc07e5a1934fb268d",
   "mime": "image/jpeg",
   "size": 48000,
   "created_at": "(a time)",
   "ref": "asset:c07e5a1934fb268dc07e5a1934fb268dc07e5a1934fb268dc07e5a1934fb268d"
  }
 ],
 "used": 48000,
 "quota": 104857600
}
```

Saved nothing.

**2. No image**

Starting point: one theme and one layout of the shooter's, and one phone. Link scopes: `read`.

Call:
```json
{}
```

Spoken line:
```text
You haven't uploaded any background images. Upload them in the theme editor in the app; I can't fetch images from the web.
```

Details:
```json
{
 "assets": [],
 "used": 0,
 "quota": 100000000
}
```

Saved nothing.

---

[All reference pages](index.md)