68 lines
3.6 KiB
Markdown
68 lines
3.6 KiB
Markdown
# The Meme Protocol API Skill
|
|
|
|
Use this skill when an agent needs to read approved memes from The Meme Protocol or add a meme image through 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 tag catalog: `GET __API_BASE_URL__/api/tags`
|
|
- Public meme metadata: `GET __API_BASE_URL__/api/memes/{id}`
|
|
- Public meme image: `GET __API_BASE_URL__/media/{id}`
|
|
- Add 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`.
|
|
|
|
Each meme includes `caption` (searchable text, possibly empty for older images) and `tags` (managed topic names).
|
|
|
|
Search using `GET __API_BASE_URL__/api/memes?q=angry%20cat&pageSize=12`. Matching ignores case and accents and tolerates prefixes and small typos. Every query word must match a caption or assigned tag. Results are ordered by relevance, then newest first. This is lexical fuzzy search, not semantic search.
|
|
|
|
Read `GET __API_BASE_URL__/api/tags` for the available tag catalog, then filter with `GET __API_BASE_URL__/api/memes?tag=cats`. Repeat `tag` to require multiple topics, and combine it with `q`. Queries are limited to 200 characters and 20 tag filters; invalid filters return `400`. Pages beyond the last page are clamped, so use `totalPages` to stop pagination.
|
|
|
|
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`.
|
|
|
|
## Add Memes
|
|
|
|
Add a meme with `POST __API_BASE_URL__/api/memes` as `multipart/form-data`. The image file field must be named `meme`. Captions and tags are generated by the server. Public clients cannot create tags or edit image metadata.
|
|
|
|
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. 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.
|