# gifs.nostr.build: integration guide for AI agents

> Free GIF search for Nostr clients, run by nostr.build. This guide is for coding agents adding a GIF button and picker to a Nostr app (web or native). Read it whole before writing code. Every rule here was checked against the live service; where it says MUST, getting it wrong breaks the integration or the terms.

- API base: https://gifs.nostr.build/api/v1
- OpenAPI 3.1: https://gifs.nostr.build/api/v1/openapi.json
- Human reference: https://gifs.nostr.build/developers/reference
- Registration and dashboard: https://gifs.nostr.build/developers
- Short index: https://gifs.nostr.build/llms.txt

---

## 0. Checklist (do all of these)

1. The app's developer (a human) registers the client at https://gifs.nostr.build/developers. You cannot do this for them: it needs their Nostr signer and a one-time 1000-sat Lightning payment. Web code can be developed before that from `http://localhost` (any port), which works without registering. Native code cannot: it needs an API key, so registration comes first (section 1).
2. Web: register the site's Origin. Send NO `Authorization` header from browser code (the CORS preflight does not allow it; the browser will block the request). Native: send `Authorization: Bearer gnb_…` (an API key from the dashboard).
3. Show "GIFs from nostr.build", linked to https://nostr.build, wherever the GIFs appear (the picker's header is the usual place). This is a condition of use.
4. Search with `GET /search?q=…`; show `previews.w240` or `previews.w480` in the grid (not the original); post the item's `url` (the original) in the note, with a NIP-92 `imeta` tag.
5. Debounce typing (about 250 ms), skip one-letter queries, abort stale requests, and handle 400 / 403 / 429 / 503 as described in section 6.
6. Lay tiles out from the API's `width`/`height` before images load (no layout shift), lazy-load, and animate only what is in view; respect `prefers-reduced-motion`.
7. Never upload or re-host the GIF. Link it where it is.

---

## 1. Identification (the part agents most often get wrong)

Every request must identify a registered client. The server decides in this order, and the first one present decides alone:

1. `Origin` header (any value other than the opaque `null`). Browsers send it automatically on cross-origin requests. If an Origin is present it alone decides: a request with an unregistered Origin is refused even if it also carries a valid API key.
2. `Authorization: Bearer gnb_…` (an API key), when there is no Origin.
3. `User-Agent`, matched against patterns a nostr.build admin has reviewed, when there is neither.

Consequences:

