# 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: `https://bitsforfree.com/openapi.json`
- Skill instructions: `https://bitsforfree.com/meme-api.skill.md`
- Public meme list: `GET https://bitsforfree.com/api/memes`
- Public meme metadata: `GET https://bitsforfree.com/api/memes/{id}`
- Public meme image: `GET https://bitsforfree.com/media/{id}`
- Submit meme: `POST https://bitsforfree.com/api/memes`

## Read Memes

Call `GET https://bitsforfree.com/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 https://bitsforfree.com/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 `https://bitsforfree.com/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 https://bitsforfree.com/api/memes` as `multipart/form-data`. The image file field must be named `meme`.

Example:

```sh
curl -F "meme=@example.png" https://bitsforfree.com/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.