API docs by Redocly

Holodex/HoloAPI V2 (2.0)

Download OpenAPI specification:Download

Holodex Public API. Successor to the HoloAPI v1

Please consider joining our Discord Server for service downtime announcements

Discord Shield

Holodex API Documentation

This is API Documentation for Public Accessible API powering holodex.net

Get Started W/ Holodex API

To properly secure your API Access (and prevent being blocked by our service), please log into Holodex and acquire a API KEY via the Account Settings page. In order to reliably access the API and prevent rate lockouts or CORS issues, please set the API KEY in every single request using the header X-APIKEY

With Holodex, you can:

  • Get quick updates on who is live and who is scheduled to be live, for Youtube vtubers in the Holodex platform.
  • Access and navigate the clips, channels, streams, and relationships tracked by Holodex backend crawler.
  • Access Holodex's stream and clip references to see which subbers clipped a particular stream.

Holodex Github / Issues / Project Management

Develop and Chat with us on Discord!

Follow us on Twitter!

License

Getting Started

Obtaining API Key

Access the API key menu from top right account icon -> Account Settings.

Use the API Key by adding it as a header to your requests using the Header X-APIKEY

image.png

ApiKeyAuth

the X-APIKEY header is required to authenticate your request against holodex

Security Scheme Type: API Key
Header parameter name: X-APIKEY

Consuming the API

LICENSE

1. Introduction;

Thank you for using the Holodex API (“we”, “our” or “Holodex”) application programming interface(s) (“Holodex API”). By using the Holodex API you are agreeing to the terms and conditions contained below (“Terms”). Your license to use the Holodex API is conditioned upon your agreement and conformant with the Terms. We reserve the right to update and otherwise amend the Terms from time to time without notice.

License grant. Holodex hereby grants you a revocable, non-sublicenseable, terminable, limited license to use the Holodex API solely in accordance with the Terms. Your license is automatically revoked if (i) you violate any of the Terms, (ii) we send a written notice of termination to you, or (iii) we disable your use of the Holodex API.

2. Restrictions

Adverse and Excessive Use. You may not use the Holodex API in a manner that adversely impacts Holodex's systems, including but not limited to Holodex servers or other applications. Further we reserve the right to suspend, terminate or throttle your use of the Holodex API in the event your use is deemed excessive by Holodex.

Keys. You may not use multiple application API keys for the same use case or application.

Monitoring. You may not use or access the Holodex API for purposes or monitoring the availability, performance or functionality of any of Holodex's services or for any other benchmarking or competitive purposes.

Third Party Access. You may provide access to the API to third party developers (e.g. agencies or approved partners). You are responsible for ensuring that any third party to whom you provide access abides by the Terms. Holodex will have exclusive discretion to determine whether a particular use of an API key by a third party is acceptable. You are not permitted to share API keys to bypass Holodex restrictions. You are responsible for ensuring that any third party to whom you provide access abides by the Terms. Further, Holodex reserves the right to reject third party access to the API.

Charging for Access. You may not charge a premium for access to the Holodex API or any content derived from Holodex API

Laws; Regulations; Privacy Policy. Do not use the Holodex API in any manner or for any purpose that violates any law, regulation, code or any rights of any person or entity, including but not limited to intellectual privacy rights, rights of privacy, or rights of personality. Further, you must maintain a privacy policy that accurately reflects your use of the content accessed through the Holodex API.

3. Support

Holodex may elect to provide you with support for the Holodex API (collectively, “Support”), in its sole discretion, and may terminate such Support at any time without notice to you. Holodex may change, suspend, or discontinue any aspect of the Holodex API at any time, including the availability of any Holodex API. Holodex may also impose limits on certain features and services or restrict your access to parts or all of the Holodex API without notice or liability.

4. Disclaimer of Warranty

The Holodex API is provided “as is” and Holodex disclaims all warranties, conditions, or representations (express, implied, oral or written) with respect to the Holodex API and any support related thereto, including all warranties of merchantability, fitness for a particular purpose, non-infringement, non-interference, accuracy of data, and warranties arising from a course of dealing.

5. Release and Waiver

