H Company Schedules API
The Schedules API from H Company — 6 operation(s) for schedules.
OpenAPI Specification
openapi: 3.1.0
info:
title: Computer-Use Agents Schedules 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: Schedules
paths:
/api/v2/schedules:
post:
tags:
- Schedules
summary: Create Schedule
description: Create a schedule that starts a session on each fire.
operationId: create_schedule_api_v2_schedules_post
security:
- HTTPBearer: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSchedule'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleRecord'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- Schedules
summary: List Schedules
description: List the organization's schedules.
operationId: list_schedules_api_v2_schedules_get
security:
- HTTPBearer: []
parameters:
- 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
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_ScheduleRecord_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v2/schedules/{schedule_id}:
get:
tags:
- Schedules
summary: Get Schedule
description: Fetch a schedule by id.
operationId: get_schedule_api_v2_schedules__schedule_id__get
security:
- HTTPBearer: []
parameters:
- name: schedule_id
in: path
required: true
schema:
type: string
format: uuid
title: Schedule Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleRecord'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
patch:
tags:
- Schedules
summary: Update Schedule
description: Update a schedule; only provided fields change. Timing changes recompute the next fire.
operationId: update_schedule_api_v2_schedules__schedule_id__patch
security:
- HTTPBearer: []
parameters:
- name: schedule_id
in: path
required: true
schema:
type: string
format: uuid
title: Schedule Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSchedule'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleRecord'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Schedules
summary: Delete Schedule
description: Delete a schedule. Future fires stop; sessions already created keep running.
operationId: delete_schedule_api_v2_schedules__schedule_id__delete
security:
- HTTPBearer: []
parameters:
- name: schedule_id
in: path
required: true
schema:
type: string
format: uuid
title: Schedule Id
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v2/schedules/{schedule_id}/pause:
post:
tags:
- Schedules
summary: Pause Schedule
description: Pause a schedule with an optional note.
operationId: pause_schedule_api_v2_schedules__schedule_id__pause_post
security:
- HTTPBearer: []
parameters:
- name: schedule_id
in: path
required: true
schema:
type: string
format: uuid
title: Schedule Id
requestBody:
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/PauseSchedule'
- type: 'null'
title: Pause
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleRecord'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v2/schedules/{schedule_id}/resume:
post:
tags:
- Schedules
summary: Resume Schedule
description: Resume a paused schedule; the next fire is recomputed from now.
operationId: resume_schedule_api_v2_schedules__schedule_id__resume_post
security:
- HTTPBearer: []
parameters:
- name: schedule_id
in: path
required: true
schema:
type: string
format: uuid
title: Schedule Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleRecord'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v2/schedules/{schedule_id}/trigger:
post:
tags:
- Schedules
summary: Trigger Schedule
description: Fire the schedule once now (works while paused); the regular cadence is unaffected.
operationId: trigger_schedule_api_v2_schedules__schedule_id__trigger_post
security:
- HTTPBearer: []
parameters:
- name: schedule_id
in: path
required: true
schema:
type: string
format: uuid
title: Schedule Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleRunRecord'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v2/schedules/{schedule_id}/runs:
get:
tags:
- Schedules
summary: List Schedule Runs
description: List the schedule's recent run outcomes, newest fire first.
operationId: list_schedule_runs_api_v2_schedules__schedule_id__runs_get
security:
- HTTPBearer: []
parameters:
- name: schedule_id
in: path
required: true
schema:
type: string
format: uuid
title: Schedule Id
- 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:
- scheduled_for
- -scheduled_for
type: string
- type: 'null'
description: Sort by field
default:
- -scheduled_for
title: Sort
description: Sort by field
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/Page_ScheduleRunRecord_'
'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.
CronTiming:
properties:
type:
type: string
const: cron
title: Type
default: cron
expression:
type: string
title: Expression
description: Five-field cron expression, e.g. '0 9 * * 1-5'.
timezone:
type: string
title: Timezone
description: IANA timezone the expression is evaluated in, e.g. 'Europe/Paris'.
type: object
required:
- expression
- timezone
title: CronTiming
description: Cron cadence evaluated in an IANA timezone.
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
ProxyPool:
type: string
enum:
- residential
- datacenter
- isp
- mobile
title: ProxyPool
description: The kind of upstream IPs a managed proxy draws from.
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.'
UpdateSchedule:
properties:
name:
anyOf:
- type: string
maxLength: 255
minLength: 1
- type: 'null'
title: Name
description:
anyOf:
- type: string
maxLength: 255
- type: 'null'
title: Description
timing:
anyOf:
- $ref: '#/components/schemas/CronTiming'
- type: 'null'
session_request:
anyOf:
- $ref: '#/components/schemas/SessionRequest'
- type: 'null'
type: object
title: UpdateSchedule
description: Partial update; omit a field to leave it unchanged.
Page_ScheduleRunRecord_:
properties:
items:
items:
$ref: '#/components/schemas/ScheduleRunRecord'
type: array
title: Items
total:
type: integer
title: Total
page:
type: integer
title: Page
type: object
required:
- items
- total
- page
title: Page[ScheduleRunRecord]
Environment:
oneOf:
- $ref: '#/components/schemas/Browser'
- $ref: '#/components/schemas/Desktop'
discriminator:
propertyName: kind
mapping:
desktop: '#/components/schemas/Desktop'
web: '#/components/schemas/Browser'
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.
ScheduleRunRecord:
properties:
id:
type: string
format: uuid
title: Id
schedule_id:
type: string
format: uuid
title: Schedule Id
status:
type: string
enum:
- created
- skipped_overlap
- skipped_quota
- error
title: Status
scheduled_for:
type: string
format: date-time
title: Scheduled For
session_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Session Id
error:
anyOf:
- type: string
- type: 'null'
title: Error
triggered_manually:
type: boolean
title: Triggered Manually
created_at:
type: string
format: date-time
title: Created At
type: object
required:
- id
- schedule_id
- status
- scheduled_for
- session_id
- error
- triggered_manually
- created_at
title: ScheduleRunRecord
description: Outcome of one schedule fire.
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.
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.
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.
CreateSchedule:
properties:
name:
type: string
maxLength: 255
minLength: 1
title: Name
description:
anyOf:
- type: string
maxLength: 255
- type: 'null'
title: Description
timing:
$ref: '#/components/schemas/CronTiming'
session_request:
$ref: '#/components/schemas/SessionRequest'
description: Template used to create each scheduled session; re-resolved on every fire.
type: object
required:
- name
- timing
- session_request
title: CreateSchedule
description: Register a schedule that creates a session on each fire.
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.
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.'
Page_ScheduleRecord_:
properties:
items:
items:
$ref: '#/components/schemas/ScheduleRecord'
type: array
title: Items
total:
type: integer
title: Total
page:
type: integer
title: Page
type: object
required:
- items
- total
- page
title: Page[ScheduleRecord]
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.'
UserMessageEvent:
properties:
type:
type: string
const: user_message
title: Type
default: user_message
message:
type: string
title: Message
description: Message text sent to the agent.
images:
items:
type: string
type: array
title: Images
description: Optional images attached to the message, as base64 data URIs.
caller_id:
type: string
title: Caller Id
default: user
type: object
required:
- message
title: UserMessageEvent
description: The user is sending a message to an active agent.
ScheduleRecord:
properties:
id:
type: string
format: uuid
title: Id
name:
type: string
title: Name
description:
anyOf:
- type: string
- type: 'null'
title: Description
timing:
$ref: '#/components/schemas/CronTiming'
session_request:
$ref: '#/components/schemas/SessionRequest'
paused:
type: boolean
title: Paused
pause_note:
anyOf:
- type: string
- type: 'null'
title: Pause Note
next_run_times:
items:
type: string
format: date-time
type: array
title: Next Run Times
description: The next few fire times, empty while paused.
last_run_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Last Run At
created_at:
type: string
format: date-time
title: Created At
updated_at:
type: string
format: date-time
title: Updated At
type: object
required:
- id
- name
- description
- timing
- session_request
- paused
- pause_note
- next_run_times
- last_run_at
- created_at
- updated_at
title: ScheduleRecord
description: Schedule as returned by reads.
PauseSchedule:
properties:
note:
anyOf:
- type: string
maxLength: 255
- type: 'null'
title: Note
type: object
title: PauseSchedule
description: Pause a schedule with an optional note explaining why.
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.
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/h-company/refs/heads/main/openapi/h-company-schedules-api-openapi.yml