Difference between revisions of "API Docs/Draft"

From SponsorBlock
Jump to navigation Jump to search
m (remove database mirror by lartza)
(add full and exclusive_access)
(39 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<!-- Formatting Notes:
userID instead of user ID
leave a space after the start of the comment,
public userID & local userID -->
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 :)
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 :)


Line 9: Line 14:
Database download: https://sponsor.ajay.app/database
Database download: https://sponsor.ajay.app/database


'''Libraries''': [https://www.npmjs.com/package/sponsorblock-api NPM]
'''Libraries''': [https://www.npmjs.com/package/sponsorblock-api Node.js], [https://github.com/wasi-master/sponsorblock.py Python], [https://crates.io/crates/sponsor-block Rust]
-----Online Database Explorer (By Lartza): https://sb.ltn.fi/
-----Online Database Explorer (By Lartza): https://sb.ltn.fi/


Database Mirror (5 min update time, provided by Lartza): https://sb.ltn.fi/database/
Database Mirror (5 min update time, provided by Lartza): https://sb.ltn.fi/database/


<sub>[https://sponsor.ajay.app/database Database Dump] | [https://github.com/ajayyy/SponsorBlock/wiki/Webhooks Webhook Docs]</sub>
<sub>[https://sponsor.ajay.app/database Database Dump] | [https://github.com/ajayyy/SponsorBlock/wiki/Webhooks Webhook Docs] | [https://github.com/mchangrh/sb-openapi OpenAPI Docs]</sub>  
-----
-----
====='''GET''' <code>/api/skipSegments</code>=====
====='''GET''' <code>/api/skipSegments</code>=====
Get segments for a video.
'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   videoID: string,
   videoID: string,
   category: string, // Optional, defaults to "sponsor", can be repeated for multiple categories.
 
    // See https://github.com/ajayyy/SponsorBlock/wiki/Types#category
   category: string, // Optional, defaults to "sponsor", can be repeated for multiple categories. [1]
   categories: string[], // Optional, use this instead of "category" if you want multiple categories. Will look like ["sponsor","intro"]
  // OR
  categories: string[], // Optional [1]
 
  requiredSegment: string, // Segment UUID to require to be retrieved, even if they don't meet the minimum vote threshold. Can be repeated for multiple segments.
  // OR
   requiredSegments: string[], // Optional, array of required segment UUIDs


   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.
   actionType: string // Optional, default skip. Can be repeated for multiple types. [3]
  // OR 
  actionTypes: string[] // Optional, array of action types


   service: string // Optional, default is 'YouTube'. See https://github.com/ajayyy/SponsorBlock/wiki/Types#service
   service: string, // Optional, default is 'YouTube' [2]
}
}
</syntaxhighlight>
</syntaxhighlight>
References: <ref name=":0">See [[Types]] for full list of possible categories. To get multiple, create an array with the format <code>["sponsor", intro"]</code>. </ref> <ref name=":1">Service to get segments for. See [https://wiki.sponsor.ajay.app/w/Types#service Types] for supported services</ref> <ref name=":2">Action Types: See [[Types]] for possible values. Select multiple with the format <code>["skip","mute]</code></ref>


'''Response''':
'''Response''':
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
[{ // Array of this object
[{ // 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). 0 when unknown. +- 1 second
  actionType: string // actionType [3]
  userID: string, // public userID of submitter
  locked: int, // if submission is locked
  votes: int, // Votes on segment
  description: string, // unused
}]
}]
</syntaxhighlight>
</syntaxhighlight>
Line 48: Line 69:
-----
-----
====='''GET''' <code>/api/skipSegments/:sha256HashPrefix</code>=====
====='''GET''' <code>/api/skipSegments/:sha256HashPrefix</code>=====
<code>sha256HashPrefix</code> is a hash of the YouTube <code>videoID</code>. 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.
Get segments for a video with extra privacy
 
<code>sha256HashPrefix</code> is a hash of the YouTube <code>videoID</code>. 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 since the server will not know exactly what video you are looking for.


'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   category: string, // Optional, defaults to "sponsor", can be repeated for multiple categories.
   prefix: string, // Can be used instead of path
  // 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.
   category: string, // Optional, defaults to "sponsor", can be repeated for multiple categories. [1]
  // OR
  categories: string[], // Optional, array of categories [1]


   service: string // Optional, default is 'YouTube'. See https://github.com/ajayyy/SponsorBlock/wiki/Types#service
   requiredSegment: string, // Segment UUID to require to be retrieved, even if they don't meet the minimum vote threshold. Can be repeated for multiple segments.
  // OR
  requiredSegments: string[], // Optional, array of required segment UUIDs
 
  actionType: string // Optional, default skip. Can be repeated for multiple types. [3]
  // OR 
  actionTypes: string[] // Optional, array of action types [3]
 
  service: string // Optional, default is 'YouTube'. [2]
}
}
</syntaxhighlight>
</syntaxhighlight>


'''Response''':
References: <ref name=":0" /> <ref name=":1" /> <ref name=":2" />
<syntaxhighlight lang="js">
 
'''Response'''
<syntaxhighlight lang="ts">
[{ // Array of this object
[{ // Array of this object
   "videoID": string,
   videoID: string,
   "hash": string, // The full hash
   hash: string, // Full hash of the videoID
   "segments": [{ // Array of this object
   segments: [{ // 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, [1]
      actionType: string, // [1]
      locked: int, // if segment is locked
      votes: int, // votes on segment
      videoDuration: int, // Duration of video when submissions occurred
      userID: string, // Public userID of submitter
      description: string // unused
   }]
   }]
 
}]
}]
</syntaxhighlight>
</syntaxhighlight>
Line 83: Line 121:
-----
-----
====='''POST''' <code>/api/skipSegments</code>=====
====='''POST''' <code>/api/skipSegments</code>=====
Create a segment on a video


'''Input Option 1 (URL Parameters)''':
'''Input''' (URL Parameters):
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   videoID: string,
   videoID: string,
   startTime: float,
   startTime: float,
   endTime: float,
   endTime: float,
   category: string,
   category: string, // [1]
   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)
   userAgent: string, // "Name of Client" or "[BOT] Name of Bot"
   userAgent: string, // "Name of Client/Version" or "[BOT] Name of Bot/Version" ex. "Chromium/1.0.0"
 
   service: string, // Optional, default is 'YouTube'. [2]
   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)
  actionType: string // Optional, default is "skip". [3]
}
}
</syntaxhighlight>
</syntaxhighlight>


