Difference between revisions of "API Docs/Draft"

From SponsorBlock
Jump to navigation Jump to search
m (removed aliased endpoints to Legacy-API)
(use syntaxhighlight instead of source)
Line 20: Line 20:
====='''GET''' <code>/api/skipSegments</code>=====
====='''GET''' <code>/api/skipSegments</code>=====
'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
 
<syntaxhighlight lang="js">
<source lang="js">{
{
   videoID: string,
   videoID: string,
   category: string, // Optional, defaults to "sponsor", can be repeated for multiple categories.
   category: string, // Optional, defaults to "sponsor", can be repeated for multiple categories.
Line 30: Line 30:


   service: string // Optional, default is 'YouTube'. See https://github.com/ajayyy/SponsorBlock/wiki/Types#service
   service: string // Optional, default is 'YouTube'. See https://github.com/ajayyy/SponsorBlock/wiki/Types#service
} </source> '''Response''':
}
</syntaxhighlight>


<source lang="js">[{ // Array of this object
'''Response''':
<syntaxhighlight lang="js">
[{ // Array of this object
   segment: float[], //[0, 15.23] start and end time in seconds
   segment: float[], //[0, 15.23] start and end time in seconds
   UUID: string,
   UUID: string,
   category: string,
   category: string,
   videoDuration: float // Duration of video when submission occurred (to be used to determine when a submission is out of date)
   videoDuration: float // Duration of video when submission occurred (to be used to determine when a submission is out of date)
}] </source> '''Error codes''':
}]
</syntaxhighlight>
 
'''Error codes''':


400: Bad Request (Your inputs are wrong/impossible)
400: Bad Request (Your inputs are wrong/impossible)
Line 47: Line 53:


'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
 
<syntaxhighlight lang="js">
<source lang="js">{
{
   category: string, // Optional, defaults to "sponsor", can be repeated for multiple categories.
   category: string, // Optional, defaults to "sponsor", can be repeated for multiple categories.
   // See https://github.com/ajayyy/SponsorBlock/wiki/Types#category
   // See https://github.com/ajayyy/SponsorBlock/wiki/Types#category
Line 56: Line 62:


   service: string // Optional, default is 'YouTube'. See https://github.com/ajayyy/SponsorBlock/wiki/Types#service
   service: string // Optional, default is 'YouTube'. See https://github.com/ajayyy/SponsorBlock/wiki/Types#service
} </source> '''Response''':
}
</syntaxhighlight>


<source lang="js">[{ // Array of this object
'''Response''':
<syntaxhighlight lang="js">
[{ // Array of this object
   "videoID": string,
   "videoID": string,
   "hash": string, // The full hash
   "hash": string, // The full hash
Line 67: Line 76:
   }]
   }]
    
    
}] </source> '''Error codes''':
}]
</syntaxhighlight>
'''Error codes''':


400: Bad Request (Your inputs are wrong/impossible)
400: Bad Request (Your inputs are wrong/impossible)
Line 74: Line 85:
-----
-----
====='''POST''' <code>/api/skipSegments</code>=====
====='''POST''' <code>/api/skipSegments</code>=====
'''Input Option 1 (URL Parameters)''':
'''Input Option 1 (URL Parameters)''':
 
<syntaxhighlight lang="js">
<source lang="js">{
{
   videoID: string,
   videoID: string,
   startTime: float,
   startTime: float,
Line 86: Line 98:
   service: string, // Optional, default is 'YouTube'. See https://github.com/ajayyy/SponsorBlock/wiki/Types#service
   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)
   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)
} </source><nowiki> </nowiki>'''Input Option 2 (JSON Body)''':
}
</syntaxhighlight>


<source lang="js">{
'''Input Option 2 (JSON Body)''':
<syntaxhighlight lang="js">
{
   videoID: string,
   videoID: string,
   userID: string, // This should be a randomly generated UUID stored locally (not the public one)
   userID: string, // This should be a randomly generated UUID stored locally (not the public one)
Line 100: Line 115:
     category: string
     category: string
   }]
   }]
} </source><nowiki> </nowiki>'''Response''':
}
</syntaxhighlight>


