SponsorBlock - User contributions [en-ca]

API Docs

2023-06-16T02:17:58Z

Grub: Bad apostrophe.

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 [https://github.com/ajayyy/SponsorBlock/wiki/Database-and-API-License this license] unless you have explicit permission. [https://gist.github.com/ajayyy/4b27dfc66e33941a45aeaadccb51de71 Attribution Template]

Public API available at https://sponsor.ajay.app.

<sub>While this is a free unlimited use API, please don't abuse it. I have limited resources.</sub>

Database download: https://sponsor.ajay.app/database

If you are looking for DeArrow API Docs, see [[API Docs/DeArrow|its page]].

'''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], [https://github.com/porjo/sponsorblockgo Go]
-----Online Database Explorer (By Lartza): https://sb.ltn.fi/

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

Database Mirror (10 min update time, provided by blab): https://mirror.sb.mchang.xyz/

Database Mirror (2 hr update time, provided by mini_bomba): https://sb.minibomba.pro/mirror/

<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 segments for a video.

'''Input''' (URL Parameters):
<syntaxhighlight lang="ts">
{
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]
}
</syntaxhighlight>

References: <ref name=":0">See [[Types#Category|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 [[Types#Service|Types]] for supported services</ref> <ref name=":2">Action Types: See [[Types#Action Type|Types]] for possible values. Select multiple with the format <code>["skip","mute]</code></ref>

'''Response''':
<syntaxhighlight lang="ts">
[{ // Array of this object
segment: float[], //[0, 15.23] start and end time in seconds
UUID: string,
category: string, // [1]
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, // [3]
locked: int, // if submission is locked
votes: int, // Votes on segment
description: string, // title for chapters, empty string for other segments
}]
</syntaxhighlight>

'''Error codes''':

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

404: Not Found
-----

====='''GET''' <code>/api/skipSegments/:sha256HashPrefix</code>=====
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):
<syntaxhighlight lang="ts">
{
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]
}
</syntaxhighlight>

References: <ref name=":0" /> <ref name=":1" /> <ref name=":2" />

'''Response'''
<syntaxhighlight lang="ts">
[{ // Array of this object
videoID: string,
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
description: string // title for chapters, empty string for other segments
}]
}]
</syntaxhighlight>
'''Error codes''':

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

404: Not Found
-----

====='''POST''' <code>/api/skipSegments</code>=====
Create a segment on a video

'''Input''' (URL Parameters):
<syntaxhighlight lang="ts">
{
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]
description: string // Chapter title for chapters, must be an empty string or not present for other segment types
}
</syntaxhighlight>

References: <ref name=":0" /> <ref name=":1" /> <ref name=":2" />

'''OR'''

'''Input''' (JSON Body):
<syntaxhighlight lang="ts">
{
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]
description: string // Chapter title for chapters, must be an empty string or not present for other segment types
}]
}
</syntaxhighlight>

References: <ref name=":0" /> <ref name=":1" /> <ref name=":2" />

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

'''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''' <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):
<syntaxhighlight lang="ts">
{
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
}
</syntaxhighlight>

'''OR'''

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

References: <ref name=":0" />

'''Response''':
<syntaxhighlight lang="ts">
{
Nothing (status code 200)
}
</syntaxhighlight>

'''Error codes''':

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

403: Reason given in request (moderation)
-----

====='''POST''' <code>/api/viewedVideoSponsorTime</code>=====
Add view to segment

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

'''Response''':
<syntaxhighlight lang="ts">
{
Nothing (status code 200)
}
</syntaxhighlight>

'''Error codes''':

400: Bad Request (Your inputs are wrong/impossible)
-----
====='''GET''' <code>/api/userInfo</code>=====
Get information about a user

'''Input''' (URL Parameters):
<syntaxhighlight lang="ts">
{
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>
'''Response''':
<syntaxhighlight lang="ts">
{
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
permissions: { // Can the user submit segments of this category?
category: boolean // [1]
}
}
</syntaxhighlight>

References: <ref name=":0" />

'''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''':
<syntaxhighlight lang="ts">
{
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,
chapter: integer
}
// IF CHOSEN
actionTypeCount: { // # of segments per type
skip: integer,
mute: integer,
full: integer,
poi: integer,
chapter: integer
}
}
</syntaxhighlight>

'''Error codes''':

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

====='''GET''' <code>/api/getViewsForUser</code>=====
Get the number of views a user has on all their segments

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

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

'''Error codes''':

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

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

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

'''Error codes''':

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

'''Input''' (URL Parameters): Setting username for self
<syntaxhighlight lang="ts">
{
userID: string, // Local userID
username: string, // Optional
}
</syntaxhighlight>

'''OR'''

'''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)
}
</syntaxhighlight>

