# list_shares

List the shooter's share links to themes and layouts, newest first.

## What it is for

`list_shares` lists the shooter's links to themes and layouts, newest first: what each shares, when it was made, how many times it was imported and whether it was stopped. These are links of the kind [share_appearance](share_appearance.md) makes (an import link `#/import/<code>`), not log shares: the profiles and logs other people share with the shooter are [list_shared_with_me](list_shared_with_me.md). It never shows an address and changes nothing. What the share tools have in common is on [the family page](appearance.md).

## What to know first

**It never shows an address.** A row holds none; for an address, make a new link with [share_appearance](share_appearance.md). The app keeps the address of a link made in the app, on the device that made it; one a tool made is only in that tool's reply.

**The `id` of a row is what `revoke_share` takes.** A row holds the name and kind in the frozen copy, not the record's id and not the version. Two links to one theme look alike but for the time made, also when they froze different versions.

**The spoken line names up to 20 running links;** the details hold every link, stopped ones included. Over 20, the line says how many more there are. A stopped link is counted in words only when no link is running.

**A name in a row can be another person's words.** It is the name the record had in the version frozen in the link. The details hold it as stored, and a name of several words is in quotation marks in the spoken line, cut to 40 characters.

**A link without the permission for appearance is not sent this tool.** It is not a read tool, though it only reads.

## Generated table

**Tool:** `list_shares` · **Family:** Appearance · **Scope:** `appearance` · **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 shooter's share links to themes and layouts, newest first. For profiles other people share use list_shared_with_me; to stop a link, revoke_share. Saves nothing. It needs the appearance permission. It says what each link shares, when it was made, how many import requests it has had and whether it was revoked; the links themselves can't be shown again. Guide: list_shares.
```

**Inputs:** none.

## When to use it, and when not

| The shooter wants | Use | Why |
|---|---|---|
| To see the links they made, or how many imports each has | `list_shares` | One row per link |
| A new link for a theme or layout | [share_appearance](share_appearance.md) | Makes a link and gives its address |
| A link stopped | [revoke_share](revoke_share.md) | Takes the `id` from here |
| The profiles or logs others shared with them | [list_shared_with_me](list_shared_with_me.md) | Those are log shares; no tool here stops or hides one |

## The inputs

The tool has no input. A key sent anyway is dropped, and the reply names it ([the connector overview](connector.md)).

## What it returns

The spoken line has four forms. With none: `You have no active share links.` With none running and some stopped: `You have no active share links (2 revoked links).` With 1 to 20 running: `You have 2 active share links: ` then each as `'<name>' (<kind>, <n> imports)`. Over 20: `You have 21 active share links. The newest 20: ...; and 1 more.` The stopped ones are never named aloud.

The details are `shares`, a list of every link, newest first, then by id.

| Key of a row | Holds |
|---|---|
| `id` | The link's id: what [revoke_share](revoke_share.md) takes |
| `kind` | `theme` or `layout` |
| `name` | The name in the frozen copy, as stored (an empty name is said as two apostrophes) |
| `created_at` | When it was made |
| `import_count` | How many import requests the link has had, signed-out ones included |
| `revoked_at` | When it was stopped; `null` while it runs |

A row holds no code and no address.

## 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 always answers when the server does. If the server fails, the reply is an error holding the server's own answer in quotation marks.

## What it reads and changes

**Reads** the account's share links from the server (the newest 20 are named aloud; the details hold all, stopped included, with no cap). **Changes** nothing.

## Below this page

- [share_appearance](share_appearance.md) and [revoke_share](revoke_share.md): make and stop a link.
- [list_shared_with_me](list_shared_with_me.md): the other kind of sharing.
- [the connector overview](connector.md), [the family page](appearance.md)

## Worked examples

**1. One running link and one stopped**

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`, `appearance`.

Call:
```json
{}
```

Spoken line:
```text
You have 1 active share link: 'Dusk' (theme, 0 imports).
```

Details:
```json
{
 "shares": [
  {
   "id": "3d8a1c6e92b7f054",
   "kind": "layout",
   "name": "Bench",
   "created_at": "(a time)",
   "import_count": 2,
   "revoked_at": "(a time)"
  },
  {
   "id": "9b4e7a20c5d1f836",
   "kind": "theme",
   "name": "Dusk",
   "created_at": "(a time)",
   "import_count": 0,
   "revoked_at": null
  }
 ]
}
```

Saved nothing.

**2. Twenty-three links**

Starting point: one theme, one layout and twenty-three share links for the theme, made on twenty-three days running, the two oldest stopped. Link scopes: `read`, `appearance`.

Call:
```json
{}
```

Spoken line:
```text
You have 21 active share links. The newest 20: 'Dusk' (theme, 0 imports), 'Dusk' (theme, 0 imports), 'Dusk' (theme, 0 imports), 'Dusk' (theme, 0 imports), 'Dusk' (theme, 0 imports), 'Dusk' (theme, 0 imports), 'Dusk' (theme, 0 imports), 'Dusk' (theme, 0 imports), 'Dusk' (theme, 0 imports), 'Dusk' (theme, 0 imports), 'Dusk' (theme, 0 imports), 'Dusk' (theme, 0 imports), 'Dusk' (theme, 0 imports), 'Dusk' (theme, 0 imports), 'Dusk' (theme, 0 imports), 'Dusk' (theme, 0 imports), 'Dusk' (theme, 0 imports), 'Dusk' (theme, 0 imports), 'Dusk' (theme, 0 imports), 'Dusk' (theme, 0 imports); and 1 more.
```

Details:
```json
{
 "shares": [
  {
   "id": "9b4e7a20c5d1f823",
   "kind": "theme",
   "name": "Dusk",
   "created_at": "(a time)",
   "import_count": 0,
   "revoked_at": null
  },
  {
   "id": "9b4e7a20c5d1f822",
   "kind": "theme",
   "name": "Dusk",
   "created_at": "(a time)",
   "import_count": 0,
   "revoked_at": null
  },
  {
   "id": "9b4e7a20c5d1f821",
   "kind": "theme",
   "name": "Dusk",
   "created_at": "(a time)",
   "import_count": 0,
   "revoked_at": null
  },
  "(20 more)"
 ]
}
```

Saved nothing.

**3. An account with no link**

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

Call:
```json
{}
```

Spoken line:
```text
You have no active share links.
```

Details:
```json
{
 "shares": []
}
```

Saved nothing.

---

[All reference pages](index.md)