{"_id":"590a04f5ed80861900cbc773","__v":0,"parentDoc":null,"project":"55b2d5baa74a380d00e290c4","category":{"_id":"590a04f3ed80861900cbc73a","__v":0,"project":"55b2d5baa74a380d00e290c4","version":"590a04f2ed80861900cbc737","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2016-04-22T20:33:51.487Z","from_sync":false,"order":2,"slug":"rest-api","title":"REST API"},"user":"55b2d5626862a10d00887af9","version":{"_id":"590a04f2ed80861900cbc737","project":"55b2d5baa74a380d00e290c4","__v":4,"createdAt":"2017-05-03T16:27:30.085Z","releaseDate":"2017-05-03T16:27:30.085Z","categories":["590a04f3ed80861900cbc738","590a04f3ed80861900cbc739","590a04f3ed80861900cbc73a","590a04f3ed80861900cbc73b","590a04f3ed80861900cbc73c","590a04f3ed80861900cbc73d","590a04f3ed80861900cbc73e","590a04f3ed80861900cbc73f","590a04f3ed80861900cbc740","590a04f3ed80861900cbc741","590a04f3ed80861900cbc742","590a04f3ed80861900cbc743","590a04f3ed80861900cbc744","590a04f3ed80861900cbc745","590a04f3ed80861900cbc746","590a04f3ed80861900cbc747","590a04f3ed80861900cbc748","590a04f3ed80861900cbc749","590a04f3ed80861900cbc74a","590a04f3ed80861900cbc74b","590a04f3ed80861900cbc74c","590a04f3ed80861900cbc74d","59124949de13f61900336a7a","5914b04e7c2c552d008b7104","5914b47242c6a22300b9dc20"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"7.0.0","version":"7"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-04-26T21:08:02.638Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":true,"order":0,"body":"[block:api-header]\n{\n  \"title\": \"Overview\"\n}\n[/block]\nThe buddybuild API is a RESTful interface, providing programmatic access to much of the data in the system. It provides predictable URLs for accessing resources, and uses built-in HTTP features to receive commands and return responses. This makes it easy to communicate with from a wide variety of environments, from command-line utilities to client libraries to apps.\n\nThe API accepts JSON or form-encoded content in requests and returns JSON content in all of its responses, including errors. Only the UTF-8 character encoding is supported for both requests and responses.\n\nAt this time the buddybuild API responds to a single version of the API. All resources are available under the `https://api.buddybuild.com/v1/` base URL.\n[block:api-header]\n{\n  \"title\": \"Authentication\"\n}\n[/block]\nEach user in buddybuild has their own unique *Personal Access Token*, which can be used to talk to buddybuild on behalf of the user.\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"To obtain your personal access token sign in to the buddybuild dashboard, hover over your profile icon and select *My Profile*, then select *Access Token* in the left menu. Or visit this direct link to <a href=\\\"https://dashboard.buddybuild.com/account/access-token\\\" target=\\\"_blank\\\">your personal access token</a>.\",\n  \"title\": \"Looking for your API access token?\"\n}\n[/block]\n\nPersonal access tokens should be used when accessing the API, passing them in the `Authorization` header. Remember to keep your token secret, treating it just like a password. It acts on your behalf when interacting with the API. Don’t hardcode them into your programs; instead opt to use them as environment variables.\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: Bearer ACCESS_TOKEN\\\" https://api.buddybuild.com/v1/apps\",\n      \"language\": \"curl\",\n      \"name\": \"Using personal access tokens in requests\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Percent Encoding\"\n}\n[/block]\nMany of the buddybuild API methods accept URL parameters that must be [percent encoded](https://en.wikipedia.org/wiki/Percent-encoding) to avoid conflicts with reserved characters. Reserved characters are those characters that sometimes have special meaning in a URL.\n\nFor example, when passing a Git branch named `feature/find&replace` as a `branch` parameter it must be percent encoded as `feature%2Ffind%26replace`.\n[block:api-header]\n{\n  \"title\": \"Errors\"\n}\n[/block]\nSometimes requests to the API are not successful. Failures can occur for a wide range of reasons. In all cases, the API returns an HTTP Status Code that indicates the reason for the failure, with a response body in JSON format containing additional information.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Code\",\n    \"h-2\": \"Description\",\n    \"h-1\": \"Reason\",\n    \"0-0\": \"200\",\n    \"1-0\": \"400\",\n    \"0-1\": \"OK\",\n    \"1-1\": \"Bad Request\",\n    \"0-2\": \"If data was requested, it will be available in the response body.\",\n    \"1-2\": \"This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.\",\n    \"2-0\": \"401\",\n    \"3-0\": \"404\",\n    \"2-2\": \"A valid API personal access token was not provided with the request, so the API could not associate a user with the request.\",\n    \"2-1\": \"Unauthorized\",\n    \"4-0\": \"500\",\n    \"4-2\": \"There was a problem on buddybuild’s end. Contact support.\",\n    \"3-2\": \"Either the request method and path supplied do not specify a known action in the API, or the object specified by the request does not exist.\",\n    \"3-1\": \"Not Found\",\n    \"4-1\": \"Server Error\",\n    \"6-2\": \"The buddybuild API server is temporarily unavailable because it is overloaded or down for maintenance. Check http://status.buddybuild.com/ for updates or contact support.\",\n    \"5-2\": \"The buddybuild API server is temporarily unavailable because it is overloaded or down for maintenance. Check http://status.buddybuild.com/ for updates or contact support.\",\n    \"5-0\": \"503\",\n    \"6-0\": \"504\",\n    \"5-1\": \"Service Unavailable\",\n    \"6-1\": \"Gateway Time-out\"\n  },\n  \"cols\": 3,\n  \"rows\": 7\n}\n[/block]\nIn the event of an error, the response body will contain an `error` field at the top level. This error message provides more detail about the error that occurred, if available.\n\n**Examples of common errors**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Request\\ncurl https://api.buddybuild.com/v1/apps\\n\\n# Response\\nHTTP/1.1 401 Unauthorized\\n{\\n  \\\"error\\\": \\\"No authorization token was found\\\"\\n}\",\n      \"language\": \"curl\",\n      \"name\": \"Missing authorization header\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Request\\ncurl -H \\\"Authorization: Bearer INVALID_TOKEN\\\" https://api.buddybuild.com/v1/apps\\n\\n# Response\\nHTTP/1.1 401 Unauthorized\\n{\\n  \\\"error\\\": \\\"Invalid authorization token\\\"\\n}\",\n      \"language\": \"curl\",\n      \"name\": \"Using an invalid or revoked access token\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"api-developer-guide","type":"basic","title":"Developer Guide"}
[block:api-header] { "title": "Overview" } [/block] The buddybuild API is a RESTful interface, providing programmatic access to much of the data in the system. It provides predictable URLs for accessing resources, and uses built-in HTTP features to receive commands and return responses. This makes it easy to communicate with from a wide variety of environments, from command-line utilities to client libraries to apps. The API accepts JSON or form-encoded content in requests and returns JSON content in all of its responses, including errors. Only the UTF-8 character encoding is supported for both requests and responses. At this time the buddybuild API responds to a single version of the API. All resources are available under the `https://api.buddybuild.com/v1/` base URL. [block:api-header] { "title": "Authentication" } [/block] Each user in buddybuild has their own unique *Personal Access Token*, which can be used to talk to buddybuild on behalf of the user. [block:callout] { "type": "info", "body": "To obtain your personal access token sign in to the buddybuild dashboard, hover over your profile icon and select *My Profile*, then select *Access Token* in the left menu. Or visit this direct link to <a href=\"https://dashboard.buddybuild.com/account/access-token\" target=\"_blank\">your personal access token</a>.", "title": "Looking for your API access token?" } [/block] Personal access tokens should be used when accessing the API, passing them in the `Authorization` header. Remember to keep your token secret, treating it just like a password. It acts on your behalf when interacting with the API. Don’t hardcode them into your programs; instead opt to use them as environment variables. [block:code] { "codes": [ { "code": "curl -H \"Authorization: Bearer ACCESS_TOKEN\" https://api.buddybuild.com/v1/apps", "language": "curl", "name": "Using personal access tokens in requests" } ] } [/block] [block:api-header] { "title": "Percent Encoding" } [/block] Many of the buddybuild API methods accept URL parameters that must be [percent encoded](https://en.wikipedia.org/wiki/Percent-encoding) to avoid conflicts with reserved characters. Reserved characters are those characters that sometimes have special meaning in a URL. For example, when passing a Git branch named `feature/find&replace` as a `branch` parameter it must be percent encoded as `feature%2Ffind%26replace`. [block:api-header] { "title": "Errors" } [/block] Sometimes requests to the API are not successful. Failures can occur for a wide range of reasons. In all cases, the API returns an HTTP Status Code that indicates the reason for the failure, with a response body in JSON format containing additional information. [block:parameters] { "data": { "h-0": "Code", "h-2": "Description", "h-1": "Reason", "0-0": "200", "1-0": "400", "0-1": "OK", "1-1": "Bad Request", "0-2": "If data was requested, it will be available in the response body.", "1-2": "This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.", "2-0": "401", "3-0": "404", "2-2": "A valid API personal access token was not provided with the request, so the API could not associate a user with the request.", "2-1": "Unauthorized", "4-0": "500", "4-2": "There was a problem on buddybuild’s end. Contact support.", "3-2": "Either the request method and path supplied do not specify a known action in the API, or the object specified by the request does not exist.", "3-1": "Not Found", "4-1": "Server Error", "6-2": "The buddybuild API server is temporarily unavailable because it is overloaded or down for maintenance. Check http://status.buddybuild.com/ for updates or contact support.", "5-2": "The buddybuild API server is temporarily unavailable because it is overloaded or down for maintenance. Check http://status.buddybuild.com/ for updates or contact support.", "5-0": "503", "6-0": "504", "5-1": "Service Unavailable", "6-1": "Gateway Time-out" }, "cols": 3, "rows": 7 } [/block] In the event of an error, the response body will contain an `error` field at the top level. This error message provides more detail about the error that occurred, if available. **Examples of common errors** [block:code] { "codes": [ { "code": "# Request\ncurl https://api.buddybuild.com/v1/apps\n\n# Response\nHTTP/1.1 401 Unauthorized\n{\n \"error\": \"No authorization token was found\"\n}", "language": "curl", "name": "Missing authorization header" } ] } [/block] [block:code] { "codes": [ { "code": "# Request\ncurl -H \"Authorization: Bearer INVALID_TOKEN\" https://api.buddybuild.com/v1/apps\n\n# Response\nHTTP/1.1 401 Unauthorized\n{\n \"error\": \"Invalid authorization token\"\n}", "language": "curl", "name": "Using an invalid or revoked access token" } ] } [/block]