Add Public API

2026-06-26 15:23:53 -03:00
parent 36edd32fa3
commit d80d596664
12 changed files with 891 additions and 42 deletions
@@ -0,0 +1,60 @@
+# 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:
+
+```sh
+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.
+
+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`.
+- `429` when upload quotas are exhausted.
+
+Do not attempt to bypass moderation, normalization, or limits. There is no privileged public upload endpoint.