{"_id":"576851debb15f40e00a2895b","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"},"user":"54c7fdeae317000d007c2765","parentDoc":null,"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"},"__v":14,"project":"563a252d50bf950d00e09798","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-06-20T20:28:14.787Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":"/klips/:id"},"isReference":false,"order":22,"body":"[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"GET /klips/{id}/annotations\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Description\",\n    \"0-1\": \"Retrieve a list of annotations for a specified Klip.\",\n    \"1-0\": \"Permissions\",\n    \"2-0\": \"Resource URL\",\n    \"3-0\": \"Parameters\",\n    \"1-1\": \"dashboard.annotation.view\",\n    \"2-1\": \"https://app.klipfolio.com/api/1.0/klips/{id}/annotations\",\n    \"3-1\": \"start_date (accepts Unix time format)\\nend_date (accepts Unix time format)\\n\\n**NOTE:** Specify either none, one or both. For example, if start_date is not specified, it will retrieve all from the beginning of time; if end_date is not specified, it will retrieve all until the current date/time.\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n##Example Request\n`GET https://app.klipfolio.com/api/1/klips/57ebf715c0fdd044e4191adaecb4fc6f/annotations`\n##Example Response\n```\n{\n  \"meta\": {\n    \"success\": true,\n    \"status\": 200\n  },\n  \"data\": {\n    \"annotations\": [\n      {\n        \"id\": \"12345eba2f065109fb88be86b2f9279e\",\n        \"createdBy\": {\n          \"id\": \"b1b1b11c7e4d34c6410d807564c470a7\",\n          \"name\": \"Jane Doe\"\n        },\n        \"date_created\": \"2016-06-21T13:18:30Z\",\n        \"body\": \"Order status for June\"\n      },\n      {\n        \"id\": \"f1ea0a852348d0f606eabac4b2443477\",\n        \"createdBy\": {\n          \"id\": \"a5a9d31c7e4d34c6410d807564c470a7\",\n          \"name\": \"Tamsin Douglas\"\n        },\n        \"date_created\": \"2016-06-21T13:32:05Z\",\n        \"body\": \"Check Florida.\"\n      }\n    ]\n  }\n}\n```\n\n\n[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"GET /klips/{id}/annotations/{id}\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Description\",\n    \"0-1\": \"Retrieve the details of an annotation for a specified Klip.\",\n    \"1-0\": \"Resource URL\",\n    \"2-0\": \"Permissions\",\n    \"3-0\": \"Parameters\",\n    \"1-1\": \"https://app.klipfolio.com/api/1.0/klips/{id}/annotations/{id}\",\n    \"2-1\": \"dashboard.annotation.view\",\n    \"3-1\": \"None.\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n##Example Request\n`GET https://app.klipfolio.com/api/1/klips/57ebf715c0fdd044e4191adaecb4fc6f/annotations/39874eba2f065109fb88be86b2f9279e`\n\n##Example Response\n```\n{\n  \"meta\": {\n    \"success\": true,\n    \"status\": 200\n  },\n  \"data\": {\n    \"id\": \"12345eba2f065109fb88be86b2f9279e\",\n    \"createdBy\": {\n      \"id\": \"b1b1b11c7e4d34c6410d807564c470a7\",\n      \"name\": \"Jane Doe\"\n    },\n    \"date_created\": \"2016-06-21T13:18:30Z\",\n    \"body\": \"Order status for June\"\n  }\n}\n```\n[block:api-header]\n{\n  \"type\": \"post\",\n  \"title\": \"POST /klips/{id}/annotations\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Description\",\n    \"0-1\": \"Create a a new annotation for a specified Klip.\",\n    \"1-1\": \"dashboard.annotation.edit\",\n    \"2-1\": \"https://app.klipfolio.com/api/1.0/klips/{id}/annotations\",\n    \"3-1\": \"body: \\\"\\\" // String, required.  Maximum 1024 characters.\\nNOTE: When creating an annotation, everything else uses a default: created_by is the authenticated user and date_created is the creation timestamp.\",\n    \"1-0\": \"Permissions\",\n    \"2-0\": \"Resource URL\",\n    \"3-0\": \"Fields\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n##Example Request\n```\nPOST https://app.klipfolio.com/api/1/klips/63d9abc8330ae256dac2e2f8c4371a8f/annotations -d \"{'body':'I am writing an annotation'}\" \n```\n##Example Response\n{\n    \"meta\":\n    {\n        \"success\":true,\n        \"status\":201,\n        \"location\":\"/klips/63d9abc1234ae256dac2e2f8c4371a8f/annotations/23c618c919b1234d5f1d3359942559eb\"\n    },\n    \"data\":{}\n}\n```\n[block:api-header]\n{\n  \"type\": \"put\",\n  \"title\": \"PUT /klips/{id}/annotations/{id}\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Description\",\n    \"0-1\": \"Update a specified Klip annotation.\",\n    \"1-0\": \"Permissions\",\n    \"2-0\": \"Resource URL\",\n    \"3-0\": \"Fields\",\n    \"1-1\": \"dashboard.annotation.edit\",\n    \"2-1\": \"https://app.klipfolio.com/api/1.0/klips/{id}/annotations/{id}\",\n    \"3-1\": \"body: \\\"\\\" // String, required.  Maximum 1024 characters.\\nNOTE 1: Editing an annotation does not update the date_created timestamp.\\nNOTE 2: The authenticated user must either be the creator of the annotation or have the \\\"admin.annotation\\\" permission to edit the annotation.\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n##Example Request \n```\nPUT https://app.klipfolio.com/api/1/klips/63d9abc8330ae256dac2e2f8c4371a8f/annotations -d \"{'body':'I am writing an annotation'}\" \n\n```\n##Example Response\n```\n{\n   \"data\": {},\n   \"meta\": {\n       \"status\": 200,\n       \"success\": true\n   }\n}\n```\n[block:api-header]\n{\n  \"type\": \"delete\",\n  \"title\": \"DELETE /klips/{id}/annotations/{id}\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Description\",\n    \"0-1\": \"Delete a specified annotation.\",\n    \"1-0\": \"Permissions\",\n    \"2-0\": \"Resource URL\",\n    \"3-0\": \"Fields\",\n    \"1-1\": \"dashboard.annotation.edit\",\n    \"2-1\": \"https://app.klipfolio.com/api/1.0/klips/{id}/annotations/{id}\",\n    \"3-1\": \"None.\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n##Example Request \n`DELETE https://app.klipfolio.com/api/1/klips/57ebf715c0fdd044e4191adaecb4fc6f/annotations/f1ea0a852348d0f606eabac4b2443477`\n\n##Example Response\n```\n{\n  \"meta\": {\n    \"success\": true,\n    \"status\": 200\n  },\n  \"data\": {}\n}\n```","excerpt":"Retrieve information on Klip annotations, create, update and delete annotations for specific Klips.","slug":"klip-annotations","type":"basic","title":"Klip Annotations"}