<source lang="js">{
'''Response''':
<syntaxhighlight lang="js">
{
   Nothing (status code 200)
   Nothing (status code 200)
} </source> '''Error codes''':
}
</syntaxhighlight>
 
'''Error codes''':


400: Bad Request (Your inputs are wrong/impossible)
400: Bad Request (Your inputs are wrong/impossible)
Line 115: Line 136:
-----
-----
====='''POST''' <code>/api/voteOnSponsorTime</code>=====
====='''POST''' <code>/api/voteOnSponsorTime</code>=====
'''Input: Normal Vote''' (URL Parameters):
'''Input: Normal Vote''' (URL Parameters):
 
<syntaxhighlight lang="js">
<source lang="js">{
{
   UUID: string, //id of the sponsor being voted on
   UUID: string, //id of the sponsor being voted on
   userID: string, //the local user id
   userID: string, //the local user id
   type: int //0 for downvote, 1 for upvote
   type: int //0 for downvote, 1 for upvote
} </source> OR
}
</syntaxhighlight>
 
OR


'''Input: Category Vote''' (URL Parameters):
'''Input: Category Vote''' (URL Parameters):
 
<syntaxhighlight lang="js">
<source lang="js">{
{
   UUID: string, //id of the sponsor being voted on
   UUID: string, //id of the sponsor being voted on
   userID: string, //the local user id
   userID: string, //the local user id
   category: string //the name of the category to change this submission to
   category: string //the name of the category to change this submission to
} </source> '''Response''':
} </syntaxhighlight>


<source lang="js">{
'''Response''':
<syntaxhighlight lang="js">
{
   Nothing (status code 200)
   Nothing (status code 200)
} </source> '''Error codes''':
}
</syntaxhighlight>


'''Error codes''':
400: Bad Request (Your inputs are wrong/impossible)
400: Bad Request (Your inputs are wrong/impossible)


Line 140: Line 169:
-----
-----
====='''POST''' <code>/api/viewedVideoSponsorTime</code>=====
====='''POST''' <code>/api/viewedVideoSponsorTime</code>=====
'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
 
<syntaxhighlight lang="js">
<source lang="js">{
{
   UUID: string
   UUID: string
} </source> '''Response''':
}
</syntaxhighlight>


<source lang="js">{
'''Response''':
<syntaxhighlight lang="js">
{
   Nothing (status code 200)
   Nothing (status code 200)
} </source> '''Error codes''':
}
</syntaxhighlight>


'''Error codes''':
400: Bad Request (Your inputs are wrong/impossible)
400: Bad Request (Your inputs are wrong/impossible)
-----
-----
====='''GET''' <code>/api/userInfo</code>=====
====='''GET''' <code>/api/userInfo</code>=====
'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
 
<syntaxhighlight lang="js">
<source lang="js">{
{
   userID: string //the local user id
   userID: string //the local user id
} </source> '''OR'''
}
 
</syntaxhighlight>
<source lang="js">{
'''OR'''
<syntaxhighlight  lang="js">
{
   publicUserID: string
   publicUserID: string
} </source> '''Response''':
}
</syntaxhighlight>


<source lang="js">{
'''Response''':
<syntaxhighlight lang="js">
{
   userID: string, // the public user ID
   userID: string, // the public user ID
   userName: string,
   userName: string,
Line 175: Line 215:
   vip: boolean,
   vip: boolean,
   lastSegmentID: string
   lastSegmentID: string
} </source> '''Error codes''':
}
</syntaxhighlight>


'''Error codes''':
400: Bad inputs
400: Bad inputs
-----
-----
====='''GET''' <code>/api/getViewsForUser</code>=====
====='''GET''' <code>/api/getViewsForUser</code>=====
'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
 
