The Picarto API

This is unofficial documentation for Picarto.tv's service APIs. I'm not responsible for anything you do with this information; it is provided as is with no guarantees.

==== UPDATE 4/16/2017 ====

It looks like there is an official well-documented api now: https://docs.picarto.tv/api/ Please use that instead!

==========================

The Picarto API - Official
- Channel Info
The Picarto API - Unofficial

The Picarto API - Official

Officialy, there is only one api endpoint provided to streamers:

Channel Info

Gives information about your channel. You must go to https://picarto.tv/settings/api to generate the access key for this endpoint.

Endpoint: https://api.picarto.tv/channel/ <accessKey>
Method: GET
Parameters: none
Response:
Returns a JSON Object with the following properties:

id Your streamer id?
channel Your channel name
channel_title Your channel's title
avatar_url Your avatar
offline_image Your channel's offline image
chat_banner Your channel's chat banner
thumbnail_url Your channel's thumbnail
background_url Your channel's background image
tags An array of your channel's tags
language_primary Your channel's primary language
- language_code The name of the language
- flag_url The image of the language's flag
language_secondary Your channel's secondary language (See: language_primary)
followers The number of followers you have
channel_views The number of views your channel has
is_online Whether or not you are streaming
is_multistream Whether or not you are in a multistream
multistream_participants An array of people you're in a multistream with
current_viewers The number of people currently watching your stream
is_nsfw Whether or not you're channel is marked NSFW
commissions_enabled Whether or not commissions are enabled on your channel
tablet The tablet you are using
program The program you are using
content_type The type of content you are streaming
description You're channel's description
commission_info You're channel's commission info
channel_url Your main social link
social_urls An object containing your social links. The key is the type of link and the value is the url.

Response Example:

{
   "id": 123456,
   "channel": "YourChannel",
   "channel_title": "Doing pony things",
   "avatar_url": "https://picarto.tv/user_data/usrimg/yourusername/dsdefault.jpg",
   "offline_image": "https://picarto.tv/user_default/offlineimage.jpg",
   "chat_banner": "",
   "thumbnail_url": "https://picarto.tv/user_data/usrimg/yourusername/thumbnail_stream.jpg",
   "background_url": "",
   "tags": [ "mlp", "programing", "coding", "3d", "fezbot" ],
   "language_primary": {
      "language_code": "United States",
      "flag_url": "https://picarto.tv/images/flags/new/us.png"
   },
   "language_secondary": { },
   "followers": 12,
   "channel_views": 381,
   "is_online": false,
   "is_multistream": false,
   "multistream_participants": [ ],
   "current_viewers": 0,
   "is_nsfw": false,
   "commissions_enabled": false,
   "tablet": "A paper notebook from Staples",
   "program": "My pencil",
   "content_type": "Sketching",
   "description": "Description stuff :P",
   "commission_info": "Commissions and stuf :P",
   "channel_url": "http://example.com/",
   "social_urls":{  
      "deviantart":"http://youraccount.deviantart.com/",
      "youtube":"https://www.youtube.com/channel/yourchannel"
   }
}

The Picarto API - Unofficial

This is unofficial documentation for Picarto.tv's service APIs. It's collected through watching client network communication and exploring client source code.

As these endpoints are unofficial, they may break or change at any time. I'm not responsible for anything you do with this information; it is provided as is with no guarantees.

Please be sure to read through Picarto's TOS (https://picarto.tv/site/terms) and make sure you're not breaking them.

Web API Endpoints

These are API endpoints that can be used for comunicating with picarto's services. Unless otherwise specified, all endpoints use https://www.picarto.tv/. You should probably set the referrer to that that as well. Custom user agents don't seem to effect things.

Login

Logs into a picarto account.

Endpoint: /process/login
Method: POST
Form Data:

username Your username
password Your password
staylogged Whether or not to stay logged in. true or false

Response:
Returns a JSON Object with the following properties:

loginstatus Whether or not the login was successfull. true or false
accountStatus The account's status?
stayloggedVal Whether or not stay logged in was checked. 1 or -1
staylogged Whether or not stay logged in was checked. "true" or "false"

Response Example:

{
	"loginstatus": true,
    "accountStatus": 0,
    "stayloggedVal": "true",
    "staylogged":1
}

Extra Info:
Auth is based on the PHPSESSID cookie. All further requests must include this cookie for identification and auth. If staylogged is set to true, then the additional picartoSession and picartoCookieID cookies are set, with an expiration of 2 weeks. These cookies will automatically re-auth the PHPSESSID.

