canonical: https://jentic.com/apis/browserstack.com/browserstack

# BrowserStack Automate API

Jentic publishes the only available OpenAPI specification for BrowserStack Automate API, keeping it validated and agent-ready. BrowserStack Automate gives QA teams thousands of real desktop and mobile browser instances to run Selenium, Cypress, and Appium tests against. The Automate REST API exposes the metadata layer behind those test runs - projects, builds, individual sessions, log artefacts (Selenium, Appium, network, console), and media uploads - so teams can list past runs, mark sessions pass or fail from CI, fetch logs for failure analysis, and clean up old projects programmatically.

## For AI agents

Manage BrowserStack Automate projects, builds, and sessions, fetch test logs and videos, and update session status from CI. Useful for QA teams orchestrating cross-browser test runs and triaging failures.

## Scope

Does not handle starting Selenium sessions (those use the WebDriver hub URL), App Live, Live, or Percy - use for Automate project, build, session, and log management only.

## Capabilities

- List projects, builds, and sessions to surface a CI dashboard of recent BrowserStack runs
- Update session status to passed or failed from a CI step so the Automate dashboard reflects the assertion outcome
- Fetch Selenium, Appium, network, console, and profiling logs for any failed session
- Tag builds with build numbers or branch names so test runs are searchable across releases
- Upload media files for tests that need to consume images, PDFs, or videos as input
- Clean up old projects and builds in bulk to control storage and keep the dashboard tidy
- Read the active automate plan and supported browser/device matrix before scheduling a parallel run

## Use cases

### Marking Session Pass/Fail from CI

QA pipelines call PUT `/automate/sessions/{sessionId}/status` at the end of each test to mark the BrowserStack session as passed or failed based on the test framework's assertion result. This makes the Automate dashboard match the truth in CI rather than relying solely on Selenium's exit signal, which can mark a session passed even when the assertions failed inside the test body.

Example prompt: PUT `/automate/sessions/{sessionId}/status` with {status: 'failed', reason: 'AssertionError: expected 200 got 500'} after the test reporter completes

### Failure Triage with Network and Console Logs

When a flaky cross-browser test fails on Safari but passes on Chrome, an engineer needs the network calls and console errors from that exact run to debug. The agent calls GET `/automate/sessions/{sessionId}/networklogs` and /consolelogs and posts the relevant excerpts into the bug report, so the next person to pick up the ticket has everything they need without re-running the test.

Example prompt: GET `/automate/sessions/{sessionId}/networklogs` and GET `/automate/sessions/{sessionId}/consolelogs` for a failed session and attach the JSON to the Jira ticket

### Tagging Builds with Release Metadata

Release managers tag every BrowserStack build with the git branch and commit so they can later pull all sessions for release v3.4.2 from the API. PUT `/automate/builds/{buildId}/tags` accepts an array of tag strings; combined with GET `/automate/builds.json` with a tag filter, this enables release-centric reporting on top of the Automate dashboard.

Example prompt: PUT `/automate/builds/{buildId}/tags` with ['release-v3.4.2', 'main'] after the CI job records the build id

### AI QA Triage Agent Through Jentic

An AI QA agent uses Jentic to triage flaky test runs without holding the BrowserStack username and access key. The agent searches for 'fetch logs for a failed BrowserStack session', loads the schema, and pulls Selenium, network, and console logs in parallel. It then summarises the likely root cause and posts to Slack, so engineers wake up to a triaged failure rather than a raw red CI badge.

Example prompt: Use Jentic to search 'fetch BrowserStack session logs', load the browserstack.com operations, and execute /networklogs, /consolelogs, and /seleniumlogs for the failed session

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| PUT | `/automate/sessions/{sessionId}/status` | Update session pass/fail status |
| GET | `/automate/sessions/{sessionId}/networklogs` | Fetch HAR-style network logs for a session |
| GET | `/automate/sessions/{sessionId}/consolelogs` | Fetch browser console logs |
| GET | `/automate/sessions/{sessionId}/seleniumlogs` | Fetch Selenium command logs |
| PUT | `/automate/builds/{buildId}/tags` | Tag a build with release metadata |
| GET | `/automate/builds.json` | List builds, optionally filtered |
| POST | `/automate/upload-media` | Upload a media file for tests |
| GET | `/automate/plan.json` | Get active plan and parallel session limits |

