summaryrefslogtreecommitdiff
path: root/rest/index.rst
blob: e656e4b29f17d94a2a7295437dc441726b767797 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
========
REST API
========

.. toctree::
   :maxdepth: 2

   authentication
   stations
   bookmarks
   account
   ads
   endpoints
   errorcodes

The Pandora REST API is used by modern Pandora apps including the website and
the various mobile apps provided by Pandora. The current REST API has multiple
versions and not all functionality seems to be supported for each version.
Released API versions are stable but new APIs are added often as the Pandora
feature set evolves. The main endpoint is:

- https://www.pandora.com/api/

All requests are JSON-encoded and sent via HTTP POST body to the endpoints over
HTTPS. Requests require a ``Content-Type`` header of ``application/json``.
Response bodies are JSON-encoded values. Unlike the JSON v5 API there is no
requirement for time syncronization, Blowfish cryptography, or partner logins.

.. _rest-csrf-token:

CSRF Token / Cookie
===================
All requests require an ``X-CsrfToken`` header as well as a matching
``csrftoken`` cookie. The current version of the API merely validates that the
token and cookie match so the client can make up whatever they want. However,
the token can also be obtained by making a ``HEAD`` request to
``https://www.pandora.com/`` and saving the cookies. The API endpoints will not
serve cookies until after authentication. Clients *SHOULD* make a ``HEAD``
request to the root domain and include the current value of the ``csrftoken``
cookie in each request.

.. code:: http

	POST /api/v1/auth/login HTTP/1.1
	Host: www.pandora.com
    Content-Type: application/json;charset=utf-8
	X-CsrfToken: 123456a7889b1c23
	X-AuthToken: 

	{ "username": "foo", "password": "bar" }

.. _rest-auth-token:

Auth Token
==========
All requests except for login require an ``X-AuthToken`` header which contains
the auth token obtained during login. It is acceptable to include the
``X-AuthToken`` header with an empty value during login.

.. code:: http

	POST /api/v1/station/getStations HTTP/1.1
	Host: www.pandora.com
    Content-Type: application/json;charset=utf-8
	X-CsrfToken: 123456a7889b1c23
	X-AuthToken: dGhpcyBpcyBqdXN0IGFuIGV4YW1wbGUgY29kZQo=

	{ "pageSize": 250 }

Errors
======
Error conditions are indicated by a combination of HTTP status code and a JSON
response body. Any responses with a 200 status code are successful.

.. code:: json

	{
		"errorCode": 0,
		"errorString": "INVALID_REQUEST",
		"message": "The request could not be validated"
	}