<syntaxhighlight lang="js">
<source lang="js">{
{
   userID: string //the local user id
   userID: string //the local user id
} </source> '''Response''':
}
</syntaxhighlight>


<source lang="js">{
'''Response''':
<syntaxhighlight lang="js">
{
   viewCount: int
   viewCount: int
} </source> '''Error codes''':
}
</syntaxhighlight>


'''Error codes''':
404: Not Found
404: Not Found
-----
-----
====='''GET''' <code>/api/getSavedTimeForUser</code>=====
====='''GET''' <code>/api/getSavedTimeForUser</code>=====
'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
 
<syntaxhighlight lang="js">
<source lang="js">{
{
   userID: string //the local user id
   userID: string //the local user id
} </source> '''Response''':
}
</syntaxhighlight>


<source lang="js">{
'''Response''':
<syntaxhighlight lang="js">
{
   timeSaved: float //in minutes
   timeSaved: float //in minutes
} </source> '''Error codes''':
}
</syntaxhighlight>


'''Error codes''':
404: Not Found
404: Not Found
-----
-----
====='''POST''' <code>/api/setUsername</code>=====
====='''POST''' <code>/api/setUsername</code>=====
'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
 
<syntaxhighlight lang="js">
<source lang="js">{
{
   userID: string, //local user id normally, public user id if adminUserID is specified
   userID: string, //local user id normally, public user id if adminUserID is specified
   username: string,
   username: string,
   //optional
   //optional
   adminUserID: string //This is if you want to change someone elses username from the admin account
   adminUserID: string //This is if you want to change someone elses username from the admin account
} </source> '''Response''':
}
</syntaxhighlight>


<source lang="js">{
'''Response''':
<syntaxhighlight lang="js">
{
   Nothing (status code 200)
   Nothing (status code 200)
} </source> '''Error codes''':
}
</syntaxhighlight>


'''Error codes''':
400: Bad Request (Your inputs are wrong/impossible)
400: Bad Request (Your inputs are wrong/impossible)
-----
-----
====='''GET''' <code>/api/getUsername</code>=====
====='''GET''' <code>/api/getUsername</code>=====
'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
 
<syntaxhighlight lang="js">
<source lang="js">{
{
   userID: string //the local user id
   userID: string //the local user id
} </source> '''Response''':
}
</syntaxhighlight>


<source lang="js">{
'''Response''':
<syntaxhighlight lang="js">
{
   userName: string //will send back hashed userID if no username has been set
   userName: string //will send back hashed userID if no username has been set
} </source> '''Error codes''':
}
</syntaxhighlight>
 
'''Error codes''':


400: Bad Request (Your inputs are wrong/impossible)
400: Bad Request (Your inputs are wrong/impossible)
Line 236: Line 302:
===Stats Calls===
===Stats Calls===
====='''GET''' <code>/api/getTopUsers</code>=====
====='''GET''' <code>/api/getTopUsers</code>=====
'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
 
<syntaxhighlight lang="js">
<source lang="js">{
{
   sortType: int //0 for by minutes saved, 1 for by view count, 2 for by total submissions
   sortType: int //0 for by minutes saved, 1 for by view count, 2 for by total submissions
} </source> '''Response''':
}
</syntaxhighlight>


<source lang="js">{
'''Response''':
<syntaxhighlight lang="js">
{
   userNames: array [string],
   userNames: array [string],
   viewCounts: array [int],
   viewCounts: array [int],
   totalSubmissions: array [int],
   totalSubmissions: array [int],
   minutesSaved: array [float]
   minutesSaved: array [float]
} </source> '''Error codes''':
}
</syntaxhighlight>


'''Error codes''':
400: Bad Request (Your inputs are wrong/impossible)
400: Bad Request (Your inputs are wrong/impossible)
-----
-----
Line 254: Line 326:
'''Input''' (URL Parameters):
'''Input''' (URL Parameters):


<source lang="js">{
<syntaxhighlight lang="js">
{
   "countContributingUsers": boolean //Optional, default false
   "countContributingUsers": boolean //Optional, default false
} </source> '''Response''':
}
</syntaxhighlight>


