{"id":21944709,"url":"https://github.com/browserstack/api","last_synced_at":"2025-03-22T16:15:18.222Z","repository":{"id":41159268,"uuid":"2555313","full_name":"browserstack/api","owner":"browserstack","description":"Spec of latest BrowserStack JavaScript testing api","archived":false,"fork":false,"pushed_at":"2023-07-03T12:13:28.000Z","size":66,"stargazers_count":120,"open_issues_count":15,"forks_count":37,"subscribers_count":34,"default_branch":"v5","last_synced_at":"2025-03-19T06:51:43.631Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.browserstack.com/javascript-testing-api","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/browserstack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-10-11T13:10:47.000Z","updated_at":"2025-03-18T17:04:16.000Z","dependencies_parsed_at":"2022-08-04T14:30:14.114Z","dependency_job_id":null,"html_url":"https://github.com/browserstack/api","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browserstack%2Fapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browserstack%2Fapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browserstack%2Fapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browserstack%2Fapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/browserstack","download_url":"https://codeload.github.com/browserstack/api/tar.gz/refs/heads/v5","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244982057,"owners_count":20542300,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-29T04:16:56.747Z","updated_at":"2025-03-22T16:15:18.171Z","avatar_url":"https://github.com/browserstack.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# API Overview\n\nThe following denotes the HTTPS-based API for [BrowserStack](https://www.browserstack.com). It provides browser-as-a-service for automated cross-browser testing. The goal is to provide a simple service which can easily be used by any browser testing framework.\n\n## Authentication\n\nAll methods need to authenticate who you are, before spawning browser workers and deleting a worker for example. Authentication is done using your username and the BrowserStack access key within the HTTP request.\n\nFor example:\n\n```bash\ncurl -u \"username:access_key\" https://api.browserstack.com/5\n```\n\n\u003e Note: _A `401 Unauthorized` response is received if an unauthorized request is made._\n\n## Schema\n\nAll requests are made to `https://api.browserstack.com/VERSION/` and all returned data is done so in JSON-format. This documentation outlines version 5.\n\n```bash\ncurl -i -u \"username:access_key\" https://api.browserstack.com/5\n```\n\nResponse:\n\n```http\nHTTP/1.1 200 OK\nContent-Type: application/json; charset=utf8\nStatus: 200 OK\nX-API-Version: 5\n\n{}\n```\n\nAll date formats are given in ISO-8601 which can be processed natively with `Date.parse` in compatible JavaScript environments.\n\n## Error Handling\n\nAll requests are pre-processed and validated. This section outlines how we handle errors within the API and respond to them.\n\nAll API requests are validated. The following is an example output for a required parameter that wasn't given.\n\n```http\nHTTP/1.1 422 Unprocessable Entity\nContent-Length: 136\n\n{\n  \"message\": \"Validation Failed\",\n  \"errors\": [\n    {\n      \"field\": \"type\",\n      \"code\": \"required\"\n    }\n  ]\n}\n```\n\nPossible error codes are `required` and `invalid`.\n\n## HTTP Verbs\n\nThe API is kept concise and simple by making use of relevant HTTP verbs on each request. The specifications for these are vague and their use within this API is specific but in general, we follow the following rules:\n\n* `HEAD` - Performs the request to assess the status of a resource and expects no content response.\n* `GET` - Used to retrieve resources.\n* `POST` - Used to create new resources.\n* `PUT` - Used to update resources.\n* `DELETE` - Used to delete resources.\n\n# API v5 Documentation\n\n## Getting Available Browsers\n\nFetches all available browsers.\n\n```http\nGET /browsers\n```\n\nFor example:\n\n```bash\ncurl -u \"username:access_key\" https://api.browserstack.com/5/browsers\n```\n\nOutput:\n\n```javascript\n{\n  'Windows':\n    {\n      '10':\n        [\n          {\n            \"browser\": \"chrome\",\n            \"browser_version\": \"83.0\"\n          },\n          {\n            \"browser\": \"chrome\",\n            \"browser_version\": \"84.0\"\n          },\n          {\n            \"browser\": \"chrome\",\n            \"browser_version\": \"85.0 beta\"\n          },\n          {\n            \"browser\": \"ie\",\n            \"browser_version\": \"11.0\"\n          },\n          {\n            \"browser\": \"edge\",\n            \"browser_version\": \"insider preview\"\n          }...\n        ],\n    },\n  'OS X':\n    {\n      'Catalina':\n        [\n          {\n            \"browser\": \"chrome\",\n            \"browser_version\": \"85.0 beta\"\n          },\n          {\n            \"browser\": \"edge\",\n            \"browser_version\": \"85.0 beta\"\n          },\n          {\n            \"browser\": \"safari\",\n            \"browser_version\": \"13.1\"\n          },\n          {\n            \"browser\": \"firefox\",\n            \"browser_version\": \"79.0\"\n          },\n          {\n            \"browser\": \"firefox\",\n            \"browser_version\": \"80.0 beta\"\n          }...\n        ],\n      }...\n    },\n}\n```\n\nA flat parameter can also be passed to get browsers in a flat structure\n\n```http\nGET /browsers?flat=true\n```\n\nFor example:\n\n```bash\ncurl -u \"username:access_key\" https://api.browserstack.com/5/browsers?flat=true\n```\n\nOutput:\n\n```javascript\n[  \n  {\n    \"os\": \"Windows\",\n    \"os_version\": \"10\",\n    \"browser\": \"chrome\",\n    \"device\": null,\n    \"browser_version\": \"84.0\",\n    \"real_mobile\": null\n  },\n  {\n    \"os\": \"Windows\",\n    \"os_version\": \"10\",\n    \"browser\": \"edge\",\n    \"device\": null,\n    \"browser_version\": \"85.0 beta\",\n    \"real_mobile\": null\n  },\n  {\n    \"os\": \"OS X\",\n    \"os_version\": \"Catalina\",\n    \"browser\": \"firefox\",\n    \"device\": null,\n    \"browser_version\": \"79.0\",\n    \"real_mobile\": null\n  },\n  {\n    \"os\": \"OS X\",\n    \"os_version\": \"Catalina\",\n    \"browser\": \"firefox\",\n    \"device\": null,\n    \"browser_version\": \"80.0 beta\",\n    \"real_mobile\": null\n  }....\n]\n```\n\n## Create a New Browser Worker\n\nA browser worker is simply a new browser instance. A user can start multiple browser worker at a time.\nAll browser workers when created are pushed in a queue and they run when their turn comes. We make sure that your browser worker starts running as soon as possible. Your testing time is calculated from the time when browser worker starts running.\n\n```http\nPOST /worker\n```\n\n\u003e Note: _This call requires authentication. A `401 Unauthorized` response is given if an unauthorized request is made._\n\nFor example:\n\n```bash\ncurl -u \"username:access_key\" -X POST -d '{\"os\":\"OS X\",\"os_version\":\"Mojave\",\"url\":\"https://browserstack.com\",\"browser\":\"chrome\",\"browser_version\":\"75.0\"}' https://api.browserstack.com/5/worker -H 'content-type: application/json'\n```\n\nResponse:\n\n```bash\n{\"id\":123456789,\"url\":\"https://browserstack.com\"}\n```\n\nOnce a worker has been spawned you can then control this browser instance remotely. You can also look at the testing session status at the [Automate Dashboard](https://automate.browserstack.com/dashboard). This will provide you with the general details about the session and a live preview of the remote machine.\n\n### Parameters\n\nA valid request for Desktop OS must contain `os`, `os_version`, `url`, `browser` and `browser_version`.\n\nFor Mobile OS, `browser` and `browser_version` are optional.\n\n`timeout` is optional but defaults to 300 seconds.\n\n#### `os`\n\nA valid OS. A list of supported OSs is given using the `GET /browsers`. See the [Getting Available Browsers](#getting-available-browsers) above for details.\n\n#### `os_version`\n\nA valid OS Version. A list of supported OS Versions is given using the `GET /browsers`. See the [Getting Available Browsers](#getting-available-browsers) above for details.\n\n#### `browser`\n\nA valid browser. A list of supported browsers is given using the `GET /browsers`. See the [Getting Available Browsers](#getting-available-browsers) above for details.\n\n#### `device`\n\nA valid device. A list of supported devices is given using the `GET /browsers`. If a device is not provided it defaults to the first device available for that os version. See the [Getting Available Browsers](#getting-available-browsers) above for details.\n\n#### `browser_version`\n\nA valid browser version. A list of supported browser versions is given using the `GET /browsers`.  See the [Getting Available Browsers](#getting-available-browsers) above for details.\n\n#### `(timeout=300)`\n\nTime in seconds before the worker is terminated. The default value is 300 seconds and the minimum value is 60 seconds.\n\n\u003e **IMPORTANT!** Irrespective of the `timeout` parameter, a browser worker is alive for a maximum time of 1800 seconds.\n\n#### `(url)`\n\nA valid url to navigate the browser to.\n\u003e Make sure the url is encoded. JavaScript: encodeURI(url), PHP: urlencode($url),\n\n#### `(name)`\n\nProvide a name to the session/worker.\n\n#### `(build)`\n\nOptional name of the build the session is running under.\n\n#### `(project)`\n\nOptional name of the project the build is under.\n\n#### `(browserstack.video)`\n\nOptional flag to enable video recording in your test.\n\n#### `(resolution)`\n\nSet the resolution of VM before the beginning of your test. Available for Desktop only. Default is 1024x768.\n\n| _OS_ | _Supported Resolutions_ |\n|:--------|:---------|\n|Windows (XP,7)| 800x600, 1024x768, 1280x800, 1280x1024, 1366x768, 1440x900, 1680x1050, 1600x1200, 1920x1200, 1920x1080, 2048x1536|\n|Windows (8,8.1,10)| 1024x768, 1280x800, 1280x1024, 1366x768, 1440x900, 1680x1050, 1600x1200, 1920x1200, 1920x1080, 2048x1536|\n|OS X| 1024x768, 1280x960, 1280x1024, 1600x1200, 1920x1080|\n\n### Response\n\nThe response will be returned when the worker has been set up and initialized. This involves loading the HTML data or navigating to the url given depending on the setup parameters. Use the `id` returned to perform any further communications etc.\n\n```http\nHTTP/1.1 200 Success\nContent-Type: application/json\nX-API-Version: 5\n\n{\n  \"id\": \"123456789\"\n}\n```\n\n### Screenshots\n\nUse this method to take a screenshot at the current state of the worker.\n\n```http\nGET /worker/\u003cid\u003e/screenshot(.format)\n```\n\nAcceptable formats are `json`, `xml` and `png`. This information can also be provided via the HTTP `Accept` headers: `text/json`, `text/xml`, `image/png` respectively.\n\nFor example:\n\n```bash\ncurl -u \"username:access_key\" https://api.browserstack.com/5/worker/123456789/screenshot.json\n```\n\n## Get Details of all Browser Workers\nReturns comprehensive information, such as, worker ID, browser URL, session ID, etc., for all the browser workers you've created. It also returns the current status of the workers, which can be either `queue` or `running`.\n \n```http\nGET /workers\n```\n### Example request:\n```bash\ncurl -u \"username:access_key\" -X GET https://api.browserstack.com/5/workers \n```\n \n### Example response:\n```javascript\n[\n  {\n   \"id\": \"\u003cworkerId\u003e\",\n   \"status\": \"running\",\n   \"os\": \"OS X\",\n   \"os_version\": \"Mojave\",\n   \"browser\": \"chrome\",\n   \"browser_version\": \"75.0\",\n   \"real_mobile\": null,\n   \"device\": null,\n   \"browser_url\": \"\u003cdashboard_url_of_the_session\u003e\",\n   \"sessionId\": \"\u003csessionId\u003e\"\n  },\n {\n    \"id\": \"\u003cworkerId\u003e\",\n    \"status\": \"queue\",\n    \"os\": \"android\",\n    \"os_version\": \"2.2\",\n    \"device\": \"Samsung Galaxy S\",\n    \"browser\": \"Android Browser\",\n    \"browser_version\": null,\n    \"real_mobile\": false,\n    \"browser_url\": \"\u003cdashboard_url_of_the_session\u003e\",\n    \"sessionId\": \"\u003csessionId\u003e\"\n  } ...]\n```\n\n## Terminating a Browser Worker\n\nUse this method to terminate a worker. Useful if you set the worker up to run indefinitely or if you've received all the information needed and you want to save on credit time.\n\n```http\nDELETE  /worker/\u003cid\u003e\n```\n\nThe `id` is the id returned when you first created the worker. Once called the browser instance will be immediately terminated and will no longer be accessible.\n\n\u003e Note: _This call requires authentication. If the request was made unauthorized a `401 Unauthorized` response is given. Alternatively, if the authorized user is not the owner of the worker or `id` does not exist a `403 Forbidden` response is given. Also, if this request is sent within 60 seconds of starting the worker, the response will be `422 Unprocessable Entity` and the worker will be terminated after 60 seconds of its running time._\n\nFor example:\n\n```bash\ncurl -u \"username:access_key\" -X DELETE https://api.browserstack.com/5/worker/123456789\n```\n\n## Getting Worker Status\n\nSometimes you will need to check on the status of a worker. Not to be confused with the state of the javascript environment within the worker, this method simply determines whether the worker is in the queue, running or terminated.\n\n```http\nGET /worker/\u003cid\u003e\n```\n\n\u003e _This call requires authentication. If the request was made unauthorized a `401 Unauthorized` response is given. Alternatively, if the authorized user is not the owner of the worker a `403 Forbidden` response is given._\n\nFor example:\n\n```bash\ncurl -u \"username:access_key\" https://api.browserstack.com/5/worker/123456789\n```\n\nIf the worker has been terminated an empty response is given. Otherwise, you get a response with status and browser details.\n\n```javascript\n{\n  status: 'running',\n  browser: 'ie',\n  browser_version: '6.0',\n  os: 'Windows',\n  os_version: 'XP',\n  sessionId: \"\u003csessionId\u003e\",\n  browser_url: \"\u003cdashboard url for the session\u003e\"\n}\n```\n\nIf you want to know the list of your current workers with their status, use the following method.\n\n```http\nGET /workers\n```\n\nThis method will return the list of workers whose status is either `queue` or `running`.\n\nFor example:\n\n```bash\ncurl -u \"username:access_key\" https://api.browserstack.com/5/workers\n```\n\nResponse:\n\n```javascript\n[\n  {\n    status: 'running',\n    browser: 'ie',\n    version: '6.0',\n    os: 'Windows',\n    os_version: 'XP',\n    sessionId: \"\u003csessionId\u003e\",\n    browser_url: \"\u003cdashboard url for the session\u003e\"\n  },\n  {\n    status: 'queue',\n    device: 'Samsung Galaxy Tab 8.9',\n    os: 'android',\n    os_version: '2.2',\n    sessionId: \"\u003csessionId\u003e\",\n    browser_url: \"\u003cdashboard url for the session\u003e\"\n  } ...\n]\n```\n\n## Getting API Status\n\nIf you want to know the status of your API, use the following method\n\n```http\nGET /status\n```\n\nThis will return the current status of API, like how much API time has been used and how many workers are running parallelly. All the paid plans have no time limits, only limit on parallel workers you can create.\n\nFor example:\n\n```bash\ncurl -u \"username:access_key\" https://api.browserstack.com/5/status\n```\n\n```javascript\n  {\n    used_time: 4235.4,\n    total_available_time: 6000,\n    running_sessions: 1,\n    sessions_limit: 1\n  }\n```\n\nThe time returned is in seconds.\n\nIf a user runs out of API time, all requests will return the following response\n\n```javascript\n{\n  message: \"You have run out of API time\"\n}\n```\n\n\u003e **Note**: _You can make up to 1600 API requests every 5 minutes._\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrowserstack%2Fapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrowserstack%2Fapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrowserstack%2Fapi/lists"}