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.
id
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.
kind
string
Environment type. Currently only web. Defaults to web.
start_url
string
default:"https://www.bing.com"
Initial URL to open.
headless
boolean
default:"false"
Run the browser without a visible window.
mode
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.
vault_id
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.
browser_profile_id
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.
use_default_browser_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.
persist_browser_profile
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.
network
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