{"_id":"563a252f50bf950d00e0979e","parentDoc":null,"project":"563a252d50bf950d00e09798","category":{"_id":"563a252e50bf950d00e0979c","project":"563a252d50bf950d00e09798","pages":["563a252f50bf950d00e0979e","563a35ac1846790d0089532c","563d1407d8f2d20d00448d3c","563d1d3f9799fb0d0004776a","564509aa2c74cf1900da48c7","56453b7e9f3f550d00fa3c7b","564b498aeed7de0d003672c3","564b523ce5d9d61700d580e0","564b58ea1a8e610d006bfd49","564b59baee12850d00958656","564b6773d969330d00aba984","564b69b2d7b95d0d00ed050f","564b7fa8cc472d0d00da9447","564b905fa8a0ba21002ad6b1","564ba051288b1a2b00b3ae83","564ba6275cc43717009bcff1","564bb2138841060d00abb2e0","564bb74e05c99e1700161dd1","564c8ad60ddedc210051e582","564cca42d0c5b42b002305e8","564cca8ecfa4452b0019926d","564ce34f404ce53500fdb255","564cea76404ce53500fdb272","564cedb77d4d31170028dd2e","564cefc1bc81632100b10468","564cf17d1f42792b00820515","564cf5462248461700bd4017","564ddd49a8671617004e7b90","564ddf9ead1d5217003e2e18","564de1dea8671617004e7b99","564de3c11133043500f4bf96","564de669e39c4435005a1f65","564df3f16eaa3a2100868961","5655d3519347d30d00d7e8e2"],"version":"563a252d50bf950d00e0979b","__v":34,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-11-04T15:33:02.244Z","from_sync":false,"order":9999,"slug":"documentation","title":"Documentation"},"user":"54c7fdeae317000d007c2765","version":{"_id":"563a252d50bf950d00e0979b","__v":7,"project":"563a252d50bf950d00e09798","createdAt":"2015-11-04T15:33:01.701Z","releaseDate":"2015-11-04T15:33:01.701Z","categories":["563a252e50bf950d00e0979c","563a2a691846790d008952fe","563a3394daf1c00d00136d9b","563a3467d25e8919005f3f0c","563a347850bf950d00e097b4","570e5cec10aa423200391fb5","5890d358d6cb8e2500a3f311"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"__v":24,"updates":["56be27b65680980d005503ff","56fa4dfdd77ef20e00a6917a"],"next":{"pages":[],"description":""},"createdAt":"2015-11-04T15:33:03.144Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"HTTP Methods\"\n}\n[/block]\nThe Klipfolio API uses four HTTP methods when accessing API resources: GET, POST, PUT and DELETE. \nThe HTTP GET method is used to retrieve (or read) a representation of a resource such as client, Klips, and tabs (now called dashboards). \nThe PUT method is used to update an existing resource. \nThe POST method is used to create new resources.\nThe DELETE method is used to delete an existing resource.\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Rate limiting\"\n}\n[/block]\nKlipfolio supports up to five API requests per second and requests per day depends on your plan. (restarts at 12:00 am ET). If you exceed either of those limits, any request you send will return a 429 Too Many Requests error with an appropriate message. Limits apply to the company making the request. The usage limit applies to the requesting company. If you require a higher limit than your plans allows, please contact sales:::at:::klipfolio.com.\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Authentication\"\n}\n[/block]\nThe Klipfolio API works with both Basic Authentication and API keys to enable secure authentication. You can generate an API key from the Klipfolio Dashboard app through either the My Profile page or from Users if you are an administrator (you must have the user.manage permission). By default, both the Admin and Editor roles have permission to generate keys. \n\nTo use the API key, you must put the following into the header for your query:\nkf-api-key:<apikey>\n\nWhere <apikey> is replaced with the actual key. \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Versioning\"\n}\n[/block]\nThe current version of the Klipfolio API is 1.0 (1 is also accepted). \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Pagination\"\n}\n[/block]\nWhen requesting a list of assets (for example, clients, Klips, and so on) using a GET call, use pagination to manage the requests. \n\nPaging is controlled by two URL parameters, \"offset\" and \"limit\" as follows:\n\n**Offset** is the index of the first item in the results.  The default is 0.\n**Limit** is the maximum number of results to return.  The default is 25.  The maximum is 100 (anything over 100 will return a 400 Bad Request error).\nIn the following example query using pagination, the result will return “page 2” of the list of Klips and each page will show 10 Klips per page:\n`GET /api/1.0/klips?limit=10&offset=10`\n\n**Note:** If the user does not specify a limit and offset, the first 25 results will be returned.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Permissions\"\n}\n[/block]\nThis refers to the permissions required for a particular API request. The permissions are based on your account and your role. The API permissions map directly to the permissions found in the Klipfolio Dashboard user interface. \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Parameters\"\n}\n[/block]\nSome API requests include additional parameters that can be used. These are listed with the particular request in the reference guide. \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Clients\"\n}\n[/block]\nView, create, update existing clients, and manage clients for all client accounts belonging to the requesting company.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Response codes\"\n}\n[/block]\nThe following are examples of HTTP error codes that the API will generate when a correctly authenticated request fails:\n\n400 — The request was formatted incorrectly, or one of the required fields contains invalid.data\n401 — Authentication failed or the user does not have permission to access the requested resource.\n403 — The user is attempting to perform an action/request that is not allowed.\n404 — The requested resource was not found.\n405 — The requested method is not supported.\n429 — Too many requests. \n500 — General error or it is an unexpected error in Klipfolio.\n\nOther response codes include:\n200 — Everything worked correctly.\n201 — Everything worked correctly and public ID or location of the new resource is returned.\n500 — General error or it is an unexpected error in Klipfolio.","excerpt":"This page will help you get started with Klipfolio API Reference Guide. \n\nKlipfolio brings your business data to life helping you and your organization understand and track KPIs, metrics and other essential information. The Klipfolio API provides the same functionality as the web app UI for managing assets (clients, dashboards, Klips, data sources). Organized around REST, the Klipfolio API is accessed over HTTPS from the https://app.klipfolio.com/api/1.0/* domain. All responses are returned in JSON.\n\nKlipfolio recently updated terminology changing tab to dashboard.\n\nWe have changed the name of our app to simply Klipfolio, instead of Klipfolio Dashboard. In addition we changed Tab and Tabs in our app to dashboard and dashboards respectively. The Klipfolio API still uses the former terms Tab and Tabs.","slug":"getting-started","type":"basic","title":"Introduction to the Klipfolio API"}

Introduction to the Klipfolio API

This page will help you get started with Klipfolio API Reference Guide. Klipfolio brings your business data to life helping you and your organization understand and track KPIs, metrics and other essential information. The Klipfolio API provides the same functionality as the web app UI for managing assets (clients, dashboards, Klips, data sources). Organized around REST, the Klipfolio API is accessed over HTTPS from the https://app.klipfolio.com/api/1.0/* domain. All responses are returned in JSON. Klipfolio recently updated terminology changing tab to dashboard. We have changed the name of our app to simply Klipfolio, instead of Klipfolio Dashboard. In addition we changed Tab and Tabs in our app to dashboard and dashboards respectively. The Klipfolio API still uses the former terms Tab and Tabs.

[block:api-header] { "type": "basic", "title": "HTTP Methods" } [/block] The Klipfolio API uses four HTTP methods when accessing API resources: GET, POST, PUT and DELETE. The HTTP GET method is used to retrieve (or read) a representation of a resource such as client, Klips, and tabs (now called dashboards). The PUT method is used to update an existing resource. The POST method is used to create new resources. The DELETE method is used to delete an existing resource. [block:api-header] { "type": "basic", "title": "Rate limiting" } [/block] Klipfolio supports up to five API requests per second and requests per day depends on your plan. (restarts at 12:00 am ET). If you exceed either of those limits, any request you send will return a 429 Too Many Requests error with an appropriate message. Limits apply to the company making the request. The usage limit applies to the requesting company. If you require a higher limit than your plans allows, please contact sales@klipfolio.com. [block:api-header] { "type": "basic", "title": "Authentication" } [/block] The Klipfolio API works with both Basic Authentication and API keys to enable secure authentication. You can generate an API key from the Klipfolio Dashboard app through either the My Profile page or from Users if you are an administrator (you must have the user.manage permission). By default, both the Admin and Editor roles have permission to generate keys. To use the API key, you must put the following into the header for your query: kf-api-key:<apikey> Where <apikey> is replaced with the actual key. [block:api-header] { "type": "basic", "title": "Versioning" } [/block] The current version of the Klipfolio API is 1.0 (1 is also accepted). [block:api-header] { "type": "basic", "title": "Pagination" } [/block] When requesting a list of assets (for example, clients, Klips, and so on) using a GET call, use pagination to manage the requests. Paging is controlled by two URL parameters, "offset" and "limit" as follows: **Offset** is the index of the first item in the results. The default is 0. **Limit** is the maximum number of results to return. The default is 25. The maximum is 100 (anything over 100 will return a 400 Bad Request error). In the following example query using pagination, the result will return “page 2” of the list of Klips and each page will show 10 Klips per page: `GET /api/1.0/klips?limit=10&offset=10` **Note:** If the user does not specify a limit and offset, the first 25 results will be returned. [block:api-header] { "type": "basic", "title": "Permissions" } [/block] This refers to the permissions required for a particular API request. The permissions are based on your account and your role. The API permissions map directly to the permissions found in the Klipfolio Dashboard user interface. [block:api-header] { "type": "basic", "title": "Parameters" } [/block] Some API requests include additional parameters that can be used. These are listed with the particular request in the reference guide. [block:api-header] { "type": "basic", "title": "Clients" } [/block] View, create, update existing clients, and manage clients for all client accounts belonging to the requesting company. [block:api-header] { "type": "basic", "title": "Response codes" } [/block] The following are examples of HTTP error codes that the API will generate when a correctly authenticated request fails: 400 — The request was formatted incorrectly, or one of the required fields contains invalid.data 401 — Authentication failed or the user does not have permission to access the requested resource. 403 — The user is attempting to perform an action/request that is not allowed. 404 — The requested resource was not found. 405 — The requested method is not supported. 429 — Too many requests. 500 — General error or it is an unexpected error in Klipfolio. Other response codes include: 200 — Everything worked correctly. 201 — Everything worked correctly and public ID or location of the new resource is returned. 500 — General error or it is an unexpected error in Klipfolio.