- **Browser / web app**: register the exact origin (`https://app.example.com`) or a wildcard for subdomains (`https://*.example.com`) in the dashboard. Origins whose domain proves the owner with a `_@domain` NIP-05 are approved automatically; others wait for review. Call the API with a plain `fetch(url)`: no custom headers.
- **Never send `Authorization` from a browser.** Only `GET, HEAD` and no request headers are allowed in CORS preflight, so a browser request with `Authorization` fails before it is sent. It would also leak the key.
- **`http://localhost`, `https://localhost`, `http://127.0.0.1` and `http://[::1]` (http or https, any port)** are admitted as a built-in development client, without registering. It is for development only: everyone shares it (and its rate limit). Register before shipping.
- **Native apps (iOS, Android, desktop, CLI, server)**: no Origin is sent, so use an API key (create it in the dashboard after registering; it is shown once). There is no unregistered path for native code: get the key first. Never fake an `Origin: http://localhost` header from native code to get around this. Keys ship inside apps and are not secret in any strong sense; that is accepted. Do not put them in public web bundles.
- **Hybrid apps (Capacitor, Ionic, Tauri, Electron, other WebViews)**: only `http`/`https` origins with a real domain can be registered, so a WebView whose Origin is `capacitor://localhost`, `tauri://localhost`, `ionic://localhost`, `file://` or similar can never be admitted by Origin (and its Origin makes the server ignore any API key). Call the API from the native side instead (CapacitorHttp / `@capacitor/core` native HTTP, the Tauri `http` plugin, Electron's main process, a native module), which sends no Origin, with the API key. A WebView served as `https://localhost` (Capacitor on Android) is admitted only as the shared development client: do not ship on that.
- **A server-side proxy** of your own: use an API key and do not forward the browser's Origin.
- Unregistered: `403 client_not_registered`. Registry hiccup: `503 registry_unavailable` (retry shortly). In a browser, both reach your code as a network/CORS error (no status, no body), because they are answered before CORS headers are added: treat a failed `fetch` as "unavailable, retry later", and check registration if it persists.
- Admission answers are cached per data centre: after the human registers an Origin or creates a key, allow up to 5 minutes before it works everywhere (an earlier 403 is remembered that long). A deleted key or origin can keep working for up to an hour. Don't change correct code because of a 403 in the first minutes after registering.

Registration facts to tell the human:

- Sign in with Nostr at https://gifs.nostr.build/developers (NIP-07 browser extension or a NIP-46 bunker such as Amber or nsec.app).
- Registering a client costs 1000 sats, once, paid by Lightning (QR, wallet link or WebLN). The fee only keeps spam sign-ups out; it is not refunded if the client is deleted.
- Limits: 5 clients per pubkey; per client 10 owners, 20 origins, 10 API keys, 10 User-Agents, 10 pending requests.
- Registering requires accepting the attribution terms (section 2).

---

## 2. Attribution (required)

Show "GIFs from nostr.build", linked to https://nostr.build, wherever these GIFs appear, for example in your GIF picker's header. Exact snippet:

```html
GIFs from <a href="https://nostr.build" target="_blank" rel="noopener noreferrer">nostr.build</a>
```

Make it visible (not hidden behind a menu), legible, and a real link. In native apps, open the link in the system browser.

---

## 3. Endpoints

All are `GET`, return JSON, and accept `safe` (`1`, the default, excludes adult GIFs; `0` is refused with `403 adult_not_allowed`, so leave it out).

### GET /api/v1/search

| Param | Type | Default | Notes |
|---|---|---|---|
| `q` | string, 1–500 chars | required | Words in any language, emoji, or both. See section 5 for how it is normalised. |
| `limit` | 1–200 | 24 | Items in this page. |
| `offset` | ≥ 0 | 0 | Past the end the page is shorter or empty (never an error). |
| `mode` | `auto` \| `text` \| `semantic` | `auto` | `auto` blends full-text and meaning. `text` matches words only. `semantic` only by meaning (503 if the embedder is down). Leave it at `auto` in a picker. |

Response:

```json
{
  "build": "20260927T234106Z",
  "gen": 2,
  "q": "wave",
  "semantic": true,
  "count": 200,
  "offset": 0,
  "limit": 24,
  "items": [ /* Gif objects, section 4 */ ]
}
```

- `q`: the query as it was searched (normalised).
- `count`: the length of this query's ranked list, at most 200. It is not the number of matching GIFs in the index; 200 is the most any query returns.
- `semantic`: `false` means the meaning leg did not run: with `mode=text` that is expected; under `mode=auto` it means the embedder was down, the results are words-only, and that degraded answer is cached for only a minute (the full answer replaces it once the embedder is back).
- `build`: the index build. If it changes between pages of the same query, start again from offset 0.
- `gen`: cache generation (ignore it unless debugging).

### GET /api/v1/suggest

Autocomplete: the index's own terms that start with `q`, most used first.

| Param | Type | Default |
|---|---|---|
| `q` | string, 1–500 chars | required |
| `limit` | 1–20 | 8 |

Response: `{ "build", "gen", "q", "terms": [{ "term": "cat face", "kind": "tag" | "character" | "title" | "text", "n": 412, "fuzzy"?: true }] }`. `fuzzy: true` marks trigram (typo-tolerant) matches that follow when prefix matches come up short (4+ characters). An emoji is completed by its name (🐱 suggests "cat face …").

### GET /api/v1/gifs/{id}/similar

GIFs that look like one GIF, nearest first. `id` is an item's `id` (for example `<sha256>.gif`, pattern `^\w[\w.-]{0,199}$`). `limit` 1–50, default 24. Unknown id: `404 not_found` (cached like a 200). Response: `{ "build", "gen", "items": [Gif…] }`.

### Examples

```js
// Browser: no headers. Origin is sent by the browser.
const res = await fetch(
  `https://gifs.nostr.build/api/v1/search?q=${encodeURIComponent(q)}&limit=24`,
  { signal }
)
```

```sh
# Native / server: API key.
curl -H 'Authorization: Bearer gnb_…' \
  'https://gifs.nostr.build/api/v1/search?q=good%20morning&limit=24'
