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>",
  "headless": true,
  "width": 123,
  "height": 123,
  "start_url": {},
  "mode": "<string>"
}
'
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; reach for 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.
​
headless
boolean
required
Run without a visible window.
​
width
integer
required
Viewport width in pixels. Must be a positive integer.
​
height
integer
required
Viewport height in pixels. Must be a positive integer.
​
start_url
string | null
required
Initial URL to open. Pass null to start on a blank page.
​
mode
string
How the agent perceives and drives the browser: visual (default), multimodal, or text. See Modes.

​
Examples

curl -X POST https://agp.eu.hcompany.ai/api/v2/environments \
  -H "Authorization: Bearer $H_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "wide-browser",
    "kind": "web",
    "headless": true,
    "width": 1920,
    "height": 1080,
    "start_url": null
  }'
Response
{
  "id": "wide-browser",
  "kind": "web",
  "headless": true,
  "width": 1920,
  "height": 1080,
  "start_url": null,
  "mode": "visual"
}

​
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.