Klip Annotations

Retrieve information on Klip annotations, create, update and delete annotations for specific Klips.

[block:api-header] { "type": "get", "title": "GET /klips/{id}/annotations" } [/block] [block:parameters] { "data": { "0-0": "Description", "0-1": "Retrieve a list of annotations for a specified Klip.", "1-0": "Permissions", "2-0": "Resource URL", "3-0": "Parameters", "1-1": "dashboard.annotation.view", "2-1": "https://app.klipfolio.com/api/1.0/klips/{id}/annotations", "3-1": "start_date (accepts Unix time format)\nend_date (accepts Unix time format)\n\n**NOTE:** Specify either none, one or both. For example, if start_date is not specified, it will retrieve all from the beginning of time; if end_date is not specified, it will retrieve all until the current date/time." }, "cols": 2, "rows": 4 } [/block] ##Example Request `GET https://app.klipfolio.com/api/1/klips/57ebf715c0fdd044e4191adaecb4fc6f/annotations` ##Example Response ``` { "meta": { "success": true, "status": 200 }, "data": { "annotations": [ { "id": "12345eba2f065109fb88be86b2f9279e", "createdBy": { "id": "b1b1b11c7e4d34c6410d807564c470a7", "name": "Jane Doe" }, "date_created": "2016-06-21T13:18:30Z", "body": "Order status for June" }, { "id": "f1ea0a852348d0f606eabac4b2443477", "createdBy": { "id": "a5a9d31c7e4d34c6410d807564c470a7", "name": "Tamsin Douglas" }, "date_created": "2016-06-21T13:32:05Z", "body": "Check Florida." } ] } } ``` [block:api-header] { "type": "get", "title": "GET /klips/{id}/annotations/{id}" } [/block] [block:parameters] { "data": { "0-0": "Description", "0-1": "Retrieve the details of an annotation for a specified Klip.", "1-0": "Resource URL", "2-0": "Permissions", "3-0": "Parameters", "1-1": "https://app.klipfolio.com/api/1.0/klips/{id}/annotations/{id}", "2-1": "dashboard.annotation.view", "3-1": "None." }, "cols": 2, "rows": 4 } [/block] ##Example Request `GET https://app.klipfolio.com/api/1/klips/57ebf715c0fdd044e4191adaecb4fc6f/annotations/39874eba2f065109fb88be86b2f9279e` ##Example Response ``` { "meta": { "success": true, "status": 200 }, "data": { "id": "12345eba2f065109fb88be86b2f9279e", "createdBy": { "id": "b1b1b11c7e4d34c6410d807564c470a7", "name": "Jane Doe" }, "date_created": "2016-06-21T13:18:30Z", "body": "Order status for June" } } ``` [block:api-header] { "type": "post", "title": "POST /klips/{id}/annotations" } [/block] [block:parameters] { "data": { "0-0": "Description", "0-1": "Create a a new annotation for a specified Klip.", "1-1": "dashboard.annotation.edit", "2-1": "https://app.klipfolio.com/api/1.0/klips/{id}/annotations", "3-1": "body: \"\" // String, required. Maximum 1024 characters.\nNOTE: When creating an annotation, everything else uses a default: created_by is the authenticated user and date_created is the creation timestamp.", "1-0": "Permissions", "2-0": "Resource URL", "3-0": "Fields" }, "cols": 2, "rows": 4 } [/block] ##Example Request ``` POST https://app.klipfolio.com/api/1/klips/63d9abc8330ae256dac2e2f8c4371a8f/annotations -d "{'body':'I am writing an annotation'}" ``` ##Example Response { "meta": { "success":true, "status":201, "location":"/klips/63d9abc1234ae256dac2e2f8c4371a8f/annotations/23c618c919b1234d5f1d3359942559eb" }, "data":{} } ``` [block:api-header] { "type": "put", "title": "PUT /klips/{id}/annotations/{id}" } [/block] [block:parameters] { "data": { "0-0": "Description", "0-1": "Update a specified Klip annotation.", "1-0": "Permissions", "2-0": "Resource URL", "3-0": "Fields", "1-1": "dashboard.annotation.edit", "2-1": "https://app.klipfolio.com/api/1.0/klips/{id}/annotations/{id}", "3-1": "body: \"\" // String, required. Maximum 1024 characters.\nNOTE 1: Editing an annotation does not update the date_created timestamp.\nNOTE 2: The authenticated user must either be the creator of the annotation or have the \"admin.annotation\" permission to edit the annotation." }, "cols": 2, "rows": 4 } [/block] ##Example Request ``` PUT https://app.klipfolio.com/api/1/klips/63d9abc8330ae256dac2e2f8c4371a8f/annotations -d "{'body':'I am writing an annotation'}" ``` ##Example Response ``` { "data": {}, "meta": { "status": 200, "success": true } } ``` [block:api-header] { "type": "delete", "title": "DELETE /klips/{id}/annotations/{id}" } [/block] [block:parameters] { "data": { "0-0": "Description", "0-1": "Delete a specified annotation.", "1-0": "Permissions", "2-0": "Resource URL", "3-0": "Fields", "1-1": "dashboard.annotation.edit", "2-1": "https://app.klipfolio.com/api/1.0/klips/{id}/annotations/{id}", "3-1": "None." }, "cols": 2, "rows": 4 } [/block] ##Example Request `DELETE https://app.klipfolio.com/api/1/klips/57ebf715c0fdd044e4191adaecb4fc6f/annotations/f1ea0a852348d0f606eabac4b2443477` ##Example Response ``` { "meta": { "success": true, "status": 200 }, "data": {} } ```