<source lang="js">{
'''Response''':
<syntaxhighlight lang="js">
{
   userCount: int, // Only if countContributingUsers was true
   userCount: int, // Only if countContributingUsers was true
   activeUsers: int, // Sum of public install stats from Chrome webstore and Firefox addons store
   activeUsers: int, // Sum of public install stats from Chrome webstore and Firefox addons store
Line 265: Line 341:
   totalSubmissions: int,
   totalSubmissions: int,
   minutesSaved: float
   minutesSaved: float
} </source> '''Error codes''':
}
</syntaxhighlight>


'''Error codes''':
None
None
-----
-----
====='''GET''' <code>/api/getDaysSavedFormatted</code>=====
====='''GET''' <code>/api/getDaysSavedFormatted</code>=====
'''Input''':
'''Input''':
 
<syntaxhighlight lang="js">
<source lang="js">{
{
   Nothing
   Nothing
} </source> '''Response''':
}
</syntaxhighlight>


<source lang="js">{
'''Response''':
<syntaxhighlight lang="js">
{
   daysSaved: float (2 decimal places)
   daysSaved: float (2 decimal places)
} </source> '''Error codes''':
}
</syntaxhighlight>


'''Error codes''':
None
None
-----
-----
====='''GET''' <code>/api/segmentInfo</code>=====
====='''GET''' <code>/api/segmentInfo</code>=====
'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
 
<syntaxhighlight lang="js">
<source lang="js">{
{
   UUID: string, // Can be used instead of UUIDs, can be repeated to fetch multiple segments
   UUID: string, // Can be used instead of UUIDs, can be repeated to fetch multiple segments
   UUIDs: string[] // Can be used instead of UUID. Maximum 10 entries. Will look like ["a...0", "b...1"]
   UUIDs: string[] // Can be used instead of UUID. Maximum 10 entries. Will look like ["a...0", "b...1"]
} </source> '''Response''':
}
</syntaxhighlight>


<source lang="js">[{ // Array of this object
'''Response''':
<syntaxhighlight lang="js">
[{ // Array of this object
   videoID: string,
   videoID: string,
   startTime: float,
   startTime: float,
Line 307: Line 395:
   shadowHidden: int,
   shadowHidden: int,
   userAgent: string
   userAgent: string
}] </source><nowiki> </nowiki>'''Error codes''':
}]
</syntaxhighlight>


'''Error codes''':
400: Bad Request (Your inputs are wrong/impossible)
400: Bad Request (Your inputs are wrong/impossible)


Line 314: Line 404:
-----
-----
====='''GET''' <code>/api/userID</code>=====
====='''GET''' <code>/api/userID</code>=====
'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
 
<syntaxhighlight lang="js">
<source lang="js">{
{
   username: string, // search string for username
   username: string, // search string for username
   // case sensitive
   // case sensitive
   // minimum for non-exact search is 3 characters, maximum is 64 characters
   // minimum for non-exact search is 3 characters, maximum is 64 characters
   exact: Boolean // if explicitly set to true, searches for exact username
   exact: Boolean // if explicitly set to true, searches for exact username
} </source> '''Response''':
}
</syntaxhighlight>


<source lang="js">[{ // Array of this object - maximum 10 results
'''Response''':
<syntaxhighlight lang="js">
[{ // Array of this object - maximum 10 results
   userName: string,
   userName: string,
   userID: string
   userID: string
}] </source> '''Error codes''':
}]
</syntaxhighlight>


'''Error codes''':
400: Bad Request (Your inputs are wrong/impossible) or exceed the character limits
400: Bad Request (Your inputs are wrong/impossible) or exceed the character limits


Line 333: Line 429:
-----
-----
====='''GET''' <code>/api/lockCategories</code>=====
====='''GET''' <code>/api/lockCategories</code>=====
'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
 
<syntaxhighlight lang="js">
<source lang="js">{
{
   videoID: string
   videoID: string
} </source> '''Response''':
}
</syntaxhighlight>


