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

`q`	search query, just like using the search bar
`v`	find one video with the given video id
`channel_id`	find videos that belong to the given channel id
`sort`	sort field, can be one of `archived_timestamp` `upload_date` `duration` `view_count` `like_count` `dislike_count`
`sort_order`	either `asc` or `desc`
`from`	offset results for pagination
`size`	number 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_begin`	worker has accepted a job from the queue
`work_end`	worker has cleanly finished a job and will request a new one
`work_failed`	something went wrong while doing a job, and the job will be requeued
`video_downloading`	worker is downloading the video from YouTube
`video_failed`	worker could not download the video, the job is discarded and will not be requeued
`video_uploading`	worker has started uploading the video to the site storage
`video_uploaded`	all video files have been uploaded but the database has not been updated yet
`worker_updated`	worker has downloaded a newer version of its software and will run that version on the next job
`rate_limit`	worker 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.