canonical: https://jentic.com/apis/browsercat.com/browsercat # BrowserCat API Jentic publishes the only available OpenAPI specification for BrowserCat API, keeping it validated and agent-ready. BrowserCat is a managed headless browser service that exposes Chromium instances over a websocket connection so Playwright, Puppeteer, and Selenium clients can run scripts without operating their own browser fleet. The REST API alongside the websocket handles API key management, billing and subscriptions, and detailed usage reporting at the session and event level so teams can audit which scripts ran, how long they took, and what they cost. ## For AI agents Spin up a managed Chromium session over websocket via /connect and audit usage, sessions, and billing through the REST API. Useful for scraping, end-to-end testing, and PDF generation agents. ## Scope Does not handle scraper script authoring, captcha solving, or proxy rental - use for managed Chromium session brokering, key management, and usage auditing only. ## Capabilities - Open a managed headless Chromium session by upgrading a websocket connection on /connect - Mint, list, rotate, and revoke API keys scoped to specific projects or environments - Inspect per-session usage with the events endpoint to see exactly which actions ran in a script - Pull current and historical billing data including invoice PDFs without leaving the API - Query usage buckets to forecast spend ahead of the next billing cycle - Verify service health and metrics before kicking off long-running browser jobs ## Use cases ### Cloud-Hosted Playwright and Puppeteer Engineering teams point their Playwright or Puppeteer client at the /connect websocket so scripts run on BrowserCat's managed Chromium fleet instead of self-hosted browsers. Each connection is a fresh isolated session, so flaky local installs and Docker image upkeep disappear. The REST API mints scoped API keys per CI environment and the usage endpoints show exactly which test runs consumed which session minutes. Example prompt: POST /auth/keys to mint a CI key, then connect a Playwright client to wss://api.browsercat.com/connect with the key in the api-key header ### Per-Session Usage Auditing Platform teams running BrowserCat across many internal projects need to attribute cost and behaviour back to the team that owns each script. The /usage/sessions and /usage/sessions/{sessionId}/events endpoints expose the full breakdown - which key opened the session, how long it lasted, and the events fired inside the script. The agent ingests these into a BI tool to chargeback teams or alert on anomalous usage. Example prompt: GET /usage/sessions for the last 24 hours, then for each session GET /usage/sessions/{sessionId}/events and aggregate by api-key id ### Automated Key Rotation and Revocation Security teams treat BrowserCat keys like any other production secret and rotate them on a schedule. The agent uses POST /auth/keys to issue a replacement key, deploys it through the secret manager, and DELETE /auth/keys/{keyId} to revoke the old one once traffic has cut over. If a key ever leaks, the same DELETE call kills it within seconds. Example prompt: POST /auth/keys to mint a new key, deploy it, then DELETE /auth/keys/{old-key-id} to revoke the previous key ### AI Browser-Use Agent Through Jentic An AI agent that needs to browse a live web page uses Jentic to discover and call BrowserCat without holding the raw API key. The agent searches for 'open a headless browser session', loads the connect schema, and the websocket session is brokered with a Jentic-vaulted credential. This is a clean separation between the LLM-driven decision logic and the cloud browser substrate. Example prompt: Use Jentic to search 'open a headless Chromium session', load the browsercat.com operation, and connect a Playwright client through the brokered websocket ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | /connect | Open a websocket to a managed Chromium session | | POST | /auth/keys | Mint a new API key | | DELETE | /auth/keys/{keyId} | Revoke an API key | | GET | /usage/sessions | List browser sessions for the account | | GET | /usage/sessions/{sessionId}/events | Get the events recorded inside a session | | GET | /billing/subscriptions/current | Get the current billing subscription | | GET | /billing/invoices/{invId}.pdf | Download an invoice PDF | ## Key resources - **Connect** — Websocket entry point for a managed Chromium session - **Auth Keys** — Manage API keys scoped to projects or environments - **Usage Sessions** — Inspect individual browser sessions and the events that ran inside them - **Usage Buckets** — Aggregated usage across the current billing window - **Billing** — Current subscription, historical subscriptions, and invoice PDFs - **Health and Metrics** — Service health and operational metrics ## Why Jentic - **Setup:** Wiring BrowserCat by hand means setting the API-key header, brokering the websocket connect upgrade with it, and managing session, key, and billing endpoints yourself. Through Jentic you install once, import the BrowserCat API from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** BrowserCat puts the key and session ids in the URL path (/auth/keys/{keyId}, /usage/sessions/{sessionId}/events), so a rule can pin your agent to one session's audit data: it can read that session's events and nothing else. You choose the operations it may call, so a destructive one like deleting an API key is not included unless you add it. - **Credential handling:** Your BrowserCat API key is stored once, encrypted, by your own Jentic One instance and injected as the API-key header at execution time, including on the websocket upgrade. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'open a headless browser session', and Jentic returns the matching BrowserCat operation with its parameter schema so the agent connects to the right endpoint without browsing the reference docs. ## Related APIs - **Browserless** — Headless Chrome as a service with Playwright, Puppeteer, and HTTP APIs - **ZenRows** — Scraping-focused headless browser API with anti-bot bypass - **Browse AI** — No-code scraping robots that you train in a UI ## FAQ ### Why is there no official OpenAPI spec for BrowserCat API? BrowserCat does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call BrowserCat 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 BrowserCat API use? The API supports an API key passed in the api-key header (`keyHeader`), as well as JWTs in either an Authorization header or a cookie for session-based usage. Through Jentic, the API key is stored encrypted in your Jentic One instance and the agent receives a scoped execution token instead of the raw key. ### Can I run Playwright scripts against BrowserCat? Yes. BrowserCat's /connect endpoint upgrades to a websocket that Playwright (or Puppeteer) can connect to via its standard chromium.connect() API. You only change the connection URL and pass the BrowserCat key; the rest of your script runs unchanged. ### How do I rotate my BrowserCat API key through Jentic? Search Jentic for 'rotate a BrowserCat API key', load the browsercat.com schema, and call POST /auth/keys to mint a new key, then DELETE /auth/keys/{keyId} to revoke the old one. Jentic stores the new key encrypted automatically so downstream agents pick it up without redeploys. ### What are the rate limits for the BrowserCat API? The OpenAPI spec does not declare explicit rate limits. BrowserCat instead bills by concurrent session minutes; check GET /billing/subscriptions/current and GET /usage/buckets to confirm your remaining allowance before launching large parallel jobs. ### Can I see exactly what happened inside a browser session? Yes. GET /usage/sessions/{sessionId}/events returns the per-event breakdown of a session - navigations, network requests, console output - which is invaluable for debugging flaky tests and for auditing what an automation actually did. ### Can I limit what my agent is allowed to do with the BrowserCat API? Yes. Because you self-host Jentic One, your own rules decide which BrowserCat operations and credentials your agent may use. BrowserCat puts key and session ids in the URL path, such as /usage/sessions/{sessionId}/events and /auth/keys/{keyId}, so you can pin an agent to read one session's events and nothing else. You choose the operations it may call, so a destructive one like DELETE /auth/keys/{keyId} is excluded unless you add it.