Create an environment
Environments
Create an environment
Create a reusable environment in your own catalog.
POST
Create an environment
Creates a new custom environment in your catalog. Once created, reference it by
id (e.g. "environments": ["wide-browser"]) from any agent. Most users define environments inline on the agent instead; use this endpoint to reuse one environment across several agents.
Returns 201 with the created Environment object.
Request body
The body is a Browser spec.Catalog identifier, kebab-case with an optional single
org/ namespace prefix. The h/ prefix is reserved for H’s catalog (rejected with 403). Immutable after creation.Environment type. Currently only
web. Defaults to web.Initial URL to open.
Run the browser without a visible window.
How the agent perceives and drives the browser. An object keyed by
type:visual(default):{"type": "visual", "width": 1200, "height": 1200, "markdown": false}. Setmarkdown: trueto include the page’s text alongside the screenshot.text:{"type": "text", "chunk_size": 20000}. Read-only paginated markdown, no screenshots.
Id of a vault to bind to this browser, letting the agent sign in to sites with secrets resolved from the vault. Must reference a vault in your organization. Omit to run without secret access.
Id of a browser profile to load into this browser, restoring saved cookies and storage so the agent starts the session already signed in. Must reference a profile in your organization. Omit to start with a fresh profile.
Load your default browser profile instead of naming one, auto-creating an empty one on first use. Sessions save their final state back automatically (best-effort). Mutually exclusive with
browser_profile_id.Save the session’s final browser state back into the loaded profile when it ends. Requires
browser_profile_id or use_default_browser_profile. Best-effort: if another session is already persisting the profile, the session starts read-only instead of failing.Network settings for the browser session. Set only one of:
managed_proxy: have H provision a proxy for browser egress. An object withpool(residential, default, ordatacenter),country(two-letter ISO code, optional), andsticky(keep one exit IP for the session, defaulttrue). Credentials are resolved server-side and never appear in your requests.proxy_url: a bring-your-own HTTP/HTTPS/SOCKS proxy URL for browser egress, with any credentials inline (e.g.http://user:pass@host:port).
Examples
Response