'''Input Option 2 (JSON Body)''':
References: <ref name=":0" /> <ref name=":1" /> <ref name=":2" />
<syntaxhighlight lang="js">
 
'''OR'''
 
'''Input''' (JSON Body):
<syntaxhighlight lang="ts">
{
{
   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)
   userAgent: string, // "Name of Client" or "[BOT] Name of Bot"
   userAgent: string, // "Name of Client/Version" or "[BOT] Name of Bot/Version" ex. "Chromium/1.0.0"
 
   service: string, // Optional, default is 'YouTube'.[2]
   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)


   segments: [{ // Array of this object
   segments: [{ // 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
     category: string
     category: string, // [1]
    actionType: string // Optional, defaults to "skip". [3]
   }]
   }]
}
}
</syntaxhighlight>
</syntaxhighlight>
References: <ref name=":0" /> <ref name=":1" /> <ref name=":2" />


'''Response''':
'''Response''':
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{ // array of this object
   Nothing (status code 200)
   UUID: string, // UUID of submitted segment
}
  category: string, // submitted category [1]
  segment: float[] // start and end time of submitted segment
}[]
</syntaxhighlight>
</syntaxhighlight>


Line 134: Line 181:
-----
-----
====='''POST''' <code>/api/voteOnSponsorTime</code>=====
====='''POST''' <code>/api/voteOnSponsorTime</code>=====
Vote on a segment or vote to change the category of the segment.
Creators of the segment and VIPs can remove the segment or change the category with only one vote.
<div class="toccolours mw-collapsible mw-collapsed" style="width:400px;">
<div style="font-weight:bold;">VIP voting notes</div>
<div class="mw-collapsible-content">
VIP upvotes will:
* lock the segment
* remove "hidden" property
* remove "shadowHidden" property
</div></div>


'''Input: Normal Vote''' (URL Parameters):
'''Input: Normal Vote''' (URL Parameters):
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   UUID: string, //id of the sponsor being voted on
   UUID: string, // UUID of the segment being voted on
   userID: string, //the local user id
   userID: string, // Local userID
   type: int //0 for downvote, 1 for upvote
   type: int // 0 for downvote, 1 for upvote, 20 to undo vote
}
}
</syntaxhighlight>
</syntaxhighlight>


OR
'''OR'''


'''Input: Category Vote''' (URL Parameters):
'''Input: Category Vote''' (URL Parameters):
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   UUID: string, //id of the sponsor being voted on
   UUID: string, // UUID of the segment being voted on
   userID: string, //the local user id
   userID: string, // Local userID
   category: string //the name of the category to change this submission to
   category: string // Category to change this submission to [1]
} </syntaxhighlight>
} </syntaxhighlight>
References: <ref name=":0" />


'''Response''':
'''Response''':
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   Nothing (status code 200)
   Nothing (status code 200)
Line 162: Line 223:


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


403: Reason given in request (moderation)
403: Reason given in request (moderation)
-----
-----
====='''POST''' <code>/api/viewedVideoSponsorTime</code>=====
====='''POST''' <code>/api/viewedVideoSponsorTime</code>=====
Add view to segment


'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   UUID: string
   UUID: string // UUID of segment viewed
}
}
</syntaxhighlight>
</syntaxhighlight>


'''Response''':
'''Response''':
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   Nothing (status code 200)
   Nothing (status code 200)
Line 183: Line 247:


'''Error codes''':
'''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>=====
Get information about a user
'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   userID: string //the local user id
   userID: string // local UserID
  // OR
  publicUserID: string // Public userID
 
  values: string[] // Optional, Values to get from userInfo
    // default values are
    // ["userID", "userName", "minutesSaved", "segmentCount", "ignoredSegmentCount",
    // "viewCount", "ignoredViewCount", "warnings", "warningReason", "reputation",
    // "vip", "lastSegmentID"]
  // OR
  value: string // Optional, Value to get from userInfo, can be repeated for multiple values
}
}
</syntaxhighlight>
</syntaxhighlight>
'''OR'''
'''Response''':
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   publicUserID: string
   userID: string, // Public userID
  userName: string, // Public userID if not set
  minutesSaved: float, // Minutes saved
  segmentCount: int, // Total number of segments excluding ignored/ hidden segments
  ignoredSegmentCount: int, // Total number of ignored/ hidden segments
  viewCount: int, // Total number of views excluding view on ignored/ hidden segments
  ignoredViewCount: int, // Total number of view on ignored/ hidden segments
  warnings: int, // Currently enabled warnings
  reputation: float,
  vip: int, // VIP status
  lastSegmentID: string // UUID of last submitted segment
}
}
</syntaxhighlight>
</syntaxhighlight>


'''Error codes''':
400: Bad Request (Your inputs are wrong/impossible)
-----
====='''GET''' <code>/api/userStats</code>=====
Get stats for a user
'''Input''' (URL Parameters):
<syntaxhighlight lang="ts">
{
  userID: string // local UserID
  // OR
  publicUserID: string // Public userID
  fetchCategoryStats: boolean // default false, display category stats
  fetchActionTypeStats: boolean // default false, display type stats
}
</syntaxhighlight>
'''Response''':
'''Response''':
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   userID: string, // the public user ID
   userID: string // hashed userID
   userName: string,
   userName: string // userName
   minutesSaved: float,
   overallStats: {
  segmentCount: int,
    minutesSaved: integer // same as userInfo
   ignoredSegmentCount: int,
    segmentCount: integer // same as userInfo
   viewCount: int,
  }
  ignoredViewCount: int,
  // IF CHOSEN
  warnings: int,
   categoryCount: { // # of segments per category
  reputation: float,
    sponsor: integer
  vip: boolean,
    intro: integer
   lastSegmentID: string
    outro: integer
    interaction: integer
    selfpromo: integer
    music_offtopic: integer
    preview: integer
    poi_highlight: integer
    filler: integer,
    exclusive_access: integer
   }
  // IF CHOSEN
  actionTypeCount: { // # of segments per type
    skip: integer,
    mute: integer,
    full: integer,
    poi: integer
   }
}
}
</syntaxhighlight>
</syntaxhighlight>


'''Error codes''':
'''Error codes''':
400: Bad inputs
 
400: Bad Request (Your inputs are wrong/impossible)
-----
-----
====='''GET''' <code>/api/getViewsForUser</code>=====
====='''GET''' <code>/api/getViewsForUser</code>=====
Get the number of views a user has on all their segments
'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   userID: string //the local user id
   userID: string // Local userID
}
}
</syntaxhighlight>
</syntaxhighlight>
Line 235: Line 360:


'''Error codes''':
'''Error codes''':
404: Not Found
404: Not Found
-----
-----
====='''GET''' <code>/api/getSavedTimeForUser</code>=====
====='''GET''' <code>/api/getSavedTimeForUser</code>=====
Get the total time saved from all the user's segments


'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   userID: string //the local user id
   userID: string // Local userID
}
}
</syntaxhighlight>
</syntaxhighlight>


'''Response''':
'''Response''':
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   timeSaved: float //in minutes
   timeSaved: float // In minutes
}
}
</syntaxhighlight>
</syntaxhighlight>


'''Error codes''':
'''Error codes''':
404: Not Found
404: Not Found
-----
-----
====='''POST''' <code>/api/setUsername</code>=====
====='''POST''' <code>/api/setUsername</code>=====
Set a username for a userID


'''Input''' (URL Parameters):
'''Input''' (URL Parameters): Setting username for self
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   userID: string, //local user id normally, public user id if adminUserID is specified
   userID: string, // Local userID
   username: string,
   username: string, // Optional
  //optional
  adminUserID: string //This is if you want to change someone elses username from the admin account
}
}
</syntaxhighlight>
</syntaxhighlight>


'''Response''':
'''OR'''
<syntaxhighlight lang="js">
 
'''Input''' (URL Parameters): Setting username as '''admin'''<syntaxhighlight lang="ts">
{
  userID: string, // Public userID
  username: string, // Optional
  adminUserID: string // Admin's local userID
}
</syntaxhighlight>'''Response''':
<syntaxhighlight lang="ts">
{
{
   Nothing (status code 200)
   Nothing (status code 200)
Line 276: Line 411:


'''Error codes''':
'''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)
-----
-----
====='''GET''' <code>/api/getUsername</code>=====
====='''GET''' <code>/api/getUsername</code>=====
Get current username