## Key resources

- **Plan** — Active BrowserStack Automate plan and parallel session limits
- **Browsers** — Supported browser and device matrix
- **Projects** — Top-level grouping of related test runs
- **Builds** — Logical bundles of sessions for a CI run
- **Sessions** — Individual test runs with logs, video, and metadata
- **Logs** — Selenium, Appium, network, console, and profiling logs
- **Media Files** — Upload and reuse input media for tests

## Why Jentic

- **Setup:** Wiring BrowserStack Automate by hand means supplying basic-auth username and access key on every request and coordinating build, session, and log endpoints yourself. Through Jentic you install once, import the BrowserStack Automate API from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** Automate puts the session and build ids in the URL path (`/automate/sessions/{sessionId}/...`, `/automate/builds/{buildId}/...`), so a rule can pin your agent to one session: it can read that session's network, console, and selenium logs and nothing else. You choose the operations it may call, so a write like marking a session's status or tagging a build is not included unless you add it.
- **Credential handling:** Your BrowserStack username and access key are stored once, encrypted, by your own Jentic One instance and injected as the basic-auth header at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'fetch BrowserStack session logs' or 'mark a session failed', and Jentic returns the matching Automate operation with its parameter schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Sauce Labs** — Cloud cross-browser and mobile test platform with REST APIs for jobs and builds
- **LambdaTest** — Cloud cross-browser test grid with REST APIs for builds and sessions
- **CircleCI** — CI/CD platform that triggers BrowserStack tests as part of a build

## FAQ

### Why is there no official OpenAPI spec for BrowserStack Automate API?

BrowserStack does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call BrowserStack Automate API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the BrowserStack Automate API use?

The Automate API uses HTTP basic authentication with your BrowserStack username and access key (the `basicAuth` security scheme in the spec). Through Jentic, both values are stored encrypted in your Jentic One instance and the agent receives a scoped execution token instead of the raw credentials.

### Can I mark a session passed or failed from my CI pipeline?

Yes. PUT `/automate/sessions/{sessionId}/status` accepts {status: 'passed' or 'failed', reason: '...'}. Wire this into your test reporter so the Automate dashboard agrees with your CI step's assertion result, not just the Selenium driver's exit signal.

### How do I fetch network logs for a session through Jentic?

Search Jentic for 'fetch BrowserStack session logs', load the browserstack.com schema, and call GET `/automate/sessions/{sessionId}/networklogs.` The response is a JSON HAR document you can attach to a bug report or pipe into a triage agent.

### What are the rate limits for the BrowserStack Automate API?

The OpenAPI spec does not declare explicit rate limits. BrowserStack scales API capacity with the active plan; check GET `/automate/plan.json` to see your parallel session limit and avoid running large bulk delete jobs during peak CI hours.

### Does this cover Live, App Live, or Percy?

No. This API covers Automate (Selenium, Cypress, Appium) only. BrowserStack Live (manual cross-browser testing), App Live (manual mobile testing), and Percy (visual review) have separate APIs that are not part of this spec.

### Can I limit what my agent is allowed to do with the BrowserStack Automate API?

Yes. Jentic One is self-hosted, so your own rules decide which BrowserStack Automate operations and credentials the agent may use. Because Automate puts session and build ids in the URL path, such as `/automate/sessions/{sessionId}/networklogs` and `/automate/builds/{buildId}/tags`, you can pin the agent to a single session so it only reads that session's network, console, and Selenium logs. You choose which operations it may call, so a write like marking a session's status or tagging a build is excluded unless you add it, and the stored username and access key are injected at execution time rather than exposed to the agent.