'''Error codes''':

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

403: Unauthorized (You are not an admin)
-----
====='''GET''' <code>/api/getUsername</code>=====
Get current username

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

'''Response''':
<syntaxhighlight lang="ts">
{
userName: string // Public userID if no username has been set
}
</syntaxhighlight>

'''Error codes''':

400: Bad Request (Your inputs are wrong/impossible)
-----
====='''GET''' <code>/api/segmentInfo</code>=====
Get information about segments

'''Input''' (URL Parameters):
<syntaxhighlight lang="ts">
{
// 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>

'''Response''':
<syntaxhighlight lang="ts">
[{ // 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]
actionType: string, // [3]
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
hashedVideoID: string, // sha256 hash of the videoID
userAgent: string, // userAgent of the submitter,
description: string // title for chapters, empty string for other segments
}]
</syntaxhighlight>

References: <ref name=":0" /> <ref name=":1" /> <ref name=":2" />

'''Error codes''':

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

404: Not Found
-----

====='''GET''' <code>/api/userID</code>=====
List all users matching the username search

'''Input''' (URL Parameters):
<syntaxhighlight lang="ts">
{
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>

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

'''Error codes''':

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

404: Not Found
-----
====='''GET''' <code>/api/lockCategories</code>=====
Get locked categories for a video

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

'''Response''':
<syntaxhighlight lang="ts">
{
categories: string[], // [1]
reason: string, // Specified reason for the lock
// Only the most recent reason will be returned
actionTypes: string[] // [3]
}
</syntaxhighlight>

References: <ref name=":0" /> <ref name=":2" />

'''Error codes''':

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

404: Not Found
-----
====='''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):
<syntaxhighlight lang="ts">
{
prefix: sha256HashPrefix // Optional if not sent through path
}
</syntaxhighlight>

'''Response''':
<syntaxhighlight lang="ts">
[{ // Array of this object
videoID: string,
hash: string, // The full hash of the videoID
categories": string[], // [1]
reason: string // Specified reason for the lock
}]
</syntaxhighlight>

References: <ref name=":0" />

'''Error codes''':

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

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

'''Input''' (URL Parameters):
<syntaxhighlight lang="ts">
{
videoID: string

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

References: <ref name=":0" /> <ref name=":2" />

'''Response''':
<syntaxhighlight lang="ts">
[{ // 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
}]
</syntaxhighlight>

'''Error codes''':

400: Bad Request (Your inputs are wrong/impossible)
-----
====='''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) '''OR''' (JSON Body):
<syntaxhighlight lang="ts">
{
// 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
}
</syntaxhighlight>

References: <ref name=":0" /> <ref name=":1" /> <ref name=":2" />

'''Response''':
<syntaxhighlight lang="ts">
{
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: string, // [1]
actionType: string, // [3]
votes: int,
views: int,
locked: int,
hidden: int,
shadowHidden: int,
userID: string, // UUID of submitter
description: string // title for chapters, empty string for other segments
}]
}
</syntaxhighlight>

References: <ref name=":0" /> <ref name=":2" />

'''Error codes''':

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 (miliseconds) that request was received
processTime: int, // Delay between DB request made and response received (miliseconds)
redisProcessTime: int, // Delay between redis request made and response received (miliseconds)
loadavg: int[], // 5 and 15 minute loadavg
statusRequests: int, // number of /status requests in the last minute
hostname: string // hostname of current server
}
</syntaxhighlight>

'''Error codes''':

404: Not Found
-----

===Stats Calls===
====='''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):
<syntaxhighlight lang="ts">
{
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>

'''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/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>