'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   userID: string //the local user id
   userID: string // Local userID
}
}
</syntaxhighlight>
</syntaxhighlight>


'''Response''':
'''Response''':
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   userName: string //will send back hashed userID if no username has been set
   userName: string // Public userID if no username has been set
}
}
</syntaxhighlight>
</syntaxhighlight>
Line 298: Line 437:
400: Bad Request (Your inputs are wrong/impossible)
400: Bad Request (Your inputs are wrong/impossible)
-----
-----
===Stats Calls===
====='''GET''' <code>/api/segmentInfo</code>=====
====='''GET''' <code>/api/getTopUsers</code>=====
Get information about segments


'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   sortType: int //0 for by minutes saved, 1 for by view count, 2 for by total submissions
   // Only the first 10 entries will be processed
  UUID: string, // Can be repeated for multiple segments
  // OR
  UUIDs: string[] // Looks like ["a...0", "b...1"]
}
}
</syntaxhighlight>
</syntaxhighlight>


'''Response''':
'''Response''':
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
[{ // Array of this object
   userNames: array [string],
  videoID: string,
   viewCounts: array [int],
  startTime: float,
   totalSubmissions: array [int],
  endTime: float,
   minutesSaved: array [float]
  votes: int,
}
  locked: int, // Status of lock - If upvoted by a VIP, the segment is locked
  UUID: string,
  userID: string, // PublicID of submitter
  timeSubmitted: int,
  views: int, // Number of reported views on the segment
   category: string, // [1]
  service: string, // [2]
  videoDuration: int,
  hidden: int, // If the segment has 2 downvotes or was downvoted by a VIP
   reputation: int, // Reputation of submitter at time of submission
   shadowHidden: int, // If the submitter is shadowbanned
  userAgent: string // userAgent of the submitter,
   actionType: string // [3]
}]
</syntaxhighlight>
</syntaxhighlight>
References: <ref name=":0" /> <ref name=":1" /> <ref name=":2" />


'''Error codes''':
'''Error codes''':
400: Bad Request (Your inputs are wrong/impossible)
400: Bad Request (Your inputs are wrong/impossible)
404: Not Found
-----
-----
====='''GET''' <code>/api/getTotalStats</code>=====
====='''GET''' <code>/api/userID</code>=====
List all users matching the username search
 
'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
 
<syntaxhighlight lang="ts">
<syntaxhighlight lang="js">
{
{
   "countContributingUsers": boolean //Optional, default false
   username: string, // search string for username
    // case sensitive
    // minimum for non-exact search is 3 characters, maximum is 64 characters
  exact: boolean // searches for exact username with no wildcard at end
}
}
</syntaxhighlight>
</syntaxhighlight>


'''Response''':
'''Response''':
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
[{ // Array of this object - maximum 10 results
  userCount: int, // Only if countContributingUsers was true
   userName: string,
  activeUsers: int, // Sum of public install stats from Chrome webstore and Firefox addons store
   userID: string
  apiUsers: int, // 48-hour active API users (https://github.com/ajayyy/PrivacyUserCount)
}]
  viewCount: int,
   totalSubmissions: int,
   minutesSaved: float
}
</syntaxhighlight>
</syntaxhighlight>


'''Error codes''':
'''Error codes''':
None
 
400: Bad Request (Your inputs are wrong/impossible) or exceed the character limits
 
404: Not Found
-----
-----
====='''GET''' <code>/api/getDaysSavedFormatted</code>=====
====='''GET''' <code>/api/lockCategories</code>=====
Get locked categories for a video


'''Input''':
'''Input''' (URL Parameters):
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   Nothing
   videoID: string,
  actionTypes: string[] // [3]
    // default [skip, mute]
}
}
</syntaxhighlight>
</syntaxhighlight>


'''Response''':
'''Response''':
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   daysSaved: float (2 decimal places)
   categories: string[], // [1]
  reason: string, // Specified reason for the lock
    // Only the most recent reason will be returned
  actionTypes: string[] // [3]
}
}
</syntaxhighlight>
</syntaxhighlight>
References: <ref name=":0" /> <ref name=":2" />


