ZenAPI

Zen API · read-only REST · GET JSON

Documentation

Before you integrate

  • All routes are read-only GET — no authentication flow on this surface.
  • Respect Cache-Control on responses; expect per-IP limits and HTTP 429 if you hammer the API — use backoff.

Integrate catalogs, anime detail, search, streaming helpers, and schedules. All endpoints are GET.

Each endpoint below includes an Example response block — expand to load live JSON from this origin. Use Refresh examples to re-fetch everything after your database changes.

Introduction

Zen API exposes predictable paths under /api/ and structured JSON responses. Optional GET /api/meta exposes api_base when configured.

AI integration prompt

Copy the prompt below and paste it into your AI coding assistant (Cursor, Copilot, ChatGPT, etc.) along with your project context. It will read your codebase, build a todo list of integration tasks, and implement them one by one — so nothing gets missed.

Copiable AI Prompt 

              
            

          


          

            
Base URL

            

              JSON routes are served from this host (/api/home, /api/info, …).
            

          


          

            
Response format

            

              Most successful list/detail calls return a small envelope with success and
              results. GET /api/schedule adds the same
              date field (YYYY-MM-DD) so clients know which calendar
              day results is for. Stream-oriented routes may send
              Cache-Control: no-store to discourage stale player responses.
            

            

              
Typical JSON envelope

              
{ "success": true, "results": [ … ] }

            

          


          

            
First request

            
From a terminal on the machine that runs the API (swap host and port for your setup):

            
Loading…

            

              Add | jq if you have jq installed for formatted output.
            

          


          

            
Caching & fair use

            

              This page documents the API from a client perspective. Operational tuning (timeouts, CDN
              keys, deployment env) stays on the operator side and is not published here.
            

            

              All JSON routes return Cache-Control: public, max-age=1800, s-maxage=1800
              (30 minutes) so browsers and CDN edge caches aggressively reuse responses. Only
              /api/update uses no-store. Always honor the headers you
              actually receive rather than assuming fixed TTLs.
            

            

              Aggressive scraping or bursting traffic can yield HTTP 429; treat overload like any
              other remote API — slow down, cache locally, or batch work.
            

            

              
Rate limits (default deployment)

              

                These figures match the bundled server defaults. A host may tune them privately; integrate against HTTP status
                and headers, not hard-coded numbers alone.
              

              

                
