# MemeStack API — Full Documentation

> Complete API reference for AI agents and developers.
> For a quick overview, see: https://memestack.ai/llms.txt
> OpenAPI 3.1 spec: https://api.memestack.ai/openapi.json
> Developer docs: https://memestack.ai/developers

## Base URL

https://api.memestack.ai

All read endpoints are public — no authentication required.
Responses are JSON unless otherwise noted (image endpoints return image bytes).

## Authentication

Read endpoints require no auth. Write endpoints (upload, zap, wallet) use JWT bearer tokens via LNURL-auth (Lightning Network login). These are not covered here — this document focuses on the public read API.

## Rate Limits

- Search: 60 requests/minute
- General endpoints: no explicit rate limit (reasonable use expected)
- Responses include standard HTTP status codes (429 for rate limit exceeded)

## Error Format

All errors return JSON:
{ "error": "Human-readable error message" }

Common status codes: 400 (bad request), 404 (not found), 429 (rate limited), 500 (server error)

---

## Search

### Unified Search

GET /v1/images/search?q={query}

Every search runs semantic similarity (vector embeddings) combined with keyword matching — no mode toggle needed. Works for both conceptual queries ("proof of work explained") and literal phrase lookups ("laser eyes").

Parameters:
- q (required for search, optional for browse): Search query string
- limit: Number of results (default 20, max 100)
- offset: Pagination offset (default 0)
- tag: Filter by a single tag slug (e.g., "bitcoin", "memes")
- tags: Filter by multiple tag slugs, comma-separated — AND logic (e.g., "bitcoin,charts")
- sort_by: Sort field — "created_at" (default), "zap_total_sats", "save_count", "trending"
- sort_order: "asc" or "desc" (default "desc")

Example:
  curl "https://api.memestack.ai/v1/images/search?q=bitcoin+halving+explained&limit=5"

Response:
{
  "images": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "caption": "Bitcoin halving cycle chart showing supply reduction every 210,000 blocks",
      "alt_text": "Line chart depicting Bitcoin's halving schedule from 2009 to 2140",
      "tags": ["bitcoin", "halving"],
      "free_tags": ["supply schedule", "block reward", "monetary policy"],
      "text_in_image": "Block Reward: 50 → 25 → 12.5 → 6.25 → 3.125 BTC",
      "width": 1920,
      "height": 1080,
      "thumb_width": 768,
      "thumb_height": 432,
      "zap_count": 42,
      "zap_total_sats": 1250,
      "save_count": 15,
      "uploader_display_name": "satoshi_charts",
      "uploader_pubkey": "02abc...def",
      "created_at": "2026-03-15T10:30:00Z",
      "updated_at": "2026-03-16T14:00:00Z"
    }
  ],
  "count": 5,
  "total": 23
}

---

## Browse Images

For browsing with filters, sorting, and pagination, use the search endpoint without a query:

### Browse by Tag

GET /v1/images/search?tag={slug}&limit=20

Example — meme images:
  curl "https://api.memestack.ai/v1/images/search?tag=memes&limit=20"

Filter by multiple tags (AND):
  curl "https://api.memestack.ai/v1/images/search?tags=bitcoin,charts&limit=20"

### Browse by Popularity

GET /v1/images/search?sort_by=zap_total_sats&sort_order=desc&limit=10

### Browse by Trending

GET /v1/images/search?sort_by=trending&sort_order=desc&limit=10

Response: Same shape as search response (images array, count, total, limit, offset).

Note: The /v1/images endpoint exists but is a simple listing without pagination or filtering. Use /v1/images/search for all browsing needs.

---

## Image Details

### Get Image Metadata

GET /v1/images/{id}/meta

Returns full metadata for an image including AI-generated caption, tags, OCR text, dimensions, and engagement stats.

Example:
  curl "https://api.memestack.ai/v1/images/a1b2c3d4-e5f6-7890-abcd-ef1234567890/meta"

Response: Single ImageRecord object (same shape as items in search results).

### Get Image File (Web-Optimized)

GET /v1/images/{id}/canonical

Returns the web-optimized image file (max 2500px, original format preserved). Falls back to original if no canonical version exists (images under 2500px are not re-encoded).

Content-Type: image/jpeg, image/png, image/webp, or image/gif (matches original)

Example:
  curl -o image.jpg "https://api.memestack.ai/v1/images/a1b2c3d4-e5f6-7890-abcd-ef1234567890/canonical"

### Get Thumbnail

GET /v1/images/{id}/thumbnail

Returns a thumbnail (max 768px). Useful for previews and galleries.

Example:
  curl -o thumb.jpg "https://api.memestack.ai/v1/images/a1b2c3d4-e5f6-7890-abcd-ef1234567890/thumbnail"

### Find Similar Images (Perceptual)

GET /v1/images/{id}/similar

Finds visually similar images using perceptual hashing (dHash hamming distance).

Parameters:
- limit: Max results (default 10, max 50)