<source lang="js">{
'''Response''':
<syntaxhighlight lang="js">
{
   "categories": string[],
   "categories": string[],
   // See https://github.com/ajayyy/SponsorBlock/wiki/Types#category
   // See https://github.com/ajayyy/SponsorBlock/wiki/Types#category
   "reason": string
   "reason": string
} </source> '''Error codes''':
}
</syntaxhighlight>


400: Bad Request (Your inputs are wrong/impossible) 404: Not Found
'''Error codes''':
400: Bad Request (Your inputs are wrong/impossible)
 
404: Not Found
-----
-----
====='''GET''' <code>/api/lockCategories/:sha256HashPrefix</code>=====
====='''GET''' <code>/api/lockCategories/:sha256HashPrefix</code>=====
Line 351: Line 455:


'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
 
<syntaxhighlight lang="js">
<source lang="js">{
{
   "prefix": sha256HashPrefix // optional if not sent through path
   "prefix": sha256HashPrefix // optional if not sent through path
} </source> '''Response''':
}
</syntaxhighlight>


<source lang="js">[{ // Array of this object
'''Response''':
<syntaxhighlight lang="js">
[{ // Array of this object
   "videoID": string,
   "videoID": string,
   "hash": string, // The full hash
   "hash": string, // The full hash
Line 362: Line 469:
   // See https://github.com/ajayyy/SponsorBlock/wiki/Types#category
   // See https://github.com/ajayyy/SponsorBlock/wiki/Types#category
   "reason": string
   "reason": string
}] </source><nowiki> </nowiki>'''Error codes''':
}]
</syntaxhighlight>


400: Bad Request (Your inputs are wrong/impossible) 404: Not Found
'''Error codes''':
400: Bad Request (Your inputs are wrong/impossible)
 
404: Not Found
-----
-----
===VIP Calls===
===VIP Calls===
These can only be called by the users added to the VIP table.
These can only be called by the users added to the VIP table.
====='''GET''' <code>/api/isUserVIP</code>=====
====='''GET''' <code>/api/isUserVIP</code>=====
'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
 
<syntaxhighlight lang="js">
<source lang="js">{
{
   userID: string, // private userID
   userID: string, // private userID
} </source> '''Response''':
}
</syntaxhighlight>


<source lang="js">{
'''Response''':
<syntaxhighlight lang="js">
{
   hashedUserID: string,
   hashedUserID: string,
   vip: boolean
   vip: boolean
} </source> '''Error codes''':
}
</syntaxhighlight>


'''Error codes''':
400: Bad Request (Your inputs are wrong/impossible)
400: Bad Request (Your inputs are wrong/impossible)
-----
-----
Line 386: Line 503:


'''Input''' (Request Body):
'''Input''' (Request Body):
 
<syntaxhighlight lang="js">
<source lang="js">{
{
   videoID: string,
   videoID: string,
   userID: string,
   userID: string,
   categories: string[],
   categories: string[],
   reason: string
   reason: string
} </source> '''Response''':
}
</syntaxhighlight>


<source lang="js">{
'''Response''':
<syntaxhighlight lang="js">
{
   Nothing (status code 200)
   Nothing (status code 200)
} </source> '''Error codes''':
}
</syntaxhighlight>


'''Error codes''':
400: Bad Request (Your inputs are wrong/impossible)
400: Bad Request (Your inputs are wrong/impossible)


Line 406: Line 528:


'''Input''' (Request Body):
'''Input''' (Request Body):
 
<syntaxhighlight lang="js">
<source lang="js">{
{
   videoID: string,
   videoID: string,
   userID: string,
   userID: string,
   categories: string[]
   categories: string[]
} </source> '''Response''':
}
</syntaxhighlight>


<source lang="js">{
'''Response''':
<syntaxhighlight lang="js">
{
   message: "Removed lock categories entrys for video {videoID}"
   message: "Removed lock categories entrys for video {videoID}"
} </source> '''Error codes''':
}
</syntaxhighlight>


