{"_id":"5435693035740020002a1c22","is_link":false,"sync_unique":"","title":"Getting Started","type":"basic","version":"5435693035740020002a1c1f","api":{"results":{"codes":[]},"settings":"","try":true,"url":"","auth":"never","basic_auth":false,"params":[]},"category":"5435693035740020002a1c20","excerpt":"Robin's API gives developers the power to interact with their team's data (locations, spaces, presence, etc.) and build third-party applications to extend Robin's capabilities.","isReference":false,"project":"5435693035740020002a1c1c","user":"543568c135740020002a1c10","__v":40,"order":0,"slug":"getting-started","hidden":false,"link_url":"","githubsync":"","link_external":false,"next":{"description":"","pages":[]},"parentDoc":null,"updates":[],"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"We're building fast, and even though we're clever you should expect bugs. Breaking changes may be deployed at any time, but we'll update here when that happens. \\n\\nIf you have issues using the API, discover inaccuracies with this documentation, or have ideas or requests for features not currently supported by the API, send us a note at [support:::at:::robinpowered.com](mailto:support+api@robinpowered.com?subject=API Help).\",\n  \"title\": \"This is a beta\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"- The `next_event` and `current_event` properties currently returned in the Event model are deprecated and will be removed in a future release. We recommend using the space \\\"state\\\" submodel and the Free/Busy APIs as replacements, depending on your use case.\\n- The `GET /free-busy/spaces` endpoints will be removed some time in the future. Please use the `POST /free-busy/spaces` endpoint instead.\\n- Event properties `started_at` and `ended_at` will be removed some time in the future. Please use `start` and `end` instead.\\n- The `?include=amenities` submodel for spaces will be removed some time in the future. Please use `?include=space_amenities` instead.\",\n  \"title\": \"Deprecations and future breaking changes\"\n}\n[/block]\n## Base URL\n\nAll requests should be made to `https://api.robinpowered.com/v1.0`. Please note that this may change with future releases of the API.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Authorization\"\n}\n[/block]\nEvery API request must contain an `Authorization` header with a valid access token. You'll need one to get started.\n\n## Get your token\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"At a Hackathon?\",\n  \"body\": \"You can skip this step and use your event's custom link to generate your token instead. #easy\"\n}\n[/block]\nLog into the web dashboard and generate a new token via [your team's integration settings](https://dashboard.robinpowered.com/redirect/:orgid/settings/integrations). (**Note:** *You must be an administrator*)\n\n## Example Authorization header\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Authorization: Access-Token [[app:Token]]\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Standard CURL request with authorization header\\ncurl -X GET https://api.robinpowered.com/v1.0/spaces/:id\\n    -H \\\"Authorization: Access-Token [[app:Token]]\\\"\",\n      \"language\": \"curl\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Response structure\"\n}\n[/block]\nAll API responses share a basic JSON structure. The response is always an object with two properties `meta` and `data` and a conditional third property, `paging`. \n\nThe examples below show what full responses looks like:\n\n## Success\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"meta\\\": {\\n    \\\"status_code\\\": 200,\\n    \\\"status\\\": \\\"OK\\\",\\n    \\\"message\\\": \\\"\\\",\\n    \\\"more_info\\\": {}\\n  },\\n  \\\"data\\\": [\\n    {\\n      \\\"space_id\\\": 1,\\n      \\\"user_id\\\": 9,\\n      \\\"last_seen_at\\\": \\\"2014-05-22T14:49:48+0000\\\",\\n      \\\"arrived_at\\\": \\\"2014-05-22T14:49:48+0000\\\",\\n      \\\"session_ttl\\\": 30,\\n      \\\"session_active\\\": true,\\n      \\\"user\\\": {\\n        \\\"id\\\": 1,\\n        \\\"access_level\\\": 9001,\\n        \\\"name\\\": \\\"George Jetson\\\",\\n        \\\"slug\\\": \\\"gjetson\\\",\\n        \\\"avatar\\\": \\\"\\\",\\n        \\\"created_at\\\": \\\"2014-05-05T16:06:58+0000\\\",\\n        \\\"updated_at\\\": \\\"2014-05-05T16:06:58+0000\\\",\\n        \\\"primary_email\\\": {\\n          \\\"email\\\": \\\"gjetson@robinpowered.com\\\",\\n          \\\"is_verified\\\": true\\n        }\\n      }\\n    }\\n  ],\\n  \\\"paging\\\": {\\n    \\\"page\\\": 1,\\n    \\\"per_page\\\": 10\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n## Error\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n   \\\"meta\\\":{\\n      \\\"status_code\\\":400,\\n      \\\"status\\\":\\\"INVALID_PARAMETERS\\\",\\n      \\\"message\\\":\\\"The posted data did not pass validation\\\",\\n      \\\"more_info\\\":{\\n         \\\"name\\\":[\\n            \\\"can't be blank\\\"\\n         ]\\n      }\\n   },\\n   \\\"data\\\":{\\n\\n   }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n## Common response codes\n\n### Success\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"`200`\",\n    \"0-1\": \"`SUCCESS`\",\n    \"1-0\": \"`201`\",\n    \"1-1\": \"`CREATED`\",\n    \"h-0\": \"Response Code\",\n    \"h-1\": \"Title\",\n    \"h-2\": \"Meaning\",\n    \"0-2\": \"The response completed successfully\",\n    \"1-2\": \"The request was a successful and a new resource was created as a result.\"\n  },\n  \"cols\": 3,\n  \"rows\": 2\n}\n[/block]\n### Error: \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Response Code\",\n    \"h-1\": \"Title\",\n    \"h-2\": \"Meaning\",\n    \"0-0\": \"`400`\",\n    \"0-1\": \"`BAD_REQUEST`\",\n    \"0-2\": \"There was an error in the request parameters. This error is most commonly send when trying to create or modify a resource with invalid attributes.\",\n    \"1-0\": \"`401`\",\n    \"1-1\": \"`UNAUTHORIZED`\",\n    \"1-2\": \"The `Authorization` header is missing or invalid.\",\n    \"2-0\": \"`403`\",\n    \"2-1\": \"`FORBIDDEN`\",\n    \"2-2\": \"The authorized entity is not permitted to view or modify a resource.\",\n    \"3-0\": \"`404`\",\n    \"3-1\": \"`NOT_FOUND`\",\n    \"3-2\": \"The resource does not exist.\"\n  },\n  \"cols\": 3,\n  \"rows\": 4\n}\n[/block]\n## HTTP request methods\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Method\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"`GET`\",\n    \"1-0\": \"`POST`\",\n    \"2-0\": \"`PUT`\",\n    \"3-0\": \"`PATCH`\",\n    \"4-0\": \"`DELETE`\",\n    \"0-1\": \"Retrieves a resource\",\n    \"1-1\": \"Creates a resource\",\n    \"2-1\": \"Creates or replaces a resource\",\n    \"3-1\": \"Updates an existing resource\",\n    \"4-1\": \"Removes a resource\"\n  },\n  \"cols\": 2,\n  \"rows\": 5\n}\n[/block]","createdAt":"2014-10-08T16:41:20.812Z","childrenPages":[]}

Getting Started

Robin's API gives developers the power to interact with their team's data (locations, spaces, presence, etc.) and build third-party applications to extend Robin's capabilities.

[block:callout] { "type": "warning", "body": "We're building fast, and even though we're clever you should expect bugs. Breaking changes may be deployed at any time, but we'll update here when that happens. \n\nIf you have issues using the API, discover inaccuracies with this documentation, or have ideas or requests for features not currently supported by the API, send us a note at [support@robinpowered.com](mailto:support+api@robinpowered.com?subject=API Help).", "title": "This is a beta" } [/block] [block:callout] { "type": "danger", "body": "- The `next_event` and `current_event` properties currently returned in the Event model are deprecated and will be removed in a future release. We recommend using the space \"state\" submodel and the Free/Busy APIs as replacements, depending on your use case.\n- The `GET /free-busy/spaces` endpoints will be removed some time in the future. Please use the `POST /free-busy/spaces` endpoint instead.\n- Event properties `started_at` and `ended_at` will be removed some time in the future. Please use `start` and `end` instead.\n- The `?include=amenities` submodel for spaces will be removed some time in the future. Please use `?include=space_amenities` instead.", "title": "Deprecations and future breaking changes" } [/block] ## Base URL All requests should be made to `https://api.robinpowered.com/v1.0`. Please note that this may change with future releases of the API. [block:api-header] { "type": "basic", "title": "Authorization" } [/block] Every API request must contain an `Authorization` header with a valid access token. You'll need one to get started. ## Get your token [block:callout] { "type": "success", "title": "At a Hackathon?", "body": "You can skip this step and use your event's custom link to generate your token instead. #easy" } [/block] Log into the web dashboard and generate a new token via [your team's integration settings](https://dashboard.robinpowered.com/redirect/:orgid/settings/integrations). (**Note:** *You must be an administrator*) ## Example Authorization header [block:code] { "codes": [ { "code": "Authorization: Access-Token [[app:Token]]", "language": "curl" } ] } [/block] [block:code] { "codes": [ { "code": "# Standard CURL request with authorization header\ncurl -X GET https://api.robinpowered.com/v1.0/spaces/:id\n -H \"Authorization: Access-Token [[app:Token]]\"", "language": "curl" } ], "sidebar": true } [/block] [block:api-header] { "type": "basic", "title": "Response structure" } [/block] All API responses share a basic JSON structure. The response is always an object with two properties `meta` and `data` and a conditional third property, `paging`. The examples below show what full responses looks like: ## Success [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"status_code\": 200,\n \"status\": \"OK\",\n \"message\": \"\",\n \"more_info\": {}\n },\n \"data\": [\n {\n \"space_id\": 1,\n \"user_id\": 9,\n \"last_seen_at\": \"2014-05-22T14:49:48+0000\",\n \"arrived_at\": \"2014-05-22T14:49:48+0000\",\n \"session_ttl\": 30,\n \"session_active\": true,\n \"user\": {\n \"id\": 1,\n \"access_level\": 9001,\n \"name\": \"George Jetson\",\n \"slug\": \"gjetson\",\n \"avatar\": \"\",\n \"created_at\": \"2014-05-05T16:06:58+0000\",\n \"updated_at\": \"2014-05-05T16:06:58+0000\",\n \"primary_email\": {\n \"email\": \"gjetson@robinpowered.com\",\n \"is_verified\": true\n }\n }\n }\n ],\n \"paging\": {\n \"page\": 1,\n \"per_page\": 10\n }\n}", "language": "json" } ] } [/block] ## Error [block:code] { "codes": [ { "code": "{\n \"meta\":{\n \"status_code\":400,\n \"status\":\"INVALID_PARAMETERS\",\n \"message\":\"The posted data did not pass validation\",\n \"more_info\":{\n \"name\":[\n \"can't be blank\"\n ]\n }\n },\n \"data\":{\n\n }\n}", "language": "json" } ] } [/block] ## Common response codes ### Success [block:parameters] { "data": { "0-0": "`200`", "0-1": "`SUCCESS`", "1-0": "`201`", "1-1": "`CREATED`", "h-0": "Response Code", "h-1": "Title", "h-2": "Meaning", "0-2": "The response completed successfully", "1-2": "The request was a successful and a new resource was created as a result." }, "cols": 3, "rows": 2 } [/block] ### Error: [block:parameters] { "data": { "h-0": "Response Code", "h-1": "Title", "h-2": "Meaning", "0-0": "`400`", "0-1": "`BAD_REQUEST`", "0-2": "There was an error in the request parameters. This error is most commonly send when trying to create or modify a resource with invalid attributes.", "1-0": "`401`", "1-1": "`UNAUTHORIZED`", "1-2": "The `Authorization` header is missing or invalid.", "2-0": "`403`", "2-1": "`FORBIDDEN`", "2-2": "The authorized entity is not permitted to view or modify a resource.", "3-0": "`404`", "3-1": "`NOT_FOUND`", "3-2": "The resource does not exist." }, "cols": 3, "rows": 4 } [/block] ## HTTP request methods [block:parameters] { "data": { "h-0": "Method", "h-1": "Description", "0-0": "`GET`", "1-0": "`POST`", "2-0": "`PUT`", "3-0": "`PATCH`", "4-0": "`DELETE`", "0-1": "Retrieves a resource", "1-1": "Creates a resource", "2-1": "Creates or replaces a resource", "3-1": "Updates an existing resource", "4-1": "Removes a resource" }, "cols": 2, "rows": 5 } [/block]