'''Error codes''':
'''Error codes''':
None
 
400: Bad Request (Your inputs are wrong/impossible)
 
404: Not Found
-----
-----
====='''GET''' <code>/api/segmentInfo</code>=====
====='''GET''' <code>/api/lockCategories/:sha256HashPrefix</code>=====
Get locked categories for a video with extra privacy
 
<code>sha256HashPrefix</code> is a hash of the YouTube <code>videoID</code>. 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):
'''Input''' (URL Parameters):
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   UUID: string, // Can be used instead of UUIDs, can be repeated to fetch multiple segments
   prefix: sha256HashPrefix // Optional if not sent through path
  UUIDs: string[] // Can be used instead of UUID. Maximum 10 entries. Will look like ["a...0", "b...1"]
}
}
</syntaxhighlight>
</syntaxhighlight>


'''Response''':
'''Response''':
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
[{ // Array of this object
[{ // Array of this object
  videoID: string,
  videoID: string,
  startTime: float,
  hash: string, // The full hash of the videoID
  endTime: fload,
  categories": string[], // [1]
  votes: int,
  reason: string // Specified reason for the lock
  locked: int,
  UUID: string,
  userID: string,
  timeSubmitted: int,
  views: int,
  category: string,
  service: string,
  videoDuration: int,
  hidden: int,
  reputation: int,
  shadowHidden: int,
  userAgent: string
}]
}]
</syntaxhighlight>
</syntaxhighlight>
References: <ref name=":0" />


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


404: Not Found
404: Not Found
-----
-----
====='''GET''' <code>/api/userID</code>=====
====='''GET''' <code>/api/lockReason</code>=====
Get reason for lock(s)


'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   username: string, // search string for username
   videoID: string
   // case sensitive
 
   // minimum for non-exact search is 3 characters, maximum is 64 characters
  // Categories to get reasons for, defaults to all [1]
   exact: Boolean // if explicitly set to true, searches for exact username
  category: string
   // OR
   categories: string[],
   actionTypes: string[] // [3]
}
}
</syntaxhighlight>
</syntaxhighlight>
References: <ref name=":0" /> <ref name=":2" />


'''Response''':
'''Response''':
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
[{ // Array of this object - maximum 10 results
[{ // Array of this object
   userName: string,
   category: string, // category [1]
   userID: string
  locked: integer, // status of lock
  reason: string, // reason for lock
   userID: string, // publicID of locking VIP
  userName: string // username of locking VIP
}]
}]
</syntaxhighlight>
</syntaxhighlight>


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


404: Not Found
400: Bad Request (Your inputs are wrong/impossible)
-----
-----
====='''GET''' <code>/api/lockCategories</code>=====
====='''GET''' <code>/api/searchSegments</code>=====
Get all segments of a video based on specified filters. Note: It is suggested that you don't use this for knowing which segments to skip on your client, as thresholds and values that determine which segments are the best change over time. Using [https://wiki.sponsor.ajay.app/index.php/API_Docs#GET_.2Fapi.2FskipSegments /api/skipSegments] ensures that you will always get the best segments.


'''Input''' (URL Parameters):
'''Input''' (URL Parameters) '''OR''' (JSON Body):
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
  // See skipSegments
   videoID: string
   videoID: string
  category: string // [1]
  // OR
  categories: string[]
  actionType: string // [3]
  // OR
  actionTypes: string[]
 
  service: string // [2]
  // End SkipSegments
  page: int // Page to start from (default 0)
 
  // Vote/ view thresholds, inclusive, default includes all segments
  minVotes: int
  maxVotes: int
  minViews: int
  maxViews: int
  // Default true - if false, don't show segments that match type
  locked: boolean
  hidden: boolean
  ignored: boolean // hidden or below vote threshold
}
}
</syntaxhighlight>
</syntaxhighlight>
References: <ref name=":0" /> <ref name=":1" /> <ref name=":2" />


'''Response''':
'''Response''':
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   "categories": string[],
   segmentCount: int, // Total number of segments matching query
   // See https://github.com/ajayyy/SponsorBlock/wiki/Types#category
   page: int, // Page number
  "reason": string
  segments: [{ // Array of this object, max 10
    // see segmentInfo
    UUID: string,
    timeSubmitted: int,
    startTime: int,
    endTime: int,
    category: int, // [1]
    actionType: int, // [3]
    votes: int,
    views: int,
    locked: int,
    hidden: int,
    shadowHidden: int,
    userID: string, // UUID of submitter
  }]
}
}
</syntaxhighlight>
</syntaxhighlight>
References: <ref name=":0" /> <ref name=":2" />


'''Error codes''':
'''Error codes''':
400: Bad Request (Your inputs are wrong/impossible)
400: Bad Request (Your inputs are wrong/impossible)
404: Not Found
-----
====='''GET''' <code>/api/status/:value</code>=====
Get status of server
'''Input:''' (URL path)
Can be any key value in response, requests without path will return all values.
'''Response''':
<syntaxhighlight lang="ts">
{
  uptime: int, // Uptime of server in seconds
  commit: string, // Full SHA hash of latest git commit, development or test
  db: int, // Current database version
  startTime: int, // Unix time that request was received
  processTime: int, // Seconds between startTime and sending response
  loadavg: int[], // 5 and 15 minute loadavg
  statusRequests: int // number of /status requests in the last minute
}
</syntaxhighlight>
'''Error codes''':


404: Not Found
404: Not Found
-----
-----
====='''GET''' <code>/api/lockCategories/:sha256HashPrefix</code>=====
===Stats Calls===
<code>sha256HashPrefix</code> is a hash of the YouTube <code>videoID</code>. 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.
====='''GET''' <code>/api/getTopUsers</code>=====
Get top submitters
 
'''Input''' (URL Parameters):
<syntaxhighlight lang="ts">
{
  sortType: int
    // 0 for by minutes saved
    // 1 for by view count
    // 2 for by total submissions
}
</syntaxhighlight>
 
'''Response''':
<syntaxhighlight lang="ts">
{
  userNames: string[],
  viewCounts: int[],
  totalSubmissions: int[],
  minutesSaved: float[]
}
</syntaxhighlight>
 
'''Error codes''':
 