Example:
  curl "https://api.memestack.ai/v1/images/a1b2c3d4-e5f6-7890-abcd-ef1234567890/similar?limit=5"

### Find Related Images (Semantic)

GET /v1/images/{id}/related

Finds semantically related images using embedding cosine similarity. Different from /similar — this finds images about the same topic, not visual duplicates.

Parameters:
- limit: Max results (default 10, max 50)

Example:
  curl "https://api.memestack.ai/v1/images/a1b2c3d4-e5f6-7890-abcd-ef1234567890/related?limit=5"

---

## Users

### Get User Profile

GET /v1/users/{pubkey}

Returns user profile including upload count and total sats earned.

Example:
  curl "https://api.memestack.ai/v1/users/02abc123def456..."

Response:
{
  "id": "uuid",
  "pubkey": "02abc123def456...",
  "display_name": "satoshi_charts",
  "role": "user",
  "has_avatar": true,
  "upload_count": 47,
  "total_sats_earned": 12500,
  "created_at": "2026-01-15T08:00:00Z"
}

### Get User's Images

GET /v1/users/{pubkey}/images

Parameters:
- limit: Default 20, max 100
- offset: Default 0
- sort_by: "created_at" (default), "zap_total_sats", "save_count"
- sort_order: "asc" or "desc" (default "desc")

### Get User's Tags

GET /v1/users/{pubkey}/tags

Returns tags aggregated from the user's images, sorted by frequency.

### Get User Avatar

GET /v1/users/{pubkey}/avatar

Returns the user's avatar image (JPEG/PNG/WebP). Returns 404 if no custom avatar.

---

## Leaderboard

### Top Zapped Images

GET /v1/leaderboard/images

Parameters:
- period: "day", "week", "month", "all" (default "all")
- limit: Default 10, max 50

### Top Zappers

GET /v1/leaderboard/zappers

Parameters:
- period: "day", "week", "month", "all" (default "all")
- limit: Default 10, max 50

---

## MCP Server (Model Context Protocol)

MemeStack provides a remote MCP server at https://mcp.memestack.ai/mcp
This wraps the REST API as native AI agent tools — no HTTP construction needed.

### Setup

Claude Desktop / Claude Code:
  {"mcpServers": {"memestack": {"type": "url", "url": "https://mcp.memestack.ai/mcp"}}}

Clients without remote MCP support:
  {"mcpServers": {"memestack": {"command": "npx", "args": ["mcp-remote", "https://mcp.memestack.ai/mcp"]}}}

### Available Tools

1. search_images(query, tag?, tags?, limit?, offset?, sort?)
   - Unified search — semantic similarity + keyword matching in one query
   - tags: comma-separated slugs for multi-tag AND filtering
   - sort: "newest", "popular", "oldest"

2. get_image(id) — full metadata for one image

3. find_similar(id, limit?) — visually similar images (perceptual hash)

4. find_related(id, limit?) — semantically related images (AI embeddings)

5. browse_images(tag?, sort?, limit?, offset?)
   - sort: "newest", "popular", "oldest", "trending"

6. get_user_profile(identifier) — user profile by pubkey or UUID

7. get_leaderboard(type, period?)
   - type: "images" or "zappers"
   - period: "day", "week", "month", "all" (default: week)

All tools return rich metadata including captions, tags, zap stats, and direct URLs.
No authentication required.

---

## Common Agent Workflows

### Find an image that explains a concept
1. GET /v1/images/search?q=concept+description&limit=3
2. Pick the best result from the response
3. GET /v1/images/{id}/canonical to get the image file
4. Use caption and alt_text from metadata for context

### Find images about the same topic
1. GET /v1/images/{id}/related?limit=5
2. Browse related images by metadata

### Browse popular content
1. GET /v1/images/search?sort_by=zap_total_sats&sort_order=desc&limit=10
2. Or GET /v1/leaderboard/images?period=week for trending

### Get OCR text from an image
1. GET /v1/images/{id}/meta
2. Read the text_in_image field (contains all text detected in the image)

---

## Tags

Images have two types of tags:
- **Controlled tags** (tags field): Curated set of categories like "bitcoin", "memes", "infographics", "charts"
- **Free tags** (free_tags field): AI-generated descriptive tags like "supply schedule", "block reward"

Filter by a single controlled tag slug: ?tag=bitcoin
Filter by multiple controlled tag slugs (AND): ?tags=bitcoin,charts

---

## Pagination

All list endpoints support limit/offset pagination:
- limit: Items per page (varies by endpoint, typically max 100)
- offset: Skip this many items

Response includes:
- count: Items in this response
- total: Total matching items
- Some endpoints include has_more: boolean

---

## Links

- Website: https://memestack.ai
- Quick reference: https://memestack.ai/llms.txt
- OpenAPI 3.1 spec: https://api.memestack.ai/openapi.json
- Developer docs: https://memestack.ai/developers
- Deep link search: https://memestack.ai/?q={query}