'''Error codes''':
400: Bad Request (Your inputs are wrong/impossible)
400: Bad Request (Your inputs are wrong/impossible)


Line 425: Line 552:


'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
 
<syntaxhighlight lang="js">
<source lang="js">{
{
   userID: string, //public userID of the user you want to shadowBan
   userID: string, //public userID of the user you want to shadowBan
   adminUserID: string, //your userID as an admin
   adminUserID: string, //your userID as an admin
   enabled: boolean, //optional, to be able to add and remove users
   enabled: boolean, //optional, to be able to add and remove users
   unHideOldSubmissions: boolean //optional, should all previous submissions be banned as well?
   unHideOldSubmissions: boolean //optional, should all previous submissions be banned as well?
} </source> '''Response''':
}
</syntaxhighlight>


<source lang="js">{
'''Response''':
<syntaxhighlight lang="js">
{
   Nothing (status code 200)
   Nothing (status code 200)
} </source> '''Error codes''':
}
</syntaxhighlight>


'''Error codes''':
400: Bad Request (Your inputs are wrong/impossible)
400: Bad Request (Your inputs are wrong/impossible)


Line 449: Line 581:


'''Input''' (Request Body):
'''Input''' (Request Body):
 
<syntaxhighlight lang="js">  
<source lang="js">{
{
   issuerUserID: string, // your userID
   issuerUserID: string, // your userID
   userID: string, // public userID you are warning
   userID: string, // public userID you are warning
   enabled: boolean //optional, default true
   enabled: boolean //optional, default true
} </source> '''Response''':
}
</syntaxhighlight>


<source lang="js">{
'''Response''':
<syntaxhighlight lang="js">
{
   Nothing (status code 200)
   Nothing (status code 200)
} </source> '''Error codes''':
}
</syntaxhighlight>


'''Error codes''':
400: Bad Request (Your inputs are wrong/impossible)
400: Bad Request (Your inputs are wrong/impossible)


Line 468: Line 605:


'''Input''' (Request Body):
'''Input''' (Request Body):
 
<syntaxhighlight lang="js">
<source lang="js">{
{
   userID: string, // your userID
   userID: string, // your userID
   videoID: string // video ID to clear cache of
   videoID: string // video ID to clear cache of
} </source> '''Response''':
}
</syntaxhighlight>


<source lang="js">{
'''Response''':
<syntaxhighlight lang="js">
{
   Cache cleared on video videoID (status code 200)
   Cache cleared on video videoID (status code 200)
} </source> '''Error codes''':
}
</syntaxhighlight>


'''Error codes''':
400: Bad Request (Your inputs are wrong/impossible)
400: Bad Request (Your inputs are wrong/impossible)


Line 486: Line 628:


'''Input''' (Request Body):
'''Input''' (Request Body):
 
<syntaxhighlight lang="js">
<source lang="js">{
{
   userID: string, // your userID
   userID: string, // your userID
   videoID: string // video ID to hide segments of
   videoID: string // video ID to hide segments of
} </source> '''Response''':
}
</syntaxhighlight>


<source lang="js">{
'''Response''':
<syntaxhighlight lang="js">
{
   Nothing (status code 200)
   Nothing (status code 200)
} </source> '''Error codes''':
}
</syntaxhighlight>


'''Error codes''':
400: Bad Request (Your inputs are wrong/impossible)
400: Bad Request (Your inputs are wrong/impossible)


Line 506: Line 653:


'''Input''' (Request Body):
'''Input''' (Request Body):
 
<syntaxhighlight lang="js">
<source lang="js">{
{
   userID: string, //public userID of the user you want to add to the VIP list
   userID: string, //public userID of the user you want to add to the VIP list
   adminUserID: string, //your userID as an admin
   adminUserID: string, //your userID as an admin
   enabled: boolean //optional, to be able to add and remove users
   enabled: boolean //optional, to be able to add and remove users
} </source> '''Response''':
}
</syntaxhighlight>


