API Documentation

We provide a publicly accessible API to query the data available in our archive. The following is a summary of the available endpoints. For more details, check out the source code.

Searching

Basic Search

GET /api/v1/search

Query parameters

qsearch query, just like using the search bar
vfind one video with the given video id
channel_idfind videos that belong to the given channel id
sortsort field, can be one of
  • archived_timestamp
  • upload_date
  • duration
  • view_count
  • like_count
  • dislike_count
sort_ordereither asc or desc
fromoffset results for pagination
sizenumber of results to show in one page

Example

  • Search for haachama, and sort results by video duration from longest to shortest.

    curl https://archive.ragtag.moe/api/v1/search?q=haachama&sort=duration&sort_order=desc

Live updates

We also provide a simple websocket service for listening to events at the following address:

wss://ws.ragtag.moe
To listen to events, connect to the socket and send the following message:
{"method":"subscribe","params":["moe.ragtag.archive:workers","ping"]}
The above message subscribes you to two topics. The ping topic will deliver a message once every 5 seconds to keep the connection alive. The moe.ragtag.archive:workers topic will deliver events from our workers. You will receive messages in the following format:
{
  "id": -1,
  "result": [
    "moe.ragtag.archive:workers",
    {
      "event": "<event type>",
      "data": "<event data>",
      "source": "<worker id>",
      "version": "<worker version>"
    }
  ]
}

The following event types are available:

work_beginworker has accepted a job from the queue
work_endworker has cleanly finished a job and will request a new one
work_failedsomething went wrong while doing a job, and the job will be requeued
video_downloadingworker is downloading the video from YouTube
video_failedworker could not download the video, the job is discarded and will not be requeued
video_uploadingworker has started uploading the video to the site storage
video_uploadedall video files have been uploaded but the database has not been updated yet
worker_updatedworker has downloaded a newer version of its software and will run that version on the next job
rate_limitworker has detected a HTTP 429 and will rest for one hour

Notes

  • this endpoint is currently unauthenticated, anyone can publish any event
  • when a worker detects a video is already present on the website, it will do nothing and emit work_end

Embedding videos

Videos from this website can be embedded with the URL /embed/:videoId. For example,

<div style="position:relative;padding-bottom:56.25%">
  <iframe
    frameborder="0"
    allow="fullscreen"
    src="https://archive.ragtag.moe/embed/vHMV44Uza4g"
    style="position:absolute;width:100%;height:100%" />
</div>

will create a responsive iframe with a 16:9 aspect ratio like the following:

Note that chat replay is not yet available for embedded videos.

Made with 🍝 by kitsune.