docs(v1): unified /api/v1 reference from the live staging spec#205
Open
LarsenCundric wants to merge 4 commits into
Open
docs(v1): unified /api/v1 reference from the live staging spec#205LarsenCundric wants to merge 4 commits into
LarsenCundric wants to merge 4 commits into
Conversation
Adds the v1 API reference (agents, browsers, browser-profiles, agent-workspaces, project) rendered from the real deployed OpenAPI at /api/v1/openapi.json, plus the guide pages (choose-an-agent, run/continue/watch/stop a task, files, browsers, billing, limits, model). - docs/cloud/openapi/v1.json is generated from staging via mock/export_spec.py (browsercode with the r; no cross-agent GET /runs; registry is just GET /agents). - docs.json nav lists exactly the endpoints the spec exposes. - Retire the local mock service (kept only export_spec.py, which now pulls the real staging spec); the dead mock app is gitignored.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
31 issues found across 35 files
Not reviewed (too large): docs/cloud/openapi/v1.json (~5,346 lines), docs/cloud/llms-full.txt (~3,927 lines), docs/llms-full.txt (~3,927 lines) - if these are generated or fixture files, add them to ignored paths to exclude them from future reviews.
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="docs/cloud/limits.mdx">
<violation number="1" location="docs/cloud/limits.mdx:11">
P1: The Python SDK snippet uses `client.project.limits()` but the real SDK has no `.project` attribute and no `.limits()` method — there is no `limits` resource on the v2 client at all.
**What happens:** A reader who copies this snippet will get an `AttributeError`. The billing resource exists (`client.billing`) but there is no limits resource defined in the SDK.
**Suggestion:** Either add a `limits` resource to the SDK and docs, or use the raw HTTP client / curl approach instead for the Python snippet.</violation>
<violation number="2" location="docs/cloud/limits.mdx:11">
P0: The Python SDK snippet imports `from browser_use import BrowserUse` but the real package is `browser_use_sdk`. This will raise an `ImportError`.
**Suggestion:** Change the import to `from browser_use_sdk import BrowserUse`.</violation>
</file>
<file name="docs/cloud/browser/playwright-puppeteer-selenium.mdx">
<violation number="1" location="docs/cloud/browser/playwright-puppeteer-selenium.mdx:97">
P1: Same incorrect Python import `from browser_use import BrowserUse` as in other files — should be `from browser_use_sdk import BrowserUse`. Additionally, changing the import from `AsyncBrowserUse` to `BrowserUse` while the remaining code (unchanged context) still calls `client = AsyncBrowserUse()` introduces an incompatibility: `AsyncBrowserUse` is no longer imported. Users will get a `NameError` on the `AsyncBrowserUse()` call.</violation>
<violation number="2" location="docs/cloud/browser/playwright-puppeteer-selenium.mdx:115">
P1: The TypeScript Playwright example cannot resolve the documented SDK because the published package is `browser-use-sdk`, not `browser-use`. Using the v3 subpath preserves the `browsers.create()` API shown below.</violation>
</file>
<file name="docs/cloud/browser/sync-cookies.mdx">
<violation number="1" location="docs/cloud/browser/sync-cookies.mdx:46">
P1: The curl example sends `browser_profile_id` at the top level, so `/api/v1/agents/browser-use/runs` rejects the request with validation error; the live spec accepts the profile only as `browser.profileId`. The Python and TypeScript snippets repeat this shape and should be updated to use the nested, spec-cased field as well.</violation>
</file>
<file name="docs/cloud/legacy/overview.mdx">
<violation number="1" location="docs/cloud/legacy/overview.mdx:20">
P2: Readers are directed to `POST /api/v4/sessions`, but that operation is not present in the v4 reference; following this row sends legacy users to a nonexistent endpoint. The row should point to `POST /api/v4/runs` instead.</violation>
</file>
<file name="docs/cloud/browser/custom-proxy.mdx">
<violation number="1" location="docs/cloud/browser/custom-proxy.mdx:52">
P2: The curl example cannot start a run because the v1 REST schema expects `browser.customProxy`, not `browser.custom_proxy`; with extra properties forbidden, this request is rejected as invalid. Using the schema's camelCase key keeps the raw HTTP example executable.</violation>
</file>
<file name="docs/cloud/browser/live-preview.mdx">
<violation number="1" location="docs/cloud/browser/live-preview.mdx:18">
P1: The API path `client.agents.browser_use.runs.create()` does not exist on the `BrowserUse` client. The client exposes top-level resources like `client.sessions`, `client.tasks`, `client.browsers`, etc. There is no `agents` property. This code will fail with `AttributeError`.</violation>
<violation number="2" location="docs/cloud/browser/live-preview.mdx:60">
P1: Runs and standalone browsers do not record by default, so users following this page will request recordings that do not exist. The guide should document the opt-in recording fields and retain the recording fetch step only when recording is enabled.</violation>
<violation number="3" location="docs/cloud/browser/live-preview.mdx:64">
P1: The `Browsers` class does not have a `recording()` method. Same issue as in manage-browser.mdx. Users will get an `AttributeError`. The curl example in the same code block correctly uses the API endpoint directly, but the SDK example cannot work without adding a `recording()` method to the SDK.</violation>
</file>
<file name="docs/generate-llms-txt.sh">
<violation number="1" location="docs/generate-llms-txt.sh:227">
P1: The public guidance advertises production, but the generated v1 reference's server is staging, so Mintlify's interactive playground will send requests to the wrong environment. Normalizing the spec server to production, or clearly making the entire reference staging-only, would prevent users from testing against staging while following production instructions.</violation>
</file>
<file name="docs/DOCS_DESIGN_PRINCIPLES.md">
<violation number="1" location="docs/DOCS_DESIGN_PRINCIPLES.md:27">
P1: The v1 spec has no top-level `GET /runs`; it exposes agent-scoped list routes and uses `sessionId`, not `session_id`. Leaving this as the run-thread route would direct guide authors and agents to a 404 and contradict the PR's no-`/api/v1/runs` contract.</violation>
<violation number="2" location="docs/DOCS_DESIGN_PRINCIPLES.md:37">
P1: `GET /agent-workspaces/{id}/files` is not part of the generated v1 contract, so the stated advanced whole-disk view and pre-load escape hatch cannot be executed against the advertised API. The checklist should either add the missing API contract/backend or describe this as a legacy-only capability rather than a v1 workflow.</violation>
<violation number="3" location="docs/DOCS_DESIGN_PRINCIPLES.md:39">
P1: The design acknowledges that the deployed implementation cannot provide the output-file contract that the v1 guides present as the golden path. Publishing that workflow before output tracking exists can leave browsercode callers unable to retrieve produced files; the backend capability and the reference should be released together or the workflow should be marked unavailable.</violation>
</file>
<file name="docs/cloud/manage-browser.mdx">
<violation number="1" location="docs/cloud/manage-browser.mdx:47">
P1: The `Browsers` class does not have a `recording()` method. Neither the sync `Browsers` nor async `AsyncBrowsers` class defines this method. Users will get an `AttributeError`. The available methods are `create`, `list`, `get`, `update`, `stop`, and `downloads`. The curl example correctly uses the v1 API endpoint `/browsers/{id}/recording` but the SDK example cannot work.</violation>
<violation number="2" location="docs/cloud/manage-browser.mdx:56">
P1: The run-to-browser and output-file workflow points to endpoints that do not exist in v1: `/runs/{id}` and `/runs/{id}/files`. Users cannot retrieve `browser_id` or output files from these snippets until the agent-specific run path is included.</violation>
</file>
<file name="docs/cloud/files.mdx">
<violation number="1" location="docs/cloud/files.mdx:42">
P1: Following this example cannot upload an input file: `POST /agents/browsercode/files` is not an operation in the v1 contract, so the subsequent `attached_file_ids` workflow has no documented way to obtain an id. The page should either use an actually exposed upload operation or wait until the v1 spec includes one.</violation>
<violation number="2" location="docs/cloud/files.mdx:195">
P1: The advanced workspace example calls an endpoint that does not exist in the published v1 contract, so users cannot preload `dataset.parquet` as shown. The workspace flow needs an exposed file-upload operation or should be removed from this guide.</violation>
</file>
<file name="docs/cloud/browser/proxies.mdx">
<violation number="1" location="docs/cloud/browser/proxies.mdx:11">
P1: The v1 examples use `proxy_country_code` and `custom_proxy`, but the v1 OpenAPI schema expects `proxyCountryCode` and `customProxy`. As a result, copying these examples will not set or disable the proxy. The examples and field descriptions should use the exact v1 camelCase names (including the Python SDK examples if that SDK does not translate them).</violation>
</file>
<file name="docs/cloud/billing.mdx">
<violation number="1" location="docs/cloud/billing.mdx:11">
P1: The Python SDK code snippet uses `client.project.billing()` but the real SDK has `client.billing.account()` — there is no `.project` resource on the v2 client.
**What happens:** A reader who copies this snippet into a Python interpreter will get an `AttributeError` because `BrowserUse` exposes `billing` (a `Billing` resource) directly, and the `Billing` class has an `account()` method, not `__call__`.
**Suggestion:** Update the snippet to match the actual SDK surface: `billing = client.billing.account()`</violation>
<violation number="2" location="docs/cloud/billing.mdx:11">
P0: The Python SDK snippet imports `from browser_use import BrowserUse` but the real package is `browser_use_sdk` (imported as `from browser_use_sdk import BrowserUse`). This will raise an `ImportError`.
**Suggestion:** Change the import to `from browser_use_sdk import BrowserUse`.</violation>
</file>
<file name="docs/cloud/run-a-task.mdx">
<violation number="1" location="docs/cloud/run-a-task.mdx:13">
P1: Wrong Python import path. The package installs as `browser-use-sdk` on PyPI and its importable module is `browser_use_sdk`, not `browser_use`. Every Python example in this batch uses `from browser_use import BrowserUse`, which will raise `ModuleNotFoundError: No module named 'browser_use'` for users who follow the docs.</violation>
<violation number="2" location="docs/cloud/run-a-task.mdx:16">
P1: After correcting the imports, these SDK snippets still fail because `BrowserUse` has no `agents` namespace. The examples should use the actual SDK surface, or be labeled as raw HTTP/client pseudocode rather than copy-paste SDK code.</violation>
<violation number="3" location="docs/cloud/run-a-task.mdx:57">
P1: The polling instruction points to a nonexistent generic endpoint and does not terminate on `failed` or `stopped`. A copied watcher can receive 404s or wait forever; use the agent-scoped endpoint and handle every terminal status.</violation>
</file>
<file name="docs/cloud/quickstart.mdx">
<violation number="1" location="docs/cloud/quickstart.mdx:21">
P1: The Python SDK import on the quickstart page uses `from browser_use import BrowserUse`, but the actual installable package is `browser-use-sdk` (PyPI) and the importable module is `browser_use_sdk`. Users who copy this code will get an `ImportError` — the very first line of the quickstart will fail. Change the import to `from browser_use_sdk import BrowserUse` to match the published SDK.</violation>
<violation number="2" location="docs/cloud/quickstart.mdx:28">
P1: The TypeScript import on the quickstart page uses `import { BrowserUse } from "browser-use"`, but the actual npm package is `browser-use-sdk`. Users who copy this code will get a module-not-found error. Change the import to `from "browser-use-sdk"` to match the published SDK.</violation>
</file>
<file name="docs/cloud/create-browser.mdx">
<violation number="1" location="docs/cloud/create-browser.mdx:17">
P0: Python import path `from browser_use import BrowserUse` references a package `browser-use` that does not exist on PyPI and is not the package defined in this repository. The published package is `browser-use-sdk` and its import path is `from browser_use_sdk import BrowserUse`. Users following this example will get `ModuleNotFoundError: No module named 'browser_use'`. This is the most basic issue preventing all code examples from working.</violation>
<violation number="2" location="docs/cloud/create-browser.mdx:19">
P1: The SDK snippets in this v1 guide send requests to `/api/v2` by default, so they do not exercise the documented v1 contract. The page should use verified v1-compatible raw requests or a v1 client/base URL with matching response models.</violation>
<violation number="3" location="docs/cloud/create-browser.mdx:25">
P1: The TypeScript example imports a package name that is not published by this repository, so it fails before the browser call runs.</violation>
</file>
<file name="docs/cloud/api-v1-reference.mdx">
<violation number="1" location="docs/cloud/api-v1-reference.mdx:20">
P1: The interactive playground on every generated endpoint page will send requests to the staging host, while this overview tells users the API base URL is production; production API keys and data can therefore be tested against the wrong environment. Align the OpenAPI `servers` entry with `https://api.browser-use.com/api/v1`, or explicitly label the reference and playground as staging.</violation>
</file>
<file name="mock/export_spec.py">
<violation number="1" location="mock/export_spec.py:24">
P1: The output path is hardcoded to an absolute path on one developer's machine. This script will fail for anyone else (and in CI) with a `FileNotFoundError` unless they replicate the same directory structure. Use a path relative to the repo root — `docs/cloud/openapi/v1.json` — and derive it from the script's location or a dedicated environment variable so the script is portable.</violation>
</file>
Tip: instead of fixing issues one by one fix them all with cubic
Re-trigger cubic
|
|
||
| <CodeGroup> | ||
| ```python Python | ||
| from browser_use import BrowserUse |
Contributor
There was a problem hiding this comment.
P0: The Python SDK snippet imports from browser_use import BrowserUse but the real package is browser_use_sdk. This will raise an ImportError.
Suggestion: Change the import to from browser_use_sdk import BrowserUse.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/cloud/limits.mdx, line 11:
<comment>The Python SDK snippet imports `from browser_use import BrowserUse` but the real package is `browser_use_sdk`. This will raise an `ImportError`.
**Suggestion:** Change the import to `from browser_use_sdk import BrowserUse`.</comment>
<file context>
@@ -0,0 +1,30 @@
+
+<CodeGroup>
+```python Python
+from browser_use import BrowserUse
+
+client = BrowserUse()
</file context>
Suggested change
| from browser_use import BrowserUse | |
| from browser_use_sdk import BrowserUse |
|
|
||
| <CodeGroup> | ||
| ```python Python | ||
| from browser_use import BrowserUse |
Contributor
There was a problem hiding this comment.
P0: The Python SDK snippet imports from browser_use import BrowserUse but the real package is browser_use_sdk (imported as from browser_use_sdk import BrowserUse). This will raise an ImportError.
Suggestion: Change the import to from browser_use_sdk import BrowserUse.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/cloud/billing.mdx, line 11:
<comment>The Python SDK snippet imports `from browser_use import BrowserUse` but the real package is `browser_use_sdk` (imported as `from browser_use_sdk import BrowserUse`). This will raise an `ImportError`.
**Suggestion:** Change the import to `from browser_use_sdk import BrowserUse`.</comment>
<file context>
@@ -0,0 +1,43 @@
+
+<CodeGroup>
+```python Python
+from browser_use import BrowserUse
+
+client = BrowserUse()
</file context>
Suggested change
| from browser_use import BrowserUse | |
| from browser_use_sdk import BrowserUse |
|
|
||
| <CodeGroup> | ||
| ```python Python | ||
| from browser_use import BrowserUse |
Contributor
There was a problem hiding this comment.
P0: Python import path from browser_use import BrowserUse references a package browser-use that does not exist on PyPI and is not the package defined in this repository. The published package is browser-use-sdk and its import path is from browser_use_sdk import BrowserUse. Users following this example will get ModuleNotFoundError: No module named 'browser_use'. This is the most basic issue preventing all code examples from working.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/cloud/create-browser.mdx, line 17:
<comment>Python import path `from browser_use import BrowserUse` references a package `browser-use` that does not exist on PyPI and is not the package defined in this repository. The published package is `browser-use-sdk` and its import path is `from browser_use_sdk import BrowserUse`. Users following this example will get `ModuleNotFoundError: No module named 'browser_use'`. This is the most basic issue preventing all code examples from working.</comment>
<file context>
@@ -0,0 +1,65 @@
+
+<CodeGroup>
+```python Python
+from browser_use import BrowserUse
+
+client = BrowserUse()
</file context>
Suggested change
| from browser_use import BrowserUse | |
| from browser_use_sdk import BrowserUse |
|
|
||
| <CodeGroup> | ||
| ```python Python | ||
| from browser_use import BrowserUse |
Contributor
There was a problem hiding this comment.
P1: The Python SDK snippet uses client.project.limits() but the real SDK has no .project attribute and no .limits() method — there is no limits resource on the v2 client at all.
What happens: A reader who copies this snippet will get an AttributeError. The billing resource exists (client.billing) but there is no limits resource defined in the SDK.
Suggestion: Either add a limits resource to the SDK and docs, or use the raw HTTP client / curl approach instead for the Python snippet.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/cloud/limits.mdx, line 11:
<comment>The Python SDK snippet uses `client.project.limits()` but the real SDK has no `.project` attribute and no `.limits()` method — there is no `limits` resource on the v2 client at all.
**What happens:** A reader who copies this snippet will get an `AttributeError`. The billing resource exists (`client.billing`) but there is no limits resource defined in the SDK.
**Suggestion:** Either add a `limits` resource to the SDK and docs, or use the raw HTTP client / curl approach instead for the Python snippet.</comment>
<file context>
@@ -0,0 +1,30 @@
+
+<CodeGroup>
+```python Python
+from browser_use import BrowserUse
+
+client = BrowserUse()
</file context>
| urls = await client.sessions.wait_for_recording(result.id) | ||
| for url in urls: | ||
| print(url) # presigned MP4 download URL | ||
| rec = client.browsers.recording(run.browser_id) |
Contributor
There was a problem hiding this comment.
P1: The Browsers class does not have a recording() method. Same issue as in manage-browser.mdx. Users will get an AttributeError. The curl example in the same code block correctly uses the API endpoint directly, but the SDK example cannot work without adding a recording() method to the SDK.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/cloud/browser/live-preview.mdx, line 64:
<comment>The `Browsers` class does not have a `recording()` method. Same issue as in manage-browser.mdx. Users will get an `AttributeError`. The curl example in the same code block correctly uses the API endpoint directly, but the SDK example cannot work without adding a `recording()` method to the SDK.</comment>
<file context>
@@ -1,153 +1,78 @@
-urls = await client.sessions.wait_for_recording(result.id)
-for url in urls:
- print(url) # presigned MP4 download URL
+rec = client.browsers.recording(run.browser_id)
+print(rec.url) # presigned MP4
</file context>
</details>
<a href="https://www.cubic.dev/action/fix/violation/1aa63930-cd80-4dd9-b6a0-9eb8d04de7fc" target="_blank" rel="noopener noreferrer" data-no-image-dialog="true">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://cubic.dev/buttons/fix-with-cubic-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://cubic.dev/buttons/fix-with-cubic-light.svg">
<img alt="Fix with cubic" src="https://cubic.dev/buttons/fix-with-cubic-dark.svg">
</picture>
</a>
| X-Browser-Use-API-Key: bu_your_key_here | ||
| ``` | ||
|
|
||
| The endpoint pages in this section are generated from the OpenAPI spec and include an interactive playground. For task-oriented guides, start with [Quickstart](/cloud/quickstart) and [Choose an agent](/cloud/choose-an-agent). |
Contributor
There was a problem hiding this comment.
P1: The interactive playground on every generated endpoint page will send requests to the staging host, while this overview tells users the API base URL is production; production API keys and data can therefore be tested against the wrong environment. Align the OpenAPI servers entry with https://api.browser-use.com/api/v1, or explicitly label the reference and playground as staging.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/cloud/api-v1-reference.mdx, line 20:
<comment>The interactive playground on every generated endpoint page will send requests to the staging host, while this overview tells users the API base URL is production; production API keys and data can therefore be tested against the wrong environment. Align the OpenAPI `servers` entry with `https://api.browser-use.com/api/v1`, or explicitly label the reference and playground as staging.</comment>
<file context>
@@ -0,0 +1,20 @@
+X-Browser-Use-API-Key: bu_your_key_here
+```
+
+The endpoint pages in this section are generated from the OpenAPI spec and include an interactive playground. For task-oriented guides, start with [Quickstart](/cloud/quickstart) and [Choose an agent](/cloud/choose-an-agent).
</file context>
| ```python Python | ||
| from browser_use import BrowserUse | ||
|
|
||
| client = BrowserUse() |
Contributor
There was a problem hiding this comment.
P1: The SDK snippets in this v1 guide send requests to /api/v2 by default, so they do not exercise the documented v1 contract. The page should use verified v1-compatible raw requests or a v1 client/base URL with matching response models.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/cloud/create-browser.mdx, line 19:
<comment>The SDK snippets in this v1 guide send requests to `/api/v2` by default, so they do not exercise the documented v1 contract. The page should use verified v1-compatible raw requests or a v1 client/base URL with matching response models.</comment>
<file context>
@@ -0,0 +1,65 @@
+```python Python
+from browser_use import BrowserUse
+
+client = BrowserUse()
+browser = client.browsers.create(proxy_country_code="us")
+print(browser.cdp_url) # connect Playwright/Puppeteer/Selenium here
</file context>
| | Legacy | Unified `/api/v1` | | ||
| | --- | --- | | ||
| | `POST /api/v2/tasks`, `POST /api/v3/sessions` (the browser agent) | [`POST /api/v1/agents/browser-use/runs`](/cloud/run-a-task) | | ||
| | `POST /api/v4/sessions` (the code + browser agent) | [`POST /api/v1/agents/browsercode/runs`](/cloud/run-a-task) | |
Contributor
There was a problem hiding this comment.
P2: Readers are directed to POST /api/v4/sessions, but that operation is not present in the v4 reference; following this row sends legacy users to a nonexistent endpoint. The row should point to POST /api/v4/runs instead.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/cloud/legacy/overview.mdx, line 20:
<comment>Readers are directed to `POST /api/v4/sessions`, but that operation is not present in the v4 reference; following this row sends legacy users to a nonexistent endpoint. The row should point to `POST /api/v4/runs` instead.</comment>
<file context>
@@ -0,0 +1,30 @@
+| Legacy | Unified `/api/v1` |
+| --- | --- |
+| `POST /api/v2/tasks`, `POST /api/v3/sessions` (the browser agent) | [`POST /api/v1/agents/browser-use/runs`](/cloud/run-a-task) |
+| `POST /api/v4/sessions` (the code + browser agent) | [`POST /api/v1/agents/browsercode/runs`](/cloud/run-a-task) |
+| v2/v3/v4 session file handling | [Files](/cloud/files) (one workspace model, all agents) |
+| v2 `keep_alive` / session-as-browser | automatic [browser lifecycle](/cloud/manage-browser) — no flag |
</file context>
Suggested change
| | `POST /api/v4/sessions` (the code + browser agent) | [`POST /api/v1/agents/browsercode/runs`](/cloud/run-a-task) | | |
| | `POST /api/v4/runs` (the code + browser agent) | [`POST /api/v1/agents/browsercode/runs`](/cloud/run-a-task) | |
| -H "Content-Type: application/json" \ | ||
| -d '{ | ||
| "task": "Check example.com loads", | ||
| "browser": {"custom_proxy": {"host": "proxy.example.com", "port": 8080, "username": "user", "password": "pass"}} |
Contributor
There was a problem hiding this comment.
P2: The curl example cannot start a run because the v1 REST schema expects browser.customProxy, not browser.custom_proxy; with extra properties forbidden, this request is rejected as invalid. Using the schema's camelCase key keeps the raw HTTP example executable.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/cloud/browser/custom-proxy.mdx, line 52:
<comment>The curl example cannot start a run because the v1 REST schema expects `browser.customProxy`, not `browser.custom_proxy`; with extra properties forbidden, this request is rejected as invalid. Using the schema's camelCase key keeps the raw HTTP example executable.</comment>
<file context>
@@ -0,0 +1,70 @@
+ -H "Content-Type: application/json" \
+ -d '{
+ "task": "Check example.com loads",
+ "browser": {"custom_proxy": {"host": "proxy.example.com", "port": 8080, "username": "user", "password": "pass"}}
+ }'
+```
</file context>
…ng fixes, llms.txt regen - port from reagan/eng-5397: stealth/captcha benchmarks, screenshots page, MCP cloud statement, fresh-IP recipe, profile persistence - restructure: overviews (get-started, browsers, account, stealth&proxies), profiles split (create/use), OSS-agent page, quickstart browser path - casing: response JSON/curl camelCase per live staging behavior; fix false prose casing claims; registry example matches live response - redirects for renamed slugs; llms.txt/llms-full.txt regenerated Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
31 issues found across 49 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="docs/cloud/browsers.mdx">
<violation number="1" location="docs/cloud/browsers.mdx:18">
P2: The card implies Selenium connects directly through the same WebSocket URL as Playwright and Puppeteer, but the linked guide requires a local WebSocket proxy or bridge for Selenium. Mentioning that caveat here avoids sending Selenium users toward an unsupported direct connection.</violation>
</file>
<file name="docs/cloud/run-a-task.mdx">
<violation number="1" location="docs/cloud/run-a-task.mdx:52">
P2: The response example advertises `stepsUrl`, but this field is not part of the `RunAccepted` schema in the live OpenAPI reference. Removing it keeps the example aligned with the documented response contract.</violation>
</file>
<file name="docs/cloud/browser/stealth.mdx">
<violation number="1" location="docs/cloud/browser/stealth.mdx:19">
P2: Agent runs provision their own browser; they do not reuse a browser created through `/cloud/create-browser`. Saying they get “the same browser” can lead readers to look for a `browser_id` input or assume CDP state carries over, so the wording should distinguish the shared stealth configuration from the browser instance.</violation>
<violation number="2" location="docs/cloud/browser/stealth.mdx:21">
P2: This page says fingerprints are randomized per browser, while the existing stealth overview says per session. Because the docs distinguish browser and session, readers cannot tell whether a fingerprint persists across runs or only within one session; aligning this wording with the existing “per session” description would avoid a misleading guarantee.</violation>
</file>
<file name="docs/cloud/choose-an-agent.mdx">
<violation number="1" location="docs/cloud/choose-an-agent.mdx:54">
P2: The registry examples no longer match the documented response shape: `agents.list()` must be unwrapped before iteration now that the response is `{ "agents": [...] }`; otherwise Python iterates object keys and TypeScript receives a non-iterable object. Updating both examples to iterate over the nested `agents` array would keep the guide runnable.</violation>
</file>
<file name="docs/cloud/browser/proxies.mdx">
<violation number="1" location="docs/cloud/browser/proxies.mdx:86">
P3: The Python snippet cannot run as shown because `old_browser` is never initialized. Showing the existing browser lookup (or accepting an explicit browser ID) would make the stop-and-recreate workflow copyable.</violation>
<violation number="2" location="docs/cloud/browser/proxies.mdx:87">
P2: The Python example does not use the profile parameter exposed by the repository's `BrowserUse` client: `browser_profile_id` is treated as an extra request field rather than mapped to the browser profile. Using `profile_id` (and a real profile UUID) keeps the example executable against the published SDK.</violation>
<violation number="3" location="docs/cloud/browser/proxies.mdx:96">
P1: This curl request does not match the live v1 request schema and can be rejected as an invalid body. Using the schema's camelCase field names makes the profile and proxy settings reach `POST /api/v1/browsers`.</violation>
</file>
<file name="docs/cloud/quickstart.mdx">
<violation number="1" location="docs/cloud/quickstart.mdx:54">
P1: The Python and TypeScript import paths in the new code examples are incorrect — they will fail for anyone running them. The Python SDK is published as `browser-use-sdk` on PyPI with the import path `browser_use_sdk`, and the TypeScript SDK is published as `browser-use-sdk` on npm with the same package name. Use `from browser_use_sdk import BrowserUse` and `import { BrowserUse } from "browser-use-sdk"` to match the actual published packages. The SDK examples in `browser-use-python/examples/` use the correct import paths as reference.</violation>
<violation number="2" location="docs/cloud/quickstart.mdx:58">
P2: A newly created browser can return no CDP URL yet, so these snippets can print `None`/`undefined` and leave the user unable to connect. Showing a poll of `GET /browsers/{id}` (or the SDK's `get`) until `cdpUrl` is non-null would make the direct-browser quickstart reliable.</violation>
</file>
<file name="docs/cloud/browser/screenshots.mdx">
<violation number="1" location="docs/cloud/browser/screenshots.mdx:16">
P1: The Python example fails at import time because `browser_use` is not the published cloud SDK module. Import `BrowserUse` from `browser_use_sdk.v3` for this browser API.</violation>
<violation number="2" location="docs/cloud/browser/screenshots.mdx:21">
P2: The Python example is not runnable as a normal script because `async with` appears at module scope. Wrap the Playwright body in `async def main()` and invoke it with `asyncio.run(main())`, or use the synchronous Playwright API.</violation>
<violation number="3" location="docs/cloud/browser/screenshots.mdx:31">
P1: The TypeScript example cannot resolve the `browser-use` module. Use the published v3 SDK package instead.</violation>
<violation number="4" location="docs/cloud/browser/screenshots.mdx:36">
P1: The TypeScript code example uses `browser.cdp_url` but the TypeScript SDK exposes this as `cdpUrl` (camelCase). A TypeScript developer who copies this code will get a runtime `undefined` error. The same PR's create-browser.mdx explicitly documents the TypeScript SDK property as `cdpUrl` and uses it correctly there. Change `browser.cdp_url` to `browser.cdpUrl` in the TypeScript code block.</violation>
<violation number="5" location="docs/cloud/browser/screenshots.mdx:60">
P2: The resolution example uses parameter names that the cloud browser client does not define, so the requested 1920×1080 size is not applied (and may be rejected by the strict request model). Use the SDK's `browser_screen_width` and `browser_screen_height` arguments.</violation>
<violation number="6" location="docs/cloud/browser/screenshots.mdx:65">
P2: The page promises a recording for every browser, but standalone v1 browser recording is opt-in and defaults to disabled. Describe recording as opt-in and show the recording option when creating a browser; update both automatic-recording statements.</violation>
<violation number="7" location="docs/cloud/browser/screenshots.mdx:69">
P2: Following the files path shown here targets a route that is not in the v1 spec. Use the agent-qualified files endpoint and identify whether the run belongs to `browser-use` or `browsercode`.</violation>
</file>
<file name="docs/cloud/use-a-profile.mdx">
<violation number="1" location="docs/cloud/use-a-profile.mdx:36">
P3: The Python code snippet imports `playwright.sync_api` which is a large 3rd-party dependency that cloud SDK users may not have installed. Consider noting that Playwright is required for the CDP approach, or using the existing cloud browser's CDP URL approach without requiring users to install Playwright separately.</violation>
<violation number="2" location="docs/cloud/use-a-profile.mdx:49">
P3: The Python example imports `from browser_use import BrowserUse` but the SDK package is published as `browser-use-sdk` on PyPI. The correct import for the v2 synchronous client is `from browser_use_sdk import BrowserUse`. This code won't run — it will raise an `ImportError`.</violation>
</file>
<file name="docs/cloud/model.mdx">
<violation number="1" location="docs/cloud/model.mdx:19">
P2: The page now teaches two different names for the same continuation field: the new response example uses `sessionId`, while the continuation request immediately below still uses `session_id`. Updating that request example and its accompanying prose to `sessionId` would keep the guide aligned with `BrowserUseRunCreateRequest`.</violation>
</file>
<file name="docs/cloud/limits.mdx">
<violation number="1" location="docs/cloud/limits.mdx:25">
P2: The sample response does not match the live `/project/limits` contract: each limit object requires `limit` and `active`, but this example shows `granted`/`remaining` and omits `teamMembers.active`. Users copying this response shape will look for fields the API does not return and miss required values.</violation>
</file>
<file name="docs/cloud/files.mdx">
<violation number="1" location="docs/cloud/files.mdx:127">
P2: The continuation example still uses `session_id` in the request body, so users copying it will get a validation error rather than continue the run. The v1 schema uses `sessionId`; please update the request field (and the surrounding prose) to the camelCase name.</violation>
</file>
<file name="docs/cloud/open-source-agent.mdx">
<violation number="1" location="docs/cloud/open-source-agent.mdx:7">
P2: Readers may choose Cloud expecting identical local behavior and every locally supported model, but this page presents that parity as fact while the repository documents different OSS and Cloud model offerings. Describing Cloud as built on/browser-use-based and linking its actual model availability would avoid an unsupported compatibility promise.</violation>
<violation number="2" location="docs/cloud/open-source-agent.mdx:9">
P2: The copy-paste example only starts an asynchronous run, so users receive an accepted handle rather than the Hacker News result and have no documented next step on this page. Calling out the async response and polling endpoint before the example would make the workflow complete.</violation>
<violation number="3" location="docs/cloud/open-source-agent.mdx:27">
P2: The recommendation guarantees that Cloud browsers do not get blocked, but the linked product docs show that protected sites and CAPTCHAs can still fail. Qualifying this as improved bot-detection resistance rather than a bypass guarantee would keep the comparison accurate.</violation>
</file>
<file name="docs/cloud/browser/captcha.mdx">
<violation number="1" location="docs/cloud/browser/captcha.mdx:11">
P2: The figures here are anti-bot bypass rates, not CAPTCHA-solving success rates: the linked benchmark counts protected-page/task blocks and includes page-load failures without evaluating solver outcomes. Label this section as protected-site/anti-bot bypass rates, or provide a CAPTCHA-specific methodology before using it to describe solver performance.</violation>
<violation number="2" location="docs/cloud/browser/captcha.mdx:32">
P2: reCAPTCHA v3 does not render an interactive challenge; it returns a risk score, so describing every entry as an interactive widget is misleading. Distinguishing score-based reCAPTCHA from interactive CAPTCHA integrations would set the correct expectation for users.</violation>
</file>
<file name="docs/cloud/create-profile.mdx">
<violation number="1" location="docs/cloud/create-profile.mdx:20">
P2: The TypeScript example imports a package name that is not the SDK published by this repository, so users copying it cannot resolve the module. Use the package name documented by the SDK instead.</violation>
<violation number="2" location="docs/cloud/create-profile.mdx:23">
P2: The TypeScript example uses `browserProfiles`, but `BrowserUse` exposes this resource as `profiles`; copied code will fail with a missing-property/type error. Calling `client.profiles.create(...)` matches the SDK API.</violation>
<violation number="3" location="docs/cloud/create-profile.mdx:34">
P2: The profile lifecycle description overstates persistence for standalone browsers: the linked guide warns that a browser timing out may not save state. Qualifying this as a clean stop (for example, `browsers.stop()`) would keep the create-page guidance consistent and prevent lost login state.</violation>
</file>
<file name="docs/cloud/billing.mdx">
<violation number="1" location="docs/cloud/billing.mdx:30">
P2: The billing response example includes a `runwayDays` field that is not defined in the live OpenAPI spec's `Credits` schema (`docs/cloud/openapi/v1.json`). The spec only defines `balanceUsd`, `monthlyUsd`, and `additionalUsd`. If the API returns `runwayDays`, the spec should be updated to include it; otherwise, the docs should omit it to stay accurate to the deployed contract.</violation>
</file>
Tip: instead of fixing issues one by one fix them all with cubic
Tip: Review your code locally with the cubic CLI to iterate faster.
Re-trigger cubic
| curl -X POST https://api.browser-use.com/api/v1/browsers \ | ||
| -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{"proxy_country_code": "us", "browser_profile_id": "bp_123"}' |
Contributor
There was a problem hiding this comment.
P1: This curl request does not match the live v1 request schema and can be rejected as an invalid body. Using the schema's camelCase field names makes the profile and proxy settings reach POST /api/v1/browsers.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/cloud/browser/proxies.mdx, line 96:
<comment>This curl request does not match the live v1 request schema and can be rejected as an invalid body. Using the schema's camelCase field names makes the profile and proxy settings reach `POST /api/v1/browsers`.</comment>
<file context>
@@ -72,6 +72,36 @@ curl -X POST https://api.browser-use.com/api/v1/agents/browser-use/runs \
+curl -X POST https://api.browser-use.com/api/v1/browsers \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"proxy_country_code": "us", "browser_profile_id": "bp_123"}'
+```
+</CodeGroup>
</file context>
| ``` | ||
| ```typescript TypeScript | ||
| import { chromium } from "playwright"; | ||
| import { BrowserUse } from "browser-use"; |
Contributor
There was a problem hiding this comment.
P1: The TypeScript example cannot resolve the browser-use module. Use the published v3 SDK package instead.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/cloud/browser/screenshots.mdx, line 31:
<comment>The TypeScript example cannot resolve the `browser-use` module. Use the published v3 SDK package instead.</comment>
<file context>
@@ -0,0 +1,69 @@
+```
+```typescript TypeScript
+import { chromium } from "playwright";
+import { BrowserUse } from "browser-use";
+
+const client = new BrowserUse();
</file context>
| <CodeGroup> | ||
| ```python Python | ||
| from playwright.async_api import async_playwright | ||
| from browser_use import BrowserUse |
Contributor
There was a problem hiding this comment.
P1: The Python example fails at import time because browser_use is not the published cloud SDK module. Import BrowserUse from browser_use_sdk.v3 for this browser API.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/cloud/browser/screenshots.mdx, line 16:
<comment>The Python example fails at import time because `browser_use` is not the published cloud SDK module. Import `BrowserUse` from `browser_use_sdk.v3` for this browser API.</comment>
<file context>
@@ -0,0 +1,69 @@
+<CodeGroup>
+```python Python
+from playwright.async_api import async_playwright
+from browser_use import BrowserUse
+
+client = BrowserUse()
</file context>
Suggested change
| from browser_use import BrowserUse | |
| from browser_use_sdk.v3 import BrowserUse |
| const client = new BrowserUse(); | ||
| const browser = await client.browsers.create(); | ||
|
|
||
| const pw = await chromium.connectOverCDP(browser.cdp_url); |
Contributor
There was a problem hiding this comment.
P1: The TypeScript code example uses browser.cdp_url but the TypeScript SDK exposes this as cdpUrl (camelCase). A TypeScript developer who copies this code will get a runtime undefined error. The same PR's create-browser.mdx explicitly documents the TypeScript SDK property as cdpUrl and uses it correctly there. Change browser.cdp_url to browser.cdpUrl in the TypeScript code block.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/cloud/browser/screenshots.mdx, line 36:
<comment>The TypeScript code example uses `browser.cdp_url` but the TypeScript SDK exposes this as `cdpUrl` (camelCase). A TypeScript developer who copies this code will get a runtime `undefined` error. The same PR's create-browser.mdx explicitly documents the TypeScript SDK property as `cdpUrl` and uses it correctly there. Change `browser.cdp_url` to `browser.cdpUrl` in the TypeScript code block.</comment>
<file context>
@@ -0,0 +1,69 @@
+const client = new BrowserUse();
+const browser = await client.browsers.create();
+
+const pw = await chromium.connectOverCDP(browser.cdp_url);
+const page = pw.contexts()[0].pages()[0];
+await page.goto("https://example.com");
</file context>
Suggested change
| const pw = await chromium.connectOverCDP(browser.cdp_url); | |
| const pw = await chromium.connectOverCDP(browser.cdpUrl); |
| ```python Python | ||
| import asyncio | ||
| from browser_use_sdk.v3 import AsyncBrowserUse | ||
| from browser_use import BrowserUse |
Contributor
There was a problem hiding this comment.
P1: The Python and TypeScript import paths in the new code examples are incorrect — they will fail for anyone running them. The Python SDK is published as browser-use-sdk on PyPI with the import path browser_use_sdk, and the TypeScript SDK is published as browser-use-sdk on npm with the same package name. Use from browser_use_sdk import BrowserUse and import { BrowserUse } from "browser-use-sdk" to match the actual published packages. The SDK examples in browser-use-python/examples/ use the correct import paths as reference.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/cloud/quickstart.mdx, line 54:
<comment>The Python and TypeScript import paths in the new code examples are incorrect — they will fail for anyone running them. The Python SDK is published as `browser-use-sdk` on PyPI with the import path `browser_use_sdk`, and the TypeScript SDK is published as `browser-use-sdk` on npm with the same package name. Use `from browser_use_sdk import BrowserUse` and `import { BrowserUse } from "browser-use-sdk"` to match the actual published packages. The SDK examples in `browser-use-python/examples/` use the correct import paths as reference.</comment>
<file context>
@@ -45,6 +45,35 @@ The SDK `run()` starts the run and waits for it to finish, then returns the resu
+
+<CodeGroup>
+```python Python
+from browser_use import BrowserUse
+
+client = BrowserUse()
</file context>
Suggested change
| from browser_use import BrowserUse | |
| from browser_use_sdk import BrowserUse |
| "balanceUsd": "142.50", | ||
| "monthlyUsd": "100.00", | ||
| "additionalUsd": "42.50", | ||
| "runwayDays": 6.5 |
Contributor
There was a problem hiding this comment.
P2: The billing response example includes a runwayDays field that is not defined in the live OpenAPI spec's Credits schema (docs/cloud/openapi/v1.json). The spec only defines balanceUsd, monthlyUsd, and additionalUsd. If the API returns runwayDays, the spec should be updated to include it; otherwise, the docs should omit it to stay accurate to the deployed contract.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/cloud/billing.mdx, line 30:
<comment>The billing response example includes a `runwayDays` field that is not defined in the live OpenAPI spec's `Credits` schema (`docs/cloud/openapi/v1.json`). The spec only defines `balanceUsd`, `monthlyUsd`, and `additionalUsd`. If the API returns `runwayDays`, the spec should be updated to include it; otherwise, the docs should omit it to stay accurate to the deployed contract.</comment>
<file context>
@@ -24,20 +24,20 @@ curl "https://api.browser-use.com/api/v1/project/billing" \
+ "balanceUsd": "142.50",
+ "monthlyUsd": "100.00",
+ "additionalUsd": "42.50",
+ "runwayDays": 6.5
},
"plan": {
</file context>
| client = BrowserUse() | ||
|
|
||
| # Stop-and-recreate is how you get a new IP; reattach a profile to keep login state. | ||
| client.browsers.stop(old_browser.id) |
Contributor
There was a problem hiding this comment.
P3: The Python snippet cannot run as shown because old_browser is never initialized. Showing the existing browser lookup (or accepting an explicit browser ID) would make the stop-and-recreate workflow copyable.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/cloud/browser/proxies.mdx, line 86:
<comment>The Python snippet cannot run as shown because `old_browser` is never initialized. Showing the existing browser lookup (or accepting an explicit browser ID) would make the stop-and-recreate workflow copyable.</comment>
<file context>
@@ -72,6 +72,36 @@ curl -X POST https://api.browser-use.com/api/v1/agents/browser-use/runs \
+client = BrowserUse()
+
+# Stop-and-recreate is how you get a new IP; reattach a profile to keep login state.
+client.browsers.stop(old_browser.id)
+browser = client.browsers.create(proxy_country_code="us", browser_profile_id="bp_123")
+```
</file context>
|
|
||
| ```python Python | ||
| from browser_use import BrowserUse | ||
| from playwright.sync_api import sync_playwright |
Contributor
There was a problem hiding this comment.
P3: The Python code snippet imports playwright.sync_api which is a large 3rd-party dependency that cloud SDK users may not have installed. Consider noting that Playwright is required for the CDP approach, or using the existing cloud browser's CDP URL approach without requiring users to install Playwright separately.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/cloud/use-a-profile.mdx, line 36:
<comment>The Python code snippet imports `playwright.sync_api` which is a large 3rd-party dependency that cloud SDK users may not have installed. Consider noting that Playwright is required for the CDP approach, or using the existing cloud browser's CDP URL approach without requiring users to install Playwright separately.</comment>
<file context>
@@ -0,0 +1,79 @@
+
+```python Python
+from browser_use import BrowserUse
+from playwright.sync_api import sync_playwright
+
+client = BrowserUse()
</file context>
| page.goto("https://en.wikipedia.org") | ||
| page.evaluate("localStorage.setItem('demo', 'hello')") | ||
| pw.close() | ||
| client.browsers.stop(b1.id) # flushes state into the profile |
Contributor
There was a problem hiding this comment.
P3: The Python example imports from browser_use import BrowserUse but the SDK package is published as browser-use-sdk on PyPI. The correct import for the v2 synchronous client is from browser_use_sdk import BrowserUse. This code won't run — it will raise an ImportError.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/cloud/use-a-profile.mdx, line 49:
<comment>The Python example imports `from browser_use import BrowserUse` but the SDK package is published as `browser-use-sdk` on PyPI. The correct import for the v2 synchronous client is `from browser_use_sdk import BrowserUse`. This code won't run — it will raise an `ImportError`.</comment>
<file context>
@@ -0,0 +1,79 @@
+ page.goto("https://en.wikipedia.org")
+ page.evaluate("localStorage.setItem('demo', 'hello')")
+ pw.close()
+client.browsers.stop(b1.id) # flushes state into the profile
+
+# Browser 2 — same profile, state is back
</file context>
…utput truth, explicit agent in quickstart, cloud-vs-OSS note - browser_profile_id top-level on runs 422s (live-verified): nest browser.profile_id everywhere; keep top-level only on POST /browsers - structured_output request param not accepted by API (live 422): document shape-in-task pattern, mark typed output as reserved - quickstart: name the agent explicitly in the first snippet + two-agents one-liner (traces: choose-an-agent link seen and skipped when code never names an agent) - quickstart: cloud-vs-open-source-library disambiguation note + inline benchmark stats (traces: OSS-prior pivots in 8/24 code runs, 0/6 organic benchmark discovery) - choose-an-agent: fix workspace_id contradiction (attached_file_ids is the files param) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
2 issues found across 9 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="docs/llms-full.txt">
<violation number="1">
P1: The copy-paste curl example for a logged-in run fails validation because the v1 JSON API expects `browser.profileId`, not `browser.profile_id`. Using the documented command therefore cannot start the run; the raw JSON examples should use the OpenAPI camelCase field names (while keeping snake_case only in SDK argument examples if the SDK translates them).</violation>
</file>
<file name="docs/cloud/llms-full.txt">
<violation number="1">
P1: The standalone-browser profile flow names the raw API field `browser_profile_id`, but v1 expects `browserProfileId`; a copied JSON request is rejected by the strict `CreateBrowser` schema. The prose and standalone-browser examples should distinguish any SDK's Python naming from the camelCase JSON field.</violation>
</file>
Tip: Review your code locally with the cubic CLI to iterate faster.
Fix all with cubic | Re-trigger cubic
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds the unified
/api/v1docs, rendered from the real deployed OpenAPI spec on staging (not a mock).What's here
docs/cloud/openapi/v1.json— generated fromhttps://api-staging.../api/v1/openapi.jsonviamock/export_spec.py. Reflects the deployed contract:browsercode(with the r), async lifecycle (POST 202 + RunAccepted, stop 200, purge 204), no cross-agentGET /runs, registry is justGET /agents.docs.jsonnav — lists exactly the endpoints the spec exposes (agents ×2, browsers, browser-profiles, agent-workspaces, project). Every nav path verified present in the spec.mock/export_spec.py(now pulls the real staging spec); the dead mock app/models/pressure-findings are gitignored.Verified
browscode(wrong spelling): 0 hits.browsercode: correct throughout./api/v1/runs, no/agents/{name}in nav or spec.mint devrenders clean (no "endpoint not found" errors).Opening this so the Mintlify preview deploy builds the full v1 reference.
Summary by cubic
Unifies the
/api/v1docs from the live staging OpenAPI and restructures the site around agents and browsers. Adds benchmarks and profile content, and applies live-verified fixes to examples and guides to match the deployed API.New Features
/api/v1reference indocs/cloud/openapi/v1.jsonwith interactive pages (agents, browsers, browser-profiles, project).llms.txtandllms-full.txtregenerated for v1 and agent focus.Refactors
docs.json.browser_use(Python) andbrowser-use(TypeScript); JSON/curl examples use camelCase; clarified CDP field names (cdpUrl/cdp_url); registry examples match live responses.browser.profile_idon runs (top-levelbrowser_profile_idonly onPOST /browsers); remove unsupportedstructured_outputparam (document shape-in-task pattern, typed output reserved); Quickstart names the agent and clarifies cloud vs open-source library; files/session wording corrected in “Choose an agent.”mock/export_spec.pynow pulls and normalizes the real staging spec for docs.Written for commit 48eb0a5. Summary will update on new commits.