Skip to main content
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.
string
required
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.
string
Environment type. Currently only web. Defaults to web.
string
default:"https://www.bing.com"
Initial URL to open.
boolean
default:"false"
Run the browser without a visible window.
object
default:"{\"type\": \"visual\"}"
How the agent perceives and drives the browser. An object keyed by type:
  • visual (default): {"type": "visual", "width": 1200, "height": 1200, "markdown": false}. Set markdown: true to include the page’s text alongside the screenshot.
  • text: {"type": "text", "chunk_size": 20000}. Read-only paginated markdown, no screenshots.
See Modes and Mode fields.
string | null
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.
string | null
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.
boolean
default:"false"
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.
boolean
default:"false"
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.
object | null
Network settings for the browser session. Set only one of:
  • managed_proxy: have H provision a proxy for browser egress. An object with pool (residential, default, or datacenter), country (two-letter ISO code, optional), and sticky (keep one exit IP for the session, default true). 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).
See Proxy.

Examples

Response

Errors

Last modified on September 11, 2026