<source lang="js">{
'''Response''':
<syntaxhighlight lang="js">
{
   Nothing (status code 200)
   Nothing (status code 200)
} </source> '''Error codes''':
}
</syntaxhighlight>


'''Error codes''':
400: Bad Request (Your inputs are wrong/impossible)
400: Bad Request (Your inputs are wrong/impossible)


403: Unauthorized (You are not an admin)
403: Unauthorized (You are not an admin)
-----
===Legacy API===
===Legacy API===
https://github.com/ajayyy/SponsorBlock/wiki/Legacy-API
https://github.com/ajayyy/SponsorBlock/wiki/Legacy-API
===Local userID vs Public userID===
===Local userID vs Public userID===
The local userID should be a randomly generated and saved client side and must be 32 characters (or more). If it is not 32 characters or more, you will not be able to vote or submit. 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.
The local userID should be a randomly generated and saved client side and must be 32 characters (or more). If it is not 32 characters or more, you will not be able to vote or submit. 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.
__NOINDEX__

Revision as of 21:43, 4 August 2021

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

Database Dump | Webhook Docs


GET /api/skipSegments

Input (URL Parameters):

{
  videoID: string,
  category: string, // Optional, defaults to "sponsor", can be repeated for multiple categories.
    // 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"]

  requiredSegments: string[], // Optional, list of segment UUIDs to require be retrieved, even if they don't meet the minimum vote threshold, can be replaced with "requiredSegment" and repeated for multiple segments like category.

  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:

400: Bad Request (Your inputs are wrong/impossible)

404: Not Found


GET /api/skipSegments/:sha256HashPrefix

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 (URL Parameters):

{
  category: string, // Optional, defaults to "sponsor", can be repeated for multiple categories.
  // 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"]

  requiredSegments: string[], // Optional, list of segment UUIDs to require be retrieved, even if they don't meet the minimum vote threshold, can be replaced with "requiredSegment" and repeated for multiple segments like category.

  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:

400: Bad Request (Your inputs are wrong/impossible)

404: Not Found


POST /api/skipSegments

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)
  userAgent: string, // "Name of Client" or "[BOT] Name of Bot"

  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)
  userAgent: string, // "Name of Client" or "[BOT] Name of Bot"

  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


POST /api/voteOnSponsorTime

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)


POST /api/viewedVideoSponsorTime

Input (URL Parameters):

{
  UUID: string
}

Response:

{
  Nothing (status code 200)
}

Error codes: 400: Bad Request (Your inputs are wrong/impossible)


GET /api/userInfo

Input (URL Parameters):

{
  userID: string //the local user id
}

OR

{
  publicUserID: string
}

Response:

{
  userID: string, // the public user ID
  userName: string,
  minutesSaved: float,
  segmentCount: int,
  ignoredSegmentCount: int,
  viewCount: int,
  ignoredViewCount: int,
  warnings: int,
  reputation: float,
  vip: boolean,
  lastSegmentID: string
}

Error codes: 400: Bad inputs


GET /api/getViewsForUser

Input (URL Parameters):

{
  userID: string //the local user id
}

Response:

{
  viewCount: int
}

Error codes: 404: Not Found


GET /api/getSavedTimeForUser

Input (URL Parameters):

{
  userID: string //the local user id
}

Response:

{
  timeSaved: float //in minutes
}

Error codes: 404: Not Found


POST /api/setUsername

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)


GET /api/getUsername

Input (URL Parameters):

{
  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)


Stats Calls

GET /api/getTopUsers

Input (URL Parameters):

{
  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)


GET /api/getTotalStats

Input (URL Parameters):

