H Company Sessions API
The Sessions API from H Company — 15 operation(s) for sessions.
The Sessions API from H Company — 15 operation(s) for sessions.
openapi: 3.1.0
info:
title: Computer-Use Agents Sessions 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: Sessions
paths:
/api/v2/sessions:
post:
tags:
- Sessions
summary: Create Session
description: Create an agentic session.
operationId: create_session_api_v2_sessions_post
security:
- HTTPBearer: []
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
anyOf:
- type: string
minLength: 1
maxLength: 255
- type: 'null'
title: Idempotency-Key
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SessionRequest'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/Session'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- Sessions
summary: List Sessions
description: List sessions visible to ``user``.
operationId: list_sessions_api_v2_sessions_get
security:
- HTTPBearer: []
parameters:
- name: owner
in: query
required: false
schema:
enum:
- me
- me-in-organization
- organization
- me-or-organization
type: string
default: me-in-organization
title: Owner
- name: status
in: query
required: false
schema:
anyOf:
- type: array
items:
$ref: '#/components/schemas/TrajectoryStatus'
- type: 'null'
title: Status
- name: agent
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
- type: 'null'
title: Agent
- name: group_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Group Id
- name: parent_session_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Parent Session Id
- name: schedule_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
description: Only sessions created by this schedule.
title: Schedule Id
description: Only sessions created by this schedule.
- name: search
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Case-insensitive match on the session's first message or answer.
title: Search
description: Case-insensitive match on the session's first message or answer.
- name: created_before
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created Before
- name: created_after
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created After
- name: finished_before
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Finished Before
- name: finished_after
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Finished After
- 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: 100
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
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_SessionSummary_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v2/sessions/quota:
get:
tags:
- Sessions
summary: Get Session Quota
description: Concurrent-session quota for the authenticated user.
operationId: get_session_quota_api_v2_sessions_quota_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/QuotaStatus'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/api/v2/sessions/{id}:
get:
tags:
- Sessions
summary: Get Session
description: Get a session.
operationId: get_session_api_v2_sessions__id__get
security:
- HTTPBearer: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
title: Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/Session'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Sessions
summary: Cancel Session
description: Cancel the session.
operationId: cancel_session_api_v2_sessions__id__delete
security:
- HTTPBearer: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
title: Id
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v2/sessions/{id}/status:
get:
tags:
- Sessions
summary: Get Session Status
description: Get a session's live status.
operationId: get_session_status_api_v2_sessions__id__status_get
security:
- HTTPBearer: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
title: Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SessionStatus'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v2/sessions/{id}/messages:
post:
tags:
- Sessions
summary: Send Session Messages
description: Send a user message (single or batch).
operationId: send_session_messages_api_v2_sessions__id__messages_post
security:
- HTTPBearer: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
title: Id
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/UserMessageEvent'
- $ref: '#/components/schemas/UserMessageBatch'
discriminator:
propertyName: type
mapping:
user_message: '#/components/schemas/UserMessageEvent'
batch: '#/components/schemas/UserMessageBatch'
title: Input
responses:
'202':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v2/sessions/{id}/tool_results:
post:
tags:
- Sessions
summary: Send Session Tool Results
description: Send results for custom tool calls (single or batch).
operationId: send_session_tool_results_api_v2_sessions__id__tool_results_post
security:
- HTTPBearer: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
title: Id
requestBody:
required: true
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/ToolResultEvent'
- $ref: '#/components/schemas/ErrorEvent'
- $ref: '#/components/schemas/ToolResultBatch'
title: Input
responses:
'202':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v2/sessions/{id}/pause:
post:
tags:
- Sessions
summary: Pause Session
description: Pause the session.
operationId: pause_session_api_v2_sessions__id__pause_post
security:
- HTTPBearer: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
title: Id
responses:
'202':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v2/sessions/{id}/resume:
post:
tags:
- Sessions
summary: Resume Session
description: Resume the session.
operationId: resume_session_api_v2_sessions__id__resume_post
security:
- HTTPBearer: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
title: Id
responses:
'202':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v2/sessions/{id}/force_answer:
post:
tags:
- Sessions
summary: Force Session Answer
description: Ask the agent to emit a final answer on its next step.
operationId: force_session_answer_api_v2_sessions__id__force_answer_post
security:
- HTTPBearer: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
title: Id
responses:
'202':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v2/sessions/{id}/changes:
get:
tags:
- Sessions
summary: Get Session Changes
description: Long-poll for new events since ``from_index``; 204 if none arrive within ``wait_for_seconds``.
operationId: get_session_changes_api_v2_sessions__id__changes_get
security:
- HTTPBearer: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
title: Id
- name: from_index
in: query
required: false
schema:
type: integer
default: 0
title: From Index
- name: limit
in: query
required: false
schema:
anyOf:
- type: integer
minimum: 0
- type: 'null'
title: Limit
- name: include_events
in: query
required: false
schema:
type: boolean
default: true
title: Include Events
- name: wait_for_seconds
in: query
required: false
schema:
type: integer
maximum: 25
minimum: 0
default: 0
title: Wait For Seconds
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SessionChanges'
'204':
description: No changes since the specified index
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v2/sessions/{id}/events:
get:
tags:
- Sessions
summary: List Session Events
description: Paginated event history. Use ``/changes`` for live tailing.
operationId: list_session_events_api_v2_sessions__id__events_get
security:
- HTTPBearer: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
title: Id
- name: page
in: query
required: false
schema:
type: integer
minimum: 1
default: 1
title: Page
- name: size
in: query
required: false
schema:
type: integer
maximum: 200
minimum: 1
default: 50
title: Size
- name: sort
in: query
required: false
schema:
anyOf:
- type: array
items:
enum:
- timestamp
- -timestamp
type: string
- type: 'null'
title: Sort
- name: type
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Type
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/Page_SessionEvent_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v2/sessions/{id}/feedback:
post:
tags:
- Sessions
summary: Submit Session Feedback
description: Record semantic-success feedback on the whole session.
operationId: submit_session_feedback_api_v2_sessions__id__feedback_post
security:
- HTTPBearer: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
title: Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Feedback'
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v2/sessions/{id}/events/{event_index}/feedback:
put:
tags:
- Sessions
summary: Submit Event Feedback
description: Record feedback on a single event in the session's history.
operationId: submit_event_feedback_api_v2_sessions__id__events__event_index__feedback_put
security:
- HTTPBearer: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
title: Id
- name: event_index
in: path
required: true
schema:
type: integer
title: Event Index
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Feedback'
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v2/sessions/{id}/share:
post:
tags:
- Sessions
summary: Share Session
description: Make the session publicly readable; returns the share URL path.
operationId: share_session_api_v2_sessions__id__share_post
security:
- HTTPBearer: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
title: Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ShareLink'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Sessions
summary: Unshare Session
description: Revoke public access to the session.
operationId: unshare_session_api_v2_sessions__id__share_delete
security:
- HTTPBearer: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
title: Id
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v2/sessions/{id}/resources/{bucket}/{key}:
get:
tags:
- Sessions
summary: Get Session Resource
description: Redirect to a presigned S3 URL for a session-owned resource.
operationId: get_session_resource_api_v2_sessions__id__resources__bucket___key__get
security:
- HTTPBearer: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
title: Id
- name: bucket
in: path
required: true
schema:
type: string
title: Bucket
- name: key
in: path
required: true
schema:
type: string
title: Key
responses:
'302':
description: Redirect to a presigned URL for a session-owned resource.
'200':
description: Resource bytes. The API redirects to a presigned S3 URL; SDK clients follow the redirect and receive the raw object (e.g. screenshot image bytes).
content:
application/octet-stream: {}
'404':
description: Session or resource not found.
4XX:
description: Client error.
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.
PolicyEvent:
properties:
kind:
type: string
const: policy_event
title: Kind
default: policy_event
reasoning_content:
anyOf:
- type: string
- type: 'null'
title: Reasoning Content
content:
anyOf:
- type: string
- type: 'null'
title: Content
tool_reqs:
items:
$ref: '#/components/schemas/ToolRequest'
type: array
title: Tool Reqs
validation_errors:
items:
type: string
type: array
title: Validation Errors
description: Validation errors raised while parsing the model output.
type: object
title: PolicyEvent
description: 'One policy (LLM) step: the model output plus the tool requests extracted from it.'
ActiveStateChangeEvent:
properties:
timestamp:
type: string
format: date-time
title: Timestamp
type:
type: string
const: ActiveStateChangeEvent
title: Type
data:
$ref: '#/components/schemas/ActiveStateChangeData'
additionalProperties: true
type: object
required:
- timestamp
- type
- data
title: ActiveStateChangeEvent
description: The agent switched between running, idle and awaiting custom tool results.
Metrics:
properties:
steps:
type: integer
title: Steps
description: Steps taken so far.
default: 0
cost_per_model:
items:
$ref: '#/components/schemas/ModelCost'
type: array
title: Cost Per Model
description: Per-model token usage and cost.
input_cost:
anyOf:
- type: number
- type: 'null'
title: Input Cost
description: Total input cost in USD; null if any model is unpriced.
output_cost:
anyOf:
- type: number
- type: 'null'
title: Output Cost
description: Total output cost in USD; null if any model is unpriced.
reasoning_cost:
anyOf:
- type: number
- type: 'null'
title: Reasoning Cost
description: Total reasoning cost in USD; null if any model is unpriced.
total_cost:
anyOf:
- type: number
- type: 'null'
title: Total Cost
description: Total cost in USD; null if any model is unpriced.
additionalProperties: true
type: object
title: Metrics
description: Rolled-up usage and cost for a session.
QuotaStatus:
properties:
scope:
type: string
enum:
- user
- org
title: Scope
limit:
type: integer
title: Limit
active:
type: integer
title: Active
available:
type: integer
title: Available
type: object
required:
- scope
- limit
- active
- available
title: QuotaStatus
description: Quota status.
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
TrajectoryEvent:
properties:
type:
type: string
title: Type
data:
title: Data
timestamp:
type: string
format: date-time
title: Timestamp
type: object
required:
- type
- data
- timestamp
title: TrajectoryEvent
description: "Event from a trajectory.\n\nUnified from agp_client and agent_platform.\nUses the richer agent_platform version with screenshot serialization.\n\nEvents represent individual actions, observations, or state changes during\ntrajectory execution. They form a chronological log of everything that happened.\n\nCommon event types:\n- AgentStartedEvent: Agent begins execution\n- AgentCompletionEvent: Agent finishes successfully\n- AgentErrorEvent: Agent encounters an error\n- AgentEvent: Generic wrapper for agent-emitted events (policy_event, tool_result, observation_event)\n- LiveViewUrlEvent: Live view URL becomes available\n- ChatMessageEvent: Agent sends a chat message\n\nAttributes:\n type: The type/name of the event (e.g., \"AgentStartedEvent\", \"AgentEvent\")\n data: Event-specific data payload (structure varies by event type)\n timestamp: When the event occurred"
FlowEvent:
properties:
kind:
type: string
const: flow_event
title: Kind
default: flow_event
flow:
type: string
title: Flow
description: Control signal, e.g. "pause", "resume", "force_answer".
origin:
type: string
title: Origin
description: Who triggered the transition.
type: object
required:
- flow
- origin
title: FlowEvent
description: Run-loop control transition (pause, resume, stop, ...).
AgentCompletionData:
properties:
reason:
type: string
enum:
- finished
- stopped
- timed_out
title: Reason
additionalProperties: true
type: object
required:
- reason
title: AgentCompletionData
ImageContent:
properties:
source:
type: string
title: Source
description: 'Image location: a fetchable URL or a base64 payload, per ``type``.'
type:
type: string
enum:
- url
- base64
title: Type
media_type:
anyOf:
- type: string
- type: 'null'
title: Media Type
description: MIME type, e.g. "image/png".
type: object
required:
- source
- type
title: ImageContent
description: 'Image payload: ``url`` for platform-served screenshots, ``base64`` for inline images.'
ProxyPool:
type: string
enum:
- residential
- datacenter
- isp
- mobile
title: ProxyPool
description: The kind of upstream IPs a managed proxy draws from.
ShareLink:
properties:
share_url:
type: string
title: Share Url
additionalProperties: false
type: object
required:
- share_url
title: ShareLink
description: Public share URL for a session.
UserMessageBatch:
properties:
type:
type: string
const: batch
title: Type
default: batch
messages:
items:
$ref: '#/components/schemas/UserMessageEvent'
type: array
minItems: 1
title: Messages
additionalProperties: false
type: object
required:
- messages
title: UserMessageBatch
description: Batch of user messages.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
SessionRequest:
properties:
agent:
anyOf:
- type: string
- $ref: '#/components/schemas/Agent'
title: Agent
description: 'Agent to run: a registered agent''s name, or an inline Agent definition.'
messages:
anyOf:
- type: string
- $ref: '#/components/schemas/UserMessageEvent'
- items:
$ref: '#/components/schemas/UserMessageEvent'
type: array
- type: 'null'
title: Messages
description: Initial task for the agent. A plain string, a single message, or a list of messages.
max_steps:
anyOf:
- type: integer
minimum: 1.0
- type: 'null'
title: Max Steps
description: Maximum reasoning steps the agent may take. Unbounded if null.
max_time_s:
anyOf:
- type: number
exclusiveMinimum: 0.0
- type: 'null'
title: Max Time S
description: Maximum wall-clock seconds the agent may run. Unbounded if null.
idle_timeout_s:
anyOf:
- type: integer
exclusiveMinimum: 0.0
- type: 'null'
title: Idle Timeout S
description: Seconds to keep the session open for follow-up messages after each answer. Null ends the session as soon as the agent answers.
delete_after_min:
anyOf:
- type: integer
minimum: 1.0
- type: 'null'
title: Delete After Min
description: Minutes after the session finishes before it is automatically deleted. Defaults to 30 days. Null keeps the session forever.
default: 43200
delete_screenshot_after_min:
anyOf:
- type: integer
minimum: 1.0
- type: 'null'
title: Delete Screenshot After Min
description: Minutes after the session finishes before its screenshots are deleted. Defaults to 30 days. Null keeps screenshots for the session's lifetime.
default: 43200
queue:
type: boolean
title: Queue
description: When the organization is at its concurrent-session limit, accept this session into a queue (status 'queued') instead of rejecting it with 429. Queued sessions start automatically, oldest first, as running sessions finish. Set to false to get an immediate 429 when no slot is available.
default: true
group_id:
anyOf:
- type: string
- type: 'null'
title: Group Id
description: Optional id to group and list related sessions together.
parent_session_id:
anyOf:
- type: string
- type: 'null'
title: Parent Session Id
description: Id of the parent session, when this is a child run.
overrides:
additionalProperties: true
type: object
title: Overrides
description: 'Per-run overrides applied to the resolved request, keyed by a dotted path. List members are selected with an explicit [field=value] clause, e.g. {"agent.environments[kind=web].start_url": "https://bing.com"}. Each value must match the type of the field its path targets.'
type: object
required:
- agent
title: SessionRequest
description: '``POST /api/v2/sessions`` body.'
Browser:
properties:
id:
type: string
minLength: 1
title: Id
description: Cata
# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/h-company/refs/heads/main/openapi/h-company-sessions-api-openapi.yml