openapi: 3.1.0
info:
  title: Herm API
  version: 1.0.0
  description: Create persistent agents, run subject-scoped sessions, and stream events.
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
  - url: https://api.herm.run
security:
  - ApiKey: []
tags:
  - name: Agents
    description: Reusable, versioned agent configuration.
  - name: Automations
    description: Subject-scoped scheduled agent runs.
  - name: Sessions
    description: Durable subject-scoped conversations.
  - name: Events
    description: Inbound events, history, and SSE streams.
  - name: Vaults
    description: Credential storage and agent attachments.
paths:
  /v1/agents:
    get:
      tags:
        - Agents
      summary: listAgents
      operationId: listAgents
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - name: status
          in: query
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/List'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    post:
      tags:
        - Agents
      summary: createAgent
      operationId: createAgent
      requestBody:
        $ref: '#/components/requestBodies/CreateAgent'
      responses:
        '201':
          $ref: '#/components/responses/Agent'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/agents/{agentId}:
    parameters:
      - $ref: '#/components/parameters/AgentId'
    get:
      tags:
        - Agents
      summary: getAgent
      operationId: getAgent
      responses:
        '200':
          $ref: '#/components/responses/Agent'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    patch:
      tags:
        - Agents
      summary: patchAgent
      operationId: patchAgent
      requestBody:
        $ref: '#/components/requestBodies/PatchAgent'
      responses:
        '200':
          $ref: '#/components/responses/Agent'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    post:
      tags:
        - Agents
      summary: replaceAgent
      operationId: replaceAgent
      requestBody:
        $ref: '#/components/requestBodies/CreateAgent'
      responses:
        '200':
          $ref: '#/components/responses/Agent'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    delete:
      tags:
        - Agents
      summary: deleteAgent
      operationId: deleteAgent
      responses:
        '200':
          $ref: '#/components/responses/Action'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/agents/{agentId}/archive:
    parameters:
      - $ref: '#/components/parameters/AgentId'
    post:
      tags:
        - Agents
      summary: archiveAgent
      operationId: archiveAgent
      responses:
        '200':
          $ref: '#/components/responses/Agent'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/agents/{agentId}/rate-limits:
    parameters:
      - $ref: '#/components/parameters/AgentId'
    patch:
      tags:
        - Agents
      summary: updateAgentRateLimits
      operationId: updateAgentRateLimits
      requestBody:
        $ref: '#/components/requestBodies/RateLimits'
      responses:
        '200':
          $ref: '#/components/responses/Agent'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/agents/{agentId}/versions:
    parameters:
      - $ref: '#/components/parameters/AgentId'
    get:
      tags:
        - Agents
      summary: listAgentVersions
      operationId: listAgentVersions
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          $ref: '#/components/responses/List'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/agents/{agentId}/versions/{version}:
    parameters:
      - $ref: '#/components/parameters/AgentId'
      - $ref: '#/components/parameters/Version'
    get:
      tags:
        - Agents
      summary: getAgentVersion
      operationId: getAgentVersion
      responses:
        '200':
          $ref: '#/components/responses/Action'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/agents/{agentId}/vaults:
    parameters:
      - $ref: '#/components/parameters/AgentId'
    get:
      tags:
        - Vaults
      summary: getAgentVaults
      operationId: getAgentVaults
      responses:
        '200':
          $ref: '#/components/responses/Action'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    put:
      tags:
        - Vaults
      summary: replaceAgentVaults
      operationId: replaceAgentVaults
      requestBody:
        $ref: '#/components/requestBodies/AgentVaults'
      responses:
        '200':
          $ref: '#/components/responses/Action'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/agents/{agentId}/mcp/installations:
    parameters:
      - $ref: '#/components/parameters/AgentId'
    post:
      tags:
        - Agents
      summary: installAgentMcpServer
      operationId: installAgentMcpServer
      requestBody:
        $ref: '#/components/requestBodies/McpInstallation'
      responses:
        '201':
          $ref: '#/components/responses/Action'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/agents/{agentId}/mcp/{serverName}/test:
    parameters:
      - $ref: '#/components/parameters/AgentId'
      - $ref: '#/components/parameters/ServerName'
    post:
      tags:
        - Agents
      summary: testAgentMcpServer
      operationId: testAgentMcpServer
      responses:
        '200':
          $ref: '#/components/responses/Action'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/agents/{agentId}/automations:
    parameters:
      - $ref: '#/components/parameters/AgentId'
    get:
      tags:
        - Automations
      summary: listAgentAutomations
      operationId: listAgentAutomations
      responses:
        '200':
          $ref: '#/components/responses/List'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/agents/{agentId}/users/{subjectId}/automations:
    parameters:
      - $ref: '#/components/parameters/AgentId'
      - $ref: '#/components/parameters/SubjectId'
    get:
      tags:
        - Automations
      summary: listSubjectAutomations
      operationId: listSubjectAutomations
      responses:
        '200':
          $ref: '#/components/responses/List'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    post:
      tags:
        - Automations
      summary: createSubjectAutomation
      operationId: createSubjectAutomation
      requestBody:
        $ref: '#/components/requestBodies/CreateAutomation'
      responses:
        '201':
          $ref: '#/components/responses/Automation'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/agents/{agentId}/users/{subjectId}/automations/{automationId}:
    parameters:
      - $ref: '#/components/parameters/AgentId'
      - $ref: '#/components/parameters/SubjectId'
      - $ref: '#/components/parameters/AutomationId'
    get:
      tags:
        - Automations
      summary: getSubjectAutomation
      operationId: getSubjectAutomation
      responses:
        '200':
          $ref: '#/components/responses/Automation'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    patch:
      tags:
        - Automations
      summary: updateSubjectAutomation
      operationId: updateSubjectAutomation
      requestBody:
        $ref: '#/components/requestBodies/PatchAutomation'
      responses:
        '200':
          $ref: '#/components/responses/Automation'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    delete:
      tags:
        - Automations
      summary: deleteSubjectAutomation
      operationId: deleteSubjectAutomation
      responses:
        '200':
          $ref: '#/components/responses/Action'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/agents/{agentId}/users/{subjectId}/automations/{automationId}/pause:
    parameters:
      - $ref: '#/components/parameters/AgentId'
      - $ref: '#/components/parameters/SubjectId'
      - $ref: '#/components/parameters/AutomationId'
    post:
      tags:
        - Automations
      summary: pauseSubjectAutomation
      operationId: pauseSubjectAutomation
      responses:
        '200':
          $ref: '#/components/responses/Automation'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/agents/{agentId}/users/{subjectId}/automations/{automationId}/resume:
    parameters:
      - $ref: '#/components/parameters/AgentId'
      - $ref: '#/components/parameters/SubjectId'
      - $ref: '#/components/parameters/AutomationId'
    post:
      tags:
        - Automations
      summary: resumeSubjectAutomation
      operationId: resumeSubjectAutomation
      responses:
        '200':
          $ref: '#/components/responses/Automation'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/agents/{agentId}/users/{subjectId}/automations/{automationId}/trigger:
    parameters:
      - $ref: '#/components/parameters/AgentId'
      - $ref: '#/components/parameters/SubjectId'
      - $ref: '#/components/parameters/AutomationId'
    post:
      tags:
        - Automations
      summary: triggerSubjectAutomation
      operationId: triggerSubjectAutomation
      responses:
        '200':
          $ref: '#/components/responses/Action'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/agents/{agentId}/users/{subjectId}/automations/{automationId}/sessions:
    parameters:
      - $ref: '#/components/parameters/AgentId'
      - $ref: '#/components/parameters/SubjectId'
      - $ref: '#/components/parameters/AutomationId'
    get:
      tags:
        - Automations
      summary: listSubjectAutomationSessions
      operationId: listSubjectAutomationSessions
      parameters:
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          $ref: '#/components/responses/List'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/sandboxes/warm:
    post:
      tags:
        - Sessions
      summary: warmSandbox
      operationId: warmSandbox
      requestBody:
        $ref: '#/components/requestBodies/WarmSandbox'
      responses:
        '202':
          $ref: '#/components/responses/Action'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/sessions:
    get:
      tags:
        - Sessions
      summary: listSessions
      operationId: listSessions
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - name: agentId
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
            enum:
              - running
              - idle
              - archived
        - name: subjectId
          in: query
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/List'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    post:
      tags:
        - Sessions
      summary: createSession
      operationId: createSession
      requestBody:
        $ref: '#/components/requestBodies/CreateSession'
      responses:
        '201':
          $ref: '#/components/responses/Session'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/sessions/{sessionId}:
    parameters:
      - $ref: '#/components/parameters/SessionId'
    get:
      tags:
        - Sessions
      summary: getSession
      operationId: getSession
      responses:
        '200':
          $ref: '#/components/responses/Session'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    post:
      tags:
        - Sessions
      summary: updateSession
      operationId: updateSession
      requestBody:
        $ref: '#/components/requestBodies/UpdateSession'
      responses:
        '200':
          $ref: '#/components/responses/Session'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    delete:
      tags:
        - Sessions
      summary: deleteSession
      operationId: deleteSession
      responses:
        '200':
          $ref: '#/components/responses/Action'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/sessions/{sessionId}/archive:
    parameters:
      - $ref: '#/components/parameters/SessionId'
    post:
      tags:
        - Sessions
      summary: archiveSession
      operationId: archiveSession
      responses:
        '200':
          $ref: '#/components/responses/Action'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/sessions/{sessionId}/events:
    parameters:
      - $ref: '#/components/parameters/SessionId'
    get:
      tags:
        - Events
      summary: listSessionEvents
      operationId: listSessionEvents
      parameters:
        - name: after
          in: query
          schema:
            type: integer
            minimum: 0
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          $ref: '#/components/responses/List'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    post:
      tags:
        - Events
      summary: sendSessionEvents
      operationId: sendSessionEvents
      requestBody:
        $ref: '#/components/requestBodies/SendEvents'
      responses:
        '202':
          $ref: '#/components/responses/List'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/sessions/{sessionId}/events/stream:
    parameters:
      - $ref: '#/components/parameters/SessionId'
    get:
      tags:
        - Events
      summary: streamSessionEvents
      operationId: streamSessionEvents
      parameters:
        - name: after
          in: query
          schema:
            type: integer
            minimum: 0
      responses:
        '200':
          $ref: '#/components/responses/EventStream'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/vaults:
    get:
      tags:
        - Vaults
      summary: listVaults
      operationId: listVaults
      responses:
        '200':
          $ref: '#/components/responses/List'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    post:
      tags:
        - Vaults
      summary: createVault
      operationId: createVault
      requestBody:
        $ref: '#/components/requestBodies/CreateVault'
      responses:
        '201':
          $ref: '#/components/responses/Vault'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/vaults/{vaultId}:
    parameters:
      - $ref: '#/components/parameters/VaultId'
    get:
      tags:
        - Vaults
      summary: getVault
      operationId: getVault
      responses:
        '200':
          $ref: '#/components/responses/Vault'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    delete:
      tags:
        - Vaults
      summary: deleteVault
      operationId: deleteVault
      responses:
        '200':
          $ref: '#/components/responses/Action'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/vaults/{vaultId}/archive:
    parameters:
      - $ref: '#/components/parameters/VaultId'
    post:
      tags:
        - Vaults
      summary: archiveVault
      operationId: archiveVault
      responses:
        '200':
          $ref: '#/components/responses/Vault'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/vaults/{vaultId}/credentials:
    parameters:
      - $ref: '#/components/parameters/VaultId'
    get:
      tags:
        - Vaults
      summary: listVaultCredentials
      operationId: listVaultCredentials
      responses:
        '200':
          $ref: '#/components/responses/List'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    post:
      tags:
        - Vaults
      summary: createVaultCredential
      operationId: createVaultCredential
      requestBody:
        $ref: '#/components/requestBodies/CreateCredential'
      responses:
        '201':
          $ref: '#/components/responses/Credential'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/vaults/{vaultId}/credentials/{credentialId}:
    parameters:
      - $ref: '#/components/parameters/VaultId'
      - $ref: '#/components/parameters/CredentialId'
    get:
      tags:
        - Vaults
      summary: getVaultCredential
      operationId: getVaultCredential
      responses:
        '200':
          $ref: '#/components/responses/Credential'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    patch:
      tags:
        - Vaults
      summary: updateVaultCredential
      operationId: updateVaultCredential
      requestBody:
        $ref: '#/components/requestBodies/PatchCredential'
      responses:
        '200':
          $ref: '#/components/responses/Credential'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    delete:
      tags:
        - Vaults
      summary: deleteVaultCredential
      operationId: deleteVaultCredential
      responses:
        '200':
          $ref: '#/components/responses/Action'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/vaults/{vaultId}/credentials/{credentialId}/archive:
    parameters:
      - $ref: '#/components/parameters/VaultId'
      - $ref: '#/components/parameters/CredentialId'
    post:
      tags:
        - Vaults
      summary: archiveVaultCredential
      operationId: archiveVaultCredential
      responses:
        '200':
          $ref: '#/components/responses/Credential'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
  parameters:
    AgentId:
      name: agentId
      in: path
      required: true
      schema:
        type: string
    SubjectId:
      name: subjectId
      in: path
      required: true
      schema:
        type: string
    AutomationId:
      name: automationId
      in: path
      required: true
      schema:
        type: string
    SessionId:
      name: sessionId
      in: path
      required: true
      schema:
        type: string
    VaultId:
      name: vaultId
      in: path
      required: true
      schema:
        type: string
    CredentialId:
      name: credentialId
      in: path
      required: true
      schema:
        type: string
    ServerName:
      name: serverName
      in: path
      required: true
      schema:
        type: string
    Version:
      name: version
      in: path
      required: true
      schema:
        type: integer
        minimum: 0
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
    Offset:
      name: offset
      in: query
      schema:
        type: integer
        minimum: 0
  responses:
    Agent:
      description: Agent response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Agent'
    Automation:
      description: Automation response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Automation'
    Session:
      description: Session response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Session'
    Vault:
      description: Vault response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Vault'
    Credential:
      description: Redacted credential response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Credential'
    List:
      description: List response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/List'
    Action:
      description: Action or resource-specific response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ActionResponse'
    EventStream:
      description: Server-Sent Event envelopes ordered by sequence.
      content:
        text/event-stream:
          schema:
            type: string
    Error:
      description: Error response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  requestBodies:
    CreateAgent:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateAgent'
    PatchAgent:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PatchAgent'
    RateLimits:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimits'
    AgentVaults:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AgentVaults'
    McpInstallation:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/McpInstallation'
    CreateAutomation:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateAutomation'
    PatchAutomation:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PatchAutomation'
    WarmSandbox:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WarmSandbox'
    CreateSession:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateSession'
    UpdateSession:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UpdateSession'
    SendEvents:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SendEvents'
    CreateVault:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateVault'
    CreateCredential:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateCredential'
    PatchCredential:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PatchCredential'
  schemas:
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
        message:
          type: string
    CreateAgent:
      type: object
      required:
        - name
        - modelName
        - systemPrompt
        - skills
        - tools
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
        modelName:
          type: string
          minLength: 1
          maxLength: 200
        systemPrompt:
          type: string
          minLength: 1
          maxLength: 20000
        skills:
          type: array
          items:
            $ref: '#/components/schemas/Skill'
        tools:
          type: array
          maxItems: 128
          items:
            $ref: '#/components/schemas/Tool'
        roles:
          type: array
          maxItems: 64
          items:
            $ref: '#/components/schemas/Role'
        mcpServers:
          type: array
          maxItems: 20
          items:
            $ref: '#/components/schemas/McpServer'
        metadata:
          $ref: '#/components/schemas/Metadata'
        rateLimits:
          $ref: '#/components/schemas/RateLimits'
        expectedVersion:
          type: integer
          minimum: 0
    PatchAgent:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
        modelName:
          type: string
          minLength: 1
          maxLength: 200
        systemPrompt:
          type: string
          minLength: 1
          maxLength: 20000
        skills:
          type: array
          items:
            $ref: '#/components/schemas/Skill'
        tools:
          type: array
          maxItems: 128
          items:
            $ref: '#/components/schemas/Tool'
        roles:
          type: array
          maxItems: 64
          items:
            $ref: '#/components/schemas/Role'
        mcpServers:
          type: array
          maxItems: 20
          items:
            $ref: '#/components/schemas/McpServer'
        metadata:
          $ref: '#/components/schemas/Metadata'
        rateLimits: false
        expectedVersion:
          type: integer
          minimum: 0
    RateLimits:
      type: object
      properties:
        conversationsPerMinute:
          type: integer
          minimum: 1
          maximum: 300
        messagesPerMinute:
          type: integer
          minimum: 1
          maximum: 1000
    AgentVaults:
      type: object
      required:
        - vaultIds
        - expectedUpdatedAt
      properties:
        vaultIds:
          type: array
          items:
            type: string
        expectedUpdatedAt:
          type: string
          format: date-time
    McpInstallation:
      type: object
      required:
        - expectedAgentVersion
        - connector
        - authentication
        - idempotencyKey
      properties:
        expectedAgentVersion:
          type: integer
          minimum: 0
        connector:
          oneOf:
            - type: object
              required:
                - type
                - connectorId
              properties:
                type:
                  const: catalog
                connectorId:
                  type: string
                  minLength: 1
                  maxLength: 200
            - type: object
              required:
                - type
                - name
                - url
              properties:
                type:
                  const: custom
                name:
                  type: string
                  minLength: 1
                  maxLength: 200
                url:
                  type: string
                  minLength: 1
                  maxLength: 2048
        authentication:
          oneOf:
            - type: object
              required:
                - type
              properties:
                type:
                  const: none
            - type: object
              required:
                - type
                - vaultId
              properties:
                type:
                  const: existing_vault
                vaultId:
                  type: string
            - type: object
              required:
                - type
                - token
              properties:
                type:
                  const: static_bearer
                token:
                  type: string
                  minLength: 1
                  maxLength: 100000
        idempotencyKey:
          type: string
          minLength: 1
          maxLength: 200
    CreateAutomation:
      type: object
      required:
        - prompt
        - schedule
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
        prompt:
          type: string
          minLength: 1
          maxLength: 5000
        schedule:
          type: string
          minLength: 1
          maxLength: 200
        skills:
          type: array
          maxItems: 64
          items:
            type: string
            minLength: 1
            maxLength: 200
        repeat:
          type: integer
        enabled:
          type: boolean
    PatchAutomation:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
        prompt:
          type: string
          minLength: 1
          maxLength: 5000
        schedule:
          type: string
          minLength: 1
          maxLength: 200
        skills:
          type: array
          maxItems: 64
          items:
            type: string
            minLength: 1
            maxLength: 200
        repeat:
          type:
            - integer
            - 'null'
        enabled:
          type: boolean
    WarmSandbox:
      type: object
      required:
        - agentId
        - subjectId
      properties:
        agentId:
          type: string
          minLength: 1
          maxLength: 200
        subjectId:
          type: string
          minLength: 1
          maxLength: 200
    CreateSession:
      type: object
      required:
        - agentId
        - subjectId
      properties:
        agentId:
          type: string
          minLength: 1
          maxLength: 200
        subjectId:
          type: string
          minLength: 1
          maxLength: 200
        role:
          type: string
          minLength: 1
          maxLength: 200
        title:
          type: string
          minLength: 1
          maxLength: 200
        yoloMode:
          type: boolean
        metadata:
          $ref: '#/components/schemas/Metadata'
    UpdateSession:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
        yoloMode:
          type: boolean
        metadata:
          $ref: '#/components/schemas/Metadata'
    SendEvents:
      type: object
      required:
        - events
      properties:
        events:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/InboundEvent'
        idempotencyKey:
          type: string
          minLength: 1
          maxLength: 200
        delivery:
          type: string
          enum:
            - immediate
            - when_idle
          default: immediate
    CreateVault:
      type: object
      required:
        - displayName
      properties:
        displayName:
          type: string
          minLength: 1
          maxLength: 255
        metadata:
          type: object
          additionalProperties:
            type: string
            maxLength: 512
    CreateCredential:
      type: object
      required:
        - auth
      properties:
        displayName:
          type: string
          minLength: 1
          maxLength: 255
        metadata:
          type: object
          additionalProperties:
            type: string
            maxLength: 512
        auth:
          oneOf:
            - type: object
              required:
                - type
                - mcpServerUrl
                - token
              properties:
                type:
                  const: static_bearer
                mcpServerUrl:
                  type: string
                token:
                  type: string
                  minLength: 1
                  maxLength: 100000
            - type: object
              required:
                - type
                - mcpServerUrl
                - accessToken
              properties:
                type:
                  const: mcp_oauth
                mcpServerUrl:
                  type: string
                accessToken:
                  type: string
                  minLength: 1
                  maxLength: 100000
            - type: object
              required:
                - type
                - secretName
                - secretValue
                - networking
              properties:
                type:
                  const: environment_variable
                secretName:
                  type: string
                secretValue:
                  type: string
                networking:
                  type: object
    PatchCredential:
      type: object
      properties:
        displayName:
          type: string
          minLength: 1
          maxLength: 255
        metadata:
          type: object
          additionalProperties:
            type: string
            maxLength: 512
        auth:
          oneOf:
            - type: object
              required:
                - type
                - token
              properties:
                type:
                  const: static_bearer
                token:
                  type: string
                  minLength: 1
                  maxLength: 100000
            - type: object
              required:
                - type
              properties:
                type:
                  const: mcp_oauth
                accessToken:
                  type: string
                  minLength: 1
                  maxLength: 100000
                expiresAt:
                  type: string
            - type: object
              required:
                - type
              properties:
                type:
                  const: environment_variable
                secretValue:
                  type: string
                  minLength: 1
                  maxLength: 100000
                networking:
                  type: object
    List:
      type: object
      required:
        - data
      properties:
        object:
          const: list
        data:
          type: array
          items:
            type: object
    Skill:
      type: object
      required:
        - name
        - content
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
        content:
          type: string
          minLength: 1
          maxLength: 100000
    PermissionPolicy:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - always_allow
            - always_ask
            - always_deny
    ToolDefaultConfig:
      type: object
      properties:
        enabled:
          type: boolean
          default: true
        permissionPolicy:
          $ref: '#/components/schemas/PermissionPolicy'
    NamedToolConfig:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
        enabled:
          type: boolean
          default: true
        permissionPolicy:
          $ref: '#/components/schemas/PermissionPolicy'
    AgentToolset:
      type: object
      required:
        - type
      properties:
        type:
          const: agent_toolset
        defaultConfig:
          $ref: '#/components/schemas/ToolDefaultConfig'
        configs:
          type: array
          maxItems: 128
          items:
            $ref: '#/components/schemas/NamedToolConfig'
    McpToolset:
      type: object
      required:
        - type
        - mcpServerName
      properties:
        type:
          const: mcp_toolset
        mcpServerName:
          type: string
          minLength: 1
          maxLength: 200
        defaultConfig:
          $ref: '#/components/schemas/ToolDefaultConfig'
        configs:
          type: array
          maxItems: 128
          items:
            $ref: '#/components/schemas/NamedToolConfig'
        resources:
          type: boolean
        prompts:
          type: boolean
    CustomTool:
      type: object
      required:
        - type
        - name
        - description
        - input_schema
      properties:
        type:
          const: custom_tool
        name:
          type: string
          minLength: 1
          maxLength: 200
        description:
          type: string
          minLength: 1
          maxLength: 20000
        input_schema:
          type: object
        enabled:
          type: boolean
          default: true
        permissionPolicy:
          $ref: '#/components/schemas/PermissionPolicy'
    Tool:
      oneOf:
        - $ref: '#/components/schemas/AgentToolset'
        - $ref: '#/components/schemas/McpToolset'
        - $ref: '#/components/schemas/CustomTool'
    Role:
      type: object
      required:
        - name
        - tools
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
        description:
          type: string
          maxLength: 2000
        tools:
          type: array
          maxItems: 128
          items:
            $ref: '#/components/schemas/Tool'
    McpServer:
      type: object
      required:
        - type
        - name
        - url
      properties:
        type:
          const: url
        name:
          type: string
          minLength: 1
          maxLength: 200
        url:
          type: string
          minLength: 1
          maxLength: 2048
    Metadata:
      type: object
      additionalProperties:
        type:
          - string
          - number
          - boolean
          - 'null'
    Agent:
      type: object
      required:
        - id
        - name
        - status
        - version
      properties:
        id:
          type: string
        name:
          type: string
        status:
          type: string
        version:
          type: object
    ActionResponse:
      type: object
      additionalProperties: true
    Automation:
      type: object
      required:
        - id
        - object
        - agentId
        - subjectId
        - schedule
        - enabled
      properties:
        id:
          type: string
        object:
          const: automation
        agentId:
          type: string
        subjectId:
          type: string
        schedule:
          type: object
        enabled:
          type: boolean
    Session:
      type: object
      required:
        - id
        - agentId
        - subjectId
        - status
      properties:
        id:
          type: string
        agentId:
          type: string
        subjectId:
          type: string
        status:
          type: string
    TextContent:
      type: array
      minItems: 1
      maxItems: 100
      items:
        type: object
        required:
          - type
          - text
        properties:
          type:
            const: text
          text:
            type: string
            minLength: 1
            maxLength: 20000
    Attachment:
      type: object
      required:
        - type
        - filename
        - mediaType
        - source
      properties:
        type:
          const: file
        filename:
          type: string
          minLength: 1
          maxLength: 200
        mediaType:
          type: string
        sizeBytes:
          type: integer
          minimum: 0
        source:
          type: object
          required:
            - type
            - dataUrl
          properties:
            type:
              const: data_url
            dataUrl:
              type: string
              minLength: 1
        analysisMode:
          type: string
          enum:
            - default
            - visual
    UserMessage:
      type: object
      required:
        - type
        - content
      properties:
        type:
          const: user.message
        content:
          $ref: '#/components/schemas/TextContent'
        attachments:
          type: array
          maxItems: 10
          items:
            $ref: '#/components/schemas/Attachment'
        metadata:
          $ref: '#/components/schemas/Metadata'
    UserSteer:
      type: object
      required:
        - type
        - message
      properties:
        type:
          const: user.steer
        message:
          type: string
          minLength: 1
          maxLength: 20000
    UserInterrupt:
      type: object
      required:
        - type
      properties:
        type:
          const: user.interrupt
        message:
          type: string
          minLength: 1
          maxLength: 20000
    UserApproval:
      type: object
      required:
        - type
        - approval_id
        - result
      properties:
        type:
          const: user.approval_response
        approval_id:
          type: string
          minLength: 1
          maxLength: 200
        result:
          type: string
          enum:
            - allow
            - deny
        scope:
          type: string
          enum:
            - once
            - session
            - always
    UserToolResult:
      type: object
      required:
        - type
        - tool_use_id
        - content
      properties:
        type:
          const: user.custom_tool_result
        tool_use_id:
          type: string
          minLength: 1
          maxLength: 200
        content:
          $ref: '#/components/schemas/TextContent'
        is_error:
          type: boolean
          default: false
        status:
          type: string
          enum:
            - running
            - completed
            - failed
    UserAnswer:
      type: object
      required:
        - type
        - request_id
        - answer
      properties:
        type:
          const: user.clarify_result
        request_id:
          type: string
          minLength: 1
          maxLength: 200
        answer:
          type: string
          maxLength: 20000
    InboundEvent:
      oneOf:
        - $ref: '#/components/schemas/UserMessage'
        - $ref: '#/components/schemas/UserSteer'
        - $ref: '#/components/schemas/UserInterrupt'
        - $ref: '#/components/schemas/UserApproval'
        - $ref: '#/components/schemas/UserToolResult'
        - $ref: '#/components/schemas/UserAnswer'
    Vault:
      type: object
      required:
        - id
        - type
        - displayName
      properties:
        id:
          type: string
        type:
          const: vault
        displayName:
          type: string
    Credential:
      type: object
      required:
        - id
        - type
        - vaultId
        - auth
      properties:
        id:
          type: string
        type:
          const: vault_credential
        vaultId:
          type: string
        auth:
          type: object