Help Documentation: API

Introduction

The API is free to use and should cover all the information that you will need. You must only use the endpoints documented below. If you need data that is not available from documentated endpoints, please request an official endpoint via GitHub rather than using something undocumented.


The base URL is https://purple.plus/api/ - though the full URL is shown for all endpoints below.


Please be respectful to the API and only make as many requests as you need to.

Users

Get Users

Gets basic information about users, in order of Twoos balance.

URL

GET https://purple.plus/api/users

Optional Parameters

offset Integer Value Must Be Greater Than and Including 1. Default: 0. The number of users to offset the list by.
limit Integer Value Must Be Between 1 and 100. Default: 25. The number of users to return.

Result Status Codes

200 Success The users were successfully found and returned.

Example Response


  {
    "status": 200,
    "message": "OK",
    "description": "Match Found",
    "users": [
      {
        "twitch_id": "58839314",
        "twitch": {
        "id": "58839314",
        "name": "Ethicmeta",
        "username": "ethicmeta"
        },
        "reddit": {
          "id": "u3fd1",
          "name": "EthicMeta",
          "username": "ethicmeta"
        },
        "discord": {
          "id": "239568354791129088",
          "name": "Ethic",
          "discriminator": "4210"
        },
        "balance": 148.5,
        "last_login": 1499597392506
      },
      {
        "twitch_id": "21427184",
        "twitch": {
          "id": "21427184",
          "name": "Zcotticus",
          "username": "zcotticus"
        },
        "reddit": {
          "id": "hp2pu",
          "name": "Zcotticus",
          "username": "zcotticus"
        },
        "discord": {
          "id": "99655085218336768",
          "name": "Zcotticus",
          "discriminator": "2105"
        },
        "balance": 94.65,
        "last_login": 1499597392506
      }
      ...
    ]
  },
            

Get User

Gets basic information about a user, including their linked accounts, Twoos balance and last login date.

URL

GET https://purple.plus/api/users/:id :id is the user's Twitch ID.

Optional Parameters
None.

Result Status Codes

200 Success The user was successfully found and returned.
404 Not Found The user was not found.

Example Response
Return data for user with Twitch ID 121219640.


  {
    "status": 200,
    "message": "OK",
    "description": "Match Found",
    "twitch_id": "121219640",
    "twitch": {
      "id": "121219640",
      "name": "TwitchSubreddit",
      "username": "twitchsubreddit"
    },
    "reddit": {
      "id": "171e0s",
      "name": "TwitchSubreddit",
      "username": "twitchsubreddit"
    },
    "discord": {
      "id": "319140751802105859",
      "name": "Purple+",
      "discriminator": "8815"
    },
    "balance": 87,
    "last_login": 1504113369348
  }
            

Get User Types

Gets the account types for the user. This includes the /r/Twitch subreddit, Twitch and Purple+.

URL

GET https://purple.plus/api/users/:id/types :id is the user's Twitch ID.

Optional Parameters
None.

Result Status Codes

200 Success The user was successfully found and returned.
404 Not Found The user was not found.

Example Response
Return data for user with Twitch ID 121219640.


  {
    "status": 200,
    "message": "OK",
    "description": "Match Found",
    "twitch_id": "121219640",
    "site_type": "user",
    "subreddit_type": "user",
    "profile_type": "other"
  }
            

Get User Profile

Gets the profile for the user. This includes their profile overview, types, social media, communities, etc.

URL

GET https://purple.plus/api/users/:id/profile :id is the user's Twitch ID.

Optional Parameters
None.

Result Status Codes

200 Success The user was successfully found and returned.
204 No Content The user was successfully found, but has no profile.
206 Partial Content The user was successfully found, but has a profile that is not approved.
404 Not Found The user was not found.

