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

# Cached emoji and images

> Search custom emoji and download cached display images without a lookup for each message

All paths on this page are relative to `https://inkbox.ai/api/v1/slack`. Cached display data belongs to one workspace connection and requires an active identity and connected workspace.

## List or search custom emoji

```text theme={null}
GET /connections/{connection_id}/emoji
```

| Query parameter | Type | Default | Meaning |
| :- | :- | :- | :- |
| `q` | string | Omitted | Filter emoji names; up to 100 characters |
| `limit` | integer | `100` | Page size, `1`–`200` |
| `cursor` | string | Omitted | Returned continuation cursor; up to 255 characters |

This endpoint reads the cached directory, not a live workspace listing. Continue with `next_cursor` while keeping the query unchanged. One page is not the entire directory. A missing cursor means this query exhausted the currently cached rows, not that synchronization is complete.

```json theme={null}
{
  "emoji": [
    {
      "name": "celebrate",
      "alias_of": "party",
      "image_url": null,
      "image_cached": false,
      "status": "ready"
    }
  ],
  "next_cursor": "celebrate",
  "status": "pending",
  "error_code": null
}
```

Each definition has `name`, nullable `alias_of` and `image_url`, `image_cached`, and `status`. An alias names another emoji; it does not necessarily have its own image. The cached-image endpoint accepts alias names and resolves their target within the selected connection, even if that target is outside the current directory page or search. Missing targets and alias cycles return `404`. If resolving aliases for display yourself, stop when a target is missing or repeats. Standard Unicode emoji are not entries in this custom directory.

The page's `status` and `error_code` describe directory readiness. Individual definitions have their own status. An empty page with pending or unavailable status is not proof that the workspace has no custom emoji. Missing `emoji:read` can leave the directory unavailable; inspect `custom_emoji_read` in [capabilities](/docs/api/slack/users#inspect-capabilities) and complete authorization again when needed. Changing requested permissions does not itself grant them.

```python Python theme={null}
page = inkbox.slack.list_cached_emoji(connection_id, q="party", limit=100)
for emoji in page.emoji:
    print(emoji.name, emoji.alias_of, emoji.image_cached)
# Continue explicitly with cursor=page.next_cursor when it is not None.
```

```typescript TypeScript theme={null}
const page = await inkbox.slack.listCachedEmoji(connectionId, {
  q: "party",
  limit: 100,
});
for (const emoji of page.emoji) {
  console.log(emoji.name, emoji.aliasOf, emoji.imageCached);
}
// Continue explicitly with cursor: page.nextCursor when it is not null.
```

```bash CLI theme={null}
inkbox slack emoji list \
  --connection-id 22222222-2222-4222-8222-222222222222 \
  --q party --limit 100 --json
```

## Download a cached display image

```text theme={null}
GET /connections/{connection_id}/cached-media/{kind}/{resource_id}
```

`kind` is `user`, `bot`, or `emoji`. Use the corresponding user ID, bot ID, or custom emoji name as `resource_id`. It is an identifier, not a URL. A successful response contains image bytes, not JSON. A missing cached image returns `404` when no capture is queued. Queued or running capture/repair and temporary storage failures return `503` with `Retry-After`; wait for that delay before retrying. These reads do not fetch an arbitrary remote image on demand.

Expanded archive actors and emoji definitions can contain authenticated relative image URLs when `avatar_cached` or `image_cached` is true. Use the SDK byte method or request the URL with your Inkbox credentials. When the cached flag is false, a fallback image URL may refer to the original image host. Never forward your Inkbox API key to that host.

```python Python theme={null}
image_bytes = inkbox.slack.download_cached_media(connection_id, "user", "U0123456789")
# An alias name can retrieve its target’s cached image.
emoji_bytes = inkbox.slack.download_cached_media(connection_id, "emoji", "celebrate")
```

```typescript TypeScript theme={null}
const imageBytes = await inkbox.slack.downloadCachedMedia(
  connectionId, "user", "U0123456789",
);
```

```bash CLI theme={null}
inkbox slack cached-media-download \
  --connection-id 22222222-2222-4222-8222-222222222222 \
  --kind user --resource-id U0123456789 --output avatar.png
```

The CLI writes a new file and refuses to overwrite an existing path. Cached images can change or become unavailable after a profile, emoji, or connection update. Keep image caches scoped to the connection and refresh when its generation changes. Use the separate [file preview endpoint](/docs/api/slack/files#download-a-cached-preview) for attachment images.


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