Logout

Logs out of a picarto account.

Endpoint: /process/logout
Method: POST
Form Data: none
Response:
On success, returns the loneliest number.

Response Example:

Extra Info:
Logging out invalidates the current session and sets the PHPSESSID, picartoSession, and picartoCookieID cookies to "deleted".

Get News Update

Gets the content for the "News update" popup.

Endpoint: /modules/newsupdate
Method: GET
Parameters: none
Response:
If there is unread news, returns a JSON Object with the following properties:

title The title of the news update
description The content of the news update

Otherwise the response is empty. (See: Set News Read)

Response Example:

{
	"title": "Looking for your Follows?",
    "description": "Are you looking for your precious follows? You can find them on our new EXPLORE page!<a target='_blank' href='https:\/\/picarto.tv\/communities\/explore' >Go to Explore!<\/a>"
}

Set News Read

Marks the current news as read (the popup woun't show up again for this session and Get News Update's response will be blank). Cannot be unset.

Endpoint: /modules/newsupdate
Method: POST
Parameters:

set_newsreaded: true

Response:
Same as Get News Update

Set Guest Chat Username

Sets a guest username for chat. Username must contain at least one letter; can only contain letters, underscores, and/or dashes; and must be 20 characters or less. Should be used when you're logged out, I don't know what will happen if you're already logged in.

Endpoint: /process/channel
Method: POST
Form Data:

setusername The username to try to use

Response:
Returns a string. Can be any of the following values:

ok The username was set successfully
userNameRegEx The username does not match the requirements
userNameTooLong The username is too long
userNameExists The username is already in use

Response Example:

userNameRegEx

getuidchat

I think it sets the channel to use when getting the chatbox HTML? It's allways called before Get Chatbox HTML

Endpoint: /process/channel
Method: POST
Form Data:

getuidchat The channel you set the guest chat name for

Response:
Returns "idset"

Response Example:

idset

Get Chatbox HTML

Gets the html for the chatbox. The last line of html also contains javascript with the key needed for connecting to the chat websocket. You will need this if you want to connect to chat.

Endpoint: /modules/channel-chat
Method: GET
Parameters: none
Response:
Returns HTML. The last line contains a <script> tag with chat properties. The initChatVariables function in this script is important!

It has the following parameters:

Whether or not simple is enabled.
Whether or not link detection is enabled.
Whether or not emoticons are enabled.
Whether or not timestamps are enabled.
Whether or not sound notifications are enabled.
Your username in chat.
The channel the chat is for.
The key to use to connect to the chat websocket.

Response Example:

...
...
...
<script>initScrollbar();initChatStyle(popoutChat);initChatVariables('0','1','1','0','0','<username>','<channelName>','<chatAuthKey>');changeHeight();</script>

Get Video Load Balancer IP

Gets the IP to use for viewing a stream.

Endpoint: /process/channel
Method: POST
Form Data:

loadbalancinginfo The name of the channel.

Response:
The IP to use, or "failedGetIP".
Response Example:

185.93.1.35

Extra Info:
As of at least 10/7/16, the internal code takes this and matches it to an actual URL. The mapping is as follows:

167.114.157.136 => edge1-ca.picarto.tv
167.114.157.137 => edge2-ca.picarto.tv
158.69.55.151 => edge3-ca.picarto.tv
198.27.85.197 => edge4-ca.picarto.tv
185.93.1.35 => edge1-us-east.picarto.tv
185.93.1.33 => edge2-us-east.picarto.tv
default => edge1-us-east.picarto.tv

This is then used to build the video url: "https://" + URL + "/hls/" + Channel + "/index.m3u8"

Get Homepage Info

Gets information about communities and channels for the homepage. More likely to change than the other endpoints so don't rely too heavily on it.

Endpoint: /process/index
Method: POST
Form Data: none
Response:
Returns a JSON object with the following properties:

videos An array of videos to show on the homepage
Each video object has the following properties:
- channel_name The name of the channel
- channel_title The title of the channel
- featured Whether or not the channel is featured
- product ??????
- offline_image The ofline image or false
communities A list of communities to show on the homepage
Each community object has the following properties:
- community_id The id of the comunity
- community_name The name of the community
- file The image for this community. (it's just the filename - I'm not sure where they're actually stored)
top_streams A list of the top streams to show on the homepage
Each stream object has the following properties:
- channel_name The name of the channel
- channel_title The title of the channel
- community_id The id of the comunity the stream is in
- community_name The name of the community the stream is in
- product ??????
top_streams A list of random streams to show on the homepage (See: top_streams)

Response Example:

{
   "videos":[
      {
         "channel_name":"Twokinds",
         "channel_title":"Twokinds",
         "featured":false,
         "product":0,
         "offline_image":false
      }
   ],
   "communities":[
      {
         "community_id":16,
         "community_name":"Pony",
         "file":"pony.jpg"
      }
   ],
   "top_streams":[
      {
         "channel_name":"Twokinds",
         "channel_title":"Twokinds",
         "community_id":8,
         "community_name":"Furry",
         "product":1
      }
   ],
   "random_streams":[
      {
         "channel_name":"manosdetrapo",
         "channel_title":"fun times with art and manos",
         "community_id":1,
         "community_name":"Creative",
         "product":1
      }
   ]
}

Search

Searches channels and tags and returns the HTML of the search results.

Endpoint: /modules/search
Method: POST
Form Data:

search The thing you're searching for

Response:
Returns the HTML of the search results

Get Explore Page Info

Gets info for the 'Explore' page.

Endpoint: /process/explore
Method: POST
Form Data:

initial:true
channels:true

Response:
Returns a JSON object with the following properties:

languages An array of all the languages that can be filtered by
Each language object has the following properties:
- lang_id The id of the language
- language The name of the language
- flag The image for the flag of the language (it's just the filename - I'm not sure where they're actually stored)
- online_sfw The number of SFW channels with this language that are live
- online_nsfw The number of NSFW channels with this language that are live
channels An array of all the channels that are live
Each channel object has the following properties:
- id The id of the channel
- channel_name The name of the channel
- channel_title The title of the channel
- channel_viewers The number of viewers the channel has
- product ??????
- adult Whether or not the channel is NSFW
- cat_id The category id of the channel
- cat_name The category name of the channel
- language_primary The channel's primary language
  - language_id The id of the language
  - language_code The name of the language
  - flag_url The image of the language's flag
- language_secondary The channel's secondary language (See: language_primary)
- tags An array of tags that the channel has
- is_multistream Whether or not the channel is in a multistream
- gamemode Whether or not the channel is in game mode
- commissions Whether or not the channel is taking commissions
tags An array of trending tags
communities An array of 4 random communities
Each community object has the following properties:
- id The id of the community
- name The name of the community
- viewers_sfw The number of people currently watching SFW channels within this community
- viewers_nsfw The number of people currently watching NSFW channels within this community
- online_sfw The number of SFW channels within this community that are live
- online_nsfw The number of NSFW channels within this community that are live
- file_name The image file for the community (it's just the filename - I'm not sure where they're actually stored)

Response Example:

{
   "languages":[
      {
         "lang_id":11,
         "language":"Argentina",
         "flag":"ar.png",
         "online_sfw":0,
         "online_nsfw":1
      }
   ],
   "channels":[
      {
         "id":88453,
         "channel_name":"A Channel",
         "channel_title":"The Title",
         "channel_viewers":100,
         "product":1,
         "adult":false,
         "cat_id":17,
         "cat_name":"Cartoon",
         "language_primary":{
            "language_id":227,
            "language_code":"United States",
            "flag":"us.png"
         },
         "language_secondary":{ },
         "tags":[ ],
         "is_multistream":false,
         "gamemode":false,
         "commissions":false
      }
   ],
   "tags":[ "furry", "art", "anime", "illustration", "cartoon", "fanart", "anthro", "digital", "pony", "animation", "drawing", "manga", "mlp", "design", "cute", "character", "comic", "sai", "undertale", "commissions" ],
   "communities":[
      {
         "id":10,
         "name":"Comic",
         "viewers_sfw":115,
         "viewers_nsfw":57,
         "online_sfw":10,
         "online_nsfw":5,
         "file_name":"comic.jpg"
      }
   ]
}

Get Show NSFW Warnings

Gets whether or not nsfw warnings should be shown.

Endpoint: /process/explore
Method: POST
Form Data:

checksafemode:true

Response:
Returns a JSON array of an object with the following properties:

nsfw_warnings Gets whether or not to show nsfw warnings.

Response Example:

[
   {
      "nsfw_warnings": true
   }
]

Get All Communities

Gets a list of all available communities

Endpoint: /process/explore
Method: POST
Form Data:

communities:all

Response:
Returns a JSON array of communities
Each community object has the following properties:

id The id of the community
name The name of the community
viewers_sfw The number of people currently watching SFW channels within this community
viewers_nsfw The number of people currently watching NSFW channels within this community
online_sfw The number of SFW channels within this community that are live
online_nsfw The number of NSFW channels within this community that are live
file_name The image file for the community (it's just the filename - I'm not sure where they're actually stored)

Response Example:

[
   {
      "id": 22,
      "name": "Adult",
      "viewers_sfw": 0,
      "viewers_nsfw": 649,
      "online_sfw": 0,
      "online_nsfw": 69,
      "file_name": "adult.jpg"
   }
]

Get Random Communities

Gets a list of 5 random communities

Endpoint: /process/explore
Method: POST
Form Data:

communities:random

Response:
See: Get All Communities

Search Live Channels

Gets a list of all live channels in a Community.

Endpoint: /process/explore
Method: POST
Form Data:

streams:all
commission Whether or not the channel takes commissions. true or blank
premium Whether or not the channel is premium. true or blank
shuffle Whether or not to shuffle the results. true or blank
language The language id to filter by. <languageId> or blank
tag The tag to filter by. <tag> or blank
community The community id to filter by. <communityId> or blank

Response:
Returns a JSON array of channel objects
See: Get Explore Page Info -> Response -> channels

Get Tag Completion

Gets a list of tags that start with the given string.

Endpoint: /process/explore
Method: POST
Form Data:

tags The string to search for

Response:
Returns a JSON array of tags

Response Example:

["pony","pokemon","porn","pop"]

Get Trending Tags

Gets a list of trending tags

Endpoint: /process/explore
Method: POST
Form Data:

tags:trending

Response:
Returns a JSON array of tags

Response Example:

["anime","art","furry","illustration","fanart","drawing","manga","digital","comic","design","character","pony","anthro","mlp","sai","cute","animation","cartoon","commissions","undertale"]

Get Languages

Gets a list of available languages

Endpoint: /process/explore
Method: POST
Form Data:

languages:true

Response:
Returns a JSON array of language objects
See: Get Explore Page Info -> Response -> languages

Chat Events

Events sent/recieved through the chat websockets.

SEE: https://github.com/Wolvan/PicartoChatBot/blob/v2/resources/picarto_protocol.proto

Misc. Stuff

Miscellaneous things.

Common URLs

These are some common URL's used by picarto's services

url	page
https://picarto.tv	Self-explanitory
https://picarto.tv/site/about	The about page
https://picarto.tv/site/feedback	Feedback page (must be signed in)
https://picarto.tv/site/report	Report a bug (must be signed in)
https://picarto.tv/site/faq	FAQ
https://picarto.tv/site/terms	Terms of Service
https://picarto.tv/site/policy	Privacy Policy
https://picarto.tv/site/press	Press information
https://picarto.tv/site/upgrade	Premium account upgrade
https://picarto.tv/communities/explore	The comunities explore page
https://picarto.tv/settings/livestreamsetup	Stream setup
https://picarto.tv/settings/account	Account settings
https://picarto.tv/settings/channel	Channel settings
https://picarto.tv/settings/chat	Chat settings
https://picarto.tv/settings/socials	Linked social accounts
https://picarto.tv/settings/connections?follows	Followers/Following
https://picarto.tv/settings/connections?subscriber	Subscriptions/Subscribers
https://picarto.tv/settings/video	Recording settings (Premium only)
https://picarto.tv/settings/multistream	Multistream settings (Premium only)
https://picarto.tv/settings/app	Mobile app settings
https://picarto.tv/settings/api	Public api settings
https://picarto.tv/ `<ChannelName>`	The channel page

Tschrock/PicartoAPI.md

The Picarto API

==== UPDATE 4/16/2017 ====

==========================

Contents

The Picarto API - Official

Channel Info

The Picarto API - Unofficial

Web API Endpoints

Login

Logout

Get News Update

Set News Read

Set Guest Chat Username

getuidchat

Get Chatbox HTML

Get Video Load Balancer IP

Get Homepage Info

Search

Get Explore Page Info

Get Show NSFW Warnings

Get All Communities

Get Random Communities

Search Live Channels

Get Tag Completion

Get Trending Tags

Get Languages

Chat Events

Misc. Stuff

Common URLs