To the maximum extent permitted by applicable law, you hereby release and waive all claims against Holodex, and its partners from any and all liability for claims, damages (actual and/or consequential), costs and expenses (including litigation costs and attorneys’ fees) of every kind and nature, arising from or in any way related to your use of the Holodex API. If you are a California resident, you waive your rights under California Civil Code 1542, which states, “A general release does not extend to claims which the creditor does not know or suspect to exist in his favor at the time of executing the release, which if known by him must have materially affected his settlement with the debtor.” You understand that any fact relating to any matter covered by this release may be found to be other than now believed to be true and you accept and assume the risk of such possible differences in fact. In addition, you expressly waive and relinquish any and all rights and benefits which you may have under any other state or federal statute or common law principle of similar effect, to the fullest extent permitted by law.

6. Attribution

If You provide public access to the Holodex API and its material (including in modified form), You should provide:

  1. Identification of Holodex, or provide a URI or hyperlink to Holodex wherever possible, plus optionally whenever applicable any others designated to receive attribution, in any reasonable manner requested by the Licensor (including pseudonym if designated);
  2. provide somewhere in the source code, a notice that refers to this Public License;
  3. provide somewhere in the source code, a notice that refers to the disclaimer of warranties;ink to Holodex wherever possible

Query Live and Upcoming Videos

This is somewhat similar to calling /videos.

However, this endpoint imposes these default values on the query parameters: You can choose to override them by providing your own values.

status: [STATUSES.LIVE, STATUSES.UPCOMING].join(','),
type: 'stream',
sort: 'available_at',
order: 'asc',
max_upcoming_hours: 48,
limit: 9999,
include: live_info + query's include
Authorizations:
ApiKeyAuth
query Parameters
channel_id
string
Example: channel_id=UCl_gCybOJRIgOXw6Qb4qJzQ

Filter by video uploader channel id

status
string
Enum: "new" "upcoming" "live" "past" "missing"
Example: status=past

Filter by video status

lang
string
Default: "all"
Example: lang=en,ja

A comma separated list of language codes to filter channels/clips, official streams do not follow this parameter

type
string
Enum: "stream" "clip"

Filter by type of video

topic
string
Example: topic=singing

Filter by video topic id

include
Array of strings
Items Enum: "clips" "refers" "sources" "simulcasts" "mentions" "description" "live_info" "channel_stats" "songs"
Example: include=live_info,clips

Comma separated string of extra info for video. Should be a string instead of an array.

org
string
Example: org=Hololive

Filter by clips that feature the org's talent or videos posted by the org's talent

mentioned_channel_id
string

Filter by mentioned channel id, excludes itself. Generally used to find collabs/clips that include the requested channel

sort
string
Default: "available_at"
Example: sort=start_scheduled

Sort by any returned video field

order
string
Default: "desc"
Enum: "asc" "desc"

Order by ascending or descending

limit
integer <= 50
Default: 25

Results limit

offset
integer
Default: 0

Offset results

paginated
string
Default: "<empty>"

If paginated is set to any non-empty value, return an object with total, otherwise returns an array.

max_upcoming_hours
number
Example: max_upcoming_hours=24

Number of maximum hours upcoming to get upcoming videos by (for rejecting waiting rooms that are two years out)

id
string

A single Youtube Video ID. If Specified, only this video can be returned (may be filtered out by other conditions though)

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Query Videos

Pretty much everything you need. This is the most 'vanilla' variant with almost no preset values, and /channels/{channelId}/{type} and /live endpoints both use the same query structure but provision default values differently for some of the query params.

Not as powerful at searching arbitrary text as the Search API (currently not documented/available).

Authorizations:
ApiKeyAuth
query Parameters
channel_id
string
Example: channel_id=UCl_gCybOJRIgOXw6Qb4qJzQ

Filter by video uploader channel id

status
string
Enum: "new" "upcoming" "live" "past" "missing"
Example: status=past

Filter by video status

lang
string
Default: "all"
Example: lang=en,ja

A comma separated list of language codes to filter channels/clips, official streams do not follow this parameter

type
string
Enum: "stream" "clip"

Filter by type of video

topic
string
Example: topic=singing

Filter by video topic id

include
Array of strings
Items Enum: "clips" "refers" "sources" "simulcasts" "mentions" "description" "live_info" "channel_stats" "songs"
Example: include=live_info,clips

Comma separated string of extra info for video. Should be a string instead of an array.

org
string
Example: org=Hololive