Scope

                

                  Counts GET /api/* requests per client IP.
                

                
Quota

                
1 000 requests per IP per 60 second window.

                
Overload

                

                  HTTP 429 with
                  { "success": false, "message": "Too many requests. Slow down or try again later." }; standard
                  RateLimit-* headers may be present on success and throttle responses.
                

              

            

          


          

            
Endpoint reference

            

              Filter narrows endpoint cards below by path name or keywords.
            

            

              
              
            

          


          

          

            
Hub & lists


            

              
GET /api · /api/home

              
Home payload with spotlights and catalog sections. GET /api returns the same shape as GET /api/home.

              

                Example GET /api/home
                
Loading…

              

            


            

              
GET /api/meta

              
Returns results.api_base when the deployment publishes a canonical API origin; otherwise null.

              

                Example GET /api/meta
                
Loading…

              

            


            

              
GET /api/top-ten

              
Top titles.

              

                Example GET /api/top-ten
                
Loading…

              

            


            

            

              
GET /api/catalog

              

                All anime from the database, 50 per page. Query page (default
                1). Each item includes slug,
                title, poster, type,
                sub_count, dub_count.
              

              

                Example GET /api/catalog?page=1
                
Loading…

              

            


            

              
GET /api/img/base

              
Poster / image base URL hint for resolving relative artwork paths.

              

                Example GET /api/img/base
                
Loading…

              

            



            

              
GET /api/{category}

              

                84 registered slug paths (e.g. genre/action,
                top-airing, movie, az-list/a).
                Query page. Demo uses genre action — every category route shares the same response
                envelope.
              

              

                Example GET /api/genre/action?page=1
                
Loading…

              

            

          


          

            
Anime detail & search


            

              
GET /api/info

              

                id — anime slug (required). Episodes include streams by type
                (sub, dub, …) with server_name,
                server_id, and embed (stream URL).
              

              

                Example GET /api/info?id=catalog slug
                
Loading…

              

            


            

            

              
GET /api/search/suggest

              
Query param keyword.

              

                Example GET /api/search/suggest?keyword=a
                
Loading…

              

            


            

              
GET /api/filter

              

                Filter UI params: type, status,
                genres, season, sort,
                keyword, ranges (sy/sm/…),
                page.
              

              

                Example GET /api/filter?keyword=test&page=1
                
Loading…

              

            


            

              
GET /api/random

              
Random anime.

              

                Example GET /api/random
                
Loading…

              

            


            

              
GET /api/random/id

              
Random id helper.

              

                Example GET /api/random/id
                
Loading…

              

            

          


          

            
Streaming


            

              
GET /api/stream

              

                id — episode key (slug?ep=N).
                type sub or dub (default
                sub). server optional—first match for
                type if omitted. Optional mal_id.
              

              

                Example GET /api/stream…
                
Loading…

              

              

                

                  Test player — loads streamingLink.link.file from
                  /api/stream for demo slug
                  date-a-live-iv-gwfwo
                  (ep=1, type=sub).
                  Some providers block embedding; a blank frame means the embed URL is restricted.
                

                

                

                

                  

                    Player Events aniplay channel
                    
                  

                  
    
                    
  • Waiting for player events…
    • 
                  

                


                

                  

                    The embedded player emits postMessage events. This page listens,
                    re-dispatches them on an aniplay channel, and logs them above.
                    Use the same listener in your own integration:
                  

                  
window.addEventListener("message", function (event) {
  let data = event.data;
  if (typeof data === "string") {
    try { data = JSON.parse(data); } catch (e) { return; }
  }

  // proxy to aniplay channel
  if (data.channel === "megacloud" || data.type === "watching-log" || data.event) {
    window.dispatchEvent(new CustomEvent("aniplay", { detail: data }));
  }
});

// consume aniplay events
window.addEventListener("aniplay", function (e) {
  const d = e.detail;

  if (d.event === "time") {
    // progress update — d.time / d.duration / d.percent
  }

  if (d.event === "complete") {
    // episode finished — trigger auto-next
  }

  if (d.event === "error") {
    // playback failed
  }

  if (d.type === "watching-log") {
    // watch-time log — d.currentTime / d.duration
  }
});

                  

              
                      
EventTriggerKey fields

              
              
                      
timeDuring playbacktime, duration, percent

                      
completeEpisode ends—

                      
errorPlayback failure—

                      
watching-logDuring playbackcurrentTime, duration

              
            

                  

                    In production, validate event.origin against your embed host before
                    trusting any message payload.
                  

            

            

          


          


          

            
Schedule & related


            

              
GET /api/schedule

              

                Optional date (YYYY-MM-DD); default is “today” in
                Asia/Dhaka. Response includes top-level date plus
                results.
              

              

                Example GET /api/schedule?date=…
                
Loading…

              

          


            

              
GET /api/schedule/by-anime/:animeId

              

                Per-anime airing schedule. Returns on_schedule, entries
                with schedule_date, release_time, and live
                countdown. Add ?upcoming=1 to return only future slots.
              

              

                Example GET /api/schedule/by-anime/…
                
Loading…

              

            



            

              
GET /api/qtip/:id

              
Tooltip / compact info for an anime id.

              

                Example GET /api/qtip/…
                
Loading…

              

            


            

              
GET /api/producer/:id

              
Studio / producer listing. Query page. Demo uses Mappa.

              

                Example GET /api/producer/mappa?page=1
                
Loading…