{
  "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


GET /api/getDaysSavedFormatted

Input:

{
  Nothing
}

Response:

{
  daysSaved: float (2 decimal places)
}

Error codes: None


GET /api/segmentInfo

Input (URL Parameters):

{
  UUID: string, // Can be used instead of UUIDs, can be repeated to fetch multiple segments
  UUIDs: string[] // Can be used instead of UUID. Maximum 10 entries. Will look like ["a...0", "b...1"]
}

Response:

[{ // Array of this object
  videoID: string,
  startTime: float,
  endTime: fload,
  votes: int,
  locked: int,
  UUID: string,
  userID: string,
  timeSubmitted: int,
  views: int,
  category: string,
  service: string,
  videoDuration: int,
  hidden: int,
  reputation: int,
  shadowHidden: int,
  userAgent: string
}]

Error codes: 400: Bad Request (Your inputs are wrong/impossible)

404: Not Found


GET /api/userID

Input (URL Parameters):

{
  username: string, // search string for username
  // case sensitive
  // minimum for non-exact search is 3 characters, maximum is 64 characters
  exact: Boolean // if explicitly set to true, searches for exact username
}

Response:

[{ // Array of this object - maximum 10 results
  userName: string,
  userID: string
}]

Error codes: 400: Bad Request (Your inputs are wrong/impossible) or exceed the character limits

404: Not Found


GET /api/lockCategories

Input (URL Parameters):

{
  videoID: string
}

Response:

{
  "categories": string[],
  // See https://github.com/ajayyy/SponsorBlock/wiki/Types#category
  "reason": string
}

Error codes: 400: Bad Request (Your inputs are wrong/impossible)

404: Not Found


GET /api/lockCategories/:sha256HashPrefix

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 (URL Parameters):

{
  "prefix": sha256HashPrefix // optional if not sent through path
}

Response:

[{ // Array of this object
   "videoID": string,
   "hash": string, // The full hash
   "categories": string[],
   // See https://github.com/ajayyy/SponsorBlock/wiki/Types#category
   "reason": string
}]

Error codes: 400: Bad Request (Your inputs are wrong/impossible)

404: Not Found


VIP Calls

These can only be called by the users added to the VIP table.

GET /api/isUserVIP

Input (URL Parameters):

{
  userID: string, // private userID
}

Response:

{
  hashedUserID: string,
  vip: boolean
}

Error codes: 400: Bad Request (Your inputs are wrong/impossible)


POST /api/lockCategories

Will block new segment submissions of the specified category on that video.

Input (Request Body):

{
  videoID: string,
  userID: string,
  categories: string[],
  reason: string
}

Response:

{
  Nothing (status code 200)
}

Error codes: 400: Bad Request (Your inputs are wrong/impossible)

403: Unauthorized (You are not a VIP)


DELETE /api/lockCategories

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)


POST /api/shadowBanUser

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)

409: User already warned


POST /api/warnUser

Temporary ban that shows a warning asking them to contact us.

If a user is re-warned but there is still a non-expired warning, it is reenabled

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: 400: Bad Request (Your inputs are wrong/impossible)

403: Unauthorized (You are not a VIP)


POST /api/clearCache

Clear redis cache for video.

Input (Request Body):

{
  userID: string, // your userID
  videoID: string // video ID to clear cache of
}

Response:

{
  Cache cleared on video videoID (status code 200)
}

Error codes: 400: Bad Request (Your inputs are wrong/impossible)

403: Unauthorized (You are not a VIP)


POST /api/purgeAllSegments

Hide all segments on a video

Input (Request Body):

{
  userID: string, // your userID
  videoID: string // video ID to hide segments of
}

Response:

{
  Nothing (status code 200)
}

Error codes: 400: Bad Request (Your inputs are wrong/impossible)

403: Unauthorized (You are not a VIP)


Admin Calls

These can only be called by the server administrator, set in the config.

POST /api/addUserAsVIP

VIPs have extra privileges and their votes count more.

Input (Request Body):

{
  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)


Legacy API

https://github.com/ajayyy/SponsorBlock/wiki/Legacy-API

Local userID vs Public userID

The local userID should be a randomly generated and saved client side and must be 32 characters (or more). If it is not 32 characters or more, you will not be able to vote or submit. 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.