Filter by clips that feature the org's talent or videos posted by the org's talent

mentioned_channel_id
string

Filter by mentioned channel id, excludes itself. Generally used to find collabs/clips that include the requested channel

sort
string
Default: "available_at"
Example: sort=start_scheduled

Sort by any returned video field

order
string
Default: "desc"
Enum: "asc" "desc"

Order by ascending or descending

limit
integer <= 50
Default: 25

Results limit

offset
integer
Default: 0

Offset results

paginated
string
Default: "<empty>"

If paginated is set to any non-empty value, return an object with total, otherwise returns an array.

max_upcoming_hours
number
Example: max_upcoming_hours=24

Number of maximum hours upcoming to get upcoming videos by (for rejecting waiting rooms that are two years out)

id
string

A single Youtube Video ID. If Specified, only this video can be returned (may be filtered out by other conditions though)

from
string

ISO8601 Date String for minimum available_at. (available_at is the most accurate timestamp of when a video has gone live or became viewable - it is the first non null value of the start_actual, start_scheduled or published_at fields)

to
string

ISO8601 Date String for maximum available_at

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "type": "stream",
  • "topic_id": "minecraft",
  • "published_at": "2019-08-24T14:15:22Z",
  • "available_at": "2019-08-24T14:15:22Z",
  • "duration": 0,
  • "status": "new",
  • "start_scheduled": "2019-08-24T14:15:22Z",
  • "start_actual": "2019-08-24T14:15:22Z",
  • "end_actual": "2019-08-24T14:15:22Z",
  • "live_viewers": 0,
  • "description": "string",
  • "songcount": 0,
  • "channel_id": "string",
  • "clips": [
    ],
  • "sources": [
    ],
  • "refers": [
    ],
  • "simulcasts": [
    ],
  • "mentions": [
    ],
  • "songs": 0
}

Get Channel Information

Authorizations:
ApiKeyAuth
path Parameters
channelId
required
string

ID of the Youtube Channel that is being queried

Responses

Response samples

Content type
application/json
{}

Query Videos Related to Channel

A simplified endpoint for access channel specific data. If you want more customization, the same result can be obtained by calling the /videos endpoint.

Authorizations:
ApiKeyAuth
path Parameters
channelId
required
string

ID of the Youtube Channel that is being queried

type
required
string
Enum: "clips" "videos" "collabs"

The type of video resource to fetch. Clips finds clip videos of a vtuber channel, Video finds the channelId channel's uploads, and collabs finds videos uploaded by other channels that mention this channelId

query Parameters
lang
string
Default: "all"
Example: lang=en,ja

A comma separated list of language codes to filter channels/clips, official streams do not follow this parameter

include
Array of strings
Items Enum: "clips" "refers" "sources" "simulcasts" "mentions" "description" "live_info" "channel_stats" "songs"
Example: include=live_info,clips

Comma separated string of extra info for video. Should be a string instead of an array.

limit
integer <= 50
Default: 25

Results limit

offset
integer
Default: 0

Offset results

paginated
string
Default: "<empty>"

If paginated is set to any non-empty value, return an object with total, otherwise returns an array.

Responses

Response samples

Content type
application/json
Example
{
  • "total": 0,
  • "items": [
    ]
}

Quickly Access Live / Upcoming for a set of Channels

This endpoint is similar to the /live endpoint and usually replies much faster. It is more friendly in general. The cost to execute a lookup is significantly cheaper. It's unfortunately less customizable as a result.

We recommends using this if you have a fixed set of channel IDs to look up status for.

Authorizations:
ApiKeyAuth
query Parameters
channels
string

comma separated Youtube Channel IDs

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a single Video's metadata

Retrieves a video object.

Also retrieves Comments if query parameter c is set.

Also retrieves Recommendations if query parameter lang is set

Authorizations:
ApiKeyAuth
path Parameters
videoId
required
string

ID of a Youtube Video

query Parameters
lang
string
Default: "all"
Example: lang=en,ja

A comma separated list of language codes to filter channels/clips, official streams do not follow this parameter

c
string
Enum: "1" "0"
Example: c=1

