Skip to main content
POST
Create an environment
Creates a custom environment in your catalog. Reference it by id (e.g. "environments": ["wide-browser"]) from any agent. Most agents define environments inline. Register one here to reuse it across agents. Returns 201 with the created environment object.

Request body

The body is a Browser spec (kind: "web", the default), documented below. A desktop on your own machine (kind: "desktop", see Local control) takes only id, host (required), session_id, lazy, settle_s (default 0.5), and screenshot_max_width (up to 1920 pixels, null keeps the host default; screenshots are only shrunk, never enlarged).
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
default:"web"
Environment type: web for a browser, desktop for a desktop.
string
default:"cloud"
Where the browser runs: cloud on H infrastructure, or user_device for Chrome on your own machine. See Local control.
string
default:"https://www.bing.com"
Initial URL to open.
boolean
default:"false"
Run the browser without a visible window.
string | null
Attach to an existing browser session by id instead of starting a new one. For a user_device browser, the Python SDK sets it for you, so set it yourself only to attach to one served with hai local browser.
boolean
default:"false"
Start the browser on the agent’s first browser action instead of when the session starts. Skips the initial observation. See Configuration.
number
default:"1.0"
Seconds the agent waits after each action, so the next observation shows the settled page. 0 to 10.
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, letting the agent sign in to sites with secrets resolved from it. Must belong to your organization. Cloud browsers only. Omit to run without secret access.
string | null
Id of a browser profile to load, restoring saved cookies and storage so the agent starts already signed in. Must belong to your organization. Cloud browsers only. 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 a newly provisioned browser (ignored when session_id attaches to an existing one). Set only one of:
  • managed_proxy: H provisions 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, with any credentials inline (e.g. http://user:pass@host:port).
See Proxy.

Examples

Response

Errors