# Nekosia API > A free, keyless REST API serving cute anime imagery — catgirls, foxgirls, wolfgirls and many other > categories — backed by the provider's own Booru. Responses are JSON carrying dominant colours, > original and compressed image variants, dimensions, tags, content rating, anime/character names, > the original source and full artist attribution. No account, no API key, no registration. Base URL: `https://api.nekosia.cat/api/v1` Authentication: none. Send no credentials; there is no key to obtain. Content: safe-rated by default. `suggestive` is returned only when explicitly requested. No NSFW. ## Before you call it - **Commercial use requires prior written consent** from the administrator (support@nekosia.cat). Free use is for standard, non-commercial public use. This is the single most important constraint on this API and it is not obvious from the fact that it is free and keyless. - **You must credit the artist** when republishing an image, wherever `attribution.artist` is populated in the response. Crediting Nekosia itself is optional. - **Rate limits are per IP address**, because there is no key: 300 requests / 5 minutes on `api.nekosia.cat`, 600 / 5 minutes on `cdn.nekosia.cat`, 96 / 140 seconds on `nekosia.cat`. Every successful response carries `ratelimit: limit=…, remaining=…, reset=…`. Read it. Sustained abuse is reported by the provider to AbuseIPDB and SniffCat. ## Operations - `GET /images/:category` — one or more random images from a category. Query: `count` (1–20, default 1), `additionalTags`, `blacklistedTags` (comma-separated slugs), `rating` (`safe` | `suggestive`, default `safe`), `session` (`ip` | `id`), `id` (4–128 chars). Categories are tags with safety filters attached. Use the special category `nothing` to search by tags alone with no filters — it then REQUIRES at least one `additionalTags` value, and the provider transfers responsibility for content appropriateness to you. - `GET /getImageById/:id` — retrieve one image by its stable 24-hex identifier. - `GET /tags` — the complete controlled vocabulary: `tags`, `anime` titles and `characters`. Validate filter inputs against this rather than guessing. - `GET /` (the base URL itself) — an unauthenticated health check returning `"Operational"`. ## Sessions — the one piece of hidden state Pass `session=id` with a stable per-end-user identifier (a Discord user id, for example) and the API will not show that user the same image twice. Sessions last 7 days and reset automatically once a category is exhausted. `session=ip` keys on the caller's IP, which is wrong for agents and serverless workloads: everything behind a shared egress address shares one de-duplication window. ## Errors Every failure returns `{"success": false, "status": , "message": ""}` as `application/json`. There are **no machine error codes** and almost every client-side failure is a 400 — unknown category, invalid `rating`, missing `additionalTags` on `nothing`, unknown image id, out-of-range `count` and a bad session id length are all 400 with different prose. Validate before calling; do not try to classify failures afterwards. An unknown path returns 404; exceeding the rate limit returns 429. ## Official client library - JavaScript / Node.js: [`nekosia.js`](https://www.npmjs.com/package/nekosia.js) (`npm install nekosia.js`), MIT, v0.2.10 (2026-06-28), ships TypeScript types. - A community Swift wrapper is listed by the provider: https://github.com/jezreelbarbosa/NekosiaAPI ## Docs - Introduction: https://nekosia.cat/documentation?page=introduction - Getting started: https://nekosia.cat/documentation?page=getting-started - Endpoints: https://nekosia.cat/documentation?page=endpoints - Rate limits: https://nekosia.cat/documentation?page=ratelimits - Changelog: https://nekosia.cat/documentation?page=changelog - Libraries: https://nekosia.cat/documentation?page=wrappers - Terms of service: https://nekosia.cat/documentation?page=tos - Privacy policy: https://nekosia.cat/documentation?page=privacy-policy - Status: https://status.nekosia.cat - Source of all the above, as markdown: https://github.com/Nekosia-API/documentation ## What this API does not have No OpenAPI, Swagger, GraphQL or AsyncAPI document. No MCP server. No A2A agent card. No webhooks or events. No pagination. No idempotency keys — and none are needed, since every operation is a GET. No SLA, no deprecation policy, no roadmap. It does serve an RFC 9116 `security.txt` on every host and emits standards-track `RateLimit` headers, which is more than many larger providers manage.