From 24a410ae8f441fcf0310a9ce7a190451d2698bfd Mon Sep 17 00:00:00 2001
From: Tim Bielawa <timbielawa@gmail.com>
Date: Wed, 18 May 2016 12:31:59 -0400
Subject: [PATCH] docs(preferences): Document user and org preferences (#5087)

closes #5069
---
 docs/sources/http_api/overview.md    |   1 +
 docs/sources/http_api/preferences.md | 100 +++++++++++++++++++++++++++
 2 files changed, 101 insertions(+)
 create mode 100644 docs/sources/http_api/preferences.md

diff --git a/docs/sources/http_api/overview.md b/docs/sources/http_api/overview.md
index 8e7e2d60ad3..7f5a3ecfac8 100644
--- a/docs/sources/http_api/overview.md
+++ b/docs/sources/http_api/overview.md
@@ -18,4 +18,5 @@ dashboards, creating users and updating data sources.
 * [User API](/http_api/user/)
 * [Admin API](/http_api/admin/)
 * [Snapshot API](/http_api/snapshot/)
+* [Preferences API](/http_api/preferences/)
 * [Other API](/http_api/other/)
diff --git a/docs/sources/http_api/preferences.md b/docs/sources/http_api/preferences.md
new file mode 100644
index 00000000000..6bb00ed8132
--- /dev/null
+++ b/docs/sources/http_api/preferences.md
@@ -0,0 +1,100 @@
+----
+page_title: Preferences API
+page_description: Grafana Preferences API Reference
+page_keywords: grafana, preferences, http, api, documentation
+---
+
+# User and Org Preferences API
+
+Keys:
+
+- **theme** - One of: ``light``, ``dark``, or an empty string for the default theme
+- **homeDashboardId** - The numerical ``:id`` of a favorited dashboard, default: ``0``
+- **timezone** - One of: ``utc``, ``browser``, or an empty string for the default
+
+Omitting a key will cause the current value to be replaced with the
+system default value.
+
+## Get Current User Prefs
+
+`GET /api/user/preferences`
+
+**Example Request**:
+
+    GET /api/user/preferences HTTP/1.1
+    Accept: application/json
+    Content-Type: application/json
+    Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
+
+**Example Response**:
+
+    HTTP/1.1 200
+    Content-Type: application/json
+
+    {"theme":"","homeDashboardId":0,"timezone":""}
+
+## Update Current User Prefs
+
+`PUT /api/user/preferences`
+
+**Example Request**:
+
+    PUT /api/user/preferences HTTP/1.1
+    Accept: application/json
+    Content-Type: application/json
+    Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
+
+    {
+      "theme": "",
+      "homeDashboardId":0,
+      "timezone":"utc"
+    }
+
+**Example Response**:
+
+    HTTP/1.1 200
+    Content-Type: text/plain; charset=utf-8
+
+    {"message":"Preferences updated"}
+
+## Get Current Org Prefs
+
+`GET /api/org/preferences`
+
+**Example Request**:
+
+    GET /api/org/preferences HTTP/1.1
+    Accept: application/json
+    Content-Type: application/json
+    Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
+
+**Example Response**:
+
+    HTTP/1.1 200
+    Content-Type: application/json
+
+    {"theme":"","homeDashboardId":0,"timezone":""}
+
+## Update Current Org Prefs
+
+`PUT /api/org/preferences`
+
+**Example Request**:
+
+    PUT /api/org/preferences HTTP/1.1
+    Accept: application/json
+    Content-Type: application/json
+    Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
+
+    {
+      "theme": "",
+      "homeDashboardId":0,
+      "timezone":"utc"
+    }
+
+**Example Response**:
+
+    HTTP/1.1 200
+    Content-Type: text/plain; charset=utf-8
+
+    {"message":"Preferences updated"}