Example Response
Return data for user with Twitch ID 121219640.


  {
    "status": 200,
    "message": "OK",
    "description": "Match Found.",
    "twitch_id": "121219640",
    "approval_status": "approved",
    "created_at": 1504112217973,
    "updated_at": 1504112376502,
    "overview": {
      "introduction": "I'm a subreddit designed to bring the Twitch Community together through positive discussions!",
      "about": "I was a banned subreddit, but was rescued and reformed in 2013. Since then, I have grown to have over 200,000 subscribers. I also have a companion site, Purple+, which handles advertisements for streams and third party services! :PogChamp:",
      "background": "I currently hold tech support questions for the most part. However, I now also [allow clips to be posted](https://redd.it/6w0dud) in order to encourage positive content. I also am a place for hosting community events and AMAs! "
    },
    "types": {
      "other": "Subreddits don't have a role on this site. :FeelsBadMan:"
    },
    "votes": 0,
    "views": 0,
    "tags": [
      "",
      "Twitch",
      "Community",
      "Clips",
      "Tech Support",
      "Discussions",
      "Questions"
    ],
    "social_media": {
      "reddit": true,
      "discord": false,
      "twitter": "TwitchSubreddit"
    },
    "communities": {
      "discord": "https://discord.gg/0gHwecaLRAzrRYWi",
      "subreddit": "https://reddit.com/r/Twitch",
      "twitch": "https://twitch.tv/communities/twitchsubreddit"
    },
    "appearance": {
      "clip": "",
      "videos": true,
      "events": true,
      "teams": true
    }
  }
            

Get User's Scheduled Streams

Gets the scheduled streams for the user.

URL

GET https://purple.plus/api/users/:id/schedule :id is the user's Twitch ID.

Optional Parameters
None.

Result Status Codes

200 Success The user was successfully found and returned.
204 No Content The user was successfully found, but has no scheduled streams.
404 Not Found The user was not found.

Example Response
Return data for user with Twitch ID 121219640.


  {
    "status": 200,
    "message": "OK",
    "description": "Match Found.",
    "streams": [
      {
        "id": "121219640_1504100640500",
        "title": "Purple+ Development",
        "description": "Join me as I finally complete the Purple+ project and test it for bugs!",
        "start": 1504101600000,
        "end": 1504107000000,
        "directory": "Creative",
        "type": "creative"
      }
    ]
  }
            

Get User's Scheduled Stream

Gets a specific scheduled stream from the user.

URL

GET https://purple.plus/api/users/:id/schedule/:stream :id is the user's Twitch ID.
:stream is the stream ID.

Optional Parameters
None.

Result Status Codes

200 Success The user was successfully found and returned.
204 No Content The user was successfully found, but has no scheduled streams.
404 Not Found The user or stream was not found.

Example Response
Return data for user with Twitch ID 121219640 and request with ID 121219640_1504100640500.


  {
    "status": 200,
    "message": "OK",
    "description": "Match Found.",
    "id": "121219640_1504100640500",
    "title": "Purple+ Development",
    "description": "Join me as I finally complete the Purple+ project and test it for bugs!",
    "start": 1504101600000,
    "end": 1504107000000,
    "directory": "Creative",
    "type": "creative"
  }
            

Get User's Advertisement Requests

Gets the approved advertisement requests from the user.

URL

GET https://purple.plus/api/users/:id/requests :id is the user's Twitch ID.

Optional Parameters
None.

Result Status Codes

200 Success The user was successfully found and returned.
204 No Content The user was successfully found, but has no approved advertisement requests.
404 Not Found The user was not found.

Example Response
Return data for user with Twitch ID 121219640.


  {
    "status": 200,
    "message": "OK",
    "description": "Match Found.",
    "requests": [
      {
        "legacy": false,
        "timestamp": 1504113232187,
        "approval_status": "approved",
        "type": "web",
        "data": {
          "name": "Purple+",
          "url": "https://purple.plus",
          "description": "Purple+ is the successor of TwitchDB, Twoos & /r/Twitch Ad Requests. The service is designed to promote everyone on Twitch - not just the streamers. Users create a profile, which will then be approved or rejected. If approved, they will be eligible to appear on the discovery features of the site!",
          "data": "Only Twitch API Data",
          "api": true,
          "tos": false,
          "source": true,
          "beta": false,
          "api_data": {
            "store": "Only what is publicly available: IDs, usernames, logos, followers, etc.",
            "scopes": "user_read",
            "scopes_description": "To log in with the account. Email addresses are **not** stored or even read."
          },
          "source_url": "https://github.com/Glyciant/PurplePlus"
        }
      }
    ]
  }
            

