// Developer docs

Mrs. Maid GIF API

Fetch a random gif URL for a topic with a simple Bearer-authenticated GET request.

Authentication

Send your key in the Authorization header on every request.

Authorization: Bearer YOUR_KEY

1,000 / day

1 key(s)

50,000 / day

3 key(s)

Quota is counted per key and resets daily at 00:00 UTC. NSFW categories are readable with any valid key.

One GET returns a random gif for the given rating and category.

GET https://mrs-maid.cc/api/v1/{rating}/{category}

curl -H "Authorization: Bearer YOUR_KEY" \
  https://mrs-maid.cc/api/v1/sfw/hug

Example response:

{
  "url": "https://mrs-maid.cc/uploads/gifs/sfw/hug/<hash>.gif",
  "rating": "sfw",
  "category": "hug",
  "id": "…"
}

No categories are available yet. Gifs still need to be uploaded.

`401`	`missing_api_key` / `invalid_api_key`	Missing or invalid API key.
`404`	`unknown_category` / `no_gifs`	Unknown rating/category, or no gifs uploaded for it yet.
`429`	`quota_exceeded`	Daily quota reached for this key. Check the Retry-After header.
`503`	`unavailable`	Service temporarily unavailable.