Create an item

curl --request POST \
  --url https://agp.eu.hcompany.ai/api/v2/vaults/{vault_id}/items \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "urls": [
    "<string>"
  ],
  "values": {}
}
'

import requests

url = "https://agp.eu.hcompany.ai/api/v2/vaults/{vault_id}/items"

payload = {
    "name": "<string>",
    "urls": ["<string>"],
    "values": {}
}
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({name: '<string>', urls: ['<string>'], values: {}})
};

fetch('https://agp.eu.hcompany.ai/api/v2/vaults/{vault_id}/items', 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/vaults/{vault_id}/items",
  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([
    'name' => '<string>',
    'urls' => [
        '<string>'
    ],
    'values' => [
        
    ]
  ]),
  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/vaults/{vault_id}/items"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"urls\": [\n    \"<string>\"\n  ],\n  \"values\": {}\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/vaults/{vault_id}/items")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"urls\": [\n    \"<string>\"\n  ],\n  \"values\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://agp.eu.hcompany.ai/api/v2/vaults/{vault_id}/items")

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  \"name\": \"<string>\",\n  \"urls\": [\n    \"<string>\"\n  ],\n  \"values\": {}\n}"

response = http.request(request)
puts response.read_body

POST

api

vaults

{vault_id}

items

Create an item

curl --request POST \
  --url https://agp.eu.hcompany.ai/api/v2/vaults/{vault_id}/items \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "urls": [
    "<string>"
  ],
  "values": {}
}
'

import requests

url = "https://agp.eu.hcompany.ai/api/v2/vaults/{vault_id}/items"

payload = {
    "name": "<string>",
    "urls": ["<string>"],
    "values": {}
}
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({name: '<string>', urls: ['<string>'], values: {}})
};

fetch('https://agp.eu.hcompany.ai/api/v2/vaults/{vault_id}/items', 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/vaults/{vault_id}/items",
  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([
    'name' => '<string>',
    'urls' => [
        '<string>'
    ],
    'values' => [
        
    ]
  ]),
  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/vaults/{vault_id}/items"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"urls\": [\n    \"<string>\"\n  ],\n  \"values\": {}\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/vaults/{vault_id}/items")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"urls\": [\n    \"<string>\"\n  ],\n  \"values\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://agp.eu.hcompany.ai/api/v2/vaults/{vault_id}/items")

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  \"name\": \"<string>\",\n  \"urls\": [\n    \"<string>\"\n  ],\n  \"values\": {}\n}"

response = http.request(request)
puts response.read_body

An item holds one login. Agents whose browser environment binds the vault fill it on pages that match its urls. The response lists which fields are set, never their values. Read them back with Reveal an item. Returns 201 with the created item object.

Path parameters

string

required

The H-hosted vault’s id (UUID).

Request body

string

required

Label for the item, 1 to 255 characters.

string[]

required

The sites this item signs in to: 1 to 20 http or https URLs with a host. A page matches when its hostname equals, or is a subdomain of, one of them.

object

required

Secret values by field, at least one. Keys: username, password, email, totp, api_key. Each value is a string of 1 to 4096 characters.For totp, send the authenticator secret: base32, or an otpauth://totp/ URI. fill_secret_at types the current code and reveal returns it. The secret itself is never returned.

Examples

curl -X POST https://agp.eu.hcompany.ai/api/v2/vaults/3b8d9c2e-6f1a-4e5b-8c7d-0a9b8c7d6e5f/items \
  -H "Authorization: Bearer $HAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example admin",
    "urls": ["https://example.com/login"],
    "values": {"username": "admin@example.com", "password": "s3cret", "totp": "JBSWY3DPEHPK3PXP"}
  }'

from hai_agents import Client

client = Client()

item = client.vaults.create_vault_item(
    vault_id="3b8d9c2e-6f1a-4e5b-8c7d-0a9b8c7d6e5f",
    name="Example admin",
    urls=["https://example.com/login"],
    values={"username": "admin@example.com", "password": "s3cret", "totp": "JBSWY3DPEHPK3PXP"},
)
print(item.id, item.fields)

import { HaiAgentsClient } from "hai-agents";

const client = new HaiAgentsClient();

const item = await client.vaults.createVaultItem({
  vaultId: "3b8d9c2e-6f1a-4e5b-8c7d-0a9b8c7d6e5f",
  name: "Example admin",
  urls: ["https://example.com/login"],
  values: { username: "admin@example.com", password: "s3cret", totp: "JBSWY3DPEHPK3PXP" },
});
console.log(item.id, item.fields);

Response

{
  "id": "7c1e4b2a-9d3f-4a6b-8e5c-2f1a0b9c8d7e",
  "vault_id": "3b8d9c2e-6f1a-4e5b-8c7d-0a9b8c7d6e5f",
  "name": "Example admin",
  "urls": ["https://example.com/login"],
  "fields": ["password", "totp", "username"],
  "created_at": "2026-05-08T09:15:00Z",
  "updated_at": "2026-05-08T09:15:00Z"
}

Errors

Status	Cause
`400`	The vault is not H-hosted, or the `totp` value is not a valid authenticator secret.
`403`	Your organization reached its vault item limit (1000, across all its vaults). Delete items you no longer need.
`404`	Vault not found or you don’t have access.
`422`	Body failed validation: a URL that is not `http(s)`, an unknown field, an empty value, or a length out of range. Validation errors never echo the submitted values.

Agents

Environments

Sessions

Skills

Vaults

Browser Profiles

Webhooks

Schedules

Create an item

Path parameters

Request body

Examples

Errors

​Path parameters

​Request body

​Examples

​Errors

Path parameters

Request body

Examples

Errors