Get User's Advertisement Request

Gets a specific advertisement request from the user.

URL

GET https://purple.plus/api/users/:id/requests/:request :id is the user's Twitch ID.
:request is the request ID.

Optional Parameters
None.

Result Status Codes

200 Success The user was successfully found and returned.
204 No Content The user was successfully found, but has no approved advertisement requests.
206 Partial Content The user was successfully found, but the requested advertisement request is not approved.
404 Not Found The user or request was not found.

Example Response
Return data for user with Twitch ID 121219640 and request with ID 1504113232187.


  {
    "status": 200,
    "message": "OK",
    "description": "Match Found.",
    "legacy": false,
    "timestamp": 1504113232187,
    "approval_status": "approved",
    "type": "web",
    "data": {
      "name": "Purple+",
      "url": "https://purple.plus",
      "description": "Purple+ is the successor of TwitchDB, Twoos & /r/Twitch Ad Requests. The service is designed to promote everyone on Twitch - not just the streamers. Users create a profile, which will then be approved or rejected. If approved, they will be eligible to appear on the discovery features of the site!",
      "data": "Only Twitch API Data",
      "api": true,
      "tos": false,
      "source": true,
      "beta": false,
      "api_data": {
        "store": "Only what is publicly available: IDs, usernames, logos, followers, etc.",
        "scopes": "user_read",
        "scopes_description": "To log in with the account. Email addresses are **not** stored or even read."
      },
      "source_url": "https://github.com/Glyciant/PurplePlus"
    }
  }
            

Discord

Get Commands

Gets all commands available in the /r/Twitch Discord Server.

URL

GET https://purple.plus/api/discord/commands

Optional Parameters
None.

Result Status Codes

200 Success The commands were successfully found and returned.

Example Response


  {
    "status": 200,
    "message": "OK",
    "description": "Match Found",
    "commands": [
      {
        "name": "!twitter",
        "response": "Follow us on Twitter! https://twitter.com/TwitchSubreddit",
        "enabled": true,
        "restricted": false
      },
      {
        "name": "!blamesaai",
        "response": "Blaming SaaiTV.",
        "enabled": false,
        "restricted": true,
        "restrictions": {
          "method": "one",
          "mods": true,
          "helpers": true,
          "wiki": false,
          "staff": false,
          "admins": false,
          "global_mods": false,
          "contributors": false,
          "profiles": false,
          "twoos": true,
          "twoos_value": 100
        }
      },
      ...
    ]
  }
            

Get Command

Gets a specific command by its name.

URL

GET https://purple.plus/api/discord/commands/:name :name is the command name.

Optional Parameters
None.

Result Status Codes

200 Success The command was successfully found and returned.
404 Not Found The command does not exist.

Example Response
Return data for command with name !twitter.


  {
    "status": 200,
    "message": "OK",
    "description": "Match Found",
    "name": "!twitter",
    "response": "Follow us on Twitter! https://twitter.com/TwitchSubreddit",
    "enabled": true,
    "restricted": false
  }
            

Queries

Get Query

Gets a query by its ID.

URL

GET https://purple.plus/api/queries/:id :id is the query ID.

Optional Parameters
None.

Result Status Codes

200 Success The query was successfully found and returned.
404 Not Found The query does not exist.

Example Response
Return data for query with ID 1503843851832.


  {
    "status": 200,
    "message": "OK",
    "description": "Match Found",
    "query_id": 1503843851832,
    "redirect": "https://purple.plus/browse/query?types=moderator&streamer_irl_collaborating=any&streamer_irl_charity=any&streamer_socialeating_collaborating=any&streamer_socialeating_charity=any&streamer_talkshow_collaborating=any&streamer_talkshow_charity=any&streamer_music_collaborating=any&streamer_music_charity=any&moderator_requests_accepts=any&overview_keywords=&moderator_keywords=&tags=&description=Moderators",
    "uses": 1,
    "last_use": 1503843851832
  }