H Company Agents API
The Agents API from H Company — 2 operation(s) for agents.
OpenAPI Specification
openapi: 3.1.0
info:
title: Computer-Use Agents API
version: 1.0.0
servers:
- url: https://agp.eu.hcompany.ai
description: Europe
x-fern-server-name: Eu
- url: https://agp.hcompany.ai
description: United States
x-fern-server-name: Us
tags:
- name: Agents
paths:
/api/v2/agents:
post:
tags:
- Agents
summary: Create Agent
description: Create an agent..
operationId: create_agent_api_v2_agents_post
security:
- HTTPBearer: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- Agents
summary: List Agents
description: List reserved + caller's org agents. Unauthenticated callers see reserved ``h/`` agents only.
operationId: list_agents_api_v2_agents_get
security:
- HTTPBearer: []
parameters:
- name: agent_name
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Case-insensitive substring match on agent name.
title: Agent Name
description: Case-insensitive substring match on agent name.
- name: search
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Case-insensitive match on agent name or description.
title: Search
description: Case-insensitive match on agent name or description.
- name: page
in: query
required: false
schema:
type: integer
minimum: 1
description: Page number (1-based)
default: 1
title: Page
description: Page number (1-based)
- name: size
in: query
required: false
schema:
type: integer
maximum: 1000
minimum: 1
description: Number of items per page
default: 10
title: Size
description: Number of items per page
- name: sort
in: query
required: false
schema:
anyOf:
- type: array
items:
enum:
- created_at
- -created_at
- agent_name
- -agent_name
type: string
- type: 'null'
description: Sort by field
default:
- -created_at
title: Sort
description: Sort by field
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/Page_Agent_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v2/agents/{agent_name}:
get:
tags:
- Agents
summary: Get Agent
description: Fetch by identifier; 404 if not visible. ``resolve=true`` materialises spec leaves.
operationId: get_agent_api_v2_agents__agent_name__get
security:
- HTTPBearer: []
parameters:
- name: agent_name
in: path
required: true
schema:
type: string
title: Agent Name
- name: resolve
in: query
required: false
schema:
type: boolean
description: Materialise string environment/skill/subagent leaves into full specs.
default: false
title: Resolve
description: Materialise string environment/skill/subagent leaves into full specs.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
put:
tags:
- Agents
summary: Update Agent
description: Replace ``spec``. ``spec.name`` must match the URL identifier; renames are not supported.
operationId: update_agent_api_v2_agents__agent_name__put
security:
- HTTPBearer: []
parameters:
- name: agent_name
in: path
required: true
schema:
type: string
title: Agent Name
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
patch:
tags:
- Agents
summary: Patch Agent
description: Partially update an agent spec; only provided fields change.
operationId: patch_agent_api_v2_agents__agent_name__patch
security:
- HTTPBearer: []
parameters:
- name: agent_name
in: path
required: true
schema:
type: string
title: Agent Name
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PatchAgent'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Agents
summary: Delete Agent
description: 'Delete by identifier. Reserved rows: H employee only.'
operationId: delete_agent_api_v2_agents__agent_name__delete
security:
- HTTPBearer: []
parameters:
- name: agent_name
in: path
required: true
schema:
type: string
title: Agent Name
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
Desktop:
properties:
id:
type: string
minLength: 1
title: Id
description: Catalog identifier for this environment.
kind:
type: string
const: desktop
title: Kind
default: desktop
host:
type: string
title: Host
const: user_device
session_id:
anyOf:
- type: string
- type: 'null'
title: Session Id
description: Connect to an existing desktop session by id instead of starting a new one.
type: object
required:
- id
- host
title: Desktop
description: A desktop the agent controls via mouse, keyboard, and screenshots.
PatchAgent:
properties:
description:
anyOf:
- type: string
minLength: 1
- type: 'null'
title: Description
environments:
anyOf:
- items:
anyOf:
- type: string
- $ref: '#/components/schemas/Environment'
type: array
- type: 'null'
title: Environments
model:
anyOf:
- type: string
- type: 'null'
title: Model
instructions:
anyOf:
- type: string
- type: 'null'
title: Instructions
subagents:
anyOf:
- items:
anyOf:
- type: string
- $ref: '#/components/schemas/Agent'
type: array
- type: 'null'
title: Subagents
skills:
anyOf:
- items:
anyOf:
- type: string
- $ref: '#/components/schemas/Skill'
type: array
- type: 'null'
title: Skills
answer_format:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Answer Format
tools:
anyOf:
- items:
$ref: '#/components/schemas/ToolDefinition'
type: array
- type: 'null'
title: Tools
type: object
title: PatchAgent
description: Partial agent update.
BrowserNetwork:
properties:
proxy_url:
anyOf:
- type: string
- type: 'null'
title: Proxy Url
description: Optional bring-your-own HTTP/HTTPS/SOCKS proxy URL for browser egress (e.g. http://user:pass@proxy.example.com:8080). Applied when provisioning a new remote browser session. Only supported for chromium-based browser runners (headful and headless). Ignored when session_id attaches to an existing session. Mutually exclusive with managed_proxy.
managed_proxy:
anyOf:
- $ref: '#/components/schemas/ManagedProxySelection'
- type: 'null'
description: Optional H-managed proxy (e.g. Oxylabs), provisioned for the session. Applied when provisioning a new remote browser session. Only supported for chromium-based browser runners (headful and headless). Ignored when session_id attaches to an existing session. Mutually exclusive with proxy_url.
type: object
title: BrowserNetwork
description: Network egress settings for a remote browser session.
Environment:
oneOf:
- $ref: '#/components/schemas/Browser'
- $ref: '#/components/schemas/Desktop'
discriminator:
propertyName: kind
mapping:
desktop: '#/components/schemas/Desktop'
web: '#/components/schemas/Browser'
Page_Agent_:
properties:
items:
items:
$ref: '#/components/schemas/Agent'
type: array
title: Items
total:
type: integer
title: Total
page:
type: integer
title: Page
type: object
required:
- items
- total
- page
title: Page[Agent]
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
Skill:
properties:
name:
type: string
minLength: 1
title: Name
description: 'Unique name for this skill in your catalog. Format: lowercase ASCII letters, digits and hyphens; must start and end with alphanumeric; max 63 chars per segment; optional single ''org/'' namespace prefix (e.g. ''h/web-environment'').'
description:
type: string
minLength: 1
title: Description
description: When to use this skill. The agent reads this to decide whether to load it.
body:
type: string
minLength: 1
title: Body
description: Markdown instructions the agent loads when it uses the skill.
source:
anyOf:
- type: string
- type: 'null'
title: Source
description: Optional URL the content was sourced from.
url_pattern:
anyOf:
- type: string
maxLength: 1024
minLength: 1
- type: 'null'
title: Url Pattern
description: Optional regex hinting at URLs where this skill applies.
type: object
required:
- name
- description
- body
title: Skill
description: A named, reusable instruction an agent can draw on during a session.
ToolDefinition:
properties:
name:
type: string
maxLength: 64
minLength: 1
title: Name
description: 'Tool name advertised to the model. Format: letters, digits and underscores; must start with a letter or underscore; max 64 chars.'
description:
type: string
minLength: 1
title: Description
description: What the tool does, when to use it, and what it returns. Shown to the model verbatim.
input_schema:
additionalProperties: true
type: object
title: Input Schema
description: JSON Schema (object type) describing the tool call arguments.
type: object
required:
- name
- description
title: ToolDefinition
description: 'Contract for a tool executed by the API client, not by the agent runtime.
The agent emits a tool call matching ``input_schema``, pauses, and resumes
once the client sends back the corresponding tool result.'
BrowserVisualMode:
properties:
type:
type: string
const: visual
title: Type
default: visual
width:
type: integer
exclusiveMinimum: 0.0
title: Width
description: Viewport width in pixels.
default: 1200
height:
type: integer
exclusiveMinimum: 0.0
title: Height
description: Viewport height in pixels.
default: 1200
markdown:
type: boolean
title: Markdown
description: Also include the viewport's text as markdown alongside each screenshot.
default: false
type: object
title: BrowserVisualMode
description: Act on screenshots by viewport coordinates.
ProxyPool:
type: string
enum:
- residential
- datacenter
- isp
- mobile
title: ProxyPool
description: The kind of upstream IPs a managed proxy draws from.
BrowserTextMode:
properties:
type:
type: string
const: text
title: Type
default: text
chunk_size:
type: integer
exclusiveMinimum: 0.0
title: Chunk Size
description: Characters of page text shown per page.
default: 20000
type: object
title: BrowserTextMode
description: Read-only markdown with URL navigation, no screenshots.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
Agent:
properties:
name:
type: string
maxLength: 127
minLength: 1
title: Name
description: 'Unique name for this agent in your catalog. Format: lowercase ASCII letters, digits and hyphens; must start and end with alphanumeric; max 63 chars per segment; optional single ''org/'' namespace prefix (e.g. ''h/web-environment'').'
description:
type: string
minLength: 1
title: Description
description: What the agent does. Parent agents read this to decide when to delegate to it.
environments:
items:
anyOf:
- type: string
- $ref: '#/components/schemas/Environment'
type: array
title: Environments
description: Environments the agent runs in. Each entry is a registered environment's id or an inline definition. At most one per kind. Required unless the agent delegates to subagents (a pure orchestrator owns none).
model:
anyOf:
- type: string
- type: 'null'
title: Model
description: Model that serves the agent. Defaults to the platform model if omitted.
instructions:
anyOf:
- type: string
- type: 'null'
title: Instructions
description: Instructions appended to the agent's system prompt to steer behavior.
subagents:
anyOf:
- items:
anyOf:
- type: string
- $ref: '#/components/schemas/Agent'
type: array
- type: 'null'
title: Subagents
description: Agents this one can delegate to. Each entry is a registered agent's name or an inline definition.
skills:
anyOf:
- items:
anyOf:
- type: string
- $ref: '#/components/schemas/Skill'
type: array
- type: 'null'
title: Skills
description: Skills the agent can draw on. Each entry is a registered skill's name or an inline definition.
answer_format:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Answer Format
description: JSON Schema the agent's final answer must conform to. Null returns a free-form text answer.
tools:
anyOf:
- items:
$ref: '#/components/schemas/ToolDefinition'
type: array
- type: 'null'
title: Tools
description: Custom tools executed by the API client. The agent emits a tool call, pauses, and resumes once the client sends back the matching tool result.
type: object
required:
- name
- description
- environments
title: Agent
description: Declarative agent definition.
ManagedProxySelection:
properties:
country:
anyOf:
- type: string
- type: 'null'
title: Country
description: Two-letter ISO 3166-1 country to source IPs from (e.g. 'US'). Validated server-side.
sticky:
type: boolean
title: Sticky
description: Keep the same IP across the session where the pool allows it.
default: true
pool:
$ref: '#/components/schemas/ProxyPool'
description: Which upstream IP pool to draw from.
default: residential
type: object
title: ManagedProxySelection
description: 'Request for an H-managed proxy, provisioned per session.
Describes intent only — pool, country, stickiness — never credentials; H resolves
and injects those when provisioning the session, including which provider backs
the requested pool.'
Browser:
properties:
id:
type: string
minLength: 1
title: Id
description: Catalog identifier for this environment.
kind:
type: string
const: web
title: Kind
default: web
host:
type: string
enum:
- user_device
- cloud
title: Host
description: 'Where the browser runs: ''cloud'' on H Company infrastructure, or ''user_device'' on your own machine.'
default: cloud
start_url:
type: string
title: Start Url
description: Initial URL to open.
default: https://www.bing.com
headless:
type: boolean
title: Headless
description: Run the browser without a visible window.
default: false
session_id:
anyOf:
- type: string
- type: 'null'
title: Session Id
description: Connect to an existing browser session by id instead of starting a new one.
mode:
oneOf:
- $ref: '#/components/schemas/BrowserVisualMode'
- $ref: '#/components/schemas/BrowserTextMode'
title: Mode
description: How the agent perceives and drives the browser.
discriminator:
propertyName: type
mapping:
text: '#/components/schemas/BrowserTextMode'
visual: '#/components/schemas/BrowserVisualMode'
vault_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Vault Id
description: Id of a vault config to bind to this browser, letting the agent sign in to sites with secrets resolved from the vault. The vault must belong to the caller's organization. Only supported on cloud-hosted browsers. Omit to run without secret access.
browser_profile_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Browser Profile Id
description: Id of a browser profile to load into this browser, restoring saved cookies and storage state from a prior session. The profile must belong to the caller's organization. Only supported on cloud-hosted browsers. Omit to run with a fresh profile.
use_default_browser_profile:
type: boolean
title: Use Default Browser Profile
description: When true, load the caller's default browser profile for this browser flavor (marked via the browser-profiles API) instead of naming one explicitly. Mutually exclusive with browser_profile_id. When no default exists, an empty profile is auto-created and marked default; default-profile sessions save their final state back on stop when no other session is already persisting the profile. Only supported on cloud-hosted browsers.
default: false
persist_browser_profile:
type: boolean
title: Persist Browser Profile
description: When true, the browser profile is updated with this session's final browser state (cookies, storage) when the session ends. Requires browser_profile_id or use_default_browser_profile. Only one active session at a time may persist a given profile; concurrent read-only use is always allowed.
default: false
network:
anyOf:
- $ref: '#/components/schemas/BrowserNetwork'
- type: 'null'
description: Optional network configuration for the remote browser session. Applied only when a new runner session is provisioned (not when session_id is set).
type: object
required:
- id
title: Browser
description: A web browser the agent navigates and acts on.
securitySchemes:
HTTPBearer:
type: http
scheme: bearer