-
-
Notifications
You must be signed in to change notification settings - Fork 335
API Docs
If you end up using the API, I'd love to know about how you're using it. Tell me about it by making a GitHub issue or emailing me :)
The API and database follow this license unless you have explicit permission. Attribution Template
Public API available at https://sponsor.ajay.app.
While this is a free unlimited use API, please don't abuse it. I have limited resources.
Database download: https://sponsor.ajay.app/database
Libraries: NPM
Online Database Explorer (By Lartza): https://sb.ltn.fi/
Database Mirror (5 min update time, provided by Lartza): https://sb.ltn.fi/database.db
Slim Database Mirror (5 min update time, provided by Lartza): https://sb.ltn.fi/database_slim.db
Input:
{
videoID: string,
category: string, // Optional, defaults to "sponsor". See https://github.com/ajayyy/SponsorBlock/wiki/Types#category
categories: string[], // Optional, use this instead of "category" if you want multiple categories. Will look like ["sponsor","intro"]
service: string // Optional, default is 'YouTube'. See https://github.com/ajayyy/SponsorBlock/wiki/Types#service
}Response:
[{ // Array of this object
segment: float[], //[0, 15.23] start and end time in seconds
UUID: string,
category: string,
videoDuration: float // Duration of video when submission occurred (to be used to determine when a submission is out of date)
}]Error codes:
404: Not Found
Input Option 1 (URL Parameters):
{
videoID: string,
startTime: float,
endTime: float,
category: string,
userID: string, //This should be a randomly generated UUID stored locally (not the public one)
service: string, // Optional, default is 'YouTube'. See https://github.com/ajayyy/SponsorBlock/wiki/Types#service
videoDuration: float, // Optional, duration of video, will attempt to retrieve from the YouTube API if missing (to be used to determine when a submission is out of date)
}Input Option 2 (JSON Body):
{
videoID: string,
userID: string, // This should be a randomly generated UUID stored locally (not the public one)
service: string, // Optional, default is 'YouTube'. See https://github.com/ajayyy/SponsorBlock/wiki/Types#service
videoDuration: float, // Optional, duration of video, will attempt to retrieve from the YouTube API if missing (to be used to determine when a submission is out of date)
segments: [{ // Array of this object
segment: float[], //[0, 15.23] start and end time in seconds
category: string
}]
}Response:
{
Nothing (status code 200)
}Error codes:
400: Bad Request (Your inputs are wrong/impossible)
403: Rejected by auto moderator (Reason will be sent in the response)
429: Rate Limit (Too many for the same user or IP)
409: Duplicate
sha256HashPrefix is a hash of the YouTube videoID. It should be the first 4 - 32 characters (4 is recommended). This provides extra privacy by potentially finding more than just the video you are looking for. This makes the server not know exactly what video you are looking for.
Input:
{
category: string, // Optional, defaults to "sponsor". See [the category list](https://raw.githubusercontent.com/ajayyy/SponsorBlock/master/config.json.example)
categories: string[], // Optional, use this instead of "category" if you want multiple categories. Will look like ["sponsor","intro"]
service: string // Optional, default is 'YouTube'. See https://github.com/ajayyy/SponsorBlock/wiki/Types#service
}Response:
[{ // Array of this object
"videoID": string,
"hash": string, // The full hash
"segments": [{ // Array of this object
segment: float[], //[0, 15.23] start and end time in seconds
UUID: string,
category: string
}]
}]Error codes:
404: Not Found
Input: Normal Vote (URL Parameters):
{
UUID: string, //id of the sponsor being voted on
userID: string, //the local user id
type: int //0 for downvote, 1 for upvote
}OR
Input: Category Vote (URL Parameters):
{
UUID: string, //id of the sponsor being voted on
userID: string, //the local user id
category: string //the name of the category to change this submission to
}Response:
{
Nothing (status code 200)
}Error codes:
400: Bad Request (Your inputs are wrong/impossible)
403: Reason given in request (moderation)
Input (URL Parameters):
{
UUID: string
}Response:
{
Nothing (status code 200)
}Error codes:
400: Bad Request (Your inputs are wrong/impossible)
Input:
{
userID: string //the local user id
}OR
{
publicUserID: string
}Response:
{
userID: string, // the public user ID
userName: string,
minutesSaved: float,
segmentCount: int,
viewCount: int,
warnings: int,
reputation: float,
vip: boolean,
}Error codes:
400: Bad inputs
Input:
{
userID: string //the local user id
}Response:
{
viewCount: int
}Error codes:
404: Not Found
Input:
{
userID: string //the local user id
}Response:
{
timeSaved: float //in minutes
}Error codes:
404: Not Found
Input (URL Parameters):
{
userID: string, //local user id normally, public user id if adminUserID is specified
username: string,
//optional
adminUserID: string //This is if you want to change someone elses username from the admin account
}Response:
{
Nothing (status code 200)
}Error codes:
400: Bad Request (Your inputs are wrong/impossible)
Input:
{
userID: string //the local user id
}Response:
{
userName: string //will send back hashed userID if no username has been set
}Error codes:
400: Bad Request (Your inputs are wrong/impossible)
Input:
{
sortType: int //0 for by minutes saved, 1 for by view count, 2 for by total submissions
}Response:
{
userNames: array [string],
viewCounts: array [int],
totalSubmissions: array [int],
minutesSaved: array [float]
}Error codes:
400: Bad Request (Your inputs are wrong/impossible)
Input:
{
"countContributingUsers": boolean //Optional, default false
}Response:
{
userCount: int, // Only if countContributingUsers was true
activeUsers: int, // Sum of public install stats from Chrome webstore and Firefox addons store
apiUsers: int, // 48-hour active API users (https://github.com/ajayyy/PrivacyUserCount)
viewCount: int,
totalSubmissions: int,
minutesSaved: float
}Error codes:
None
Input:
{
Nothing
}Response:
{
daysSaved: float (2 decimal places)
}Error codes:
None
These can only be called by the users added to the VIP table.
Input:
{
userID: string, // private userID
}Response:
{
hashedUserID: string,
vip: boolean
}Error codes:
400: Bad Request (Your inputs are wrong/impossible)
Will block new segment submissions of the specified category on that video.
Input (Request Body):
{
videoID: string,
userID: string,
categories: string[]
}Response:
{
Nothing (status code 200)
}Error codes:
400: Bad Request (Your inputs are wrong/impossible)
403: Unauthorized (You are not a VIP)
Will block new segment submissions of the specified category on that video.
Input (Request Body):
{
videoID: string,
userID: string,
categories: string[]
}Response:
{
message: "Removed lock categories entrys for video {videoID}"
}Error codes:
400: Bad Request (Your inputs are wrong/impossible)
403: Unauthorized (You are not a VIP)
Shadow banned submissions are hidden for everyone but the IP that originally submitted it. Shadow banning a user shadow bans all future submissions.
Input (URL Parameters):
{
userID: string, //public userID of the user you want to shadowBan
adminUserID: string, //your userID as an admin
enabled: boolean, //optional, to be able to add and remove users
unHideOldSubmissions: boolean //optional, should all previous submissions be banned as well?
}Response:
{
Nothing (status code 200)
}Error codes:
400: Bad Request (Your inputs are wrong/impossible)
403: Unauthorized (You are not a VIP)
Temporary ban that shows a warning asking them to contact us.
Input (Request Body):
{
issuerUserID: string, // your userID
userID: string, // public userID you are warning
enabled: boolean //optional, default true
}Response:
{
Nothing (status code 200)
}Error codes:
403: Unauthorized (You are not a VIP)
These can only be called by the server administrator, set in the config.
VIPs have extra privileges and their votes count more.
Input:
{
userID: string, //public userID of the user you want to add to the VIP list
adminUserID: string, //your userID as an admin
enabled: boolean //optional, to be able to add and remove users
}Response:
{
Nothing (status code 200)
}Error codes:
400: Bad Request (Your inputs are wrong/impossible)
403: Unauthorized (You are not an admin)
https://github.com/ajayyy/SponsorBlock/wiki/Legacy-API
The local userID should be a randomly generated and saved client side. It is used to submit and vote. The public userID is what is used as an identifier in the database. This is the local userID with a SHA 256 hash 5000 times.