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>",
"start_url": "<string>",
"headless": true,
"mode": {},
"vault_id": {},
"browser_profile_id": {},
"use_default_browser_profile": true,
"persist_browser_profile": true,
"network": {}
}
'import requests
url = "https://agp.eu.hcompany.ai/api/v2/environments"
payload = {
"id": "<string>",
"kind": "<string>",
"start_url": "<string>",
"headless": True,
"mode": {},
"vault_id": {},
"browser_profile_id": {},
"use_default_browser_profile": True,
"persist_browser_profile": True,
"network": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
id: '<string>',
kind: '<string>',
start_url: '<string>',
headless: true,
mode: {},
vault_id: {},
browser_profile_id: {},
use_default_browser_profile: true,
persist_browser_profile: true,
network: {}
})
};
fetch('https://agp.eu.hcompany.ai/api/v2/environments', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://agp.eu.hcompany.ai/api/v2/environments",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'id' => '<string>',
'kind' => '<string>',
'start_url' => '<string>',
'headless' => true,
'mode' => [
],
'vault_id' => [
],
'browser_profile_id' => [
],
'use_default_browser_profile' => true,
'persist_browser_profile' => true,
'network' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://agp.eu.hcompany.ai/api/v2/environments"
payload := strings.NewReader("{\n \"id\": \"<string>\",\n \"kind\": \"<string>\",\n \"start_url\": \"<string>\",\n \"headless\": true,\n \"mode\": {},\n \"vault_id\": {},\n \"browser_profile_id\": {},\n \"use_default_browser_profile\": true,\n \"persist_browser_profile\": true,\n \"network\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://agp.eu.hcompany.ai/api/v2/environments")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"id\": \"<string>\",\n \"kind\": \"<string>\",\n \"start_url\": \"<string>\",\n \"headless\": true,\n \"mode\": {},\n \"vault_id\": {},\n \"browser_profile_id\": {},\n \"use_default_browser_profile\": true,\n \"persist_browser_profile\": true,\n \"network\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://agp.eu.hcompany.ai/api/v2/environments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"id\": \"<string>\",\n \"kind\": \"<string>\",\n \"start_url\": \"<string>\",\n \"headless\": true,\n \"mode\": {},\n \"vault_id\": {},\n \"browser_profile_id\": {},\n \"use_default_browser_profile\": true,\n \"persist_browser_profile\": true,\n \"network\": {}\n}"
response = http.request(request)
puts response.read_bodyEnvironments
Create an environment
Create a reusable environment in your own catalog.
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>",
"start_url": "<string>",
"headless": true,
"mode": {},
"vault_id": {},
"browser_profile_id": {},
"use_default_browser_profile": true,
"persist_browser_profile": true,
"network": {}
}
'import requests
url = "https://agp.eu.hcompany.ai/api/v2/environments"
payload = {
"id": "<string>",
"kind": "<string>",
"start_url": "<string>",
"headless": True,
"mode": {},
"vault_id": {},
"browser_profile_id": {},
"use_default_browser_profile": True,
"persist_browser_profile": True,
"network": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
id: '<string>',
kind: '<string>',
start_url: '<string>',
headless: true,
mode: {},
vault_id: {},
browser_profile_id: {},
use_default_browser_profile: true,
persist_browser_profile: true,
network: {}
})
};
fetch('https://agp.eu.hcompany.ai/api/v2/environments', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://agp.eu.hcompany.ai/api/v2/environments",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'id' => '<string>',
'kind' => '<string>',
'start_url' => '<string>',
'headless' => true,
'mode' => [
],
'vault_id' => [
],
'browser_profile_id' => [
],
'use_default_browser_profile' => true,
'persist_browser_profile' => true,
'network' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://agp.eu.hcompany.ai/api/v2/environments"
payload := strings.NewReader("{\n \"id\": \"<string>\",\n \"kind\": \"<string>\",\n \"start_url\": \"<string>\",\n \"headless\": true,\n \"mode\": {},\n \"vault_id\": {},\n \"browser_profile_id\": {},\n \"use_default_browser_profile\": true,\n \"persist_browser_profile\": true,\n \"network\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://agp.eu.hcompany.ai/api/v2/environments")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"id\": \"<string>\",\n \"kind\": \"<string>\",\n \"start_url\": \"<string>\",\n \"headless\": true,\n \"mode\": {},\n \"vault_id\": {},\n \"browser_profile_id\": {},\n \"use_default_browser_profile\": true,\n \"persist_browser_profile\": true,\n \"network\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://agp.eu.hcompany.ai/api/v2/environments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"id\": \"<string>\",\n \"kind\": \"<string>\",\n \"start_url\": \"<string>\",\n \"headless\": true,\n \"mode\": {},\n \"vault_id\": {},\n \"browser_profile_id\": {},\n \"use_default_browser_profile\": true,\n \"persist_browser_profile\": true,\n \"network\": {}\n}"
response = http.request(request)
puts response.read_bodyCreates 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}. Setmarkdown: trueto include the page’s text alongside the screenshot.text:{"type": "text", "chunk_size": 20000}. Read-only paginated markdown, no screenshots.
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 withpool(residential, default, ordatacenter),country(two-letter ISO code, optional), andsticky(keep one exit IP for the session, defaulttrue). 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).
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",
"start_url": "https://www.google.com",
"mode": {"type": "visual", "width": 1920, "height": 1080}
}'
from hai_agents import Client
client = Client()
environment = client.environments.create_environment(
id="wide-browser",
start_url="https://www.google.com",
mode={"type": "visual", "width": 1920, "height": 1080},
)
print(environment.id)
import { HaiAgentsClient } from "hai-agents";
const client = new HaiAgentsClient();
const environment = await client.environments.createEnvironment({
kind: "web",
id: "wide-browser",
startUrl: "https://www.google.com",
mode: { type: "visual", width: 1920, height: 1080 },
});
console.log(environment.id);
Response
{
"id": "wide-browser",
"kind": "web",
"start_url": "https://www.google.com",
"mode": {"type": "visual", "width": 1920, "height": 1080, "markdown": false},
"vault_id": null,
"browser_profile_id": null,
"use_default_browser_profile": false,
"persist_browser_profile": false,
"network": null
}
Errors
| Status | Cause |
|---|---|
403 | Attempted to use the reserved h/ namespace. |
409 | An environment with this id already exists in your catalog. |
422 | Body fails validation. Common cases: invalid id shape, missing required field. |
Last modified on September 11, 2026
Was this page helpful?