# Klipy GIFs

> **Status:** Active
> **Last updated:** 2026-07-05

## Overview

GIF search in chat and DM composers via a **Klipy API proxy** on the signaling server. API keys stay server-side; clients call same-origin routes on the active signal server.

## Responsibilities

- Server: proxy/search Klipy API (`variables.json` `klipyApiKey`).
- Client `chat` domain: `KlipyService`, composer picker; DMs reuse the same integration.

## API

### `GET /api/klipy/config`

- **Auth:** Public
- **Response:** `{ enabled: boolean }` — `enabled` when server has a configured API key

### `GET /api/klipy/gifs`

- **Auth:** Public
- **Query:** `q` (search), `page`, `per_page` (default 24, max 50)
- **Response:** Normalised `{ gifs: [{ id, slug, title, url, previewUrl, width, height }], hasNext }`
- **Upstream:** `https://api.klipy.com/api/v1` with 8 s timeout

## Client behavior

- GIF picker visibility is resolved against the **current chat-server's** signal server (not a global offline endpoint) so KLIPY availability matches the room's backend.
- Selected GIFs send as markdown image messages; rendering uses [link-preview-media-proxy.md](link-preview-media-proxy.md) image proxy when needed.

## Related

- [server-directory.md](server-directory.md) — per-room signal server for config
- [direct-messaging.md](direct-messaging.md) — DM composer reuse
- Domain README: [`toju-app/src/app/domains/chat/README.md`](../../toju-app/src/app/domains/chat/README.md)

## Changelog

| Date | Change |
|------|--------|
| 2026-07-05 | Initial Klipy proxy contract |