```

Always build the query with `encodeURIComponent` (or `URLSearchParams`): queries contain spaces, emoji and non-Latin scripts.

---

## 4. The Gif object, and which file to use where

```json
{
  "id": "20099e4e…59051.gif",
  "url": "https://gifs.nostr.build/20099e4e…59051.gif",
  "width": 224, "height": 126,
  "frames": 37, "duration": 3.7, "bytes": 806309,
  "format": "gif",
  "title": "Giant wave curling with an eye",
  "tags": ["wave", "ocean", "sea"],
  "lqip": "data:image/webp;base64,UklGRs4AAABXRUJQ…",
  "mp4": "https://gifs.nostr.build/mp4/orig/20099e4e…59051.gif",
  "previews": {
    "small":  { "width": 171, "height": 96,  "animated": "…/anim/96/…",   "still": "…/still/96/…" },
    "medium": { "width": 224, "height": 126, "animated": "…/anim/192/…",  "still": "…/still/192/…" },
    "w240":   { "width": 224, "height": 126, "animated": "…/anim/w240/…", "still": "…/still/w240/…" },
    "w480":   { "width": 224, "height": 126, "animated": "…/anim/w480/…", "still": "…/still/w480/…" }
  }
}
```

| Field | Use it for | Gotchas |
|---|---|---|
| `url` | What you post in the note; what "copy link" copies. | The original file (GIF or WebP per `format`), often MBs. Never use it as a grid thumbnail. |
| `previews.w240` / `w480` | Grid tiles in columns: `w240` when the viewport is under 640 px, `w480` from 640 px (or pick by column width × devicePixelRatio). | Fitted to a width, never enlarged: a small GIF's `w480` is its own size. Same shape as the original. |
| `previews.small` / `medium` | Horizontal strips (rows). | Fitted to at most 96 or 192 px tall, never enlarged: a small GIF's `medium` is shorter than 192 px. Lay each tile out from that preview's own `width`/`height`. |
| `…animated` | The moving preview. | **Animated WebP even though the URL ends in `.gif`.** Do not infer type from the extension. `null` when the GIF is too large to animate: show `still` instead. |
| `…still` | First frame (PNG): poster while loading, the preview under reduced motion, the fallback when `animated` is null or fails. | |
| `lqip` | A tiny blurred placeholder (data URI) to paint before the preview loads. | **Remove it when the image loads**: many GIFs are transparent and the blur shows through otherwise. May be `null`. |
| `mp4` | H.264 of the animation at source size, many times smaller than the GIF: best for large grids or full-size playback. | No audio, no loop flag: use `<video loop muted autoplay playsinline poster="…still…">`. Transparency renders on black. `null` for stills and past 60 s, 1800 frames or 4096 px. It can still return 404 the first time if conversion fails: on the video `error` event fall back to the animated preview or `url`. |
| `width`, `height` | Lay out tiles before anything loads. | Use them for aspect ratio; clamp extreme shapes (for example ratio 0.75–2) so no tile is a sliver or a tower. |
| `title` | `alt` text, tooltip, the note's `imeta` `alt`. | May be empty: fall back to "GIF". |
| `format`, `bytes`, `frames`, `duration` | `imeta` `m` (`image/gif` or `image/webp`) and `size`; showing file size. | `bytes`, `frames`, `duration` may be `null`. `duration` is in seconds. |

Media gotchas:

- Load previews with `<img>` (or `new Image()` for preloading), not `fetch()`. The media host varies responses on `Origin`, so a `fetch` (CORS mode) and an `<img>` are different cache entries: prefetching with `fetch` downloads twice.
- Validate URLs you render: media URLs (`url`, previews, `mp4`) are always `https://gifs.nostr.build/…`; treat any other host as invalid. `lqip` is the exception: a `data:image/…;base64,…` URI (accept only that form).
- Media files are public and need no identification; only the JSON API does.