if 1 then will reply with timestamp comments for this video

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "type": "stream",
  • "topic_id": "minecraft",
  • "published_at": "2019-08-24T14:15:22Z",
  • "available_at": "2019-08-24T14:15:22Z",
  • "duration": 0,
  • "status": "new",
  • "start_scheduled": "2019-08-24T14:15:22Z",
  • "start_actual": "2019-08-24T14:15:22Z",
  • "end_actual": "2019-08-24T14:15:22Z",
  • "live_viewers": 0,
  • "description": "string",
  • "songcount": 0,
  • "channel_id": "string",
  • "clips": [
    ],
  • "sources": [
    ],
  • "refers": [
    ],
  • "simulcasts": [
    ],
  • "mentions": [
    ],
  • "songs": 0,
  • "comments": [
    ],
  • "recommendations": [
    ]
}

List Channels

Authorizations:
ApiKeyAuth
query Parameters
type
string
Enum: "subber" "vtuber"

Type of Channel, whether it's a vtuber or a subber. Leave unset to query all.

offset
integer
Default: 0

Offset results

limit
integer <= 50
Default: 25

Results limit

org
string
Example: org=Hololive

If set, filter for Vtuber belonging to a specific org

lang
string
Example: lang=en,ja,zh

Comma separated list of languages. Language is a property of Channel, so only Channels satisfying the language will be returned. Leave empty to search for Vtubers and/or all clippers.

sort
string

Column to sort on, leave default to use 'org' as sort. Any first level property of channel should work here.

order
string
Enum: "asc" "desc"

ASC or DESC order, default asc.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

post-search-videoSearch

Flexible endpoint to search for videos fufilling multiple conditions. Descriptions with "any" implies an OR condition, and "all" implies a AND condition.

Searching for topics and clips is not supported, because clips do not contain topic_ids

Authorizations:
ApiKeyAuth
Request Body schema: application/json
sort
required
string non-empty
Default: "newest"
Enum: "oldest" "newest"
lang
Array of strings

If set, will filter clips to only show clips with these langs + all vtuber streams (provided target is not set to filter out streams)

target
Array of strings
Items Enum: "clip" "stream"

Target types of videos

Array of objects

Match all the following conditions

topic
Array of strings

Return videos that match one of the provided topics

vch
Array of strings

Videos with all of the specified channel ids. If two or more channel IDs are specified, will only return their collabs, or if one channel is a clipper, it will only show clips of the other vtubers made by this clipper.

org
Array of strings

Videos of channels in any of the specified orgs, or clips that involve a channel in the specified org.

paginated
boolean

If set at all, responds with total and items wrapping the array of objects

offset
required
number
limit
required
number

Responses

Request samples

Content type
application/json
{
  • "sort": "newest",
  • "lang": [
    ],
  • "target": [
    ],
  • "conditions": [ ],
  • "topic": [
    ],
  • "vch": [
    ],
  • "org": [
    ],
  • "comment": [ ],
  • "paginated": true,
  • "offset": 0,
  • "limit": 30
}

Response samples

Content type
application/json
Example
[ ]

post-search-commentSearch

Flexible endpoint to search for comments in videos fufilling multiple conditions. Descriptions with "any" implies an OR condition, and "all" implies a AND condition.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
sort
required
string non-empty
Default: "newest"
Enum: "oldest" "newest"
lang
Array of strings

If set, will filter clips to only show clips with these langs + all vtuber streams (provided target is not set to filter out streams)

target
Array of strings
Items Enum: "clip" "stream"

Target types of videos

comment
required
string

Find videos with comments containing specified string (case insensitive)

topic
Array of strings

Return videos that match one of the provided topics

vch
Array of strings

Videos with all of the specified channel ids. If two or more channel IDs are specified, will only return their collabs, or if one channel is a clipper, it will only show clips of the other vtubers made by this clipper.

org
Array of strings

Videos of channels in any of the specified orgs, or clips that involve a channel in the specified org.

paginated
boolean

If set at all, responds with total and items wrapping the array of objects

offset
required
number
limit
required
number

Responses

Request samples

Content type
application/json
{
  • "sort": "newest",
  • "lang": [
    ],
  • "target": [
    ],
  • "conditions": [ ],
  • "topic": [
    ],
  • "vch": [
    ],
  • "org": [
    ],
  • "comment": "Lemon",
  • "paginated": true,
  • "offset": 0,
  • "limit": 30
}

Response samples

Content type
application/json
{
  • "total": 11,
  • "items": [
    ]
}