H Company Sessions API

openapi: 3.2.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:
    AnswerOutcome:
      type: string
      enum:
      - success
      - partial
      - infeasible
      - blocked
      title: AnswerOutcome
      description: Agent's self-assessment of how the task concluded, reported with the final answer.
    Session:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        request:
          $ref: '#/components/schemas/SessionRequest'
        status:
          $ref: '#/components/schemas/SessionStatus'
        agent_view_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent View Url
          description: URL of the session's Agent View page on the H Platform (live view and replay).
        latest_answer:
          title: Latest Answer
          description: 'The agent''s most recent final answer: free-form text, or structured data when the agent runs with a custom answer format. Null until the agent first answers. Mirrors the answer streamed from the changes endpoint, surfaced here for non-interactive runs.'
        created_at:
          type: string
          format: date-time
          title: Created At
        started_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Started At
        finished_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Finished At
      additionalProperties: false
      type: object
      required:
      - id
      - request
      - status
      - created_at
      title: Session
      description: 'Full session envelope: original request + live status.'
    ErrorEvent:
      properties:
        kind:
          type: string
          const: error_event
          title: Kind
          default: error_event
        error:
          type: string
          title: Error
        origin:
          type: string
          title: Origin
          description: Component that raised the error.
        tool_req:
          anyOf:
          - $ref: '#/components/schemas/ToolRequest'
          - type: 'null'
          description: Tool request being executed, if any.
      type: object
      required:
      - error
      - origin
      title: ErrorEvent
      description: Recoverable error raised while running the agent loop.
    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, ...).
    ToolResultBatch:
      properties:
        type:
          type: string
          const: batch
          title: Type
          default: batch
        results:
          items:
            oneOf:
            - $ref: '#/components/schemas/ToolResultEvent'
            - $ref: '#/components/schemas/ErrorEvent'
            discriminator:
              propertyName: kind
              mapping:
                error_event: '#/components/schemas/ErrorEvent'
                tool_result: '#/components/schemas/ToolResultEvent'
          type: array
          minItems: 1
          title: Results
      additionalProperties: false
      type: object
      required:
      - results
      title: ToolResultBatch
      description: Batch of custom tool results.
    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.
    Page_SessionEvent_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/SessionEvent'
          type: array
          title: Items
        total:
          type: integer
          title: Total
        page:
          type: integer
          title: Page
      type: object
      required:
      - items
      - total
      - page
      title: Page[SessionEvent]
    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.'
    ToolRequest:
      properties:
        tool_name:
          type: string
          title: Tool Name
        args:
          additionalProperties: true
          type: object
          title: Args
        id:
          anyOf:
          - type: string
          - type: 'null'
          title: Id
          description: Identifier correlating the request with its result.
      type: object
      required:
      - tool_name
      title: ToolRequest
      description: Tool invocation proposed by the policy.
    SessionStatus:
      properties:
        status:
          $ref: '#/components/schemas/TrajectoryStatus'
          description: Current lifecycle state of the session.
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if the session failed; null otherwise.
        error_code:
          anyOf:
          - $ref: '#/components/schemas/SessionErrorCode'
          - type: 'null'
          description: Machine-readable failure category if the session failed or timed out; null otherwise.
        outcome:
          anyOf:
          - $ref: '#/components/schemas/AnswerOutcome'
          - type: 'null'
          description: Agent's self-assessed task outcome, set with the final answer; null until then.
        steps:
          type: integer
          title: Steps
          description: Number of steps the agent has taken.
          default: 0
        usage_per_model:
          items:
            $ref: '#/components/schemas/ModelUsage'
          type: array
          title: Usage Per Model
          description: Per-model token usage. Empty until the agent calls a model.
        subagent_session_ids:
          items:
            type: string
            format: uuid
          type: array
          title: Subagent Session Ids
          description: Session ids of any subagents this session spawned.
      type: object
      required:
      - status
      title: SessionStatus
      description: '``GET /api/v2/sessions/{id}/status`` response.'
    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.
    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
      t

# --- 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