bitsforfree/meme-api.skill.md

The Meme Protocol API Skill

Use this skill when an agent needs to read approved memes from The Meme Protocol or submit a meme image to the public upload API.

Discovery

• OpenAPI: __API_BASE_URL__/openapi.json
• Skill instructions: __API_BASE_URL__/meme-api.skill.md
• Public meme list: GET __API_BASE_URL__/api/memes
• Public meme metadata: GET __API_BASE_URL__/api/memes/{id}
• Public meme image: GET __API_BASE_URL__/media/{id}
• Submit meme: POST __API_BASE_URL__/api/memes

Read Memes

Call GET __API_BASE_URL__/api/memes?page=1&pageSize=12 to list approved memes. page starts at 1; pageSize is capped at 48. The response includes page, pageSize, total, totalPages, memes, and rateLimit.

Call GET __API_BASE_URL__/api/memes/{id} to retrieve one approved meme by its 64-character lowercase hex SHA-256 ID. Pending, rejected, deleted, or unknown memes return 404.

Use each meme's url field to fetch the normalized WebP image. Public image URLs are under __API_BASE_URL__/media/{id} and may be cached aggressively by clients.

Read endpoints are rate-limited per IP. Respect RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and Retry-After headers. Prefer small page sizes and back off on 429.

Submit Memes

Submit with POST __API_BASE_URL__/api/memes as multipart/form-data. The image file field must be named meme.

Example:

curl -F "meme=@example.png" __API_BASE_URL__/api/memes

The API intentionally uses the same upload path as the human browser form:

• Accepts one image per request.
• Accepts PNG and JPEG only.
• Rejects empty files and unsupported media types.
• Rejects files over 5 MB.
• Rejects images with any edge over 6000 px.
• Rejects images over 20 megapixels.
• Normalizes accepted images to metadata-stripped WebP with longest edge at most 1600 px.
• Runs the same AI moderation workflow.
• Applies the same per-IP upload limits: 5 per hour, 10 per day, and 100 global uploads per day.

Successful upload responses:

• 201 means the meme was approved and published immediately.
• 202 means the meme was accepted and queued for admin review. The body includes moderationReason.

Rejected or invalid upload responses:

• 400 for malformed multipart requests, missing image field, multiple images, or invalid dimensions.
• 411 when upload size is missing.
• 413 when request, file, dimension, or pixel limits are exceeded.
• 415 when the image is not PNG or JPEG.
• 422 when moderation rejects the upload. The body includes moderationScore and moderationReason.
• 429 when upload quotas are exhausted.

Do not attempt to bypass moderation, normalization, or limits. There is no privileged public upload endpoint.