POST /api/v2/anime/suggest/

Search Suggestions

Autocomplete: turn a partial keyword into likely search terms.

Overview

Use it behind a search box: send what the user has typed so far and show the returned words as suggestions. It's cheap and fast, but each call still counts as one request, so debounce keystrokes (300 ms works well).

POST https://api.animedoc.cloud/api/v2/anime/suggest/
X-API-Key: <your key>

Parameters

Name	In	Type	Required	Default	Description
keyword	body	string	yes	—	The partial text the user typed.
perPage	body	integer	no	30	Maximum number of suggestions.

Example request

cURL

curl -X POST "https://api.animedoc.cloud/api/v2/anime/suggest/" \
  -H "X-API-Key: $ANIMEDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"naru","perPage":5}'

JavaScript (Node 18+)

const res = await fetch("https://api.animedoc.cloud/api/v2/anime/suggest/", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.ANIMEDOC_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"keyword":"naru","perPage":5}),
});
if (res.status === 429) {
  console.log("Rate limited, retry in", res.headers.get("Retry-After"), "s");
}
const { data } = await res.json();
console.log(data);

Python

import os
import requests

res = requests.post(
    "https://api.animedoc.cloud/api/v2/anime/suggest/",
    headers={"X-API-Key": os.environ["ANIMEDOC_API_KEY"]},
    json={"keyword":"naru","perPage":5},
    timeout=15,
)
if res.status_code == 429:
    print("Rate limited, retry in", res.headers["Retry-After"], "s")
res.raise_for_status()
print(res.json()["data"])

Example response

{
  "code": 0,
  "message": "ok",
  "data": {
    "items": [
      { "word": "naruto" },
      { "word": "naruto shippuden" },
      { "word": "boruto naruto next generations" }
    ]
  }
}

Error codes

Status	Body	What it means
400	{"error": "Missing detailPath query parameter"}	A required parameter is missing or invalid.
401	{"detail": "An API key is required. Send it as the X-API-Key header. ..."}	No `X-API-Key` header, or the key doesn't exist (`Invalid API key`). Every catalog endpoint needs a key; get a free one at /docs/pricing.
403	{"detail": "Playback through the API needs a paid plan ..."}	Your plan doesn't include this endpoint. The stream proxy needs a paid plan.
404	{"error": "No playable source is available ..."}	The title or episode doesn't exist, or has no playable source right now.
429	{"error": "rate_limit_exceeded"} or {"error": "daily_quota_exceeded"}	Over your plan's requests per minute or per day. Wait `Retry-After` seconds, or upgrade.
502	{"error": "...", "details": "..."}	The content provider didn't answer in time. Safe to retry with backoff.

When you go over a limit you get 429 Too Many Requests with a Retry-After header (seconds):

HTTP/1.1 429 Too Many Requests
Retry-After: 34
Content-Type: application/json

{
  "error": "rate_limit_exceeded",
  "detail": "Your free plan allows 10 requests per minute. Slow down and retry in 34s.",
  "limit": 10,
  "window": "minute",
  "retry_after_seconds": 34,
  "upgrade_url": "https://animedoc.cloud/pricing"
}

Rate limits per plan

Plan	Requests / day	Requests / minute	Stream proxy	Price
Free	20	10	No	$0
Starter	3,000	60	Yes	$12/month or $60/6 months
Pro	20,000	300	Yes	$22/month or $110/6 months
Business	500,000+	Custom	Yes	From $100/month
3-Day Pass	2,000	60	Yes	$1 for 3 days

Every call made with your API key counts as one request. Daily quotas reset at 00:00 UTC. See rate limits for headers and retry advice, or pricing to raise your limits.