mirror of
https://github.com/ajayyy/SponsorBlock.git
synced 2025-12-15 16:07:06 +03:00
Moved to mediawiki
Ajay Ramachandran
745
API-Docs.md
745
API-Docs.md
@@ -1,744 +1,3 @@
|
||||
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 :)
|
||||
[This page has been moved](https://wiki.sponsor.ajay.app/index.php/API_Docs)
|
||||
|
||||
The API and database follow [this license](https://github.com/ajayyy/SponsorBlock/wiki/Database-and-API-License) unless you have explicit permission. [Attribution Template](https://gist.github.com/ajayyy/4b27dfc66e33941a45aeaadccb51de71)
|
||||
|
||||
Public API available at https://sponsor.ajay.app.
|
||||
<br/><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
|
||||
|
||||
**Libraries**: [NPM](https://www.npmjs.com/package/sponsorblock-api)
|
||||
________________________________________________________________________________
|
||||
|
||||
Online Database Explorer (By Lartza): https://sb.ltn.fi/
|
||||
|
||||
Database Mirror (5 min update time, provided by Lartza): https://sb.ltn.fi/database.db
|
||||
|
||||
Slim Database Mirror (5 min update time, provided by Lartza): https://sb.ltn.fi/database_slim.db
|
||||
|
||||
<sub>[Database Dump](https://sponsor.ajay.app/database) | [Webhook Docs](https://github.com/ajayyy/SponsorBlock/wiki/Webhooks)</sub>
|
||||
________________________________________________________________________________
|
||||
|
||||
##### **GET** `/api/skipSegments`
|
||||
|
||||
**Input** (URL Parameters):
|
||||
```js
|
||||
{
|
||||
videoID: string,
|
||||
category: string, // Optional, defaults to "sponsor", can be repeated for multiple categories.
|
||||
// See https://github.com/ajayyy/SponsorBlock/wiki/Types#category
|
||||
categories: string[], // Optional, use this instead of "category" if you want multiple categories. Will look like ["sponsor","intro"]
|
||||
|
||||
requiredSegments: string[], // Optional, list of segment UUIDs to require be retrieved, even if they don't meet the minimum vote threshold, can be replaced with "requiredSegment" and repeated for multiple segments like category.
|
||||
|
||||
service: string // Optional, default is 'YouTube'. See https://github.com/ajayyy/SponsorBlock/wiki/Types#service
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```js
|
||||
[{ // Array of this object
|
||||
segment: float[], //[0, 15.23] start and end time in seconds
|
||||
UUID: string,
|
||||
category: string,
|
||||
videoDuration: float // Duration of video when submission occurred (to be used to determine when a submission is out of date)
|
||||
}]
|
||||
```
|
||||
|
||||
**Error codes**:
|
||||
|
||||
400: Bad Request (Your inputs are wrong/impossible)
|
||||
|
||||
404: Not Found
|
||||
__________________________________________________________________
|
||||
|
||||
##### **GET** `/api/skipSegments/:sha256HashPrefix`
|
||||
|
||||
`sha256HashPrefix` is a hash of the YouTube `videoID`. It should be the first 4 - 32 characters (4 is recommended). This provides extra privacy by potentially finding more than just the video you are looking for. This makes the server not know exactly what video you are looking for.
|
||||
|
||||
**Input** (URL Parameters):
|
||||
```js
|
||||
{
|
||||
category: string, // Optional, defaults to "sponsor", can be repeated for multiple categories.
|
||||
// See https://github.com/ajayyy/SponsorBlock/wiki/Types#category
|
||||
categories: string[], // Optional, use this instead of "category" if you want multiple categories. Will look like ["sponsor","intro"]
|
||||
|
||||
requiredSegments: string[], // Optional, list of segment UUIDs to require be retrieved, even if they don't meet the minimum vote threshold, can be replaced with "requiredSegment" and repeated for multiple segments like category.
|
||||
|
||||
service: string // Optional, default is 'YouTube'. See https://github.com/ajayyy/SponsorBlock/wiki/Types#service
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```js
|
||||
[{ // Array of this object
|
||||
"videoID": string,
|
||||
"hash": string, // The full hash
|
||||
"segments": [{ // Array of this object
|
||||
segment: float[], //[0, 15.23] start and end time in seconds
|
||||
UUID: string,
|
||||
category: string
|
||||
}]
|
||||
}]
|
||||
```
|
||||
|
||||
**Error codes**:
|
||||
|
||||
400: Bad Request (Your inputs are wrong/impossible)
|
||||
|
||||
404: Not Found
|
||||
__________________________________________________________________
|
||||
|
||||
##### **POST** `/api/skipSegments`
|
||||
|
||||
**Input Option 1 (URL Parameters)**:
|
||||
```js
|
||||
{
|
||||
videoID: string,
|
||||
startTime: float,
|
||||
endTime: float,
|
||||
category: string,
|
||||
userID: string, //This should be a randomly generated UUID stored locally (not the public one)
|
||||
userAgent: string, // "Name of Client" or "[BOT] Name of Bot"
|
||||
|
||||
service: string, // Optional, default is 'YouTube'. See https://github.com/ajayyy/SponsorBlock/wiki/Types#service
|
||||
videoDuration: float, // Optional, duration of video, will attempt to retrieve from the YouTube API if missing (to be used to determine when a submission is out of date)
|
||||
}
|
||||
```
|
||||
|
||||
**Input Option 2 (JSON Body)**:
|
||||
```js
|
||||
{
|
||||
videoID: string,
|
||||
userID: string, // This should be a randomly generated UUID stored locally (not the public one)
|
||||
userAgent: string, // "Name of Client" or "[BOT] Name of Bot"
|
||||
|
||||
service: string, // Optional, default is 'YouTube'. See https://github.com/ajayyy/SponsorBlock/wiki/Types#service
|
||||
videoDuration: float, // Optional, duration of video, will attempt to retrieve from the YouTube API if missing (to be used to determine when a submission is out of date)
|
||||
|
||||
segments: [{ // Array of this object
|
||||
segment: float[], //[0, 15.23] start and end time in seconds
|
||||
category: string
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```js
|
||||
{
|
||||
Nothing (status code 200)
|
||||
}
|
||||
```
|
||||
|
||||
**Error codes**:
|
||||
|
||||
400: Bad Request (Your inputs are wrong/impossible)
|
||||
|
||||
403: Rejected by auto moderator (Reason will be sent in the response)
|
||||
|
||||
429: Rate Limit (Too many for the same user or IP)
|
||||
|
||||
409: Duplicate
|
||||
________________________________________________________________________________
|
||||
|
||||
##### **POST** `/api/voteOnSponsorTime`
|
||||
|
||||
**Input: Normal Vote** (URL Parameters):
|
||||
```js
|
||||
{
|
||||
UUID: string, //id of the sponsor being voted on
|
||||
userID: string, //the local user id
|
||||
type: int //0 for downvote, 1 for upvote
|
||||
}
|
||||
```
|
||||
|
||||
OR
|
||||
|
||||
**Input: Category Vote** (URL Parameters):
|
||||
```js
|
||||
{
|
||||
UUID: string, //id of the sponsor being voted on
|
||||
userID: string, //the local user id
|
||||
category: string //the name of the category to change this submission to
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```js
|
||||
{
|
||||
Nothing (status code 200)
|
||||
}
|
||||
```
|
||||
|
||||
**Error codes**:
|
||||
|
||||
400: Bad Request (Your inputs are wrong/impossible)
|
||||
|
||||
403: Reason given in request (moderation)
|
||||
__________________________________________________________________
|
||||
|
||||
##### **POST** `/api/viewedVideoSponsorTime`
|
||||
|
||||
**Input** (URL Parameters):
|
||||
```js
|
||||
{
|
||||
UUID: string
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```js
|
||||
{
|
||||
Nothing (status code 200)
|
||||
}
|
||||
```
|
||||
|
||||
**Error codes**:
|
||||
|
||||
400: Bad Request (Your inputs are wrong/impossible)
|
||||
__________________________________________________________________
|
||||
|
||||
##### **GET** `/api/userInfo`
|
||||
|
||||
**Input** (URL Parameters):
|
||||
```js
|
||||
{
|
||||
userID: string //the local user id
|
||||
}
|
||||
```
|
||||
**OR**
|
||||
```js
|
||||
{
|
||||
publicUserID: string
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```js
|
||||
{
|
||||
userID: string, // the public user ID
|
||||
userName: string,
|
||||
minutesSaved: float,
|
||||
segmentCount: int,
|
||||
ignoredSegmentCount: int,
|
||||
viewCount: int,
|
||||
ignoredViewCount: int,
|
||||
warnings: int,
|
||||
reputation: float,
|
||||
vip: boolean,
|
||||
lastSegmentID: string
|
||||
}
|
||||
```
|
||||
|
||||
**Error codes**:
|
||||
|
||||
400: Bad inputs
|
||||
__________________________________________________________________
|
||||
|
||||
##### **GET** `/api/getViewsForUser`
|
||||
|
||||
**Input** (URL Parameters):
|
||||
```js
|
||||
{
|
||||
userID: string //the local user id
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```js
|
||||
{
|
||||
viewCount: int
|
||||
}
|
||||
```
|
||||
|
||||
**Error codes**:
|
||||
|
||||
404: Not Found
|
||||
__________________________________________________________________
|
||||
|
||||
##### **GET** `/api/getSavedTimeForUser`
|
||||
|
||||
**Input** (URL Parameters):
|
||||
```js
|
||||
{
|
||||
userID: string //the local user id
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```js
|
||||
{
|
||||
timeSaved: float //in minutes
|
||||
}
|
||||
```
|
||||
|
||||
**Error codes**:
|
||||
|
||||
404: Not Found
|
||||
__________________________________________________________________
|
||||
|
||||
##### **POST** `/api/setUsername`
|
||||
|
||||
**Input** (URL Parameters):
|
||||
```js
|
||||
{
|
||||
userID: string, //local user id normally, public user id if adminUserID is specified
|
||||
username: string,
|
||||
//optional
|
||||
adminUserID: string //This is if you want to change someone elses username from the admin account
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```js
|
||||
{
|
||||
Nothing (status code 200)
|
||||
}
|
||||
```
|
||||
|
||||
**Error codes**:
|
||||
|
||||
400: Bad Request (Your inputs are wrong/impossible)
|
||||
__________________________________________________________________
|
||||
|
||||
##### **GET** `/api/getUsername`
|
||||
|
||||
**Input** (URL Parameters):
|
||||
```js
|
||||
{
|
||||
userID: string //the local user id
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```js
|
||||
{
|
||||
userName: string //will send back hashed userID if no username has been set
|
||||
}
|
||||
```
|
||||
|
||||
**Error codes**:
|
||||
|
||||
400: Bad Request (Your inputs are wrong/impossible)
|
||||
__________________________________________________________________
|
||||
|
||||
### Stats Calls
|
||||
|
||||
##### **GET** `/api/getTopUsers`
|
||||
|
||||
**Input** (URL Parameters):
|
||||
```js
|
||||
{
|
||||
sortType: int //0 for by minutes saved, 1 for by view count, 2 for by total submissions
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```js
|
||||
{
|
||||
userNames: array [string],
|
||||
viewCounts: array [int],
|
||||
totalSubmissions: array [int],
|
||||
minutesSaved: array [float]
|
||||
}
|
||||
```
|
||||
|
||||
**Error codes**:
|
||||
|
||||
400: Bad Request (Your inputs are wrong/impossible)
|
||||
__________________________________________________________________
|
||||
|
||||
##### **GET** `/api/getTotalStats`
|
||||
|
||||
**Input** (URL Parameters):
|
||||
```js
|
||||
{
|
||||
"countContributingUsers": boolean //Optional, default false
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```js
|
||||
{
|
||||
userCount: int, // Only if countContributingUsers was true
|
||||
activeUsers: int, // Sum of public install stats from Chrome webstore and Firefox addons store
|
||||
apiUsers: int, // 48-hour active API users (https://github.com/ajayyy/PrivacyUserCount)
|
||||
viewCount: int,
|
||||
totalSubmissions: int,
|
||||
minutesSaved: float
|
||||
}
|
||||
```
|
||||
|
||||
**Error codes**:
|
||||
|
||||
None
|
||||
__________________________________________________________________
|
||||
|
||||
##### **GET** `/api/getDaysSavedFormatted`
|
||||
|
||||
**Input**:
|
||||
```js
|
||||
{
|
||||
Nothing
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```js
|
||||
{
|
||||
daysSaved: float (2 decimal places)
|
||||
}
|
||||
```
|
||||
|
||||
**Error codes**:
|
||||
|
||||
None
|
||||
__________________________________________________________________
|
||||
|
||||
##### **GET** `/api/segmentInfo`
|
||||
|
||||
**Input** (URL Parameters):
|
||||
```js
|
||||
{
|
||||
UUID: string, // Can be used instead of UUIDs, can be repeated to fetch multiple segments
|
||||
UUIDs: string[] // Can be used instead of UUID. Maximum 10 entries. Will look like ["a...0", "b...1"]
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```js
|
||||
[{ // Array of this object
|
||||
videoID: string,
|
||||
startTime: float,
|
||||
endTime: fload,
|
||||
votes: int,
|
||||
locked: int,
|
||||
UUID: string,
|
||||
userID: string,
|
||||
timeSubmitted: int,
|
||||
views: int,
|
||||
category: string,
|
||||
service: string,
|
||||
videoDuration: int,
|
||||
hidden: int,
|
||||
reputation: int,
|
||||
shadowHidden: int
|
||||
}]
|
||||
```
|
||||
|
||||
**Error codes**:
|
||||
|
||||
400: Bad Request (Your inputs are wrong/impossible)
|
||||
|
||||
404: Not Found
|
||||
__________________________________________________________________
|
||||
|
||||
##### **GET** `/api/userID`
|
||||
|
||||
**Input** (URL Parameters):
|
||||
```js
|
||||
{
|
||||
username: string, // search string for username
|
||||
// case sensitive
|
||||
// minimum for non-exact search is 3 characters, maximum is 64 characters
|
||||
exact: Boolean // if explicitly set to true, searches for exact username
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```js
|
||||
[{ // Array of this object - maximum 10 results
|
||||
userName: string,
|
||||
userID: string
|
||||
}]
|
||||
```
|
||||
|
||||
**Error codes**:
|
||||
|
||||
400: Bad Request (Your inputs are wrong/impossible) or exceed the character limits
|
||||
|
||||
404: Not Found
|
||||
________________________________________________________________________________
|
||||
|
||||
##### **GET** `/api/lockCategories`
|
||||
|
||||
**Input** (URL Parameters):
|
||||
```js
|
||||
{
|
||||
videoID: string
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```js
|
||||
{
|
||||
"categories": string[],
|
||||
// See https://github.com/ajayyy/SponsorBlock/wiki/Types#category
|
||||
"reason": string
|
||||
}
|
||||
```
|
||||
|
||||
**Error codes**:
|
||||
|
||||
400: Bad Request (Your inputs are wrong/impossible)
|
||||
|
||||
404: Not Found
|
||||
__________________________________________________________________
|
||||
|
||||
##### **GET** `/api/lockCategories/:sha256HashPrefix`
|
||||
|
||||
`sha256HashPrefix` is a hash of the YouTube `videoID`. It should be the first 4 - 32 characters (4 is recommended). This provides extra privacy by potentially finding more than just the video you are looking for. This makes the server not know exactly what video you are looking for.
|
||||
|
||||
**Input** (URL Parameters):
|
||||
```js
|
||||
{
|
||||
"prefix": sha256HashPrefix // optional if not sent through path
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```js
|
||||
[{ // Array of this object
|
||||
"videoID": string,
|
||||
"hash": string, // The full hash
|
||||
"categories": string[],
|
||||
// See https://github.com/ajayyy/SponsorBlock/wiki/Types#category
|
||||
"reason": string
|
||||
}]
|
||||
```
|
||||
|
||||
**Error codes**:
|
||||
|
||||
400: Bad Request (Your inputs are wrong/impossible)
|
||||
|
||||
404: Not Found
|
||||
__________________________________________________________________
|
||||
|
||||
### VIP Calls
|
||||
|
||||
These can only be called by the users added to the VIP table.
|
||||
|
||||
##### **GET** `/api/isUserVIP`
|
||||
|
||||
**Input** (URL Parameters):
|
||||
```js
|
||||
{
|
||||
userID: string, // private userID
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```js
|
||||
{
|
||||
hashedUserID: string,
|
||||
vip: boolean
|
||||
}
|
||||
```
|
||||
|
||||
**Error codes**:
|
||||
|
||||
400: Bad Request (Your inputs are wrong/impossible)
|
||||
__________________________________________________________________
|
||||
|
||||
##### **POST** `/api/lockCategories` (`/api/noSegments` deprecated)
|
||||
|
||||
Will block new segment submissions of the specified category on that video.
|
||||
|
||||
**Input** (Request Body):
|
||||
```js
|
||||
{
|
||||
videoID: string,
|
||||
userID: string,
|
||||
categories: string[],
|
||||
reason: string
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```js
|
||||
{
|
||||
Nothing (status code 200)
|
||||
}
|
||||
```
|
||||
|
||||
**Error codes**:
|
||||
|
||||
400: Bad Request (Your inputs are wrong/impossible)
|
||||
|
||||
403: Unauthorized (You are not a VIP)
|
||||
__________________________________________________________________
|
||||
|
||||
##### **DELETE** `/api/lockCategories` (`/api/noSegments` deprecated)
|
||||
|
||||
Will block new segment submissions of the specified category on that video.
|
||||
|
||||
**Input** (Request Body):
|
||||
```js
|
||||
{
|
||||
videoID: string,
|
||||
userID: string,
|
||||
categories: string[]
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```js
|
||||
{
|
||||
message: "Removed lock categories entrys for video {videoID}"
|
||||
}
|
||||
```
|
||||
|
||||
**Error codes**:
|
||||
|
||||
400: Bad Request (Your inputs are wrong/impossible)
|
||||
|
||||
403: Unauthorized (You are not a VIP)
|
||||
__________________________________________________________________
|
||||
|
||||
##### **POST** `/api/shadowBanUser`
|
||||
|
||||
Shadow banned submissions are hidden for everyone but the IP that originally submitted it. Shadow banning a user shadow bans all future submissions.
|
||||
|
||||
**Input** (URL Parameters):
|
||||
```js
|
||||
{
|
||||
userID: string, //public userID of the user you want to shadowBan
|
||||
adminUserID: string, //your userID as an admin
|
||||
enabled: boolean, //optional, to be able to add and remove users
|
||||
unHideOldSubmissions: boolean //optional, should all previous submissions be banned as well?
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```js
|
||||
{
|
||||
Nothing (status code 200)
|
||||
}
|
||||
```
|
||||
|
||||
**Error codes**:
|
||||
|
||||
400: Bad Request (Your inputs are wrong/impossible)
|
||||
|
||||
403: Unauthorized (You are not a VIP)
|
||||
__________________________________________________________________
|
||||
|
||||
##### **POST** `/api/warnUser`
|
||||
|
||||
Temporary ban that shows a warning asking them to contact us.
|
||||
|
||||
**Input** (Request Body):
|
||||
```js
|
||||
{
|
||||
issuerUserID: string, // your userID
|
||||
userID: string, // public userID you are warning
|
||||
enabled: boolean //optional, default true
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```js
|
||||
{
|
||||
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):
|
||||
```js
|
||||
{
|
||||
userID: string, // your userID
|
||||
videoID: string // video ID to clear cache of
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```js
|
||||
{
|
||||
Cache cleared on video videoID (status code 200)
|
||||
}
|
||||
```
|
||||
|
||||
**Error codes**:
|
||||
|
||||
400: Bad Request (Your inputs are wrong/impossible)
|
||||
|
||||
403: Unauthorized (You are not a VIP)
|
||||
__________________________________________________________________
|
||||
|
||||
##### **POST** `/api/purgeAllSegments`
|
||||
|
||||
Hide all segments on a video
|
||||
|
||||
**Input** (Request Body):
|
||||
```js
|
||||
{
|
||||
userID: string, // your userID
|
||||
videoID: string // video ID to hide segments of
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```js
|
||||
{
|
||||
Nothing (status code 200)
|
||||
}
|
||||
```
|
||||
|
||||
**Error codes**:
|
||||
|
||||
400: Bad Request (Your inputs are wrong/impossible)
|
||||
|
||||
403: Unauthorized (You are not a VIP)
|
||||
__________________________________________________________________
|
||||
|
||||
### Admin Calls
|
||||
|
||||
These can only be called by the server administrator, set in the config.
|
||||
|
||||
##### **POST** `/api/addUserAsVIP`
|
||||
|
||||
VIPs have extra privileges and their votes count more.
|
||||
|
||||
**Input** (Request Body):
|
||||
```js
|
||||
{
|
||||
userID: string, //public userID of the user you want to add to the VIP list
|
||||
adminUserID: string, //your userID as an admin
|
||||
enabled: boolean //optional, to be able to add and remove users
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```js
|
||||
{
|
||||
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.
|
||||
https://wiki.sponsor.ajay.app/index.php/API_Docs
|
||||
Reference in New Issue
Block a user