Skip to main content
POST
/
api
/
v2
/
environments
Create an environment
curl --request POST \
  --url https://agp.eu.hcompany.ai/api/v2/environments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "<string>",
  "kind": "<string>",
  "width": 123,
  "height": 123,
  "start_url": "<string>",
  "mode": "<string>",
  "page_chars": 123,
  "vault_id": {},
  "browser_profile_id": {},
  "network": {}
}
'
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 employees (rejected with 403 otherwise). Immutable after creation.
​
kind
string
Environment type. Currently only web. Defaults to web.
​
width
integer
default:"1200"
Viewport width in pixels. Must be a positive integer.
​
height
integer
default:"1200"
Viewport height in pixels. Must be a positive integer.
​
start_url
string
default:"https://www.bing.com"
Initial URL to open.
​
mode
string
How the agent perceives and drives the browser: visual (default), multimodal, or text. See Modes.
​
page_chars
integer
default:"20000"
Characters of page text shown per page in text mode. Rejected in other modes.
​
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.
​
network
object | null
Network settings for the browser session. Holds a single field, 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). Only headful chromium sessions support a proxy; ignored when session_id attaches to an existing session. See Proxy.

​
Examples

curl -X POST https://agp.eu.hcompany.ai/api/v2/environments \
  -H "Authorization: Bearer $HAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "wide-browser",
    "kind": "web",
    "width": 1920,
    "height": 1080,
    "start_url": "https://www.google.com"
  }'
Response
{
  "id": "wide-browser",
  "kind": "web",
  "width": 1920,
  "height": 1080,
  "start_url": "https://www.google.com",
  "mode": "visual",
  "page_chars": 20000,
  "vault_id": null,
  "browser_profile_id": null,
  "network": null
}

​
Errors

StatusCause
403Attempted to use the reserved h/ namespace without H employee privileges.
409An environment with this id already exists in your catalog.
422Body fails validation; common cases: invalid id shape, missing required field.