Skip to content

API Docs

Ajay Ramachandran edited this page Feb 11, 2020 · 7 revisions

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

NOTICE: The API has now been moved to https://api.sponsor.ajay.app from https://sponsor.ajay.app.

Public API available at https://api.sponsor.ajay.app.
While this is a free unlimited use API, please don't abuse it. I have limited resources.

The API follows the same license as the public database unless you have explicit permission.


GET /api/getVideoSponsorTimes

Input:

{
  videoID: string
}

Response:

{
  sponsorTimes: array [float],
  UUIDs: array [string] //The ID for this sponsor time, used to submit votes
}

Error codes:

404: Not Found


GET /api/postVideoSponsorTimes

Input:

{
  videoID: string,
  startTime: float,
  endTime: float,
  userID: string //This should be a randomly generated UUID stored locally (not the public one)
}

Response:

{
  Nothing (status code 200)
}

Error codes:

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

429: Rate Limit (Too many for the same user or IP)

409: Duplicate


POST or GET (legacy) /api/voteOnSponsorTime

Input:

{
  UUID: string, //id of the sponsor being voted on
  userID: string, //the local user id
  type: int //0 for downvote, 1 for upvote
}

Response:

{
  Nothing (status code 200)
}

Error codes:

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

405: Duplicate


POST or GET (legacy) /api/viewedVideoSponsorTime

Input:

{
  UUID: string
}

Response:

{
  Nothing (status code 200)
}

Error codes:

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


GET /api/getViewsForUser

Input:

{
  userID: string //the local user id
}

Response:

{
  viewCount: int
}

Error codes:

404: Not Found


GET /api/getSavedTimeForUser

Input:

{
  userID: string //the local user id
}

Response:

{
  timeSaved: float //in minutes
}

Error codes:

404: Not Found


POST /api/setUsername

Input:

{
  userID: string, //local user id normally, public user id if adminUserID is specified
  userName: string,
  //optional
  adminUserID: string //This is if you want to change someone elses username from the admin account
}

Response:

{
  Nothing (status code 200)
}

Error codes:

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


GET /api/getUsername

Input:

{
  userID: string //the local user id
}

Response:

{
  userName: string //will send back hashed userID if no username has been set
}

Error codes:

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


Stats Calls

GET /api/getTopUsers

Input:

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

Response:

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

Error codes:

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


GET /api/getTotalStats

Input:

{
  Nothing
}

Response:

{
  userCount: int,
  viewCount: int,
  totalSubmissions: int,
  minutesSaved: float
}

Error codes:

None


GET /api/getDaysSavedFormatted

Input:

{
  Nothing
}

Response:

{
  daysSaved: float (2 decimal places)
}

Error codes:

None


Admin Calls

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

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:

{
  userID: string, //public userID of the user you want to shadowBan
  adminUserID: string, //your userID as an admin
  enabled: boolean, //optional, to be able to add and remove users
  unHideOldSubmissions: boolean //optional, should all previous submissions be banned as well?
}

Response:

{
  Nothing (status code 200)
}

Error codes:

400: Bad Request (Your inputs are wrong/impossible) 403: Unauthorized (You are not an admin)


POST /api/addUserAsVIP

VIPs have extra privileges and their votes count more.

Input:

{
  userID: string, //public userID of the user you want to add to the VIP list
  adminUserID: string, //your userID as an admin
  enabled: boolean //optional, to be able to add and remove users
}

Response:

{
  Nothing (status code 200)
}

Error codes:

400: Bad Request (Your inputs are wrong/impossible) 403: Unauthorized (You are not an admin)

Local userID vs Public userID

The local userID should be a randomly generated and saved client side. It is used to submit and vote. The public userID is what is used as an identifier in the database. This is the local userID with a SHA 256 hash 5000 times.

Clone this wiki locally
You can’t perform that action at this time.