'''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===
These can only be called by the users added to the VIP table.
====='''GET''' <code>/api/isUserVIP</code>=====
If the user is a VIP

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

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

'''Error codes''':

400: Bad Request (Your inputs are wrong/impossible)
-----
====='''POST''' <code>/api/lockCategories</code>=====
Create a category lock on the video, disallowing further submissions for that category

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

References: <ref name=":0" /> <ref name=":2" />

'''Response''':
<syntaxhighlight lang="ts">
{
submitted: string[], // categories [1]
submittedValues: {
actionType: string, // [3]
category: string // [1]
} // array of this object
}
</syntaxhighlight>

References: <ref name=":0" /> <ref name=":2" />

'''Error codes''':

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

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

===== '''DELETE''' <code>/api/lockCategories</code>=====
Delete existing category locks on that video

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

References: <ref name=":0" />

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

'''Error codes''':

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

403: Unauthorized (You are not a VIP)
-----
====='''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.

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

'''Input''' (URL Parameters):
<syntaxhighlight lang="ts">
{
userID: string, // Public userID of the user you want to shadowBan
adminUserID: string, // Local userID of VIP or Admin
enabled: boolean, // Optional, default true, true to ban and false to unban
unHideOldSubmissions: boolean, // Optional, depends on the enabled parameter, should all previous submissions be (un)hidden as well?
categories: string // Optional, defaults to all categories, in the format "["sponsor", "selfpromo"]" etc...
}
</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)

409: Duplicate (User already shadowbanned & unHideOldSubmissions not changed)
-----
===== '''POST''' <code>/api/warnUser</code>=====
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):
<syntaxhighlight lang="ts"> {
issuerUserID: string, // Issuer userID (Local userID)
userID: string, // Public userID you are warning
reason: string, // Optional
enabled: boolean // Optional, default true
}
</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)

409: User already warned
-----

====='''POST''' <code>/api/clearCache</code>=====
Clear redis cache for video.

'''Input''' (Request Body):
<syntaxhighlight lang="ts">
{
userID: string, // Local userID
videoID: string
}
</syntaxhighlight>

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

'''Error codes''':

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

403: Unauthorized (You are not a VIP)
-----
====='''POST''' <code>/api/purgeAllSegments</code>=====
Hide all segments on a video without affecting submitters' reputation