400: Bad Request (Your inputs are wrong/impossible)
-----'''GET''' <code>/api/getTopCategoryUsers</code>
 
Get top submitters by category


'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   "prefix": sha256HashPrefix // optional if not sent through path
   sortType: int,
    // 0 for by minutes saved
    // 1 for by view count
    // 2 for by total submissions
  category: string // category to fetch stats for
}
}
</syntaxhighlight>
</syntaxhighlight>


'''Response''':
'''Response''':
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
[{ // Array of this object
{
  "videoID": string,
  userNames: string[],
  "hash": string, // The full hash
  viewCounts: int[],
  "categories": string[],
  totalSubmissions: int[],
  // See https://github.com/ajayyy/SponsorBlock/wiki/Types#category
  minutesSaved: float[]
  "reason": string
}
}]
</syntaxhighlight>
</syntaxhighlight>


'''Error codes''':
'''Error codes''':
400: Bad Request (Your inputs are wrong/impossible)
400: Bad Request (Your inputs are wrong/impossible)
-----
====='''GET''' <code>/api/getTotalStats</code>=====
Get total stats
'''Input''' (URL Parameters):
<syntaxhighlight lang="ts">
{
  countContributingUsers: boolean // Optional, default false
}
</syntaxhighlight>
'''Response''':
<syntaxhighlight lang="ts">
{
  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
}
</syntaxhighlight>


404: Not Found
'''Error codes''':
 
None
-----
====='''GET''' <code>/api/getDaysSavedFormatted</code>=====
Get days saved by all skips
 
'''Input''':
<syntaxhighlight lang="ts">
{
  Nothing
}
</syntaxhighlight>
 
'''Response''':
<syntaxhighlight lang="ts">
{
  daysSaved: float (2 decimal places)
}
</syntaxhighlight>
 
'''Error codes''':
 
None
-----
-----
===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>=====
If the user is a VIP


'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   userID: string, // private userID
   userID: string, // Local userID
}
}
</syntaxhighlight>
</syntaxhighlight>


'''Response''':
'''Response''':
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   hashedUserID: string,
   hashedUserID: string, // Public userID
   vip: boolean
   vip: boolean
}
}
Line 495: Line 820:


'''Error codes''':
'''Error codes''':
400: Bad Request (Your inputs are wrong/impossible)
400: Bad Request (Your inputs are wrong/impossible)
-----
-----
====='''POST''' <code>/api/lockCategories</code>=====
====='''POST''' <code>/api/lockCategories</code>=====
Will block new segment submissions of the specified category on that video.
Create a category lock on the video, disallowing further submissions for that category


'''Input''' (Request Body):
'''Input''' (Request Body):
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   videoID: string,
   videoID: string,
   userID: string,
   userID: string, // Local userID
   categories: string[],
   categories: string[], // [1]
   reason: string
   reason: string // Reason for lock
}
}
</syntaxhighlight>
</syntaxhighlight>
References: <ref name=":0" />


'''Response''':
'''Response''':
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   Nothing (status code 200)
   Nothing (status code 200)
Line 518: Line 846:


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


403: Unauthorized (You are not a VIP)
403: Unauthorized (You are not a VIP)
-----
-----
====='''DELETE''' <code>/api/lockCategories</code>=====
===== '''DELETE''' <code>/api/lockCategories</code>=====
Will block new segment submissions of the specified category on that video.
Delete existing category locks on that video


'''Input''' (Request Body):
'''Input''' (Request Body):
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   videoID: string,
   videoID: string,
   userID: string,
   userID: string, // Local userID
   categories: string[]
   categories: string[] // [1]
}
}
</syntaxhighlight>
</syntaxhighlight>
References: <ref name=":0" />


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


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


Line 548: Line 880:
====='''POST''' <code>/api/shadowBanUser</code>=====
====='''POST''' <code>/api/shadowBanUser</code>=====
Shadow banned submissions are hidden for everyone but the IP that originally submitted it. Shadow banning a user shadow bans all future submissions.
Shadow banned submissions are hidden for everyone but the IP that originally submitted it. Shadow banning a user shadow bans all future submissions.
User can be re-shadowbanned if segments were not previously hidden


'''Input''' (URL Parameters):
'''Input''' (URL Parameters):
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   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, // Local userID of VIP or Admin
   enabled: boolean, //optional, to be able to add and remove users
   enabled: boolean, // Optional, default true, enable or disable ban
   unHideOldSubmissions: boolean //optional, should all previous submissions be banned as well?
   unHideOldSubmissions: boolean, // Optional, should all previous submissions be banned as well?
  categories: string // Optional, defaults to all categories, in the format "["sponsor", "selfpromo"]" etc...
}
}
</syntaxhighlight>
</syntaxhighlight>


'''Response''':
'''Response''':
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   Nothing (status code 200)
   Nothing (status code 200)
Line 567: Line 902:


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


403: Unauthorized (You are not a VIP)
403: Unauthorized (You are not a VIP)


409: User already warned
409: Duplicate (User already shadowbanned & unHideOldSubmissions not changed)
-----
-----
====='''POST''' <code>/api/warnUser</code>=====
===== '''POST''' <code>/api/warnUser</code>=====
Temporary ban that shows a warning asking them to contact us.
Temporary ban that shows a warning asking them to contact us.


Line 579: Line 915:


'''Input''' (Request Body):
'''Input''' (Request Body):
<syntaxhighlight lang="js">  
<syntaxhighlight lang="ts"> {
{
   issuerUserID: string, // Issuer userID (Local 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
}
}
</syntaxhighlight>
</syntaxhighlight>


'''Response''':
'''Response''':
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   Nothing (status code 200)
   Nothing (status code 200)
Line 595: Line 930:


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


403: Unauthorized (You are not a VIP)
403: Unauthorized (You are not a VIP)
409: User already warned
-----
-----
====='''POST''' <code>/api/clearCache</code>=====
====='''POST''' <code>/api/clearCache</code>=====
Line 603: Line 941:


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


'''Response''':
'''Response''':
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   Cache cleared on video videoID (status code 200)
   Cache cleared on video videoID (status code 200)
Line 618: Line 956:


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


Line 623: Line 962:
-----
-----
====='''POST''' <code>/api/purgeAllSegments</code>=====
====='''POST''' <code>/api/purgeAllSegments</code>=====
Hide all segments on a video
Hide all segments on a video without affecting submitters' reputation