---

## 5. Queries

The server normalises `q` before searching and caching, and returns the normalised form in `q`:

- Lower-cased, Unicode NFKC, whitespace collapsed, cut to 100 characters (never inside a character).
- Letters and digits in any script are kept; punctuation and search syntax (`-word`, `"phrase"`) are dropped. An apostrophe is kept only inside a word ("don't").
- **Emoji work** and are searched by meaning: 😂 → laughing faces, 🐱 → cats, 🇺🇸 → the flag, 👍🏽 → thumbs up (skin tones are ignored). Mix them with words ("lol 😂"). A lone skin tone is nothing.
- A `q` that normalises to nothing (`"!!!"`, `"🏽"`) is `400 validation`. Check before sending: if your input has no letter, digit or emoji, show the starters instead.

Client-side rules for a good picker:

- Don't search a single Latin letter (it is noise and spends the rate budget). Do search one emoji, one CJK ideograph (猫) or Hangul syllable (개), and any two characters.
- Debounce typing about 250 ms. Abort the previous request when a new one starts (`AbortController`), and ignore late answers.
- Key your client cache by the normalised query (or by the `q` the server returns), so "Cat!" and "cat" are one entry.
- There is no trending endpoint. Open the picker on a few everyday starter searches shown as chips, for example: gm, lol, yes, wow, applause, facepalm, love, fire. Run the first one on open.
- Show `suggest` terms as chips under the field while typing (leave out the one equal to the current query).

---

## 6. Errors, limits and retries

Error body (all non-2xx): `{ "error": { "code": "…", "message": "…" } }`.

| Status | code | Meaning | What to do |
|---|---|---|---|
| 400 | `validation` | Bad parameter, or `q` normalised to nothing. | Fix the request; don't retry as is. |
| 403 | `client_not_registered` | Origin / key / UA not registered. | Register (section 1). Don't retry. |
| 403 | `adult_not_allowed` | `safe=0` was sent. | Drop `safe=0`. |
| 404 | `not_found` | Unknown GIF id (similar) or route. | Don't retry. |
| 429 | `rate_limited` | Over the limit. Sends `Retry-After: 60`. | Tell the user to wait a minute, then retry. Browser JavaScript cannot read `Retry-After` (the header is not exposed to CORS), so wait 60 s rather than reading it; native code can read it. Don't hammer. |
| 503 | `upstream_unavailable` / `registry_unavailable` | Temporary (search backend or client registry). | "Search is unavailable right now"; retry with backoff (a few seconds, then longer). |