'''Input''' (Request Body):
<syntaxhighlight lang="ts">
{
userID: string, // Local userID
videoID: string,
service: string // Service of video, defaults to YouTube
}
</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/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''' (URL Parameters):
<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)
-----

====='''POST''' <code>/api/feature</code>=====
Add or remove user features

'''Input''' (Request Body):
<syntaxhighlight lang="ts">
{
userID: string, // User to add or remove features from
adminUserID: string, // Local userID of existing VIP
feature: int, // [4]
enabled: boolean // default "true" Enable or disable feature
}
</syntaxhighlight>

References: <ref name=":4">See [[Types#User_Features|Types]] for a full list of possible user features.</ref>

'''Response''':
<syntaxhighlight lang="ts">
{
Nothing (status code 200)
}
</syntaxhighlight>

'''Error codes''':

400: Bad Request (Your inputs are wrong/impossible or the feature does not exist)

403: Unauthorized (You are not a VIP)
-----
===Admin Calls===
These can only be called by the server administrator, set in the config.
====='''POST''' <code>/api/addUserAsVIP</code>=====
VIPs have extra privileges and their votes count more.

'''Input''' (URL Parameters):
<syntaxhighlight lang="ts">
{
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 (default: false)
}
</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 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 ===
<references />
__INDEX__
__NEWSECTIONLINK__

Full Video Labels

2022-01-16T03:41:59Z

Grub: seperated -> separated

'''''Full video labels should not be used on every video or channel which is sponsored.'''''

The label should only be applied if the entire video is based around or features the product and removing mentions would remove the majority of the video.

Even when a video is labelled as such, the parts that '''can be cleanly skipped''' should still be skipped but the disclosure should still be left intact.

=== Sponsor ===
This label should only be used when the creator has been '''paid in money''' to advertise something shown in the video that cannot be completely removed by cuts.

This should not be used when a creator is given a free product from a company

=== Exclusive Access ===
This label should only be used when the creator showcases a product, service or location that they've received free or subsidised access to in the video that cannot be completely removed by cuts.

=== Unpaid/Self Promotion ===
This follows the same rules as [[Unpaid/Self Promotion]]

This should not be used when a creator is given a free product from a company.

https://blog.ajay.app/full-video-sponsorblock

=== Examples ===
{| class="wikitable"
|+
!Description
!Video Link
|-
! colspan="2" |Sponsor
|-
|Sponsored showcase
|[https://www.youtube.com/watch?v=R3iNAQqqnjE Never Do Tech Support For Your Family Again! - Acronis Friday Showcase]
|-
|Sponsored showcase
|[https://www.youtube.com/watch?v=wBfNE5fi5BE Sponsors Aren't SAFE! - NZXT Capsule Microphone]
|-
! colspan="2" |Exclusive Access
|-
|Exclusive access to product under embargo
|[https://www.youtube.com/watch?v=V7DnNoAnbDc <nowiki>They FINALLY Made a PERFECT CAMERA [DJi RONIN 4D]</nowiki>]
|-
|Exclusive access to facility
|[https://www.youtube.com/watch?v=ssZ_8cqfBlE How many robots does it take to run a grocery store?]
|-
|Exclusive access to product under embargo
|[https://www.youtube.com/watch?v=UMBLCv54JPw Intel i5 12600K Review vs. AMD Ryzen - 10 Cores?!]
|-
|Early access to press copy
|[https://www.youtube.com/watch?v=SQ3Qvuw_fg4 The Far Cry 6 Story Was SHOCKINGLY Great!]
|-
! colspan="2" |Unpaid/Self Promotion
|-
|Entire video is selfpromo for merch & can't be separated
|[https://www.youtube.com/watch?v=YMJJZoiFeCY national berd day]
|-
|Entire video is trailer
|[https://www.youtube.com/watch?v=a1x2wn7vcho Achievement Hunter Wrestling | [https://www.youtube.com/watch?v=a1x2wn7vcho Achievement Hunter Wrestling | Official Trailer]
|-
|Entire video is for fundraiser & can't be separated
|[https://www.youtube.com/watch?v=HPJKxAhLw5I Planting 20,000,000 Trees, My Biggest Project Ever!]
|}

Highlight

2021-11-07T04:28:25Z

Grub: /* Specifics */

__FORCETOC__
=== Description ===
This is for getting to the point or highlight of the video.

=== Specifics ===
Highlights are not "chapters", only one highlight is displayed per video. [https://github.com/ajayyy/SponsorBlock/issues/409 Chapters Proposal]

Highlights will only jump to a point in the video, hence the start and end time is identical.

Highlight doesn't label the content before it, it labels the content ''after'' it.

==== Uses (In order of priority)[https://blog.ajay.app/highlight-sponsorblock] ====

# Skipping to the point/most important part of the video
# Skipping to the part of the video referred to by the title
# Skipping to the part of the video referred to by the thumbnail
# Skipping to the part of the video referenced from a preview/teaser at the start of the video

Highlight

2021-11-07T04:22:14Z

Grub: /* Had some good discussion in channel and clarification from Ajay https://discord.com/channels/603643120093233162/609441389423493128/906758072272302101 */

__FORCETOC__
=== Description ===
This is for getting to the point or highlight of the video.

=== Specifics ===
Highlights are not "chapters", only one highlight is displayed per video. [https://github.com/ajayyy/SponsorBlock/issues/409 Chapters Proposal]

Highlights will only jump to a point in the video, hence the start and end time is identical.

Highlight doesn't label the content before it, it labels the content ''after'' it. If other segment types exist in what would be labelled Highlight, include them in the Highlight segment. Do not tag them separately.

==== Uses (In order of priority)[https://blog.ajay.app/highlight-sponsorblock] ====

# Skipping to the point/most important part of the video
# Skipping to the part of the video referred to by the title
# Skipping to the part of the video referred to by the thumbnail
# Skipping to the part of the video referenced from a preview/teaser at the start of the video

Unpaid/Self Promotion

2021-09-02T23:53:17Z

Grub: added giveaways

Similar to "sponsor" except for unpaid or self promotion. This includes sections about merchandise, donations, giveaways, or information about who they collaborated with.