'''Input''' (Request Body):
'''Input''' (Request Body):
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   userID: string, // your userID
   userID: string, // Local userID
   videoID: string // video ID to hide segments of
   videoID: string,
  service: string // Service of video, defaults to YouTube
}
}
</syntaxhighlight>
</syntaxhighlight>


'''Response''':
'''Response''':
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   Nothing (status code 200)
   Nothing (status code 200)
Line 641: Line 981:


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


403: Unauthorized (You are not a VIP)
403: Unauthorized (You are not a VIP)
-----
====='''POST''' <code>/api/segmentShift</code>=====
Shift all segments on a video
'''Input''' (Request Body):
<syntaxhighlight lang="ts">
{
  videoID: string,
  userID: string, // Local userID
  startTime: float,
  endTime: float
}
</syntaxhighlight>
'''Response''':
<syntaxhighlight lang="ts">
{
  Nothing (status code 200)
}
</syntaxhighlight>
'''Error codes''':
400: Bad Request (Your inputs are wrong/impossible)
403: Unauthorized (You are not a VIP)
-----
====='''POST''' <code>/api/addUserAsTempVIP</code>=====
Add temporary 24 Hour Channel VIP
A user cannot be a VIP of multiple channels, the most recent channel will take precedence and override
'''Input''' (Request Body):
<syntaxhighlight lang="ts">
{
  userID: string, // User to grant temp VIP to
  adminUserID: string, // Local userID of existing VIP
  channelVideoID: string, // videoID of channel to grant VIP on
  enabled: string // default "true" Enable or disable VIP status
}
</syntaxhighlight>
'''Response''':
<syntaxhighlight lang="ts">
{
  Temp VIP added on channel channelName (status code 200)
  Temp VIP removed (status code 200)
}
</syntaxhighlight>
'''Error codes''':
400: Bad Request (Your inputs are wrong/impossible)
403: Unauthorized (You are not a VIP)
404: Not Found (No channel found for videoID)
409: Duplicate (User is already a permanent VIP)
-----
-----
===Admin Calls===
===Admin Calls===
Line 651: Line 1,051:


'''Input''' (Request Body):
'''Input''' (Request Body):
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   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, // Admin's local userID
   enabled: boolean //optional, to be able to add and remove users
   enabled: boolean // Optional, to be able to add and remove users
}
}
</syntaxhighlight>
</syntaxhighlight>


'''Response''':
'''Response''':
<syntaxhighlight lang="js">
<syntaxhighlight lang="ts">
{
{
   Nothing (status code 200)
   Nothing (status code 200)
Line 667: Line 1,067:


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


Line 675: Line 1,076:
===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.
=== References ===
<references />

Revision as of 02:27, 20 January 2022

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: Node.js, Python, Rust


Online Database Explorer (By Lartza): https://sb.ltn.fi/

Database Mirror (5 min update time, provided by Lartza): https://sb.ltn.fi/database/

Database Dump | Webhook Docs | OpenAPI Docs


GET /api/skipSegments

Get segments for a video.

Input (URL Parameters):

{
  videoID: string,
  
  category: string, // Optional, defaults to "sponsor", can be repeated for multiple categories. [1]
  // OR
  categories: string[], // Optional [1]

  requiredSegment: string, // Segment UUID to require to be retrieved, even if they don't meet the minimum vote threshold. Can be repeated for multiple segments.
  // OR
  requiredSegments: string[], // Optional, array of required segment UUIDs

  actionType: string // Optional, default skip. Can be repeated for multiple types. [3]
  // OR  
  actionTypes: string[] // Optional, array of action types

  service: string, // Optional, default is 'YouTube' [2]
}

References: [1] [2] [3]

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). 0 when unknown. +- 1 second
   actionType: string // actionType [3]
   userID: string, // public userID of submitter
   locked: int, // if submission is locked
   votes: int, // Votes on segment
   description: string, // unused
}]

Error codes:

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

404: Not Found


GET /api/skipSegments/:sha256HashPrefix

Get segments for a video with extra privacy

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 since the server will not know exactly what video you are looking for.

Input (URL Parameters):

{
  prefix: string, // Can be used instead of path

  category: string, // Optional, defaults to "sponsor", can be repeated for multiple categories. [1]
  // OR
  categories: string[], // Optional, array of categories [1]

  requiredSegment: string, // Segment UUID to require to be retrieved, even if they don't meet the minimum vote threshold. Can be repeated for multiple segments.
  // OR
  requiredSegments: string[], // Optional, array of required segment UUIDs

  actionType: string // Optional, default skip. Can be repeated for multiple types. [3]
  // OR  
  actionTypes: string[] // Optional, array of action types [3]

  service: string // Optional, default is 'YouTube'. [2]
}

References: [1] [2] [3]

Response

[{ // Array of this object
   videoID: string,
   hash: string, // Full hash of the videoID
   segments: [{ // Array of this object
       segment: float[], // [0, 15.23] start and end time in seconds
       UUID: string,
       category: string, [1]
       actionType: string, // [1]
       locked: int, // if segment is locked
       votes: int, // votes on segment
       videoDuration: int, // Duration of video when submissions occurred
       userID: string, // Public userID of submitter
       description: string // unused
   }]
}]

Error codes:

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

404: Not Found


POST /api/skipSegments

Create a segment on a video

Input (URL Parameters):

{
  videoID: string,
  startTime: float,
  endTime: float,
  category: string, // [1]
  userID: string, // This should be a randomly generated UUID stored locally (not the public one)
  userAgent: string, // "Name of Client/Version" or "[BOT] Name of Bot/Version" ex. "Chromium/1.0.0"
  service: string, // Optional, default is 'YouTube'. [2]
  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)
  actionType: string // Optional, default is "skip". [3]
}

References: [1] [2] [3]

OR

Input (JSON Body):

{
  videoID: string,
  userID: string, // This should be a randomly generated UUID stored locally (not the public one)
  userAgent: string, // "Name of Client/Version" or "[BOT] Name of Bot/Version" ex. "Chromium/1.0.0"
  service: string, // Optional, default is 'YouTube'.[2]
  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, // [1]
     actionType: string // Optional, defaults to "skip". [3]
  }]
}

References: [1] [2] [3]

Response:

{ // array of this object
  UUID: string, // UUID of submitted segment
  category: string, // submitted category [1]
  segment: float[] // start and end time of submitted segment
}[]

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

Vote on a segment or vote to change the category of the segment.

Creators of the segment and VIPs can remove the segment or change the category with only one vote.

VIP voting notes

VIP upvotes will:

  • lock the segment
  • remove "hidden" property
  • remove "shadowHidden" property

Input: Normal Vote (URL Parameters):

{
  UUID: string, // UUID of the segment being voted on
  userID: string, // Local userID
  type: int // 0 for downvote, 1 for upvote, 20 to undo vote
}

OR

Input: Category Vote (URL Parameters):

{
  UUID: string, // UUID of the segment being voted on
  userID: string, // Local userID
  category: string // Category to change this submission to [1]
}

References: [1]

Response:

{
  Nothing (status code 200)
}

Error codes:

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

403: Reason given in request (moderation)


POST /api/viewedVideoSponsorTime

Add view to segment

Input (URL Parameters):

{
  UUID: string // UUID of segment viewed
}

Response:

{
  Nothing (status code 200)
}

Error codes:

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


GET /api/userInfo

Get information about a user

Input (URL Parameters):

{
  userID: string // local UserID
  // OR
  publicUserID: string // Public userID

  values: string[] // Optional, Values to get from userInfo
    // default values are
    // ["userID", "userName", "minutesSaved", "segmentCount", "ignoredSegmentCount",
    // "viewCount", "ignoredViewCount", "warnings", "warningReason", "reputation",
    // "vip", "lastSegmentID"]
  // OR
  value: string // Optional, Value to get from userInfo, can be repeated for multiple values
}

Response:

{
  userID: string, // Public userID
  userName: string, // Public userID if not set
  minutesSaved: float, // Minutes saved
  segmentCount: int, // Total number of segments excluding ignored/ hidden segments
  ignoredSegmentCount: int, // Total number of ignored/ hidden segments
  viewCount: int, // Total number of views excluding view on ignored/ hidden segments
  ignoredViewCount: int, // Total number of view on ignored/ hidden segments
  warnings: int, // Currently enabled warnings
  reputation: float, 
  vip: int, // VIP status
  lastSegmentID: string // UUID of last submitted segment
}

Error codes:

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


GET /api/userStats

Get stats for a user

Input (URL Parameters):

{
  userID: string // local UserID
  // OR
  publicUserID: string // Public userID

  fetchCategoryStats: boolean // default false, display category stats
  fetchActionTypeStats: boolean // default false, display type stats
}

Response:

{
  userID: string // hashed userID
  userName: string // userName
  overallStats: {
    minutesSaved: integer // same as userInfo
    segmentCount: integer // same as userInfo
  }
  // IF CHOSEN
  categoryCount: { // # of segments per category
    sponsor: integer
    intro: integer
    outro: integer
    interaction: integer
    selfpromo: integer
    music_offtopic: integer
    preview: integer
    poi_highlight: integer
    filler: integer,
    exclusive_access: integer
  }
  // IF CHOSEN
  actionTypeCount: { // # of segments per type
    skip: integer,
    mute: integer,
    full: integer,
    poi: integer
  }
}

Error codes:

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


GET /api/getViewsForUser

Get the number of views a user has on all their segments

Input (URL Parameters):

{
  userID: string // Local userID
}

Response:

{
  viewCount: int
}

Error codes:

404: Not Found


GET /api/getSavedTimeForUser

Get the total time saved from all the user's segments

Input (URL Parameters):

{
  userID: string // Local userID
}

Response:

{
  timeSaved: float // In minutes
}

Error codes:

404: Not Found


POST /api/setUsername

Set a username for a userID

Input (URL Parameters): Setting username for self

{
  userID: string, // Local userID
  username: string, // Optional
}

OR

Input (URL Parameters): Setting username as admin

{
  userID: string, // Public userID
  username: string, // Optional
  adminUserID: string // Admin's local userID
}

Response:

{
  Nothing (status code 200)
}

Error codes:

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

403: Unauthorized (You are not an admin)


GET /api/getUsername

Get current username

Input (URL Parameters):

{
  userID: string // Local userID
}

Response:

{
  userName: string // Public userID if no username has been set
}

Error codes:

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


GET /api/segmentInfo

Get information about segments

Input (URL Parameters):

{
  // Only the first 10 entries will be processed
  UUID: string, // Can be repeated for multiple segments
  // OR
  UUIDs: string[] // Looks like ["a...0", "b...1"]
}

Response:

[{ // Array of this object
  videoID: string,
  startTime: float,
  endTime: float,
  votes: int,
  locked: int, // Status of lock - If upvoted by a VIP, the segment is locked
  UUID: string,
  userID: string, // PublicID of submitter
  timeSubmitted: int,
  views: int, // Number of reported views on the segment
  category: string, // [1]
  service: string, // [2]
  videoDuration: int,
  hidden: int, // If the segment has 2 downvotes or was downvoted by a VIP
  reputation: int, // Reputation of submitter at time of submission
  shadowHidden: int, // If the submitter is shadowbanned
  userAgent: string // userAgent of the submitter,
  actionType: string // [3]
}]

References: [1] [2] [3]

Error codes:

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

404: Not Found


GET /api/userID

List all users matching the username search

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 // searches for exact username with no wildcard at end
}

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

Get locked categories for a video

Input (URL Parameters):

{
  videoID: string,
  actionTypes: string[] // [3]
    // default [skip, mute]
}

Response:

{
  categories: string[], // [1]
  reason: string, // Specified reason for the lock
    // Only the most recent reason will be returned
  actionTypes: string[] // [3]
}

References: [1] [3]

Error codes:

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

404: Not Found


GET /api/lockCategories/:sha256HashPrefix

Get locked categories for a video with extra privacy

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 of the videoID
   categories": string[], // [1]
   reason: string // Specified reason for the lock
}]

References: [1]

Error codes:

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

404: Not Found


GET /api/lockReason

Get reason for lock(s)

Input (URL Parameters):

{
  videoID: string
  
  // Categories to get reasons for, defaults to all [1]
  category: string
  // OR
  categories: string[],
  actionTypes: string[] // [3]
}

References: [1] [3]

Response:

[{ // Array of this object
  category: string, // category [1]
  locked: integer, // status of lock
  reason: string, // reason for lock
  userID: string, // publicID of locking VIP
  userName: string // username of locking VIP
}]

Error codes:

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


GET /api/searchSegments

Get all segments of a video based on specified filters. Note: It is suggested that you don't use this for knowing which segments to skip on your client, as thresholds and values that determine which segments are the best change over time. Using /api/skipSegments ensures that you will always get the best segments.

Input (URL Parameters) OR (JSON Body):

{
  // See skipSegments
  videoID: string

  category: string // [1]
  // OR
  categories: string[]

  actionType: string // [3]
  // OR
  actionTypes: string[]
  
  service: string // [2]
  // End SkipSegments

  page: int // Page to start from (default 0)
  
  // Vote/ view thresholds, inclusive, default includes all segments
  minVotes: int
  maxVotes: int

  minViews: int
  maxViews: int

  // Default true - if false, don't show segments that match type
  locked: boolean
  hidden: boolean
  ignored: boolean // hidden or below vote threshold
}

References: [1] [2] [3]

Response:

{
  segmentCount: int, // Total number of segments matching query
  page: int, // Page number
  segments: [{ // Array of this object, max 10
    // see segmentInfo
    UUID: string,
    timeSubmitted: int,
    startTime: int,
    endTime: int,
    category: int, // [1]
    actionType: int, // [3]
    votes: int,
    views: int,
    locked: int,
    hidden: int,
    shadowHidden: int,
    userID: string, // UUID of submitter
  }]
}

References: [1] [3]

Error codes:

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

404: Not Found


GET /api/status/:value

Get status of server

Input: (URL path)

Can be any key value in response, requests without path will return all values.

Response:

{
  uptime: int, // Uptime of server in seconds
  commit: string, // Full SHA hash of latest git commit, development or test
  db: int, // Current database version
  startTime: int, // Unix time that request was received
  processTime: int, // Seconds between startTime and sending response
  loadavg: int[], // 5 and 15 minute loadavg
  statusRequests: int // number of /status requests in the last minute
}

Error codes:

404: Not Found


Stats Calls

GET /api/getTopUsers

Get top submitters

Input (URL Parameters):

{
  sortType: int
    // 0 for by minutes saved
    // 1 for by view count
    // 2 for by total submissions
}

Response:

{
  userNames: string[],
  viewCounts: int[],
  totalSubmissions: int[],
  minutesSaved: float[]
}

Error codes:

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


GET /api/getTopCategoryUsers

Get top submitters by category

Input (URL Parameters):

{
  sortType: int,
    // 0 for by minutes saved
    // 1 for by view count
    // 2 for by total submissions
  category: string // category to fetch stats for
}

Response:

{
  userNames: string[],
  viewCounts: int[],
  totalSubmissions: int[],
  minutesSaved: float[]
}

Error codes:

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


GET /api/getTotalStats

Get total stats

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

Get days saved by all skips

Input:

{
  Nothing
}

Response:

{
  daysSaved: float (2 decimal places)
}

Error codes:

None


VIP Calls

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

GET /api/isUserVIP

If the user is a VIP

Input (URL Parameters):

{
  userID: string, // Local userID
}

Response:

{
  hashedUserID: string, // Public userID
  vip: boolean
}

Error codes:

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


POST /api/lockCategories

Create a category lock on the video, disallowing further submissions for that category

Input (Request Body):

{
  videoID: string,
  userID: string, // Local userID
  categories: string[], // [1]
  reason: string // Reason for lock
}

References: [1]

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

Delete existing category locks on that video

Input (Request Body):

{
  videoID: string,
  userID: string, // Local userID
  categories: string[] // [1]
}

References: [1]

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.

User can be re-shadowbanned if segments were not previously hidden

Input (URL Parameters):

{
  userID: string, // Public userID of the user you want to shadowBan
  adminUserID: string, // Local userID of VIP or Admin
  enabled: boolean, // Optional, default true, enable or disable ban
  unHideOldSubmissions: boolean, // Optional, should all previous submissions be banned as well?
  categories: string // Optional, defaults to all categories, in the format "["sponsor", "selfpromo"]" etc...
}

Response:

{
  Nothing (status code 200)
}

Error codes:

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

403: Unauthorized (You are not a VIP)

409: Duplicate (User already shadowbanned & unHideOldSubmissions not changed)


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, // Issuer userID (Local 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)

409: User already warned


POST /api/clearCache

Clear redis cache for video.

Input (Request Body):

{
  userID: string, // Local userID
  videoID: string
}

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 without affecting submitters' reputation

Input (Request Body):

{
  userID: string, // Local userID
  videoID: string,
  service: string // Service of video, defaults to YouTube
}

Response:

{
  Nothing (status code 200)
}

Error codes:

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

403: Unauthorized (You are not a VIP)


POST /api/segmentShift

Shift all segments on a video

Input (Request Body):

{
  videoID: string,
  userID: string, // Local userID
  startTime: float,
  endTime: float
}

Response:

{
  Nothing (status code 200)
}

Error codes:

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

403: Unauthorized (You are not a VIP)


POST /api/addUserAsTempVIP

Add temporary 24 Hour Channel VIP

A user cannot be a VIP of multiple channels, the most recent channel will take precedence and override

Input (Request Body):

{
  userID: string, // User to grant temp VIP to
  adminUserID: string, // Local userID of existing VIP
  channelVideoID: string, // videoID of channel to grant VIP on
  enabled: string // default "true" Enable or disable VIP status
}

Response:

{
  Temp VIP added on channel channelName (status code 200)
  Temp VIP removed (status code 200)
}

Error codes:

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

403: Unauthorized (You are not a VIP)

404: Not Found (No channel found for videoID)

409: Duplicate (User is already a permanent 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, // Admin's local userID
  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.

References

  1. 1.00 1.01 1.02 1.03 1.04 1.05 1.06 1.07 1.08 1.09 1.10 1.11 1.12 See Types for full list of possible categories. To get multiple, create an array with the format ["sponsor", intro"].
  2. 2.0 2.1 2.2 2.3 2.4 2.5 Service to get segments for. See Types for supported services
  3. 3.0 3.1 3.2 3.3 3.4 3.5 3.6 3.7 3.8 Action Types: See Types for possible values. Select multiple with the format ["skip","mute]