Limits: 120 requests per minute per IP and 1000 per minute per client, counted only on requests that reach the API (answers already cached at the edge are free, but you can't tell which those are). A debounced picker stays far below this. Use a request timeout of about 15 s; answers usually take well under a second.

CORS: responses echo your registered Origin in `Access-Control-Allow-Origin` with `Vary: Origin`. Unregistered origins get no CORS headers (the browser shows a CORS error; the real answer is 403).

---

## 7. Caching and paging

- Search, suggest and similar answers are cached at the edge for an hour and in the browser for 5 minutes (`Cache-Control: public, max-age=300`); a degraded (words-only) answer for a minute. Don't add cache-busting parameters.
- A query's list is fixed for its cache life, so paging is stable: page with `offset` += `limit` until a page has fewer than `limit` items or `offset` reaches `count`. Past the end you simply get fewer or no items.
- Alternatively fetch the whole list once with `limit=200` and render it virtually (only tiles near the viewport in the DOM). That is one request per query instead of up to nine.
- If `build` changes between pages, restart from offset 0 (the index was rebuilt). Do the same if `semantic` changes between pages of one query (a degraded words-only list was replaced by the full one).

---

## 8. UI/UX blueprint for the GIF button and picker

The button:

- Put a "GIF" button next to the composer's attach/emoji buttons. Accessible name "Add a GIF" (or the visible text "GIF"). Same size and style as its neighbours.
- It opens the picker as a popover/sheet anchored to the composer (a bottom sheet on phones). Escape and a click outside close it; focus returns to the button.

The picker:

- Header: the search field, then the attribution "GIFs from nostr.build" link (required, section 2), and a close button.
- On phones, do not focus the field on open (that pops the keyboard over the grid); open on the first starter chip's results and let the user tap the field.
- Chips row: starters when the field is empty, `suggest` terms while typing; horizontally scrollable on small screens.
- Grid: masonry columns, each GIF at its own shape. Two columns on a phone; more only where each column stays at least about 180 px wide (three or four at most). A few large GIFs, not a wall of tiny ones: every GIF in view is animating and costs data and battery.
- Size each tile from `width`/`height` at the column width before it loads, paint `lqip` (or a solid placeholder) behind it, and remove the placeholder on `load`. `loading="lazy"` and `decoding="async"` on images.
- Animate only tiles in or near the viewport (virtualize long lists). Under `prefers-reduced-motion: reduce` show `still`, animating at most on hover/focus.
- Each tile is a button whose accessible name is the GIF's `title` (or "GIF"). Picking a GIF inserts it into the composer (section 9) and closes the picker. One pick per opening (ignore a double tap during the close animation).
- Optional per-tile actions (show them on hover/focus, and on touch only after the tile is opened by a first tap so a stray tap never fires a hidden action): "Similar" (calls `/gifs/{id}/similar`), "Copy link" (copies `url`).
- States: a skeleton grid while the first page loads; "No GIFs for “…”" with the starters when empty; for 429 "Too many searches, wait a minute"; for 503 or a network error "Search is unavailable right now" with a retry button. Never leave an endless spinner.
- Keyboard: Tab reaches the field, the chips and the tiles in order; arrow keys may move between tiles; Enter picks. Visible focus rings that are never clipped by a scroll container or rounded tile (inset them or leave padding). Announce result counts in a polite live region.
- Dark and light themes: tiles need a neutral placeholder colour, since transparent GIFs show the background.
- Keep `safe` at its default. There is no adult mode.

---

## 9. Posting the GIF to Nostr

- Put the item's `url` in the note's content (on its own line, or where the cursor is). Never post a preview URL; previews are for picking.
- Add a NIP-92 `imeta` tag describing it, so clients can lay it out before loading:

```json
["imeta",
  "url https://gifs.nostr.build/20099e4e…59051.gif",
  "m image/gif",
  "dim 224x126",
  "size 806309",
  "alt Giant wave curling with an eye"]
```

  `m` comes from `format` (`gif` → `image/gif`, `webp` → `image/webp`); leave out `size` when `bytes` is null and `alt` when `title` is empty.
- Do not upload the GIF anywhere (it is already hosted) and do not rewrite the URL.

---

## 10. Before you call it done

- [ ] Web: works from `http://localhost` before registering; the human has registered the production Origin. Native / hybrid: requests go from native code with the API key.
- [ ] Browser requests send no custom headers; native requests send the API key.
- [ ] "GIFs from nostr.build" link visible in the picker.
- [ ] Grid uses `w240`/`w480` previews (not `url`), sized from `width`/`height`, placeholder removed on load, still shown when `animated` is null.
- [ ] Notes contain `url` plus an `imeta` tag.
- [ ] Debounce, one-letter skip, abort of stale requests; 400/403/429/503 each handled with a clear message.
- [ ] Emoji and non-Latin queries tried (😂, 猫, "café").
- [ ] Keyboard-only and screen-reader pass; focus rings fully visible; reduced motion respected.
- [ ] Tested on a phone-width screen: two columns, no keyboard popping on open, no horizontal scroll.

---

## Links

- Register a client and manage origins, keys and User-Agents: https://gifs.nostr.build/developers
- API reference (human): https://gifs.nostr.build/developers/reference
- OpenAPI JSON: https://gifs.nostr.build/api/v1/openapi.json
- Try it live (search demo on the landing page): https://gifs.nostr.build/developers#try-it
- nostr.build: https://nostr.build