# gifs.so

> The GIFs you actually use.

Search a curated library of reaction GIFs. REST and MCP share the same paid usage meter.

## Authentication

1. Create an account at https://gifs.so/signup using email/password, or GitHub when offered on the sign-in page. A verified email is required.
2. Email/password users must click the verification link sent by gifs.so through Resend. GitHub must report a verified email.
3. Activate usage billing at https://gifs.so/settings?tab=billing. Polar shows the rate before checkout. If pricing is not configured, paid access is unavailable.
4. Create an API key at https://gifs.so/settings?tab=api-keys. Keep it on your server; never include it in public browser code.

- REST: send an API key in the `x-api-key` header (keys are created by the user in the app; prefix `zts_`).
- MCP: OAuth 2.1 with PKCE, discovered from https://gifs.so/.well-known/oauth-protected-resource. Read-only tools need the read scope; everything else needs write scope.

## Endpoints

- MCP server (Streamable HTTP): https://gifs.so/api/mcp
- OpenAPI document: https://gifs.so/api/openapi.json
- REST base URL: https://gifs.so/api/rest
- OAuth authorization server metadata: https://gifs.so/.well-known/oauth-authorization-server

## MCP tools (read-only)

- get_gif (read-only): Get a GIF and its shareable media URLs Costs one usage request on success.
- list_categories (read-only): List reaction categories and their cover GIFs Costs one usage request on success.
- list_gifs (read-only): Search GIFs by text or reaction category Costs one usage request on success.

## MCP tools (write)


## REST example

```sh
curl 'https://gifs.so/api/rest/gifs?query=happy&limit=10' -H 'x-api-key: YOUR_API_KEY'
```

Search returns items, total, and nextOffset. Use offset=nextOffset for the next page. Each item contains gifUrl, mp4Url, thumbnailUrl, dimensions, title, tags, and sourceUrl. GET /categories lists category IDs; GET /gifs/{id} looks up one GIF.

## Connect an MCP client

Add https://gifs.so/api/mcp as a remote Streamable HTTP MCP server in your client (for example, Claude or Cursor). Follow its OAuth authorization flow and connect an API key from your verified account.
The OAuth scopes are zts:read and zts:write. GIF tools only need zts:read. Use list_categories, list_gifs, and get_gif. Tool discovery and OAuth do not incur usage charges.

## Usage and retries

API and MCP are paid-only. There is no free request allowance or free API trial.

- One successful GIF search, GIF lookup, or category-list operation costs one request, on either REST or MCP. Results per page do not multiply the charge.
- Browser library browsing, raw media downloads, authentication, failed operations, and tool discovery are not metered.
- All GIF operations accept an optional requestId UUID. Generate it once per logical operation and reuse it with identical parameters when retrying. A different requestId is a new billable operation; reuse with changed parameters returns CONFLICT. Without requestId, every successful call counts.
- Usage is durably recorded and sent to Polar asynchronously. Billing totals can take a few minutes to update. Late delivery appears in the current Polar billing cycle.
- REST errors: 401 authentication/verified email required; 402 active usage subscription required; 404 unknown GIF/category; 409 conflicting requestId; 429 rate limit; 503 billing unavailable. MCP reports these as tool errors. Do not automatically retry successful calls with a new requestId.
- Share and embed the returned media URLs directly. They are public, immutable URLs hosted on Cloudflare R2.

## Notes

- Tool input schemas are served by the MCP `tools/list` method and mirror the OpenAPI request bodies.
- Destructive tools (delete/remove/clear/reset) are marked with `destructiveHint` and may require explicit confirmation from the user.