openapi: 3.0.3
info:
  title: AgentZ HTTP API
  version: 0.1.0
  description: HTTP API for AgentZ agents, lens, secrets, and sandboxes.
servers:
- url: /
  description: Current origin
security:
- GatewayBearer: []
tags:
- name: agents
  description: Agent lifecycle and status APIs.
- name: tenants
  description: Tenant bootstrap and readiness APIs.
- name: workspaces
  description: Workspace provisioning and navigation APIs.
- name: event-trail
  description: Organisation event trail investigation APIs.
- name: lens
  description: Trace, span, and OS observability APIs.
- name: secrets
  description: Session secret management APIs.
- name: sandboxes
  description: Sandbox resource management APIs.
- name: inference
  description: Tenant inference provider, model, and pool APIs.
- name: skills
  description: Immutable skill catalog and attachment APIs.
- name: mcp-connections
  description: MCPConnection resource and credential management APIs.
- name: workflows
  description: Workflow definition management APIs.
- name: workflow-schedules
  description: Workflow schedule management APIs.
- name: workflow-runs
  description: Workflow run browsing and status APIs.
- name: workflow-webhooks
  description: Workflow webhook invocation and trigger listing APIs.

paths:
  /api/event-trail-event:
    post:
      operationId: listEventTrailEvents
      summary: List Organisation event trail events.
      description: >
        Lists rolling event trail history in the selected scope. An active
        Superadmin may read Organisation-wide or Workspace events; an active
        Workspace Admin may read only the Workspace bound into the bearer.
      tags: [event-trail]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListEventTrailEventsRequest'
      responses:
        '200':
          description: Paginated scoped event trail events and filter options.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEventTrailEventsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/event-trail-event/{eventId}:
    get:
      operationId: getEventTrailEvent
      summary: Get an Organisation event trail event.
      description: >
        Returns one event from the selected scope's rolling event trail history.
        Workspace Admins are restricted to the Workspace bound into the
        bearer; Superadmins may read Organisation-wide events.
      tags: [event-trail]
      parameters:
      - $ref: '#/components/parameters/EventTrailEventIDPath'
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      responses:
        '200':
          description: Scoped event trail event detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventTrailEvent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/tenant:
    get:
      operationId: getTenant
      summary: Get the current tenant bootstrap state.
      tags: [tenants]
      responses:
        '200':
          description: Tenant bootstrap state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tenant'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: ensureTenant
      summary: Create the current tenant resource when missing.
      description: >
        Ensures a Tenant custom resource exists for the bearer token's active
        Better Auth organization. The request returns immediately with the
        current bootstrap state and does not wait for the tenant to become
        ready.
      tags: [tenants]
      responses:
        '200':
          description: Tenant exists and current bootstrap state is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tenant'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workspace:
    get:
      operationId: listWorkspaces
      summary: List accessible Workspaces.
      description: >
        Lists nondeleted Workspaces accessible to the current active
        Organisation membership. Superadmins receive every Workspace.
      tags: [workspaces]
      parameters:
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      responses:
        '200':
          description: Accessible Workspaces and navigation capabilities.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWorkspacesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createWorkspace
      summary: Create a Workspace.
      description: >
        Creates the complete relational Workspace aggregate and starts
        cluster provisioning. Only an active Superadmin may create a
        Workspace or assign its initial Workspace Admins.
      tags: [workspaces]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkspaceRequest'
      responses:
        '201':
          description: Workspace creation was accepted for provisioning.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workspace/member-candidate:
    get:
      operationId: listWorkspaceMemberCandidates
      summary: List eligible initial Workspace Admins.
      description: >
        Lists active, non-Superadmin members of the current Organisation.
        Only an active Superadmin may inspect the candidates.
      tags: [workspaces]
      responses:
        '200':
          description: Eligible Workspace Admin candidates.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWorkspaceMemberCandidatesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workspace/slug/{workspaceSlug}:
    get:
      operationId: resolveWorkspaceSlug
      summary: Resolve an accessible Workspace slug.
      description: >
        Resolves current and historical slugs inside the active Organisation
        without exposing inaccessible Workspace identity.
      tags: [workspaces]
      parameters:
      - $ref: '#/components/parameters/WorkspaceSlugPath'
      responses:
        '200':
          description: Accessible Workspace and canonical slug.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workspace/{workspaceId}:
    get:
      operationId: getWorkspace
      summary: Get an accessible Workspace.
      tags: [workspaces]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDPath'
      responses:
        '200':
          description: Accessible Workspace lifecycle state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workspace/{workspaceId}/inherited-resource/{resourceType}:
    get:
      operationId: listWorkspaceInheritedResources
      summary: List Organisation resources available for Workspace inheritance.
      description: Only an active Superadmin may browse and manage inheritance.
      tags: [workspaces]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDPath'
      - $ref: '#/components/parameters/InheritedResourceTypePath'
      responses:
        '200':
          description: Organisation resource selection state and consumers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWorkspaceInheritedResourcesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: replaceWorkspaceInheritedResources
      summary: Replace one type of explicitly inherited Organisation resource.
      description: Consumed resources cannot be unselected.
      tags: [workspaces]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDPath'
      - $ref: '#/components/parameters/InheritedResourceTypePath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplaceWorkspaceInheritedResourcesRequest'
      responses:
        '200':
          description: Updated Organisation resource selection state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWorkspaceInheritedResourcesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workspace/{workspaceId}/retry:
    post:
      operationId: retryWorkspace
      summary: Retry failed Workspace provisioning.
      description: Only an active Superadmin may retry a failed Workspace.
      tags: [workspaces]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDPath'
      responses:
        '200':
          description: Workspace returned to provisioning.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workspace/{workspaceId}/lifecycle:
    patch:
      operationId: updateWorkspaceLifecycle
      summary: Record observed Workspace lifecycle state.
      description: >
        Accepts a controller-observed terminal state for the current
        provisioning attempt. Stale attempts cannot overwrite current state.
      tags: [workspaces]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWorkspaceLifecycleRequest'
      responses:
        '204':
          description: Lifecycle observation recorded or already current.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/agent:
    get:
      operationId: listAgents
      summary: List paginated agent summaries.
      tags: [agents]
      parameters:
      - $ref: '#/components/parameters/AgentNameFilterQuery'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      responses:
        '200':
          description: Paginated agent summaries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAgentsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createAgent
      summary: Create an Agent resource.
      description: >
        Creates an agent record and Agent custom resource. The request returns
        after the Agent resource is created and does not wait for the Agent to
        become ready.
      tags: [agents]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '201':
          description: Agent resource created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/agent/{agentName}:
    put:
      operationId: updateAgent
      summary: Update an Agent resource.
      description: >
        Updates mutable Agent fields for an existing Agent. The agent name in
        the path identifies the Agent and is immutable.
      tags: [agents]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgentRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '200':
          description: Agent resource updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteAgent
      summary: Delete an Agent resource.
      tags: [agents]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      responses:
        '204':
          description: Agent was deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/agent/watch:
    post:
      operationId: watchAgents
      summary: Watch agent status changes.
      description: >
        Returns an SSE stream. Each event data payload is a JSON object matching
        WatchAgentsEvent. If agent_names is omitted or empty, all known agents
        are watched.
      tags: [agents]
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchAgentsRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '200':
          description: Stream of agent status changes.
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/WatchAgentsEvent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/agent/{agentName}/fs/file:
    get:
      operationId: readAgentFile
      summary: Read a text file from the agent workspace.
      tags: [agents]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/FilePathQuery'
      responses:
        '200':
          description: File content and metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentFile'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/BadRequest'
        '415':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createAgentFile
      summary: Create an empty file in the agent workspace.
      tags: [agents]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentFileRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '201':
          description: File created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentFileMetadata'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: writeAgentFile
      summary: Atomically write a text file in the agent workspace.
      tags: [agents]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WriteAgentFileRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '200':
          description: File written.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentFileMetadata'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: File changed since it was read.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentFileConflict'
        '413':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/agent/{agentName}/fs/stat:
    get:
      operationId: statAgentFile
      summary: Read agent workspace entry metadata.
      tags: [agents]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/FilePathQuery'
      responses:
        '200':
          description: Entry metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentFileMetadata'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/agent/{agentName}/fs/raw:
    get:
      operationId: readAgentFileRaw
      summary: Stream an agent workspace file without text decoding.
      tags: [agents]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/FilePathQuery'
      responses:
        '200':
          description: Raw file content.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: writeAgentFileRaw
      summary: Atomically write an agent workspace file without text encoding.
      tags: [agents]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/FilePathQuery'
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: File written.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentFileMetadata'
        '400':
          $ref: '#/components/responses/BadRequest'
        '413':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/agent/{agentName}/owner:
    get:
      operationId: getAgentOwner
      summary: Read Agent ownership metadata.
      tags: [agents]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      responses:
        '200':
          description: Agent ownership metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentOwner'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: transferAgentOwner
      summary: Transfer Agent ownership.
      tags: [agents]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferAgentOwnerRequest'
      responses:
        '200':
          description: Agent owner transferred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentOwner'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/agent/{agentName}/share:
    get:
      operationId: listAgentShares
      summary: List Agent Shares.
      tags: [agents]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      responses:
        '200':
          description: Agent Shares for the selected Agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAgentSharesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: upsertAgentShare
      summary: Create or replace an Agent Share.
      description: >
        Creates or replaces one User or Team Agent Share. UseShared permits
        Agent sessions, files, and workflows; it does not permit Agent
        modification, deletion, sharing, ownership, or secret access.
      tags: [agents]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertAgentShareRequest'
      responses:
        '200':
          description: Agent Share created or replaced.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentShare'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/agent/{agentName}/share/{shareId}:
    delete:
      operationId: deleteAgentShare
      summary: Delete an Agent Share.
      tags: [agents]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/AgentShareIDPath'
      responses:
        '204':
          description: Agent Share deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/agent/{agentName}/access-targets:
    get:
      operationId: listAgentAccessTargets
      summary: List Agent access targets and their eligible capabilities.
      tags: [agents]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      responses:
        '200':
          description: Active Users and Teams with their eligible Agent capabilities.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAgentAccessTargetsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/agent/{agentName}/fs/directory:
    post:
      operationId: createAgentDirectory
      summary: Create a directory in the agent workspace.
      tags: [agents]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentDirectoryRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '201':
          description: Directory created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentFileMetadata'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/agent/{agentName}/fs/rename:
    post:
      operationId: renameAgentEntry
      summary: Rename an entry in the agent workspace.
      tags: [agents]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenameAgentEntryRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '200':
          description: Entry renamed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentFileMetadata'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/agent/{agentName}/fs/entry:
    delete:
      operationId: deleteAgentEntry
      summary: Recursively delete an entry from the agent workspace.
      tags: [agents]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/FilePathQuery'
      responses:
        '204':
          description: Entry deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/agent/{agentName}/skill:
    get:
      operationId: listAgentMutableSkills
      summary: List mutable skills stored in an Agent workspace.
      tags: [skills]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      responses:
        '200':
          description: Paginated mutable skill summaries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListMutableSkillsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/Conflict'
        '502':
          $ref: '#/components/responses/BadGateway'
    delete:
      operationId: deleteAgentMutableSkills
      summary: Delete mutable skills from an Agent workspace.
      tags: [skills]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteSkillsRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '204':
          description: Skills deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/Conflict'
        '502':
          $ref: '#/components/responses/BadGateway'

  /api/agent/{agentName}/skill/export:
    post:
      operationId: exportAgentMutableSkills
      summary: Stream mutable Agent skills as a ZIP archive.
      tags: [skills]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportMutableSkillsRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '200':
          description: ZIP archive containing the selected skills.
          headers:
            Content-Disposition:
              schema:
                type: string
          content:
            application/zip:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/Conflict'
        '502':
          $ref: '#/components/responses/BadGateway'

  /api/agent/skill/import/preview:
    post:
      operationId: previewMutableSkillImport
      summary: Parse a mutable skill import and report Agent conflicts.
      tags: [skills]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file, agents]
              properties:
                file:
                  type: string
                  format: binary
                agents:
                  type: array
                  minItems: 1
                  maxItems: 200
                  uniqueItems: true
                  items:
                    $ref: '#/components/schemas/AgentName'
      responses:
        '200':
          description: Parsed skills and current Agent conflicts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MutableSkillImportPreviewResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '502':
          $ref: '#/components/responses/BadGateway'

  /api/agent/skill/import:
    post:
      operationId: importMutableSkills
      summary: Import mutable skills into selected Agents.
      tags: [skills]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file, agents, decisions]
              properties:
                file:
                  type: string
                  format: binary
                agents:
                  type: array
                  minItems: 1
                  maxItems: 200
                  uniqueItems: true
                  items:
                    $ref: '#/components/schemas/AgentName'
                decisions:
                  type: string
                  minLength: 2
                  maxLength: 65536
                  description: JSON-encoded array of SkillImportDecision objects.
      responses:
        '200':
          description: Imported skills and a result for every targeted Agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillImportResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '502':
          $ref: '#/components/responses/BadGateway'

  /api/skill/import/preview:
    post:
      operationId: previewImmutableSkillImport
      summary: Parse an immutable skill import and report scope conflicts.
      tags: [skills]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      security:
      - GatewayBearer: [skill.read]
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '200':
          description: Parsed skills and current conflicts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImmutableSkillImportPreviewResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'

  /api/skill/import:
    post:
      operationId: importImmutableSkills
      summary: Import immutable skills.
      tags: [skills]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      security:
      - GatewayBearer: [skill.create]
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file, decisions]
              properties:
                file:
                  type: string
                  format: binary
                decisions:
                  type: string
                  minLength: 2
                  maxLength: 65536
                  description: JSON-encoded array of SkillImportDecision objects.
                agents:
                  type: array
                  maxItems: 200
                  uniqueItems: true
                  description: Workspace Agents to attach imported skills to.
                  items:
                    $ref: '#/components/schemas/AgentName'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '200':
          description: Imported skills and any requested Agent attachment results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillImportResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'

  /api/skill:
    get:
      operationId: listSkills
      summary: List immutable Skill resources.
      tags: [skills]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      - $ref: '#/components/parameters/AgentNameQueryOptional'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      security:
      - GatewayBearer: [skill.read]
      responses:
        '200':
          description: Paginated immutable skills.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSkillsResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createSkill
      summary: Create an immutable Skill resource.
      tags: [skills]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      security:
      - GatewayBearer: [skill.create]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSkillRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '201':
          description: Skill created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Skill'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteImmutableSkills
      summary: Delete immutable Skill resources in one request.
      tags: [skills]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      security:
      - GatewayBearer: [skill.delete]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteSkillsRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '204':
          description: Skills deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/skill/summary:
    get:
      operationId: listImmutableSkillSummaries
      summary: List immutable skills with active version file summaries.
      tags: [skills]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      - $ref: '#/components/parameters/AgentNameQueryOptional'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      security:
      - GatewayBearer: [skill.read]
      responses:
        '200':
          description: Paginated immutable skill summaries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListImmutableSkillSummariesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/skill/export:
    post:
      operationId: exportImmutableSkills
      summary: Stream selected active immutable Skill versions as ZIP.
      tags: [skills]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      security:
      - GatewayBearer: [skill.read]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportImmutableSkillsRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '200':
          description: ZIP archive containing selected active versions.
          content:
            application/zip:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/skill/{skillName}:
    put:
      operationId: updateSkill
      summary: Update an immutable Skill active version and references.
      tags: [skills]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      - $ref: '#/components/parameters/SkillNamePath'
      security:
      - GatewayBearer: [skill.modify]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSkillRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '200':
          description: Skill updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Skill'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteSkill
      summary: Delete an immutable Skill resource.
      tags: [skills]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      - $ref: '#/components/parameters/SkillNamePath'
      security:
      - GatewayBearer: [skill.delete]
      responses:
        '204':
          description: Skill deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/skill/{skillName}/references:
    get:
      operationId: getSkillReferences
      summary: List Agents and Sandboxes referencing an immutable Skill.
      tags: [skills]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      - $ref: '#/components/parameters/SkillNamePath'
      - $ref: '#/components/parameters/ResourceScopeQuery'
      security:
      - GatewayBearer: [skill.read]
      responses:
        '200':
          description: Skill references.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillReferences'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/skill/{skillName}/version:
    get:
      operationId: listImmutableSkillVersions
      summary: List stored versions for an immutable Skill.
      tags: [skills]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      - $ref: '#/components/parameters/SkillNamePath'
      - $ref: '#/components/parameters/ResourceScopeQuery'
      security:
      - GatewayBearer: [skill.read]
      responses:
        '200':
          description: Sorted stored versions.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: integer
                  format: int64
                  minimum: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/lens/{agentName}/{sessionID}/trace:
    get:
      operationId: listTraceSessions
      summary: List paginated per-session trace summaries.
      tags: [lens]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: sessionID
        in: path
        required: true
        description: Session identifier scoped to an agent.
        schema:
          type: string
          minLength: 1
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      - $ref: '#/components/parameters/StartedAfterQuery'
      - $ref: '#/components/parameters/StartedBeforeQuery'
      responses:
        '200':
          description: Paginated per-session trace summaries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTraceSessionsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/lens/{agentName}/{sessionID}/trace/{traceID}/span:
    get:
      operationId: listSpans
      summary: List paginated spans for a trace.
      tags: [lens]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: sessionID
        in: path
        required: true
        description: Session identifier scoped to an agent.
        schema:
          type: string
          minLength: 1
      - name: traceID
        in: path
        required: true
        description: Trace identifier scoped to a session.
        schema:
          $ref: '#/components/schemas/TraceID'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      responses:
        '200':
          description: Paginated spans for a trace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSpansResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/lens/{agentName}/{sessionID}/trace/{traceID}/span/{spanID}:
    get:
      operationId: getSpanDetail
      summary: Get span details and correlated OS observability.
      tags: [lens]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: sessionID
        in: path
        required: true
        description: Session identifier scoped to an agent.
        schema:
          type: string
          minLength: 1
      - name: traceID
        in: path
        required: true
        description: Trace identifier scoped to a session.
        schema:
          $ref: '#/components/schemas/TraceID'
      - name: spanID
        in: path
        required: true
        description: Span identifier scoped to a trace.
        schema:
          $ref: '#/components/schemas/SpanID'
      responses:
        '200':
          description: Span detail with payload and correlated events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpanDetailResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/lens/{agentName}/observability/process:
    get:
      operationId: listProcessObservability
      summary: List paginated process observability events.
      tags: [lens]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      - $ref: '#/components/parameters/EventTimeAfterQuery'
      - $ref: '#/components/parameters/EventTimeBeforeQuery'
      - $ref: '#/components/parameters/ActionQuery'
      responses:
        '200':
          description: Paginated process observability events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListProcessObservabilityResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/lens/{agentName}/observability/process/summary:
    get:
      operationId: listProcessObservabilitySummary
      summary: List paginated process observability summaries.
      tags: [lens]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      - $ref: '#/components/parameters/EventTimeAfterRequiredQuery'
      - $ref: '#/components/parameters/EventTimeBeforeRequiredQuery'
      - $ref: '#/components/parameters/ActionQuery'
      responses:
        '200':
          description: Paginated process observability summaries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListProcessObservabilitySummaryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/lens/{agentName}/observability/file:
    get:
      operationId: listFileObservability
      summary: List paginated file observability events.
      tags: [lens]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      - $ref: '#/components/parameters/EventTimeAfterQuery'
      - $ref: '#/components/parameters/EventTimeBeforeQuery'
      - $ref: '#/components/parameters/ActionQuery'
      responses:
        '200':
          description: Paginated file observability events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListFileObservabilityResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/lens/{agentName}/observability/file/summary:
    get:
      operationId: listFileObservabilitySummary
      summary: List paginated file observability summaries.
      tags: [lens]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      - $ref: '#/components/parameters/EventTimeAfterRequiredQuery'
      - $ref: '#/components/parameters/EventTimeBeforeRequiredQuery'
      - $ref: '#/components/parameters/ActionQuery'
      responses:
        '200':
          description: Paginated file observability summaries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListFileObservabilitySummaryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/lens/{agentName}/observability/network:
    get:
      operationId: listNetworkObservability
      summary: List paginated network observability events.
      tags: [lens]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      - $ref: '#/components/parameters/EventTimeAfterQuery'
      - $ref: '#/components/parameters/EventTimeBeforeQuery'
      - $ref: '#/components/parameters/ActionQuery'
      responses:
        '200':
          description: Paginated network observability events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListNetworkObservabilityResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/lens/{agentName}/observability/network/summary:
    get:
      operationId: listNetworkObservabilitySummary
      summary: List paginated network observability summaries.
      tags: [lens]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      - $ref: '#/components/parameters/EventTimeAfterRequiredQuery'
      - $ref: '#/components/parameters/EventTimeBeforeRequiredQuery'
      - $ref: '#/components/parameters/ActionQuery'
      responses:
        '200':
          description: Paginated network observability summaries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListNetworkObservabilitySummaryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/lens/{agentName}/mcp/graph:
    get:
      operationId: getMCPGraph
      summary: Get MCP observability graph data for an agent given a date range.
      tags: [lens]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/FromDateQuery'
      - $ref: '#/components/parameters/ToDateQuery'
      responses:
        '200':
          description: Graph-ready MCP observability for an agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPGraphResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/secret/{agentName}:
    get:
      operationId: listSecrets
      summary: List secret keys for an agent.
      description: >
        Returns a paginated list of secret keys with creation timestamps.
        Secret values are never included in the response.
      tags: [secrets]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      responses:
        '200':
          description: Paginated secret keys.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSecretsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: putSecret
      summary: Create a secret for an agent.
      description: >
        Creates a static or OAuth-backed secret for the agent. Secret values
        are stored only in OpenBao. OAuth secrets keep refresh lifecycle state
        in the Secret CRD status.
      tags: [secrets]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/UpdateSandboxQuery'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSecretRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '201':
          description: Secret created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PutSecretsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/secret/{agentName}/watch:
    post:
      operationId: watchSecrets
      summary: Watch secret status changes for an agent.
      description: >
        Returns an SSE stream. Each event data payload is a JSON object matching
        WatchSecretsEvent. If keys is omitted or empty, all known secrets for
        the addressed agent are watched.
      tags: [secrets]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchSecretsRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '200':
          description: Stream of secret updates.
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/WatchSecretsEvent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/secret/{agentName}/delete:
    post:
      operationId: deleteSecret
      summary: Delete secrets for an agent.
      description: >
        Deletes the specified secret keys for the agent. Missing keys are
        ignored.
      tags: [secrets]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteSecretsRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '204':
          description: Secrets deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/sandbox:
    get:
      operationId: listSandboxes
      summary: List paginated Sandbox resources.
      tags: [sandboxes]
      security:
      - GatewayBearer: [sandbox.read]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      responses:
        '200':
          description: Paginated sandboxes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSandboxesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createSandbox
      summary: Create a Sandbox resource.
      tags: [sandboxes]
      security:
      - GatewayBearer: [sandbox.create]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSandboxRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '201':
          description: Sandbox created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sandbox'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/inference/provider:
    get:
      operationId: listInferenceProviders
      summary: List paginated inference providers.
      tags: [inference]
      security:
      - GatewayBearer: [inference_provider.read]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      responses:
        '200':
          description: Paginated inference providers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListInferenceProvidersResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createInferenceProvider
      summary: Create an inference provider and its write-only credentials.
      tags: [inference]
      security:
      - GatewayBearer: [inference_provider.create]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInferenceProviderRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '201':
          description: Provider created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceProvider'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/inference/provider/oauth-ticket:
    post:
      operationId: createInferenceProviderOAuthTicket
      summary: Store subscription credentials and return a single-use provider ticket.
      description: >
        Credential material is written directly to OpenBao and is never
        included in this or any later API response.
      tags: [inference]
      security:
      - GatewayBearer: [inference_provider.create]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInferenceProviderOAuthTicketRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '201':
          description: Single-use provider ticket and non-secret model metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateInferenceProviderOAuthTicketResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/inference/provider/{providerName}:
    parameters:
    - $ref: '#/components/parameters/InferenceProviderNamePath'
    - $ref: '#/components/parameters/WorkspaceIDHeader'
    get:
      operationId: getInferenceProvider
      summary: Get an inference provider without credential material.
      tags: [inference]
      parameters:
      - $ref: '#/components/parameters/ResourceScopeQuery'
      security:
      - GatewayBearer: [inference_provider.read]
      responses:
        '200':
          description: Inference provider.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceProvider'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

    put:
      operationId: updateInferenceProvider
      summary: Replace provider configuration and optionally rotate credentials.
      tags: [inference]
      security:
      - GatewayBearer: [inference_provider.modify]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateInferenceProviderRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '200':
          description: Provider updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceProvider'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteInferenceProvider
      summary: Delete an unreferenced inference provider.
      tags: [inference]
      security:
      - GatewayBearer: [inference_provider.delete]
      responses:
        '204':
          description: Provider deletion accepted.
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/inference/provider/watch:
    post:
      operationId: watchInferenceProviders
      summary: Watch inference provider status changes.
      description: >
        Returns an SSE stream. Each payload contains the current read shapes
        for the requested provider IDs, or all providers when IDs are omitted.
      tags: [inference]
      security:
      - GatewayBearer: [inference_provider.read]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchInferenceProvidersRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '200':
          description: Stream of inference provider updates.
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/WatchInferenceProvidersEvent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/inference/provider/{providerName}/usage:
    get:
      operationId: getInferenceProviderUsage
      summary: List Sandboxes referencing an inference provider.
      tags: [inference]
      security:
      - GatewayBearer: [inference_provider.read]
      parameters:
      - $ref: '#/components/parameters/InferenceProviderNamePath'
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      - $ref: '#/components/parameters/ResourceScopeQuery'
      responses:
        '200':
          description: Provider usage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceProviderUsage'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/inference/provider/{providerName}/models:
    get:
      operationId: refreshInferenceProviderModels
      summary: Refresh non-secret model metadata for a subscription provider.
      tags: [inference]
      security:
      - GatewayBearer: [inference_provider.read]
      parameters:
      - $ref: '#/components/parameters/InferenceProviderNamePath'
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      - $ref: '#/components/parameters/ResourceScopeQuery'
      responses:
        '200':
          description: Current subscription model suggestions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceModelSuggestions'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/inference/provider/catalog:
    get:
      operationId: listInferenceProviderCatalog
      summary: Search the pinned OpenCode provider catalog.
      tags: [inference]
      security:
      - GatewayBearer: [inference_provider.read]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      - name: q
        in: query
        required: false
        schema:
          type: string
          maxLength: 128
      responses:
        '200':
          description: Supported provider/runtime variants.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceProviderCatalog'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/inference/provider/catalog/{catalogProvider}/models:
    get:
      operationId: listInferenceModelSuggestions
      summary: List Models.dev suggestions for one provider/runtime variant.
      tags: [inference]
      security:
      - GatewayBearer: [inference_provider.read]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      - name: catalogProvider
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 128
      - name: provider_kind
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/InferenceProviderKind'
      responses:
        '200':
          description: Model suggestions with cache provenance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceModelSuggestions'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/inference/pool:
    get:
      operationId: listInferencePools
      summary: List paginated inference Pools.
      tags: [inference]
      security:
      - GatewayBearer: [inference_pool.read]
      parameters:
      - in: header
        name: X-AgentZ-Workspace-ID
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      responses:
        '200':
          description: Paginated inference Pools.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListInferencePoolsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createInferencePool
      summary: Create an inference Pool with ordered provider-model members.
      tags: [inference]
      security:
      - GatewayBearer: [inference_pool.create]
      parameters:
      - in: header
        name: X-AgentZ-Workspace-ID
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInferencePoolRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '201':
          description: Pool created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferencePool'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/inference/pool/{poolName}:
    parameters:
    - $ref: '#/components/parameters/InferencePoolNamePath'
    - in: header
      name: X-AgentZ-Workspace-ID
      required: true
      schema:
        type: string
    get:
      operationId: getInferencePool
      summary: Get an inference Pool and its derived contract.
      tags: [inference]
      security:
      - GatewayBearer: [inference_pool.read]
      responses:
        '200':
          description: Inference Pool.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferencePool'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: updateInferencePool
      summary: Replace Pool membership or routing behavior.
      tags: [inference]
      security:
      - GatewayBearer: [inference_pool.modify]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateInferencePoolRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '200':
          description: Pool updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferencePool'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteInferencePool
      summary: Delete an inference Pool not referenced by a Sandbox.
      tags: [inference]
      security:
      - GatewayBearer: [inference_pool.delete]
      responses:
        '204':
          description: Pool deletion accepted.
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/inference/pool/{poolName}/usage:
    get:
      operationId: getInferencePoolUsage
      summary: List Sandboxes directly referencing an inference Pool.
      tags: [inference]
      parameters:
      - $ref: '#/components/parameters/InferencePoolNamePath'
      - in: header
        name: X-AgentZ-Workspace-ID
        required: true
        schema:
          type: string
      security:
      - GatewayBearer: [inference_pool.read]
      responses:
        '200':
          description: Pool usage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferencePoolUsage'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/inference/pool/watch:
    post:
      operationId: watchInferencePools
      summary: Watch inference Pool status and usage changes.
      description: >
        Returns an SSE stream. Each payload contains current Pool read shapes
        for the requested IDs, or all Pools when IDs are omitted.
      tags: [inference]
      security:
      - GatewayBearer: [inference_pool.read]
      parameters:
      - in: header
        name: X-AgentZ-Workspace-ID
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchInferencePoolsRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '200':
          description: Stream of inference Pool updates.
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/WatchInferencePoolsEvent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/sandbox/{sandboxName}:
    put:
      operationId: updateSandbox
      summary: Update a Sandbox resource.
      description: >
        Replaces the mutable configuration for an existing Sandbox. The name
        in the path identifies the Sandbox.
      tags: [sandboxes]
      security:
      - GatewayBearer: [sandbox.modify]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      - name: sandboxName
        in: path
        required: true
        description: Sandbox resource name.
        schema:
          $ref: '#/components/schemas/SandboxName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSandboxRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '200':
          description: Sandbox updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sandbox'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteSandbox
      summary: Delete a Sandbox resource.
      tags: [sandboxes]
      security:
      - GatewayBearer: [sandbox.delete]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      - name: sandboxName
        in: path
        required: true
        description: Sandbox resource name.
        schema:
          $ref: '#/components/schemas/SandboxName'
      responses:
        '204':
          description: Sandbox deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/mcp-connection:
    get:
      operationId: listMCPConnections
      summary: List paginated MCPConnection resources.
      tags: [mcp-connections]
      security:
      - GatewayBearer: [mcp_connection.read]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      responses:
        '200':
          description: Paginated MCPConnections.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListMCPConnectionsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createMCPConnection
      summary: Create an MCPConnection resource.
      tags: [mcp-connections]
      security:
      - GatewayBearer: [mcp_connection.create]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMCPConnectionRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '201':
          description: MCPConnection created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPConnectionDetail'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/Conflict'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/mcp-connection/{name}:
    get:
      operationId: getMCPConnection
      summary: Get an MCPConnection resource.
      tags: [mcp-connections]
      security:
      - GatewayBearer: [mcp_connection.read]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      - $ref: '#/components/parameters/MCPConnectionNamePath'
      - $ref: '#/components/parameters/ResourceScopeQuery'
      responses:
        '200':
          description: MCPConnection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPConnectionDetail'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteMCPConnection
      summary: Delete an MCPConnection resource.
      tags: [mcp-connections]
      security:
      - GatewayBearer: [mcp_connection.delete]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      - $ref: '#/components/parameters/MCPConnectionNamePath'
      responses:
        '204':
          description: MCPConnection deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/mcp-connection/watch:
    post:
      operationId: watchMCPConnections
      summary: Watch MCP connection status changes.
      description: >
        Returns an SSE stream. Each event data payload is a JSON object matching
        WatchMCPConnectionsEvent. If names is omitted or empty, all MCP
        connections are watched.
      tags: [mcp-connections]
      security:
      - GatewayBearer: [mcp_connection.read]
      parameters:
      - $ref: '#/components/parameters/WorkspaceIDHeader'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchMCPConnectionsRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '200':
          description: Stream of MCP connection updates.
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/WatchMCPConnectionsEvent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workflow/{agentName}:
    get:
      operationId: listWorkflowSummaries
      summary: List workflow summaries.
      description: >
        Lists saved workflow metadata for a single agent without loading the
        full workflow graph.
      tags: [workflows]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      responses:
        '200':
          description: Workflow summaries for an agent.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WorkflowSummary'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createWorkflow
      summary: Create a workflow definition.
      description: >
        Creates a normalized workflow DAG for a single agent. The workflow
        definition is stored as metadata, nodes, and edges, and later retrieval
        can derive a markdown execution playbook from the structured graph.
      tags: [workflows]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkflowRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '201':
          description: Workflow created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteWorkflows
      summary: Delete workflow definitions.
      description: >
        Deletes multiple persisted workflow DAGs for an agent in a single
        request. Deletion is strict: if any requested workflow name does not
        exist, the request fails and no workflows are deleted.
      tags: [workflows]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteWorkflowsRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '204':
          description: Workflows deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workflow/{agentName}/{workflowName}:
    get:
      operationId: getWorkflow
      summary: Get a workflow definition.
      description: >
        Retrieves a persisted workflow DAG for a single agent. The response
        preserves the normalized workflow structure so clients can derive a
        detailed execution playbook from the graph.
      tags: [workflows]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: workflowName
        in: path
        required: true
        description: Workflow name scoped to an agent.
        schema:
          $ref: '#/components/schemas/WorkflowName'
      responses:
        '200':
          description: Workflow definition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workflow/{agentName}/schedule:
    get:
      operationId: listAgentWorkflowSchedules
      summary: List workflow schedules for an agent.
      description: >
        Lists paginated workflow schedules for an agent across all workflows.
      tags: [workflow-schedules]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      responses:
        '200':
          description: Paginated workflow schedules for an agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWorkflowSchedulesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workflow/{agentName}/{workflowName}/schedule:
    get:
      operationId: listWorkflowSchedules
      summary: List workflow schedules.
      description: >
        Lists paginated workflow schedules for a workflow definition.
      tags: [workflow-schedules]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: workflowName
        in: path
        required: true
        description: Workflow name scoped to an agent.
        schema:
          $ref: '#/components/schemas/WorkflowName'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      responses:
        '200':
          description: Paginated workflow schedules for a workflow.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWorkflowSchedulesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createWorkflowSchedule
      summary: Create a workflow schedule.
      description: >
        Creates a WorkflowSchedule resource for an agent-workflow pair. The
        gateway forwards schedule validation to the existing Kubernetes webhook.
      tags: [workflow-schedules]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: workflowName
        in: path
        required: true
        description: Workflow name scoped to an agent.
        schema:
          $ref: '#/components/schemas/WorkflowName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkflowScheduleRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '201':
          description: Workflow schedule created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowSchedule'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workflow/{agentName}/{workflowName}/schedule/{scheduleName}:
    put:
      operationId: updateWorkflowSchedule
      summary: Update a workflow schedule.
      description: >
        Replaces all mutable workflow schedule fields for an existing schedule.
      tags: [workflow-schedules]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: workflowName
        in: path
        required: true
        description: Workflow name scoped to an agent.
        schema:
          $ref: '#/components/schemas/WorkflowName'
      - name: scheduleName
        in: path
        required: true
        description: WorkflowSchedule resource name.
        schema:
          $ref: '#/components/schemas/WorkflowScheduleName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWorkflowScheduleRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '200':
          description: Workflow schedule updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowSchedule'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteWorkflowSchedule
      summary: Delete a workflow schedule.
      description: >
        Deletes a workflow schedule addressed by agent, workflow, and
        schedule name.
      tags: [workflow-schedules]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: workflowName
        in: path
        required: true
        description: Workflow name scoped to an agent.
        schema:
          $ref: '#/components/schemas/WorkflowName'
      - name: scheduleName
        in: path
        required: true
        description: WorkflowSchedule resource name.
        schema:
          $ref: '#/components/schemas/WorkflowScheduleName'
      responses:
        '204':
          description: Workflow schedule deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workflow/{agentName}/{workflowName}/schedule/{scheduleName}/run:
    post:
      operationId: createWorkflowRun
      summary: Trigger a workflow run from a workflow schedule.
      description: >
        Creates a WorkflowRun from the addressed WorkflowSchedule without
        overriding any schedule-derived execution fields.
      tags: [workflow-schedules]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: workflowName
        in: path
        required: true
        description: Workflow name scoped to an agent.
        schema:
          $ref: '#/components/schemas/WorkflowName'
      - name: scheduleName
        in: path
        required: true
        description: WorkflowSchedule resource name.
        schema:
          $ref: '#/components/schemas/WorkflowScheduleName'
      responses:
        '202':
          description: Workflow run accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRunSummary'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workflow/{agentName}/{workflowName}/webhook:
    post:
      operationId: invokeWorkflowWebhook
      summary: Trigger a workflow run through a webhook API key.
      description: >
        Validates the request body against the saved workflow input contract, then
        creates a direct WorkflowRun for the addressed tenant, agent, and
        workflow. Every request body is interpreted as JSON regardless of its
        Content-Type header. Authentication uses the X-API-Key header.
      security:
      - GatewayAPIKey: []
      tags: [workflow-webhooks]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: workflowName
        in: path
        required: true
        description: Workflow name scoped to an agent.
        schema:
          $ref: '#/components/schemas/WorkflowName'
      - name: timeout_seconds
        in: query
        required: false
        description: Timeout for the created WorkflowRun.
        schema:
          type: integer
          format: int32
          default: 3600
          minimum: 1
          maximum: 604800
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowRunInputs'
          '*/*': {}
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '202':
          description: Workflow run accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRunSummary'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workflow/{agentName}/webhook:
    get:
      operationId: listWorkflowWebhookTriggers
      summary: List webhook trigger rows for an agent.
      description: >
        Lists the distinct API key and workflow pairs that have produced at
        least a webhook-triggered WorkflowRun for the addressed agent.
      tags: [workflow-webhooks]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      responses:
        '200':
          description: Paginated webhook trigger rows for an agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWorkflowWebhookTriggersResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workflow/{agentName}/{workflowName}/run:
    get:
      operationId: listWorkflowRuns
      summary: List workflow runs for a workflow.
      description: >
        Lists paginated WorkflowRuns for an agent-workflow pair. Optional
        trigger filters narrow the results to schedule-triggered or
        webhook-triggered runs.
      tags: [workflow-runs]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: workflowName
        in: path
        required: true
        description: Workflow name scoped to an agent.
        schema:
          $ref: '#/components/schemas/WorkflowName'
      - name: status
        in: query
        required: false
        description: Optional WorkflowRun phase filter.
        schema:
          $ref: '#/components/schemas/WorkflowRunStatus'
      - name: trigger_type
        in: query
        required: false
        description: Optional workflow trigger type filter.
        schema:
          $ref: '#/components/schemas/WorkflowRunTriggerType'
      - name: schedule_name
        in: query
        required: false
        description: >
          Optional schedule filter. When set, trigger_type must be Schedule.
        schema:
          $ref: '#/components/schemas/WorkflowScheduleName'
      - name: webhook_api_key_id
        in: query
        required: false
        description: >
          Optional webhook API key filter. When set, trigger_type must be
          Webhook.
        schema:
          $ref: '#/components/schemas/APIKeyID'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      responses:
        '200':
          description: Paginated workflow runs for a workflow.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWorkflowRunsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workflow/{agentName}/{workflowName}/run/watch:
    post:
      operationId: watchWorkflowRuns
      summary: Watch workflow runs for a workflow.
      description: >
        Returns an SSE stream. Each event data payload is a JSON object matching
        WatchWorkflowRunsEvent. If run_names is omitted or empty, all runs for
        the addressed workflow are watched.
      tags: [workflow-runs]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: workflowName
        in: path
        required: true
        description: Workflow name scoped to an agent.
        schema:
          $ref: '#/components/schemas/WorkflowName'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchWorkflowRunsRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '200':
          description: Stream of workflow run updates.
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/WatchWorkflowRunsEvent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workflow/{agentName}/{workflowName}/run/{runName}:
    get:
      operationId: getWorkflowRun
      summary: Get a workflow run.
      description: >
        Returns all public details for a WorkflowRun owned by the addressed
        agent-workflow pair.
      tags: [workflow-runs]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: workflowName
        in: path
        required: true
        description: Workflow name scoped to an agent.
        schema:
          $ref: '#/components/schemas/WorkflowName'
      - name: runName
        in: path
        required: true
        description: WorkflowRun resource name.
        schema:
          $ref: '#/components/schemas/WorkflowRunName'
      responses:
        '200':
          description: Workflow run details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRunDetail'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteWorkflowRun
      summary: Delete a workflow run.
      description: >
        Deletes a WorkflowRun owned by the addressed agent-workflow pair and
        waits until controller-driven cleanup completes.
      tags: [workflow-runs]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: workflowName
        in: path
        required: true
        description: Workflow name scoped to an agent.
        schema:
          $ref: '#/components/schemas/WorkflowName'
      - name: runName
        in: path
        required: true
        description: WorkflowRun resource name.
        schema:
          $ref: '#/components/schemas/WorkflowRunName'
      responses:
        '204':
          description: Workflow run deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workflow/{agentName}/{workflowName}/run/{runName}/status:
    patch:
      operationId: patchWorkflowRunStatus
      summary: Set a WorkflowRun terminal status.
      description: >
        Marks a running WorkflowRun as succeeded or failed. The gateway owns
        request validation and state-transition checks, then patches the
        WorkflowRun status in the configured namespace.
      tags: [workflow-runs]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: workflowName
        in: path
        required: true
        description: Workflow name scoped to an agent.
        schema:
          $ref: '#/components/schemas/WorkflowName'
      - name: runName
        in: path
        required: true
        description: WorkflowRun resource name.
        schema:
          $ref: '#/components/schemas/WorkflowRunName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchWorkflowRunStatusRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '204':
          description: WorkflowRun status updated.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workflow/{agentName}/{workflowName}/run/{runName}/nodes/{nodeName}/status:
    patch:
      operationId: patchWorkflowRunNodeStatus
      summary: Set a WorkflowRun node status.
      description: >
        Records execution progress for one WorkflowRun node. The gateway
        validates node membership and basic state transitions before patching
        the WorkflowRun status in the configured namespace.
      tags: [workflow-runs]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: workflowName
        in: path
        required: true
        description: Workflow name scoped to an agent.
        schema:
          $ref: '#/components/schemas/WorkflowName'
      - name: runName
        in: path
        required: true
        description: WorkflowRun resource name.
        schema:
          $ref: '#/components/schemas/WorkflowRunName'
      - name: nodeName
        in: path
        required: true
        description: Workflow node name.
        schema:
          $ref: '#/components/schemas/WorkflowNodeName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchWorkflowRunNodeStatusRequest'
      responses:
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '204':
          description: WorkflowRun node status updated.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

components:
  securitySchemes:
    GatewayBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
    GatewayAPIKey:
      type: apiKey
      in: header
      name: X-API-Key
  parameters:
    WorkspaceIDHeader:
      name: X-AgentZ-Workspace-ID
      in: header
      required: false
      description: >
        Stable Workspace ID selecting Workspace scope. Omit for Organisation
        scope.
      schema:
        type: string
        minLength: 1
        maxLength: 128

    WorkspaceIDPath:
      name: workspaceId
      in: path
      required: true
      description: Stable Workspace ID.
      schema:
        type: string
        minLength: 1
        maxLength: 128

    InheritedResourceTypePath:
      name: resourceType
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/InheritedResourceType'

    ResourceScopeQuery:
      name: scope
      in: query
      required: true
      schema:
        $ref: '#/components/schemas/ResourceScope'

    WorkspaceSlugPath:
      name: workspaceSlug
      in: path
      required: true
      description: Current or historical Workspace slug.
      schema:
        type: string
        minLength: 1
        maxLength: 128

    EventTrailEventIDPath:
      name: eventId
      in: path
      required: true
      description: Stable event trail event ID.
      schema:
        type: string
        minLength: 1

    AgentNameQuery:
      name: agent_name
      in: query
      required: true
      description: Agent name.
      schema:
        $ref: '#/components/schemas/AgentName'

    AgentNameQueryOptional:
      name: agent_name
      in: query
      required: false
      description: Optional Agent name.
      schema:
        $ref: '#/components/schemas/AgentName'

    AgentNamePath:
      name: agentName
      in: path
      required: true
      description: Agent name.
      schema:
        $ref: '#/components/schemas/AgentName'

    AgentShareIDPath:
      name: shareId
      in: path
      required: true
      description: Stable Agent Share ID.
      schema:
        type: string
        minLength: 1

    InferenceProviderNamePath:
      name: providerName
      in: path
      required: true
      description: Stable inference provider ID.
      schema:
        $ref: '#/components/schemas/InferenceProviderName'

    InferencePoolNamePath:
      name: poolName
      in: path
      required: true
      description: Stable inference Pool ID.
      schema:
        $ref: '#/components/schemas/InferencePoolName'

    FilePathQuery:
      name: path
      in: query
      required: true
      description: Path relative to the agent workspace root.
      schema:
        type: string
        minLength: 1
        maxLength: 4096

    SandboxNamePath:
      name: name
      in: path
      required: true
      description: Sandbox name.
      schema:
        $ref: '#/components/schemas/SandboxName'

    SkillNamePath:
      name: skillName
      in: path
      required: true
      description: Skill name.
      schema:
        $ref: '#/components/schemas/SkillName'

    MCPConnectionNamePath:
      name: name
      in: path
      required: true
      description: MCPConnection name.
      schema:
        $ref: '#/components/schemas/MCPConnectionName'

    AgentNameFilterQuery:
      name: agent_name
      in: query
      required: false
      description: Optional agent name filters. Repeat the query parameter for multiple agents.
      style: form
      explode: true
      schema:
        type: array
        items:
          $ref: '#/components/schemas/AgentName'

    LimitQuery:
      name: limit
      in: query
      required: false
      description: Maximum number of items to return.
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 200
        default: 50

    PageTokenQuery:
      name: page_token
      in: query
      required: false
      description: Opaque pagination token from a previous response.
      schema:
        type: string
        minLength: 1

    UpdateSandboxQuery:
      name: update_sandbox
      in: query
      required: false
      description: >
        When true, append compatible secret hosts that are missing from the
        agent sandbox allowed host list before creating the secret.
      schema:
        type: boolean
        default: false

    TraceIDQuery:
      name: trace_id
      in: query
      required: true
      description: Lowercase hexadecimal OTLP trace ID.
      schema:
        $ref: '#/components/schemas/TraceID'

    SpanIDQuery:
      name: span_id
      in: query
      required: true
      description: Lowercase hexadecimal OTLP span ID.
      schema:
        $ref: '#/components/schemas/SpanID'

    SessionIDQuery:
      name: session_id
      in: query
      required: false
      description: Optional root session ID.
      schema:
        type: string
        minLength: 1

    StartedAfterQuery:
      name: started_after
      in: query
      required: false
      description: Inclusive lower bound for trace start time.
      schema:
        type: string
        format: date-time

    StartedBeforeQuery:
      name: started_before
      in: query
      required: false
      description: Inclusive upper bound for trace start time.
      schema:
        type: string
        format: date-time

    EventTimeAfterQuery:
      name: event_time_after
      in: query
      required: false
      description: Inclusive lower bound for event time.
      schema:
        type: string
        format: date-time

    EventTimeBeforeQuery:
      name: event_time_before
      in: query
      required: false
      description: Inclusive upper bound for event time.
      schema:
        type: string
        format: date-time

    EventTimeAfterRequiredQuery:
      name: event_time_after
      in: query
      required: true
      description: Inclusive lower bound for event time.
      schema:
        type: string
        format: date-time

    EventTimeBeforeRequiredQuery:
      name: event_time_before
      in: query
      required: true
      description: Inclusive upper bound for event time.
      schema:
        type: string
        format: date-time

    ActionQuery:
      name: action
      in: query
      required: false
      description: Optional observability action filter.
      schema:
        $ref: '#/components/schemas/ObservabilityAction'

    FromDateQuery:
      name: from
      in: query
      required: true
      description: Inclusive lower bound for MCP tool activity date.
      schema:
        type: string
        format: date

    ToDateQuery:
      name: to
      in: query
      required: true
      description: Inclusive upper bound for MCP tool activity date.
      schema:
        type: string
        format: date

  responses:
    BadRequest:
      description: Request validation failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Request authentication failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The authenticated principal lacks authority for this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: >
        Requested resource was not found. For tenant-gated APIs this can also
        mean the current tenant is not initialized and the error code is
        `tenant_not_found`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: >
        Request conflicts with current state. For tenant-gated APIs this can
        also mean the current tenant is still bootstrapping and the error code
        is `tenant_not_ready`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PayloadTooLarge:
      description: Request body or expanded content exceeds a documented limit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnsupportedMediaType:
      description: The request Content-Type is not supported by this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableContent:
      description: The request body does not match the operation schema.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadGateway:
      description: The Agent filesystem is unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    EventTrailActorType:
      type: string
      enum: [user, api_key, system]

    EventTrailResult:
      type: string
      enum: [succeeded, denied, failed]

    EventTrailTargetType:
      type: string
      enum: [organization, organization_membership, workspace, role, sandbox, skill, team, mcp_connection, inference_provider, inference_pool, agent]
      x-enum-varnames:
      - EventTrailTargetOrganization
      - EventTrailTargetOrganizationMembership
      - EventTrailTargetWorkspace
      - EventTrailTargetRole
      - EventTrailTargetSandbox
      - EventTrailTargetSkill
      - EventTrailTargetTeam
      - EventTrailTargetMCPConnection
      - EventTrailTargetInferenceProvider
      - EventTrailTargetInferencePool
      - EventTrailTargetAgent

    EventTrailField:
      type: object
      additionalProperties: false
      properties:
        field:
          type: string
          enum: [member_id, name, provisioning_attempt, role, slug, state, user_id]
          x-enum-varnames:
          - EventTrailFieldMemberID
          - EventTrailFieldName
          - EventTrailFieldProvisioningAttempt
          - EventTrailFieldRole
          - EventTrailFieldSlug
          - EventTrailFieldState
          - EventTrailFieldUserID
        value:
          type: string
      required: [field, value]

    EventTrailActor:
      type: object
      additionalProperties: false
      properties:
        type:
          $ref: '#/components/schemas/EventTrailActorType'
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
      required: [type]

    EventTrailTarget:
      type: object
      additionalProperties: false
      properties:
        type:
          $ref: '#/components/schemas/EventTrailTargetType'
        id:
          type: string
        name:
          type: string
        slug:
          type: string
      required: [type, id]

    EventTrailWorkspace:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        name:
          type: string
        slug:
          type: string
      required: [id]

    EventTrailEvent:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        actor:
          $ref: '#/components/schemas/EventTrailActor'
        target:
          $ref: '#/components/schemas/EventTrailTarget'
        workspace:
          $ref: '#/components/schemas/EventTrailWorkspace'
        category:
          type: string
        action:
          type: string
        result:
          $ref: '#/components/schemas/EventTrailResult'
        before:
          type: array
          items:
            $ref: '#/components/schemas/EventTrailField'
        after:
          type: array
          items:
            $ref: '#/components/schemas/EventTrailField'
        created_at:
          type: string
          format: date-time
      required:
      - id
      - actor
      - target
      - category
      - action
      - result
      - before
      - after
      - created_at

    EventTrailActorFilter:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        type:
          $ref: '#/components/schemas/EventTrailActorType'
        name:
          type: string
        email:
          type: string
          format: email
      required: [type]

    EventTrailWorkspaceFilter:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        name:
          type: string
        slug:
          type: string
      required: [id]

    EventTrailFilters:
      type: object
      additionalProperties: false
      properties:
        actors:
          type: array
          items:
            $ref: '#/components/schemas/EventTrailActorFilter'
        categories:
          type: array
          items:
            type: string
        workspaces:
          type: array
          items:
            $ref: '#/components/schemas/EventTrailWorkspaceFilter'
        target_types:
          type: array
          items:
            $ref: '#/components/schemas/EventTrailTargetType'
      required: [actors, categories, workspaces, target_types]

    EventTrailFilterField:
      type: string
      enum: [actor_type, actor_id, category, workspace_id, target_type, result, created_at]

    EventTrailFilter:
      type: object
      additionalProperties: false
      properties:
        field:
          $ref: '#/components/schemas/EventTrailFilterField'
        values:
          type: array
          minItems: 1
          maxItems: 100
          items:
            type: string
            minLength: 1
            maxLength: 256
      required: [field, values]

    ListEventTrailEventsRequest:
      type: object
      additionalProperties: false
      properties:
        filters:
          type: array
          maxItems: 7
          items:
            $ref: '#/components/schemas/EventTrailFilter'
        limit:
          type: integer
          format: int32
          minimum: 1
          maximum: 100
          default: 50
        page_token:
          type: string
      required: [filters, limit]

    ListEventTrailEventsResponse:
      type: object
      additionalProperties: false
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/EventTrailEvent'
        filter_options:
          $ref: '#/components/schemas/EventTrailFilters'
        next_page_token:
          type: string
      required: [events, filter_options, next_page_token]

    TraceID:
      type: string
      minLength: 32
      maxLength: 32
      pattern: '^[0-9a-f]{32}$'
      description: Lowercase hexadecimal OTLP trace ID.

    SpanID:
      type: string
      minLength: 16
      maxLength: 16
      pattern: '^[0-9a-f]{16}$'
      description: Lowercase hexadecimal OTLP span ID.

    OptionalSpanID:
      type: string
      maxLength: 16
      pattern: '^([0-9a-f]{16})?$'
      description: Lowercase hexadecimal OTLP span ID, or empty for root spans.

    TenantPhase:
      type: string
      enum: [BOOTSTRAPPING, READY, FAILED]

    TenantCondition:
      type: object
      required: [type, status, reason, message]
      properties:
        type:
          type: string
        status:
          type: string
          enum: ['True', 'False', 'Unknown']
        reason:
          type: string
        message:
          type: string

    ResourceCapabilities:
      type: object
      additionalProperties: false
      required: [read, create, modify, delete]
      properties:
        read:
          type: boolean
        create:
          type: boolean
        modify:
          type: boolean
        delete:
          type: boolean

    ResourceActor:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          minLength: 1
        name:
          type: string
          nullable: true
        email:
          type: string
          format: email
          nullable: true
        image:
          type: string
          nullable: true
      required: [id, name, email, image]

    Tenant:
      type: object
      required: [organization_id, namespace, ready, phase, conditions, skill_capabilities, mcp_connection_capabilities, sandbox_capabilities, inference_provider_capabilities, inference_pool_capabilities]
      properties:
        organization_id:
          type: string
        namespace:
          type: string
        ready:
          type: boolean
        phase:
          $ref: '#/components/schemas/TenantPhase'
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/TenantCondition'
        skill_capabilities:
          $ref: '#/components/schemas/ResourceCapabilities'
        mcp_connection_capabilities:
          $ref: '#/components/schemas/ResourceCapabilities'
        sandbox_capabilities:
          $ref: '#/components/schemas/ResourceCapabilities'
        inference_provider_capabilities:
          $ref: '#/components/schemas/ResourceCapabilities'
        inference_pool_capabilities:
          $ref: '#/components/schemas/ResourceCapabilities'

    WorkspaceState:
      type: string
      enum: [provisioning, ready, failed, deleting]
      x-enum-varnames:
      - WorkspaceStateProvisioning
      - WorkspaceStateReady
      - WorkspaceStateFailed
      - WorkspaceStateDeleting

    Workspace:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        name:
          type: string
        slug:
          type: string
        namespace:
          type: string
        state:
          $ref: '#/components/schemas/WorkspaceState'
        provisioning_attempt:
          type: integer
          format: int64
          minimum: 1
        failure_reason:
          type: string
        capabilities:
          $ref: '#/components/schemas/WorkspaceCapabilities'
        workspace_admin_count:
          type: integer
          format: int64
          minimum: 0
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - name
      - slug
      - namespace
      - state
      - provisioning_attempt
      - workspace_admin_count
      - capabilities
      - created_at
      - updated_at

    WorkspaceCapabilities:
      type: object
      additionalProperties: false
      properties:
        administer:
          type: boolean
        agents:
          $ref: '#/components/schemas/AgentWorkspaceCapabilities'
        skills:
          $ref: '#/components/schemas/ResourceCapabilities'
        mcp_connections:
          $ref: '#/components/schemas/ResourceCapabilities'
        sandboxes:
          $ref: '#/components/schemas/ResourceCapabilities'
        inference_providers:
          $ref: '#/components/schemas/ResourceCapabilities'
        inference_pools:
          $ref: '#/components/schemas/ResourceCapabilities'
        api_keys:
          $ref: '#/components/schemas/ResourceCapabilities'
        observability:
          $ref: '#/components/schemas/ResourceCapabilities'
      required:
      - administer
      - agents
      - skills
      - mcp_connections
      - sandboxes
      - inference_providers
      - inference_pools
      - api_keys
      - observability

    AgentWorkspaceCapabilities:
      type: object
      additionalProperties: false
      properties:
        author:
          type: boolean
      required: [author]

    ListWorkspacesResponse:
      type: object
      additionalProperties: false
      properties:
        workspaces:
          type: array
          items:
            $ref: '#/components/schemas/Workspace'
        can_create:
          type: boolean
        can_enter_organization:
          type: boolean
        next_page_token:
          type: string
      required: [workspaces, can_create, can_enter_organization, next_page_token]

    CreateWorkspaceRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 80
          pattern: '.*\S.*'
        admin_member_ids:
          type: array
          maxItems: 100
          uniqueItems: true
          items:
            type: string
            minLength: 1
            maxLength: 128
        selected_organization_resources:
          $ref: '#/components/schemas/SelectedOrganizationResources'
      required: [name, admin_member_ids, selected_organization_resources]

    InheritedResourceType:
      type: string
      enum: [skill, sandbox, mcp_connection, inference_provider]
      x-enum-varnames:
      - InheritedResourceTypeSkill
      - InheritedResourceTypeSandbox
      - InheritedResourceTypeMCPConnection
      - InheritedResourceTypeInferenceProvider

    SelectedOrganizationResources:
      type: object
      additionalProperties: false
      properties:
        skills:
          type: array
          uniqueItems: true
          items: {type: string, minLength: 1}
        sandboxes:
          type: array
          uniqueItems: true
          items: {type: string, minLength: 1}
        mcp_connections:
          type: array
          uniqueItems: true
          items: {type: string, minLength: 1}
        inference_providers:
          type: array
          uniqueItems: true
          items: {type: string, minLength: 1}
      required: [skills, sandboxes, mcp_connections, inference_providers]

    InheritedResourceConsumer:
      type: object
      additionalProperties: false
      properties:
        kind:
          type: string
        name:
          type: string
      required: [kind, name]

    ResourceLifecycle:
      type: string
      enum: [Accepted, Ready, NotReady, Degraded, Error]

    WorkspaceInheritedResource:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
        status:
          $ref: '#/components/schemas/ResourceLifecycle'
        message:
          type: string
        selected:
          type: boolean
        consumers:
          type: array
          items:
            $ref: '#/components/schemas/InheritedResourceConsumer'
        disabled_reason:
          type: string
      required: [name, status, selected, consumers]

    ListWorkspaceInheritedResourcesResponse:
      type: object
      additionalProperties: false
      properties:
        resource_type:
          $ref: '#/components/schemas/InheritedResourceType'
        resources:
          type: array
          items:
            $ref: '#/components/schemas/WorkspaceInheritedResource'
      required: [resource_type, resources]

    ReplaceWorkspaceInheritedResourcesRequest:
      type: object
      additionalProperties: false
      properties:
        names:
          type: array
          uniqueItems: true
          items:
            type: string
            minLength: 1
      required: [names]

    WorkspaceMemberCandidate:
      type: object
      additionalProperties: false
      properties:
        member_id:
          type: string
        user_id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
        image:
          type: string
          nullable: true
      required: [member_id, user_id, name, email, image]

    ListWorkspaceMemberCandidatesResponse:
      type: object
      additionalProperties: false
      properties:
        members:
          type: array
          items:
            $ref: '#/components/schemas/WorkspaceMemberCandidate'
      required: [members]

    UpdateWorkspaceLifecycleRequest:
      type: object
      additionalProperties: false
      properties:
        provisioning_attempt:
          type: integer
          format: int64
          minimum: 1
        state:
          type: string
          enum: [ready, failed]
          x-enum-varnames:
          - UpdateWorkspaceLifecycleRequestStateReady
          - UpdateWorkspaceLifecycleRequestStateFailed
        failure_reason:
          type: string
          minLength: 1
          maxLength: 1024
      required: [provisioning_attempt, state]

    ObservabilityAction:
      type: string
      enum: [Allowed, Blocked]

    AgentName:
      type: string
      minLength: 1
      maxLength: 32
      pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?$'

    ResourceScope:
      type: string
      enum: [Organisation, Workspace]

    ResourceReference:
      type: object
      additionalProperties: false
      properties:
        scope:
          $ref: '#/components/schemas/ResourceScope'
        name:
          type: string
          minLength: 1
          maxLength: 63
          pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?$'
      required: [scope, name]

    AgentMemoryConfig:
      type: object
      additionalProperties: false
      properties:
        enabled:
          type: boolean
      required: [enabled]

    AgentFileType:
      type: string
      enum: [file, directory]

    AgentFileMetadata:
      type: object
      additionalProperties: false
      properties:
        path:
          type: string
        size:
          type: integer
          format: int64
          minimum: 0
        media_type:
          type: string
        modified_at:
          type: string
          format: date-time
        version:
          type: string
        type:
          $ref: '#/components/schemas/AgentFileType'
      required: [path, size, media_type, modified_at, version, type]

    AgentFile:
      allOf:
      - $ref: '#/components/schemas/AgentFileMetadata'
      - type: object
        additionalProperties: false
        properties:
          content:
            type: string
          truncated:
            type: boolean
        required: [content, truncated]

    AgentFileConflict:
      type: object
      additionalProperties: false
      properties:
        code:
          type: string
          enum: [file_version_conflict]
        message:
          type: string
        current:
          $ref: '#/components/schemas/AgentFileMetadata'
      required: [code, message, current]

    CreateAgentFileRequest:
      type: object
      additionalProperties: false
      properties:
        path:
          type: string
          minLength: 1
          maxLength: 4096
      required: [path]

    WriteAgentFileRequest:
      type: object
      additionalProperties: false
      properties:
        path:
          type: string
          minLength: 1
          maxLength: 4096
        content:
          type: string
        expected_version:
          type: string
          minLength: 1
        overwrite:
          type: boolean
          default: false
      required: [path, content, expected_version]

    CreateAgentDirectoryRequest:
      type: object
      additionalProperties: false
      properties:
        path:
          type: string
          minLength: 1
          maxLength: 4096
      required: [path]

    RenameAgentEntryRequest:
      type: object
      additionalProperties: false
      properties:
        path:
          type: string
          minLength: 1
          maxLength: 4096
        target:
          type: string
          minLength: 1
          maxLength: 4096
      required: [path, target]

    SandboxName:
      type: string
      minLength: 1
      maxLength: 32
      pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?$'
      description: Sandbox resource name.

    InferenceProviderName:
      type: string
      minLength: 1
      maxLength: 63
      pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?$'
      description: Stable tenant-scoped inference provider ID.

    InferencePoolName:
      type: string
      minLength: 1
      maxLength: 63
      pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?$'
      description: Stable tenant-scoped inference Pool ID.

    SkillName:
      type: string
      minLength: 1
      maxLength: 32
      pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?$'
      description: Immutable Skill resource name.

    MCPConnectionName:
      type: string
      minLength: 1
      maxLength: 32
      pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?$'
      description: MCPConnection resource name.

    WorkflowName:
      type: string
      minLength: 1
      maxLength: 32
      pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?$'
      description: Workflow name scoped to an agent.

    WorkflowScheduleName:
      type: string
      minLength: 1
      maxLength: 32
      pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?$'
      description: WorkflowSchedule resource name.

    WorkflowRunName:
      type: string
      minLength: 1
      maxLength: 253
      pattern: '^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$'
      description: WorkflowRun resource name.

    WorkflowNodeName:
      type: string
      minLength: 1
      maxLength: 64
      pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?$'
      description: Stable workflow node identifier.

    Error:
      type: object
      additionalProperties: false
      properties:
        code:
          type: string
          minLength: 1
        message:
          type: string
          minLength: 1
        errors:
          type: array
          items:
            $ref: '#/components/schemas/FieldError'
        details:
          $ref: '#/components/schemas/JSONValue'
      required: [code, message]

    FieldError:
      type: object
      additionalProperties: false
      properties:
        field:
          type: string
          minLength: 1
        message:
          type: string
          minLength: 1
      required: [field, message]

    WorkflowRunTerminalPhase:
      type: string
      enum:
      - Succeeded
      - Failed

    WorkflowRunNodePhase:
      type: string
      enum:
      - Disabled
      - Running
      - Unacked
      - Succeeded
      - Failed

    WorkflowRunNodePatchPhase:
      type: string
      enum:
      - Running
      - Succeeded
      - Failed

    WorkflowRunStatus:
      type: string
      enum:
      - Pending
      - Running
      - Succeeded
      - Failed
      - Unacked

    PatchWorkflowRunStatusRequest:
      type: object
      additionalProperties: false
      properties:
        phase:
          $ref: '#/components/schemas/WorkflowRunTerminalPhase'
        message:
          type: string
          maxLength: 4096
      required: [phase]

    PatchWorkflowRunNodeStatusRequest:
      type: object
      additionalProperties: false
      properties:
        phase:
          $ref: '#/components/schemas/WorkflowRunNodePatchPhase'
        message:
          type: string
          maxLength: 4096
      required: [phase]

    ListAgentsResponse:
      type: object
      additionalProperties: false
      properties:
        agents:
          type: array
          items:
            $ref: '#/components/schemas/Agent'
        next_page_token:
          type: string
      required: [agents, next_page_token]

    ListAgentSharesResponse:
      type: object
      additionalProperties: false
      properties:
        shares:
          type: array
          items:
            $ref: '#/components/schemas/AgentShare'
        next_page_token:
          type: string
      required: [shares, next_page_token]

    ListSkillsResponse:
      type: object
      additionalProperties: false
      properties:
        skills:
          type: array
          items:
            $ref: '#/components/schemas/Skill'
        next_page_token:
          type: string
      required: [skills, next_page_token]

    ListMutableSkillsResponse:
      type: object
      additionalProperties: false
      properties:
        skills:
          type: array
          items:
            $ref: '#/components/schemas/MutableSkillSummary'
        next_page_token:
          type: string
      required: [skills, next_page_token]

    ListImmutableSkillSummariesResponse:
      type: object
      additionalProperties: false
      properties:
        skills:
          type: array
          items:
            $ref: '#/components/schemas/ImmutableSkillSummary'
        next_page_token:
          type: string
      required: [skills, next_page_token]

    ListWorkflowSchedulesResponse:
      type: object
      additionalProperties: false
      properties:
        workflow_schedules:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowSchedule'
        next_page_token:
          type: string
      required: [workflow_schedules, next_page_token]

    ListWorkflowRunsResponse:
      type: object
      additionalProperties: false
      properties:
        workflow_runs:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowRunSummary'
        next_page_token:
          type: string
      required: [workflow_runs, next_page_token]

    ListWorkflowWebhookTriggersResponse:
      type: object
      additionalProperties: false
      properties:
        webhook_triggers:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowWebhookTrigger'
        next_page_token:
          type: string
      required: [webhook_triggers, next_page_token]

    Agent:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/AgentName'
        sandbox:
          $ref: '#/components/schemas/ResourceReference'
        created_by:
          $ref: '#/components/schemas/ResourceActor'
        last_modified_by:
          $ref: '#/components/schemas/ResourceActor'
        last_activity:
          type: string
          format: date-time
        memory:
          $ref: '#/components/schemas/AgentMemoryConfig'
        created_at:
          type: string
          format: date-time
        modified_at:
          type: string
          format: date-time
        skills:
          type: array
          items:
            $ref: '#/components/schemas/ResourceReference'
        status:
          $ref: '#/components/schemas/AgentStatus'
        capabilities:
          $ref: '#/components/schemas/AgentCapabilities'
      required:
      - name
      - sandbox
      - created_by
      - last_modified_by
      - last_activity
      - memory
      - created_at
      - modified_at
      - skills
      - status
      - capabilities

    AgentCapabilities:
      type: object
      additionalProperties: false
      properties:
        use:
          type: boolean
        modify:
          type: boolean
        delete:
          type: boolean
        share:
          type: boolean
        manage_ownership:
          type: boolean
        read_secrets:
          type: boolean
        write_secrets:
          type: boolean
        delete_secrets:
          type: boolean
      required:
      - use
      - modify
      - delete
      - share
      - manage_ownership
      - read_secrets
      - write_secrets
      - delete_secrets

    AgentOwner:
      type: object
      additionalProperties: false
      properties:
        agent_name:
          $ref: '#/components/schemas/AgentName'
        creator_user_id:
          type: string
        owner_user_id:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - agent_name
      - creator_user_id
      - owner_user_id
      - created_at
      - updated_at

    AgentShare:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        agent_name:
          $ref: '#/components/schemas/AgentName'
        target_user_id:
          type: string
          nullable: true
        target_team_id:
          type: string
          nullable: true
        created_by:
          type: string
        capabilities:
          type: array
          items:
            $ref: '#/components/schemas/AgentShareCapability'
        created_at:
          type: string
          format: date-time
      required:
      - id
      - agent_name
      - target_user_id
      - target_team_id
      - created_by
      - capabilities
      - created_at

    AgentShareCapability:
      type: string
      enum:
      - share_non_authored
      - use_shared
      - read_shared_secret
      - write_shared_secret
      - delete_shared_secret
      x-enum-varnames:
      - AgentShareCapabilityShareNonAuthored
      - AgentShareCapabilityUseShared
      - AgentShareCapabilityReadSharedSecret
      - AgentShareCapabilityWriteSharedSecret
      - AgentShareCapabilityDeleteSharedSecret

    AgentAccessTargetKind:
      type: string
      enum: [user, team]
      x-enum-varnames:
      - AgentAccessTargetKindUser
      - AgentAccessTargetKindTeam

    AgentAccessTarget:
      type: object
      additionalProperties: false
      properties:
        kind:
          $ref: '#/components/schemas/AgentAccessTargetKind'
        id:
          type: string
        label:
          type: string
        email:
          type: string
          nullable: true
        image:
          type: string
          nullable: true
        capabilities:
          type: array
          items:
            $ref: '#/components/schemas/AgentShareCapability'
        can_own:
          type: boolean
      required: [kind, id, label, email, image, capabilities, can_own]

    ListAgentAccessTargetsResponse:
      type: object
      additionalProperties: false
      properties:
        targets:
          type: array
          items:
            $ref: '#/components/schemas/AgentAccessTarget'
      required: [targets]

    Skill:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/SkillName'
        scope:
          $ref: '#/components/schemas/ResourceScope'
        created_by:
          $ref: '#/components/schemas/ResourceActor'
        last_modified_by:
          $ref: '#/components/schemas/ResourceActor'
        description:
          type: string
          minLength: 1
          maxLength: 1024
        version:
          type: integer
          format: int64
          minimum: 1
        storage_path:
          type: string
          minLength: 1
        agents:
          type: array
          items:
            $ref: '#/components/schemas/AgentName'
        sandboxes:
          type: array
          items:
            $ref: '#/components/schemas/SandboxName'
        created_at:
          type: string
          format: date-time
        can_modify:
          type: boolean
        can_delete:
          type: boolean
      required:
      - name
      - scope
      - created_by
      - last_modified_by
      - description
      - version
      - storage_path
      - agents
      - sandboxes
      - created_at
      - can_modify
      - can_delete

    SkillFileSummary:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/SkillName'
        file_count:
          type: integer
          minimum: 1
        size_bytes:
          type: integer
          format: int64
          minimum: 0
        modified_at:
          type: string
          format: date-time
          nullable: true
      required: [name, file_count, size_bytes, modified_at]

    MutableSkillSummary:
      allOf:
      - $ref: '#/components/schemas/SkillFileSummary'

    ImmutableSkillSummary:
      allOf:
      - $ref: '#/components/schemas/SkillFileSummary'
      - type: object
        additionalProperties: false
        properties:
          description:
            type: string
          created_by:
            $ref: '#/components/schemas/ResourceActor'
          last_modified_by:
            $ref: '#/components/schemas/ResourceActor'
          scope:
            $ref: '#/components/schemas/ResourceScope'
          can_modify:
            type: boolean
          can_delete:
            type: boolean
          version:
            type: integer
            format: int64
            minimum: 1
          agents:
            type: array
            items:
              $ref: '#/components/schemas/AgentName'
          sandboxes:
            type: array
            items:
              $ref: '#/components/schemas/SandboxName'
        required: [description, created_by, last_modified_by, scope, version, agents, sandboxes, can_modify, can_delete]

    DeleteSkillsRequest:
      type: object
      additionalProperties: false
      properties:
        skill_names:
          type: array
          minItems: 1
          maxItems: 200
          uniqueItems: true
          items:
            $ref: '#/components/schemas/SkillName'
      required: [skill_names]

    ExportMutableSkillsRequest:
      type: object
      additionalProperties: false
      properties:
        skill_names:
          type: array
          minItems: 1
          maxItems: 200
          uniqueItems: true
          items:
            $ref: '#/components/schemas/SkillName'
      required: [skill_names]

    ExportImmutableSkillsRequest:
      type: object
      additionalProperties: false
      properties:
        skills:
          description: Skill references whose names are unique across scopes.
          type: array
          minItems: 1
          maxItems: 200
          uniqueItems: true
          items:
            $ref: '#/components/schemas/ResourceReference'
      required: [skills]

    ImmutableSkillImportPreviewItem:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/SkillName'
        conflict:
          type: boolean
      required: [name, conflict]

    ImmutableSkillImportPreviewResponse:
      type: object
      additionalProperties: false
      properties:
        skills:
          type: array
          items:
            $ref: '#/components/schemas/ImmutableSkillImportPreviewItem'
      required: [skills]

    MutableSkillImportPreviewItem:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/SkillName'
        conflict_agents:
          type: array
          items:
            $ref: '#/components/schemas/AgentName'
      required: [name, conflict_agents]

    MutableSkillImportPreviewResponse:
      type: object
      additionalProperties: false
      properties:
        skills:
          type: array
          items:
            $ref: '#/components/schemas/MutableSkillImportPreviewItem'
      required: [skills]

    SkillImportDecision:
      oneOf:
      - $ref: '#/components/schemas/CreateSkillImportDecision'
      - $ref: '#/components/schemas/OverwriteSkillImportDecision'
      - $ref: '#/components/schemas/RenameSkillImportDecision'
      discriminator:
        propertyName: action
        mapping:
          create: '#/components/schemas/CreateSkillImportDecision'
          overwrite: '#/components/schemas/OverwriteSkillImportDecision'
          rename: '#/components/schemas/RenameSkillImportDecision'

    CreateSkillImportDecision:
      type: object
      additionalProperties: false
      properties:
        action:
          type: string
          enum: [create]
        name:
          $ref: '#/components/schemas/SkillName'
      required: [action, name]

    OverwriteSkillImportDecision:
      type: object
      additionalProperties: false
      properties:
        action:
          type: string
          enum: [overwrite]
        name:
          $ref: '#/components/schemas/SkillName'
      required: [action, name]

    RenameSkillImportDecision:
      type: object
      additionalProperties: false
      properties:
        action:
          type: string
          enum: [rename]
        name:
          $ref: '#/components/schemas/SkillName'
        rename:
          $ref: '#/components/schemas/SkillName'
      required: [action, name, rename]

    SkillImportAgentResult:
      type: object
      additionalProperties: false
      properties:
        agent:
          $ref: '#/components/schemas/AgentName'
        status:
          type: string
          enum: [succeeded, failed]
        error:
          type: string
      required: [agent, status]

    SkillImportResponse:
      type: object
      additionalProperties: false
      properties:
        skills:
          type: array
          items:
            $ref: '#/components/schemas/SkillName'
        agents:
          type: array
          items:
            $ref: '#/components/schemas/SkillImportAgentResult'
      required: [skills, agents]

    SkillReferences:
      type: object
      additionalProperties: false
      properties:
        agents:
          type: array
          items:
            $ref: '#/components/schemas/AgentName'
        sandboxes:
          type: array
          items:
            $ref: '#/components/schemas/SandboxName'
      required: [agents, sandboxes]

    CreateSkillRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/SkillName'
        description:
          type: string
          minLength: 1
          maxLength: 1024
        version:
          type: integer
          format: int64
          minimum: 1
        storage_path:
          type: string
          minLength: 1
      required: [name, description, version, storage_path]

    UpdateSkillRequest:
      type: object
      additionalProperties: false
      properties:
        description:
          type: string
          minLength: 1
          maxLength: 1024
        version:
          type: integer
          format: int64
          minimum: 1
      required: [version]

    AgentStatus:
      type: string
      enum:
      - UNSPECIFIED
      - PROGRESSING
      - DEGRADED
      - DELETED
      - IDLE

    CreateAgentRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/AgentName'
        memory:
          $ref: '#/components/schemas/AgentMemoryConfig'
        env:
          type: object
          additionalProperties:
            type: string
        sandbox:
          $ref: '#/components/schemas/ResourceReference'
        skills:
          type: array
          items:
            $ref: '#/components/schemas/ResourceReference'
        opencode:
          $ref: '#/components/schemas/AgentOpencodeConfig'
      required: [name, sandbox]

    CreateWorkflowRequest:
      type: object
      additionalProperties: false
      properties:
        workflow_name:
          $ref: '#/components/schemas/WorkflowName'
        title:
          type: string
          minLength: 1
          maxLength: 256
        summary:
          type: string
          minLength: 1
          maxLength: 4096
        inputs:
          $ref: '#/components/schemas/WorkflowInputs'
        arbitrary_json:
          $ref: '#/components/schemas/WorkflowArbitraryJSON'
        nodes:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/WorkflowNode'
        edges:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowEdge'
      required:
      - workflow_name
      - title
      - summary
      - nodes
      - edges

    Workflow:
      type: object
      additionalProperties: false
      properties:
        agent_name:
          $ref: '#/components/schemas/AgentName'
        workflow_name:
          $ref: '#/components/schemas/WorkflowName'
        title:
          type: string
        summary:
          type: string
        inputs:
          $ref: '#/components/schemas/WorkflowInputs'
        arbitrary_json:
          $ref: '#/components/schemas/WorkflowArbitraryJSON'
        nodes:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowNode'
        edges:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowEdge'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - agent_name
      - workflow_name
      - title
      - summary
      - nodes
      - edges
      - created_at
      - updated_at

    WorkflowSchedule:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/WorkflowScheduleName'
        agent_name:
          $ref: '#/components/schemas/AgentName'
        workflow_name:
          $ref: '#/components/schemas/WorkflowName'
        schedule:
          type: string
          minLength: 1
        time_zone:
          type: string
        inputs:
          $ref: '#/components/schemas/JSONValue'
        timeout_seconds:
          type: integer
          format: int32
          minimum: 1
          maximum: 604800
        suspend:
          type: boolean
        successful_runs_history_limit:
          type: integer
          format: int32
          minimum: 1
          maximum: 10
        failed_runs_history_limit:
          type: integer
          format: int32
          minimum: 1
          maximum: 10
        created_at:
          type: string
          format: date-time
      required:
      - name
      - agent_name
      - workflow_name
      - schedule
      - timeout_seconds
      - inputs
      - suspend
      - successful_runs_history_limit
      - failed_runs_history_limit
      - created_at

    APIKeyID:
      type: string
      minLength: 1
      description: Better Auth API key identifier.

    WorkflowRunInputs:
      $ref: '#/components/schemas/JSONValue'
      description: >
        Runtime workflow input values. The gateway validates this value against
        the saved workflow input contract before creating a WorkflowRun.

    WorkflowRunTriggerType:
      type: string
      enum:
      - Schedule
      - Webhook

    WorkflowRunSummary:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/WorkflowRunName'
        workflow_name:
          $ref: '#/components/schemas/WorkflowName'
        trigger_type:
          $ref: '#/components/schemas/WorkflowRunTriggerType'
        schedule_name:
          $ref: '#/components/schemas/WorkflowScheduleName'
        status:
          $ref: '#/components/schemas/WorkflowRunStatus'
        reason:
          type: string
        created_at:
          type: string
          format: date-time
        duration_seconds:
          type: integer
          format: int64
          minimum: 0
      required:
      - name
      - workflow_name
      - trigger_type
      - status
      - reason
      - created_at

    WorkflowRunDetail:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/WorkflowRunName'
        agent_name:
          $ref: '#/components/schemas/AgentName'
        workflow_name:
          $ref: '#/components/schemas/WorkflowName'
        trigger_type:
          $ref: '#/components/schemas/WorkflowRunTriggerType'
        schedule_name:
          $ref: '#/components/schemas/WorkflowScheduleName'
        inputs:
          $ref: '#/components/schemas/JSONValue'
        timeout_seconds:
          type: integer
          format: int32
          minimum: 1
          maximum: 604800
        status:
          $ref: '#/components/schemas/WorkflowRunStatus'
        reason:
          type: string
        message:
          type: string
        session_id:
          type: string
        created_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
        duration_seconds:
          type: integer
          format: int64
          minimum: 0
        node_statuses:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowRunNodeStatus'
      required:
      - name
      - agent_name
      - workflow_name
      - trigger_type
      - inputs
      - timeout_seconds
      - status
      - reason
      - message
      - created_at
      - node_statuses

    WorkflowRunNodeStatus:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/WorkflowNodeName'
        phase:
          $ref: '#/components/schemas/WorkflowRunNodePhase'
        message:
          type: string
        started_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
      required:
      - name
      - phase
      - message

    WorkflowWebhookTrigger:
      type: object
      additionalProperties: false
      properties:
        workflow_name:
          $ref: '#/components/schemas/WorkflowName'
        api_key_id:
          $ref: '#/components/schemas/APIKeyID'
        last_triggered_at:
          type: string
          format: date-time
      required:
      - workflow_name
      - api_key_id
      - last_triggered_at

    CreateWorkflowScheduleRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/WorkflowScheduleName'
        schedule:
          type: string
          minLength: 1
        time_zone:
          type: string
        inputs:
          $ref: '#/components/schemas/JSONValue'
        timeout_seconds:
          type: integer
          format: int32
          minimum: 1
          maximum: 604800
        suspend:
          type: boolean
        successful_runs_history_limit:
          type: integer
          format: int32
          minimum: 1
          maximum: 10
        failed_runs_history_limit:
          type: integer
          format: int32
          minimum: 1
          maximum: 10
      required:
      - name
      - schedule
      - timeout_seconds

    UpdateWorkflowScheduleRequest:
      type: object
      additionalProperties: false
      properties:
        schedule:
          type: string
          minLength: 1
        time_zone:
          type: string
        inputs:
          $ref: '#/components/schemas/JSONValue'
        timeout_seconds:
          type: integer
          format: int32
          minimum: 1
          maximum: 604800
        suspend:
          type: boolean
        successful_runs_history_limit:
          type: integer
          format: int32
          minimum: 1
          maximum: 10
        failed_runs_history_limit:
          type: integer
          format: int32
          minimum: 1
          maximum: 10
      required:
      - schedule
      - timeout_seconds

    WorkflowSummary:
      type: object
      additionalProperties: false
      properties:
        workflow_name:
          $ref: '#/components/schemas/WorkflowName'
        title:
          type: string
        summary:
          type: string
        updated_at:
          type: string
          format: date-time
      required:
      - workflow_name
      - title
      - summary
      - updated_at

    WorkflowNode:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/WorkflowNodeName'
        instructions:
          type: string
          minLength: 1
          maxLength: 16384
        goal:
          type: string
          minLength: 1
          maxLength: 2048
        done_criteria:
          type: string
          minLength: 1
          maxLength: 2048
        preferred_skills:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 64
            pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
        preferred_tools:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 128
      required:
      - name
      - instructions
      - goal
      - done_criteria

    WorkflowEdge:
      type: object
      additionalProperties: false
      properties:
        source:
          $ref: '#/components/schemas/WorkflowNodeName'
        target:
          $ref: '#/components/schemas/WorkflowNodeName'
        branch_label:
          type: string
          maxLength: 256
        condition_summary:
          type: string
          maxLength: 1024
      required:
      - source
      - target
      - branch_label
      - condition_summary

    WorkflowInputs:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/WorkflowInputSchema'

    WorkflowArbitraryJSON:
      type: object
      additionalProperties: false
      description: >
        Arbitrary JSON workflow input contract. Use this instead of typed
        workflow inputs when a workflow should accept one free-form JSON
        payload.
      properties:
        description:
          type: string
          minLength: 1
        default_payload:
          allOf:
          - $ref: '#/components/schemas/JSONValue'
          x-omitempty: true

    WorkflowInputStringFormat:
      type: string
      enum:
      - email
      - uri
      - uuid
      - date
      - date-time

    WorkflowInputType:
      type: string
      enum:
      - string
      - integer
      - number
      - boolean

    WorkflowInputScalarValue:
      oneOf:
      - type: boolean
      - type: number
        format: double
      - type: string

    WorkflowInputSchema:
      type: object
      additionalProperties: false
      description: |
        Per-input validation schema. Only these keys are accepted: type,
        description, required, default, enum, minLength, maxLength, pattern,
        format, minimum, maximum, exclusiveMinimum, exclusiveMaximum, and
        multipleOf. Extra JSON Schema metadata is not supported.
      properties:
        type:
          $ref: '#/components/schemas/WorkflowInputType'
        description:
          type: string
          minLength: 1
        required:
          type: boolean
        default:
          $ref: '#/components/schemas/WorkflowInputScalarValue'
        enum:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            $ref: '#/components/schemas/WorkflowInputScalarValue'
        minLength:
          type: integer
          minimum: 0
        maxLength:
          type: integer
          minimum: 0
        pattern:
          type: string
          minLength: 1
        format:
          $ref: '#/components/schemas/WorkflowInputStringFormat'
        minimum:
          type: number
          format: double
        maximum:
          type: number
          format: double
        exclusiveMinimum:
          type: number
          format: double
        exclusiveMaximum:
          type: number
          format: double
        multipleOf:
          type: number
          format: double
          minimum: 0
          exclusiveMinimum: true
      required:
      - type
      - required

    DeleteWorkflowsRequest:
      type: object
      additionalProperties: false
      properties:
        workflow_names:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/WorkflowName'
      required: [workflow_names]

    UpdateAgentRequest:
      type: object
      additionalProperties: false
      properties:
        env:
          type: object
          additionalProperties:
            type: string
        memory:
          $ref: '#/components/schemas/AgentMemoryConfig'
        sandbox:
          $ref: '#/components/schemas/ResourceReference'
        skills:
          type: array
          items:
            $ref: '#/components/schemas/ResourceReference'
        opencode:
          $ref: '#/components/schemas/AgentOpencodeConfig'
      minProperties: 1

    TransferAgentOwnerRequest:
      type: object
      additionalProperties: false
      properties:
        owner_user_id:
          type: string
          minLength: 1
      required: [owner_user_id]

    UpsertAgentShareRequest:
      type: object
      additionalProperties: false
      properties:
        target_user_id:
          type: string
          minLength: 1
        target_team_id:
          type: string
          minLength: 1
        capabilities:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/AgentShareCapability'
      required: [capabilities]

    AgentOpencodeConfig:
      type: object
      additionalProperties: false
      properties:
        instruction:
          type: string
          maxLength: 4096

    ListTracesResponse:
      type: object
      additionalProperties: false
      properties:
        traces:
          type: array
          items:
            $ref: '#/components/schemas/Trace'
        next_page_token:
          type: string
      required: [traces, next_page_token]

    ListTraceSessionsResponse:
      type: object
      additionalProperties: false
      properties:
        trace_sessions:
          type: array
          items:
            $ref: '#/components/schemas/TraceSession'
        next_page_token:
          type: string
      required: [trace_sessions, next_page_token]

    Trace:
      type: object
      additionalProperties: false
      properties:
        trace_id:
          $ref: '#/components/schemas/TraceID'
        agent_name:
          $ref: '#/components/schemas/AgentName'
        root_span_id:
          $ref: '#/components/schemas/OptionalSpanID'
        started_at:
          type: string
          format: date-time
        ended_at:
          type: string
          format: date-time
        duration_ns:
          type: integer
          format: int64
          minimum: 0
        duration_ms:
          type: number
          format: double
          minimum: 0
        span_count:
          type: integer
          format: int64
          minimum: 0
        error_count:
          type: integer
          format: int64
          minimum: 0
        tool_count:
          type: integer
          format: int64
          minimum: 0
        model_count:
          type: integer
          format: int64
          minimum: 0
        input_tokens:
          type: integer
          format: int64
          minimum: 0
        output_tokens:
          type: integer
          format: int64
          minimum: 0
        cached_input_tokens:
          type: integer
          format: int64
          minimum: 0
        cached_write_tokens:
          type: integer
          format: int64
          minimum: 0
        cost_usd:
          type: number
          format: double
          minimum: 0
        status_code:
          type: string
        updated_at:
          type: string
          format: date-time
      required:
      - trace_id
      - agent_name
      - root_span_id
      - started_at
      - ended_at
      - duration_ns
      - duration_ms
      - span_count
      - error_count
      - tool_count
      - model_count
      - input_tokens
      - output_tokens
      - cached_input_tokens
      - cached_write_tokens
      - cost_usd
      - status_code
      - updated_at

    TraceSession:
      type: object
      additionalProperties: false
      properties:
        trace_id:
          $ref: '#/components/schemas/TraceID'
        session_id:
          type: string
        agent_name:
          $ref: '#/components/schemas/AgentName'
        root_span_id:
          $ref: '#/components/schemas/OptionalSpanID'
        started_at:
          type: string
          format: date-time
        ended_at:
          type: string
          format: date-time
        duration_ns:
          type: integer
          format: int64
          minimum: 0
        duration_ms:
          type: number
          format: double
          minimum: 0
        span_count:
          type: integer
          format: int64
          minimum: 0
        error_count:
          type: integer
          format: int64
          minimum: 0
        tool_count:
          type: integer
          format: int64
          minimum: 0
        model_count:
          type: integer
          format: int64
          minimum: 0
        input_tokens:
          type: integer
          format: int64
          minimum: 0
        output_tokens:
          type: integer
          format: int64
          minimum: 0
        cached_input_tokens:
          type: integer
          format: int64
          minimum: 0
        cached_write_tokens:
          type: integer
          format: int64
          minimum: 0
        cost_usd:
          type: number
          format: double
          minimum: 0
        status_code:
          type: string
        updated_at:
          type: string
          format: date-time
      required:
      - trace_id
      - session_id
      - agent_name
      - root_span_id
      - started_at
      - ended_at
      - duration_ns
      - duration_ms
      - span_count
      - error_count
      - tool_count
      - model_count
      - input_tokens
      - output_tokens
      - cached_input_tokens
      - cached_write_tokens
      - cost_usd
      - status_code
      - updated_at

    ListSpansResponse:
      type: object
      additionalProperties: false
      properties:
        spans:
          type: array
          items:
            $ref: '#/components/schemas/Span'
        next_page_token:
          type: string
      required: [spans, next_page_token]

    Span:
      type: object
      additionalProperties: false
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
        agent_name:
          $ref: '#/components/schemas/AgentName'
        session_id:
          type: string
        trace_id:
          $ref: '#/components/schemas/TraceID'
        span_id:
          $ref: '#/components/schemas/SpanID'
        parent_span_id:
          $ref: '#/components/schemas/OptionalSpanID'
        start_time:
          type: string
          format: date-time
        end_time:
          type: string
          format: date-time
        duration_ns:
          type: integer
          format: int64
          minimum: 0
        duration_ms:
          type: number
          format: double
          minimum: 0
        name:
          type: string
        span_class:
          type: string
        operation_name:
          type: string
        kind:
          type: string
        status_code:
          type: string
        error_type:
          type: string
        error_message:
          type: string
        model:
          type: string
        tool_name:
          type: string
        input_tokens:
          type: integer
          format: int64
          minimum: 0
        output_tokens:
          type: integer
          format: int64
          minimum: 0
        cached_input_tokens:
          type: integer
          format: int64
          minimum: 0
        cached_write_tokens:
          type: integer
          format: int64
          minimum: 0
        cost_usd:
          type: number
          format: double
          minimum: 0
        llm_finish_reason:
          type: string
        ingested_at:
          type: string
          format: date-time
      required:
      - id
      - agent_name
      - session_id
      - trace_id
      - span_id
      - parent_span_id
      - start_time
      - end_time
      - duration_ns
      - duration_ms
      - name
      - span_class
      - operation_name
      - kind
      - status_code
      - error_type
      - error_message
      - model
      - tool_name
      - input_tokens
      - output_tokens
      - cached_input_tokens
      - cached_write_tokens
      - cost_usd
      - llm_finish_reason
      - ingested_at

    SpanDetail:
      allOf:
      - $ref: '#/components/schemas/Span'
      - type: object
        additionalProperties: false
        properties:
          resource_attributes:
            $ref: '#/components/schemas/JSONValue'
          span_attributes:
            $ref: '#/components/schemas/JSONValue'
        required:
        - resource_attributes
        - span_attributes

    SpanPayload:
      type: object
      additionalProperties: false
      properties:
        input_messages:
          $ref: '#/components/schemas/JSONValue'
        output_messages:
          $ref: '#/components/schemas/JSONValue'
        tool_arguments:
          $ref: '#/components/schemas/JSONValue'
        tool_result:
          $ref: '#/components/schemas/JSONValue'
      required:
      - input_messages
      - output_messages
      - tool_arguments
      - tool_result

    MCPGraphResponse:
      type: object
      additionalProperties: false
      properties:
        agent:
          $ref: '#/components/schemas/MCPGraphAgent'
        connections:
          type: array
          items:
            $ref: '#/components/schemas/MCPGraphConnection'
        tools:
          type: array
          items:
            $ref: '#/components/schemas/MCPGraphTool'
        edges:
          type: array
          items:
            $ref: '#/components/schemas/MCPGraphEdge'
      required: [agent, connections, tools, edges]

    MCPGraphAgent:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/AgentName'
      required: [name]

    MCPGraphConnection:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        name:
          type: string
        server_url:
          type: string
          format: uri
      required: [id, name]

    MCPGraphTool:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        connection_id:
          type: string
        name:
          type: string
      required: [id, connection_id, name]

    MCPGraphEdge:
      type: object
      additionalProperties: false
      properties:
        source:
          type: string
        target:
          type: string
        kind:
          type: string
          enum: [agent_connection, connection_tool]
        avg_latency_ms:
          type: number
          format: double
          minimum: 0
        success_count:
          type: integer
          format: int64
          minimum: 0
        failed_count:
          type: integer
          format: int64
          minimum: 0
        last_called_at:
          type: string
          format: date-time
      required:
      - source
      - target
      - kind

    SpanDetailResponse:
      type: object
      additionalProperties: false
      properties:
        span:
          $ref: '#/components/schemas/SpanDetail'
        payload:
          $ref: '#/components/schemas/SpanPayload'
      required: [span, payload]

    ListProcessObservabilityResponse:
      type: object
      additionalProperties: false
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/ProcessObservabilityEvent'
        next_page_token:
          type: string
      required: [events, next_page_token]

    ListProcessObservabilitySummaryResponse:
      type: object
      additionalProperties: false
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/ProcessObservabilityEventAggregated'
        next_page_token:
          type: string
      required: [events, next_page_token]

    ProcessObservabilityEvent:
      type: object
      additionalProperties: false
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
        agent_name:
          $ref: '#/components/schemas/AgentName'
        event_time:
          type: string
          format: date-time
        ingested_at:
          type: string
          format: date-time
        pod_namespace:
          type: string
        pod_name:
          type: string
        process:
          type: string
        parent_process:
          type: string
        command_invocation:
          type: string
        action:
          $ref: '#/components/schemas/ObservabilityAction'
        source:
          type: string
      required:
      - id
      - agent_name
      - event_time
      - ingested_at
      - pod_namespace
      - pod_name
      - process
      - parent_process
      - command_invocation
      - action
      - source

    ProcessObservabilityEventAggregated:
      type: object
      additionalProperties: false
      properties:
        agent_name:
          $ref: '#/components/schemas/AgentName'
        last_seen:
          type: string
          format: date-time
        process:
          type: string
        parent_process:
          type: string
        command_invocation:
          type: string
        action:
          $ref: '#/components/schemas/ObservabilityAction'
        source:
          type: string
        occurrences:
          type: integer
          format: int64
          minimum: 1
      required:
      - agent_name
      - last_seen
      - process
      - parent_process
      - command_invocation
      - action
      - source
      - occurrences

    ListFileObservabilityResponse:
      type: object
      additionalProperties: false
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/FileObservabilityEvent'
        next_page_token:
          type: string
      required: [events, next_page_token]

    ListFileObservabilitySummaryResponse:
      type: object
      additionalProperties: false
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/FileObservabilityEventAggregated'
        next_page_token:
          type: string
      required: [events, next_page_token]

    FileObservabilityEvent:
      type: object
      additionalProperties: false
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
        agent_name:
          $ref: '#/components/schemas/AgentName'
        event_time:
          type: string
          format: date-time
        ingested_at:
          type: string
          format: date-time
        pod_namespace:
          type: string
        pod_name:
          type: string
        file_path_accessed:
          type: string
        process:
          type: string
        command_invocation:
          type: string
        action:
          $ref: '#/components/schemas/ObservabilityAction'
        source:
          type: string
      required:
      - id
      - agent_name
      - event_time
      - ingested_at
      - pod_namespace
      - pod_name
      - file_path_accessed
      - process
      - command_invocation
      - action
      - source

    FileObservabilityEventAggregated:
      type: object
      additionalProperties: false
      properties:
        agent_name:
          $ref: '#/components/schemas/AgentName'
        last_seen:
          type: string
          format: date-time
        file_path_accessed:
          type: string
        process:
          type: string
        command_invocation:
          type: string
        action:
          $ref: '#/components/schemas/ObservabilityAction'
        source:
          type: string
        occurrences:
          type: integer
          format: int64
          minimum: 1
      required:
      - agent_name
      - last_seen
      - file_path_accessed
      - process
      - command_invocation
      - action
      - source
      - occurrences

    ListNetworkObservabilityResponse:
      type: object
      additionalProperties: false
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/NetworkObservabilityEvent'
        next_page_token:
          type: string
      required: [events, next_page_token]

    ListNetworkObservabilitySummaryResponse:
      type: object
      additionalProperties: false
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/NetworkObservabilityEventAggregated'
        next_page_token:
          type: string
      required: [events, next_page_token]

    NetworkObservabilityEvent:
      type: object
      additionalProperties: false
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
        agent_name:
          $ref: '#/components/schemas/AgentName'
        event_time:
          type: string
          format: date-time
        ingested_at:
          type: string
          format: date-time
        pod_namespace:
          type: string
        pod_name:
          type: string
        destination_domain:
          type: string
        destination_ip:
          type: string
        destination_port:
          type: integer
          format: int64
          minimum: 0
        protocol:
          type: string
        action:
          $ref: '#/components/schemas/ObservabilityAction'
        source:
          type: string
      required:
      - id
      - agent_name
      - event_time
      - ingested_at
      - pod_namespace
      - pod_name
      - destination_domain
      - destination_ip
      - destination_port
      - protocol
      - action
      - source

    NetworkObservabilityEventAggregated:
      type: object
      additionalProperties: false
      properties:
        agent_name:
          $ref: '#/components/schemas/AgentName'
        last_seen:
          type: string
          format: date-time
        destination_domain:
          type: string
        destination_ip:
          type: string
        destination_port:
          type: integer
          format: int64
          minimum: 0
        protocol:
          type: string
        action:
          $ref: '#/components/schemas/ObservabilityAction'
        source:
          type: string
        occurrences:
          type: integer
          format: int64
          minimum: 1
      required:
      - agent_name
      - last_seen
      - destination_domain
      - destination_ip
      - destination_port
      - protocol
      - action
      - source
      - occurrences

    WatchAgentsRequest:
      type: object
      additionalProperties: false
      properties:
        agent_names:
          type: array
          items:
            $ref: '#/components/schemas/AgentName'
          uniqueItems: true

    WatchAgentsEvent:
      type: object
      additionalProperties: false
      properties:
        agents:
          type: array
          items:
            $ref: '#/components/schemas/Agent'
      required: [agents]

    WatchWorkflowRunsRequest:
      type: object
      additionalProperties: false
      properties:
        run_names:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowRunName'
          uniqueItems: true

    WatchWorkflowRunsEvent:
      type: object
      additionalProperties: false
      properties:
        workflow_runs:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowRunDetail'
      required: [workflow_runs]

    JSONValue:
      nullable: true
      oneOf:
      - type: boolean
      - type: number
      - type: string
      - type: array
        items:
          $ref: '#/components/schemas/JSONValue'
      - type: object
        additionalProperties:
          $ref: '#/components/schemas/JSONValue'

    JSONObject:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/JSONValue'

    SecretKey:
      type: string
      minLength: 1
      maxLength: 128
      pattern: '^[A-Za-z_][A-Za-z0-9_]*$'
      description: Secret key name. Must be a valid environment variable name.

    SecretValue:
      type: string
      maxLength: 49152
      description: Secret value. Max 48 KB.

    SecretHost:
      type: string
      minLength: 1
      maxLength: 253
      description: >
        Allowed request host. Use an exact hostname, wildcard hostname with a
        leading "*." or "**.", exact IPv4/IPv6 address, or IPv4/IPv6 CIDR
        range. "*." matches exactly a subdomain label, while "**." matches
        any subdomain depth. Wildcards do not match the apex domain.

    SecretType:
      type: string
      enum: [static, oauth]

    SecretState:
      type: string
      enum: [accepted, ready, degraded]

    SecretOAuthConfig:
      type: object
      additionalProperties: false
      properties:
        provider:
          type: string
        issuer:
          type: string
          format: uri
        authorization_endpoint:
          type: string
          format: uri
        token_endpoint:
          type: string
          format: uri
        registration_endpoint:
          type: string
          format: uri
        resource:
          type: string
          format: uri
        scopes:
          type: array
          items:
            type: string
            minLength: 1
          minItems: 1
      required: [token_endpoint, scopes]

    SecretOAuthCredentials:
      type: object
      additionalProperties: false
      properties:
        client_id:
          type: string
        client_secret:
          type: string
        access_token:
          type: string
        refresh_token:
          type: string
        expires_at:
          type: string
          format: date-time
        token_type:
          type: string
        scopes:
          type: array
          items:
            type: string
            minLength: 1
        registration:
          $ref: '#/components/schemas/JSONObject'
        revocation:
          $ref: '#/components/schemas/JSONObject'

    CreateSecretRequest:
      type: object
      additionalProperties: false
      properties:
        type:
          $ref: '#/components/schemas/SecretType'
        key:
          $ref: '#/components/schemas/SecretKey'
        hosts:
          type: array
          items:
            $ref: '#/components/schemas/SecretHost'
          minItems: 1
          maxItems: 100
        value:
          $ref: '#/components/schemas/SecretValue'
        oauth:
          allOf:
          - $ref: '#/components/schemas/SecretOAuthConfig'
          - type: object
            additionalProperties: false
            properties:
              credentials:
                $ref: '#/components/schemas/SecretOAuthCredentials'
            required: [credentials]
      required: [type, key, hosts]

    SecretListItem:
      type: object
      additionalProperties: false
      properties:
        key:
          $ref: '#/components/schemas/SecretKey'
        created_by:
          $ref: '#/components/schemas/ResourceActor'
        last_modified_by:
          $ref: '#/components/schemas/ResourceActor'
        type:
          $ref: '#/components/schemas/SecretType'
        hosts:
          type: array
          items:
            $ref: '#/components/schemas/SecretHost'
        provider:
          type: string
        status:
          $ref: '#/components/schemas/SecretState'
        reason:
          type: string
        message:
          type: string
        created_at:
          type: string
          format: date-time
        last_refresh_time:
          type: string
          format: date-time
        token_expiry_time:
          type: string
          format: date-time
      required: [key, type, hosts, status, reason, message, created_at, created_by, last_modified_by]

    PutSecretsResponse:
      type: object
      additionalProperties: false
      properties:
        secret:
          $ref: '#/components/schemas/SecretListItem'
      required: [secret]

    DeleteSecretsRequest:
      type: object
      additionalProperties: false
      properties:
        keys:
          type: array
          items:
            $ref: '#/components/schemas/SecretKey'
          maxItems: 100
      required: [keys]

    ListSecretsResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SecretListItem'
        next_page_token:
          type: string
      required: [items, next_page_token]

    WatchSecretsRequest:
      type: object
      additionalProperties: false
      properties:
        keys:
          type: array
          items:
            $ref: '#/components/schemas/SecretKey'
          uniqueItems: true

    WatchSecretsEvent:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SecretListItem'
      required: [items]

    Sandbox:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/SandboxName'
        scope:
          $ref: '#/components/schemas/ResourceScope'
        created_by:
          $ref: '#/components/schemas/ResourceActor'
        last_modified_by:
          $ref: '#/components/schemas/ResourceActor'
        packages:
          type: array
          items:
            type: string
            minLength: 1
        allowed_hosts:
          type: array
          items:
            type: string
            minLength: 1
        mcp_connection_refs:
          type: array
          items:
            $ref: '#/components/schemas/MCPConnectionRef'
        skills:
          type: array
          items:
            $ref: '#/components/schemas/ResourceReference'
        inference:
          $ref: '#/components/schemas/SandboxInference'
        can_modify:
          type: boolean
        can_delete:
          type: boolean
        created_at:
          type: string
          format: date-time
        metadata:
          type: object
          additionalProperties: false
          properties:
            package_count:
              type: integer
              format: int32
              minimum: 0
            allowed_host_count:
              type: integer
              format: int32
              minimum: 0
            skill_count:
              type: integer
              format: int32
              minimum: 0
            referenced_by_agent:
              type: boolean
          required: [package_count, allowed_host_count, skill_count, referenced_by_agent]
      required: [name, scope, created_by, last_modified_by, packages, allowed_hosts, mcp_connection_refs, skills, inference, created_at, can_modify, can_delete, metadata]

    ListSandboxesResponse:
      type: object
      additionalProperties: false
      properties:
        sandboxes:
          type: array
          items:
            $ref: '#/components/schemas/Sandbox'
        next_page_token:
          type: string
      required: [sandboxes, next_page_token]

    CreateSandboxRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/SandboxName'
        packages:
          type: array
          items:
            type: string
            minLength: 1
        allowed_hosts:
          type: array
          items:
            type: string
            minLength: 1
        mcp_connection_refs:
          type: array
          items:
            $ref: '#/components/schemas/MCPConnectionRef'
        skills:
          type: array
          items:
            $ref: '#/components/schemas/ResourceReference'
        inference:
          $ref: '#/components/schemas/SandboxInference'
      required: [name, inference]

    UpdateSandboxRequest:
      type: object
      additionalProperties: false
      properties:
        packages:
          type: array
          items:
            type: string
            minLength: 1
        allowed_hosts:
          type: array
          items:
            type: string
            minLength: 1
        mcp_connection_refs:
          type: array
          items:
            $ref: '#/components/schemas/MCPConnectionRef'
        skills:
          type: array
          items:
            $ref: '#/components/schemas/ResourceReference'
        inference:
          $ref: '#/components/schemas/SandboxInference'
      required: [packages, allowed_hosts, mcp_connection_refs, skills, inference]

    SandboxInferenceModelRef:
      type: object
      additionalProperties: false
      properties:
        scope:
          $ref: '#/components/schemas/ResourceScope'
        provider:
          $ref: '#/components/schemas/InferenceProviderName'
        model:
          type: string
          minLength: 1
          maxLength: 512
      required: [scope, provider, model]

    SandboxInference:
      type: object
      additionalProperties: false
      properties:
        models:
          type: array
          minItems: 1
          maxItems: 500
          items:
            $ref: '#/components/schemas/SandboxInferenceModelRef'
        default_model:
          $ref: '#/components/schemas/SandboxInferenceModelRef'
        small_model:
          $ref: '#/components/schemas/SandboxInferenceModelRef'
        attachment_model:
          $ref: '#/components/schemas/SandboxInferenceModelRef'
      required: [models, default_model]

    InferenceProviderKind:
      type: string
      enum: [OpenAI, OpenAICodex, Anthropic, Gemini, GitHubCopilot, OpenAICompatible, AnthropicCompatible, Bedrock, VertexAI, Azure]

    InferenceModelAPI:
      type: string
      enum: [ChatCompletions, Responses, Messages]

    InferenceModelModality:
      type: string
      enum: [text, audio, image, video, pdf]

    InferenceModelCapabilities:
      type: object
      additionalProperties: false
      properties:
        attachment: {type: boolean}
        reasoning: {type: boolean}
        temperature: {type: boolean}
        tool_call: {type: boolean}
      required: [attachment, reasoning, temperature, tool_call]

    InferenceModelModalities:
      type: object
      additionalProperties: false
      properties:
        input:
          type: array
          minItems: 1
          uniqueItems: true
          items: {$ref: '#/components/schemas/InferenceModelModality'}
        output:
          type: array
          minItems: 1
          uniqueItems: true
          items: {$ref: '#/components/schemas/InferenceModelModality'}
      required: [input, output]

    InferenceModelLimits:
      type: object
      additionalProperties: false
      properties:
        context: {type: integer, format: int32, minimum: 1, maximum: 2147483647}
        input: {type: integer, format: int32, minimum: 1, maximum: 2147483647}
        output: {type: integer, format: int32, minimum: 1, maximum: 2147483647}
      required: [context, output]

    InferenceModel:
      type: object
      additionalProperties: false
      properties:
        id: {type: string, minLength: 1, maxLength: 512}
        display_name: {type: string, minLength: 1, maxLength: 128}
        capabilities: {$ref: '#/components/schemas/InferenceModelCapabilities'}
        modalities: {$ref: '#/components/schemas/InferenceModelModalities'}
        limits: {$ref: '#/components/schemas/InferenceModelLimits'}
        api: {$ref: '#/components/schemas/InferenceModelAPI'}
        catalog_provider: {type: string, minLength: 1, maxLength: 128}
      required: [id, display_name, capabilities, modalities, limits]

    InferenceProviderHeader:
      type: object
      additionalProperties: false
      properties:
        name: {type: string, minLength: 1, maxLength: 128, pattern: "^[a-z0-9!#$%&'*+.^_|~-]+$"}
        value:
          type: string
          minLength: 1
          maxLength: 1024
      required: [name, value]

    OpenAIProviderConfig:
      type: object
      additionalProperties: false
      properties:
        base_url: {type: string, format: uri, maxLength: 2048}

    AnthropicProviderConfig:
      type: object
      additionalProperties: false
      properties:
        base_url: {type: string, format: uri, maxLength: 2048}

    GeminiProviderConfig:
      type: object
      additionalProperties: false
      properties:
        base_url: {type: string, format: uri, maxLength: 2048}

    VertexAIProviderConfig:
      type: object
      additionalProperties: false
      properties:
        project: {type: string, minLength: 1, maxLength: 128}
        region: {type: string, minLength: 1, maxLength: 64}
      required: [project, region]

    BedrockProviderConfig:
      type: object
      additionalProperties: false
      properties:
        region: {type: string, minLength: 1, maxLength: 63, pattern: '^[a-z]{2}(-gov)?-[a-z]+-[0-9]+$'}
        auth_mode: {type: string, enum: [AccessKey, BearerToken]}
      required: [region, auth_mode]

    AzureProviderConfig:
      type: object
      additionalProperties: false
      properties:
        resource_type: {type: string, enum: [OpenAI, Foundry]}
        resource_name: {type: string, minLength: 1, maxLength: 64}
        project: {type: string, minLength: 1, maxLength: 64}
        api_version: {type: string, minLength: 1, maxLength: 64}
        auth_mode: {type: string, enum: [APIKey, ServicePrincipal]}
      required: [resource_type, resource_name, api_version, auth_mode]

    CompatibleProviderConfig:
      type: object
      additionalProperties: false
      properties:
        base_url: {type: string, format: uri, maxLength: 2048}
        path: {type: string, maxLength: 1024, pattern: '^/[^?#]*$'}
        path_prefix: {type: string, maxLength: 1024, pattern: '^/[^?#]*$'}
        auth_mode: {type: string, enum: [None, APIKey]}
        auth_header: {type: string, minLength: 1, maxLength: 128, pattern: "^[a-z0-9!#$%&'*+.^_|~-]+$"}
        auth_prefix:
          type: string
          maxLength: 128
        headers:
          type: array
          maxItems: 32
          items: {$ref: '#/components/schemas/InferenceProviderHeader'}
        allow_private_endpoint: {type: boolean, default: false}
        skip_tls_verify: {type: boolean, default: false}
      required: [base_url, auth_mode]

    InferenceProviderAPIKeyCredentials:
      type: object
      additionalProperties: false
      properties:
        api_key: {type: string, format: password, writeOnly: true, maxLength: 49152}

    InferenceProviderVertexCredentials:
      type: object
      additionalProperties: false
      properties:
        service_account_json: {type: string, format: password, writeOnly: true, maxLength: 49152}

    InferenceProviderBedrockCredentials:
      type: object
      additionalProperties: false
      properties:
        access_key: {type: string, format: password, writeOnly: true, maxLength: 49152}
        secret_key: {type: string, format: password, writeOnly: true, maxLength: 49152}
        session_token: {type: string, format: password, writeOnly: true, maxLength: 49152}
        bearer_token: {type: string, format: password, writeOnly: true, maxLength: 49152}

    InferenceProviderAzureCredentials:
      type: object
      additionalProperties: false
      properties:
        api_key: {type: string, format: password, writeOnly: true, maxLength: 49152}
        client_id: {type: string, format: password, writeOnly: true, maxLength: 49152}
        tenant_id: {type: string, format: password, writeOnly: true, maxLength: 49152}
        client_secret: {type: string, format: password, writeOnly: true, maxLength: 49152}

    InferenceProviderOAuthCredentials:
      type: object
      additionalProperties: false
      properties:
        access_token: {type: string, format: password, writeOnly: true, minLength: 1, maxLength: 49152}
        refresh_token: {type: string, format: password, writeOnly: true, minLength: 1, maxLength: 49152}
        id_token: {type: string, format: password, writeOnly: true, minLength: 1, maxLength: 49152}
        expires_at: {type: string, format: date-time, writeOnly: true}
      required: [access_token]

    CreateInferenceProviderOAuthTicketRequest:
      type: object
      additionalProperties: false
      properties:
        kind: {type: string, enum: [OpenAICodex, GitHubCopilot]}
        credentials: {$ref: '#/components/schemas/InferenceProviderOAuthCredentials'}
      required: [kind, credentials]

    CreateInferenceProviderOAuthTicketResponse:
      type: object
      additionalProperties: false
      properties:
        ticket: {type: string, minLength: 1, maxLength: 256}
        expires_at: {type: string, format: date-time}
        models:
          type: array
          maxItems: 500
          items: {$ref: '#/components/schemas/InferenceModelSuggestion'}
        provenance: {$ref: '#/components/schemas/InferenceModelSuggestionsProvenance'}
      required: [ticket, expires_at, models, provenance]

    InferenceProviderReadFields:
      type: object
      properties:
        catalog_provider: {type: string, minLength: 1, maxLength: 128}
        display_name: {type: string, minLength: 1, maxLength: 128}
        models:
          type: array
          minItems: 1
          maxItems: 500
          items: {$ref: '#/components/schemas/InferenceModel'}
      required: [catalog_provider, display_name, models]

    OpenAIInferenceProviderWrite:
      type: object
      additionalProperties: false
      properties:
        catalog_provider: {type: string, minLength: 1, maxLength: 128}
        display_name: {type: string, minLength: 1, maxLength: 128}
        models: {type: array, minItems: 1, maxItems: 500, items: {$ref: '#/components/schemas/InferenceModel'}}
        kind: {type: string, enum: [OpenAI]}
        openai: {$ref: '#/components/schemas/OpenAIProviderConfig'}
        credentials: {$ref: '#/components/schemas/InferenceProviderAPIKeyCredentials'}
      required: [catalog_provider, display_name, models, kind, openai, credentials]
    OpenAICodexInferenceProviderWrite:
      type: object
      additionalProperties: false
      properties:
        catalog_provider: {type: string, enum: [openai]}
        display_name: {type: string, minLength: 1, maxLength: 128}
        models: {type: array, minItems: 1, maxItems: 500, items: {$ref: '#/components/schemas/InferenceModel'}}
        kind: {type: string, enum: [OpenAICodex]}
      required: [catalog_provider, display_name, models, kind]
    AnthropicInferenceProviderWrite:
      type: object
      additionalProperties: false
      properties:
        catalog_provider: {type: string, minLength: 1, maxLength: 128}
        display_name: {type: string, minLength: 1, maxLength: 128}
        models: {type: array, minItems: 1, maxItems: 500, items: {$ref: '#/components/schemas/InferenceModel'}}
        kind: {type: string, enum: [Anthropic]}
        anthropic: {$ref: '#/components/schemas/AnthropicProviderConfig'}
        credentials: {$ref: '#/components/schemas/InferenceProviderAPIKeyCredentials'}
      required: [catalog_provider, display_name, models, kind, anthropic, credentials]
    GeminiInferenceProviderWrite:
      type: object
      additionalProperties: false
      properties:
        catalog_provider: {type: string, minLength: 1, maxLength: 128}
        display_name: {type: string, minLength: 1, maxLength: 128}
        models: {type: array, minItems: 1, maxItems: 500, items: {$ref: '#/components/schemas/InferenceModel'}}
        kind: {type: string, enum: [Gemini]}
        gemini: {$ref: '#/components/schemas/GeminiProviderConfig'}
        credentials: {$ref: '#/components/schemas/InferenceProviderAPIKeyCredentials'}
      required: [catalog_provider, display_name, models, kind, gemini, credentials]
    GitHubCopilotInferenceProviderWrite:
      type: object
      additionalProperties: false
      properties:
        catalog_provider: {type: string, enum: [github-copilot]}
        display_name: {type: string, minLength: 1, maxLength: 128}
        models: {type: array, minItems: 1, maxItems: 500, items: {$ref: '#/components/schemas/InferenceModel'}}
        kind: {type: string, enum: [GitHubCopilot]}
      required: [catalog_provider, display_name, models, kind]
    VertexAIInferenceProviderWrite:
      type: object
      additionalProperties: false
      properties:
        catalog_provider: {type: string, minLength: 1, maxLength: 128}
        display_name: {type: string, minLength: 1, maxLength: 128}
        models: {type: array, minItems: 1, maxItems: 500, items: {$ref: '#/components/schemas/InferenceModel'}}
        kind: {type: string, enum: [VertexAI]}
        vertex_ai: {$ref: '#/components/schemas/VertexAIProviderConfig'}
        credentials: {$ref: '#/components/schemas/InferenceProviderVertexCredentials'}
      required: [catalog_provider, display_name, models, kind, vertex_ai, credentials]
    BedrockInferenceProviderWrite:
      type: object
      additionalProperties: false
      properties:
        catalog_provider: {type: string, minLength: 1, maxLength: 128}
        display_name: {type: string, minLength: 1, maxLength: 128}
        models: {type: array, minItems: 1, maxItems: 500, items: {$ref: '#/components/schemas/InferenceModel'}}
        kind: {type: string, enum: [Bedrock]}
        bedrock: {$ref: '#/components/schemas/BedrockProviderConfig'}
        credentials: {$ref: '#/components/schemas/InferenceProviderBedrockCredentials'}
      required: [catalog_provider, display_name, models, kind, bedrock, credentials]
    AzureInferenceProviderWrite:
      type: object
      additionalProperties: false
      properties:
        catalog_provider: {type: string, minLength: 1, maxLength: 128}
        display_name: {type: string, minLength: 1, maxLength: 128}
        models: {type: array, minItems: 1, maxItems: 500, items: {$ref: '#/components/schemas/InferenceModel'}}
        kind: {type: string, enum: [Azure]}
        azure: {$ref: '#/components/schemas/AzureProviderConfig'}
        credentials: {$ref: '#/components/schemas/InferenceProviderAzureCredentials'}
      required: [catalog_provider, display_name, models, kind, azure, credentials]
    OpenAICompatibleInferenceProviderWrite:
      type: object
      additionalProperties: false
      properties:
        catalog_provider: {type: string, minLength: 1, maxLength: 128}
        display_name: {type: string, minLength: 1, maxLength: 128}
        models: {type: array, minItems: 1, maxItems: 500, items: {$ref: '#/components/schemas/InferenceModel'}}
        kind: {type: string, enum: [OpenAICompatible]}
        openai_compatible: {$ref: '#/components/schemas/CompatibleProviderConfig'}
        credentials: {$ref: '#/components/schemas/InferenceProviderAPIKeyCredentials'}
      required: [catalog_provider, display_name, models, kind, openai_compatible, credentials]
    AnthropicCompatibleInferenceProviderWrite:
      type: object
      additionalProperties: false
      properties:
        catalog_provider: {type: string, minLength: 1, maxLength: 128}
        display_name: {type: string, minLength: 1, maxLength: 128}
        models: {type: array, minItems: 1, maxItems: 500, items: {$ref: '#/components/schemas/InferenceModel'}}
        kind: {type: string, enum: [AnthropicCompatible]}
        anthropic_compatible: {$ref: '#/components/schemas/CompatibleProviderConfig'}
        credentials: {$ref: '#/components/schemas/InferenceProviderAPIKeyCredentials'}
      required: [catalog_provider, display_name, models, kind, anthropic_compatible, credentials]
    InferenceProviderWriteDiscriminator:
      oneOf:
      - {$ref: '#/components/schemas/OpenAIInferenceProviderWrite'}
      - {$ref: '#/components/schemas/OpenAICodexInferenceProviderWrite'}
      - {$ref: '#/components/schemas/AnthropicInferenceProviderWrite'}
      - {$ref: '#/components/schemas/GeminiInferenceProviderWrite'}
      - {$ref: '#/components/schemas/GitHubCopilotInferenceProviderWrite'}
      - {$ref: '#/components/schemas/VertexAIInferenceProviderWrite'}
      - {$ref: '#/components/schemas/BedrockInferenceProviderWrite'}
      - {$ref: '#/components/schemas/AzureInferenceProviderWrite'}
      - $ref: '#/components/schemas/OpenAICompatibleInferenceProviderWrite'
      - $ref: '#/components/schemas/AnthropicCompatibleInferenceProviderWrite'
      discriminator:
        propertyName: kind
        mapping:
          OpenAI: '#/components/schemas/OpenAIInferenceProviderWrite'
          OpenAICodex: '#/components/schemas/OpenAICodexInferenceProviderWrite'
          Anthropic: '#/components/schemas/AnthropicInferenceProviderWrite'
          Gemini: '#/components/schemas/GeminiInferenceProviderWrite'
          GitHubCopilot: '#/components/schemas/GitHubCopilotInferenceProviderWrite'
          VertexAI: '#/components/schemas/VertexAIInferenceProviderWrite'
          Bedrock: '#/components/schemas/BedrockInferenceProviderWrite'
          Azure: '#/components/schemas/AzureInferenceProviderWrite'
          OpenAICompatible: '#/components/schemas/OpenAICompatibleInferenceProviderWrite'
          AnthropicCompatible: '#/components/schemas/AnthropicCompatibleInferenceProviderWrite'

    OpenAIInferenceProviderRead:
      type: object
      properties:
        kind: {type: string, enum: [OpenAI]}
        openai: {$ref: '#/components/schemas/OpenAIProviderConfig'}
      required: [kind, openai]

    OpenAICodexInferenceProviderRead:
      type: object
      properties:
        kind: {type: string, enum: [OpenAICodex]}
      required: [kind]

    AnthropicInferenceProviderRead:
      type: object
      properties:
        kind: {type: string, enum: [Anthropic]}
        anthropic: {$ref: '#/components/schemas/AnthropicProviderConfig'}
      required: [kind, anthropic]

    GeminiInferenceProviderRead:
      type: object
      properties:
        kind: {type: string, enum: [Gemini]}
        gemini: {$ref: '#/components/schemas/GeminiProviderConfig'}
      required: [kind, gemini]

    GitHubCopilotInferenceProviderRead:
      type: object
      properties:
        kind: {type: string, enum: [GitHubCopilot]}
      required: [kind]

    VertexAIInferenceProviderRead:
      type: object
      properties:
        kind: {type: string, enum: [VertexAI]}
        vertex_ai: {$ref: '#/components/schemas/VertexAIProviderConfig'}
      required: [kind, vertex_ai]

    BedrockInferenceProviderRead:
      type: object
      properties:
        kind: {type: string, enum: [Bedrock]}
        bedrock: {$ref: '#/components/schemas/BedrockProviderConfig'}
      required: [kind, bedrock]

    AzureInferenceProviderRead:
      type: object
      properties:
        kind: {type: string, enum: [Azure]}
        azure: {$ref: '#/components/schemas/AzureProviderConfig'}
      required: [kind, azure]

    OpenAICompatibleInferenceProviderRead:
      type: object
      properties:
        kind: {type: string, enum: [OpenAICompatible]}
        openai_compatible: {$ref: '#/components/schemas/CompatibleProviderConfig'}
      required: [kind, openai_compatible]

    AnthropicCompatibleInferenceProviderRead:
      type: object
      properties:
        kind: {type: string, enum: [AnthropicCompatible]}
        anthropic_compatible: {$ref: '#/components/schemas/CompatibleProviderConfig'}
      required: [kind, anthropic_compatible]

    InferenceProviderReadDiscriminator:
      oneOf:
      - {$ref: '#/components/schemas/OpenAIInferenceProviderRead'}
      - {$ref: '#/components/schemas/OpenAICodexInferenceProviderRead'}
      - {$ref: '#/components/schemas/AnthropicInferenceProviderRead'}
      - {$ref: '#/components/schemas/GeminiInferenceProviderRead'}
      - {$ref: '#/components/schemas/GitHubCopilotInferenceProviderRead'}
      - {$ref: '#/components/schemas/VertexAIInferenceProviderRead'}
      - {$ref: '#/components/schemas/BedrockInferenceProviderRead'}
      - {$ref: '#/components/schemas/AzureInferenceProviderRead'}
      - $ref: '#/components/schemas/OpenAICompatibleInferenceProviderRead'
      - $ref: '#/components/schemas/AnthropicCompatibleInferenceProviderRead'
      discriminator:
        propertyName: kind
        mapping:
          OpenAI: '#/components/schemas/OpenAIInferenceProviderRead'
          OpenAICodex: '#/components/schemas/OpenAICodexInferenceProviderRead'
          Anthropic: '#/components/schemas/AnthropicInferenceProviderRead'
          Gemini: '#/components/schemas/GeminiInferenceProviderRead'
          GitHubCopilot: '#/components/schemas/GitHubCopilotInferenceProviderRead'
          VertexAI: '#/components/schemas/VertexAIInferenceProviderRead'
          Bedrock: '#/components/schemas/BedrockInferenceProviderRead'
          Azure: '#/components/schemas/AzureInferenceProviderRead'
          OpenAICompatible: '#/components/schemas/OpenAICompatibleInferenceProviderRead'
          AnthropicCompatible: '#/components/schemas/AnthropicCompatibleInferenceProviderRead'

    CreateInferenceProviderRequest:
      type: object
      additionalProperties: false
      properties:
        provider: {$ref: '#/components/schemas/InferenceProviderWriteDiscriminator'}
        oauth_ticket: {type: string, minLength: 1, maxLength: 256}
      required: [provider]

    UpdateInferenceProviderRequest:
      type: object
      additionalProperties: false
      properties:
        resource_version: {type: string, minLength: 1}
        provider: {$ref: '#/components/schemas/InferenceProviderWriteDiscriminator'}
      required: [resource_version, provider]

    InferenceProviderCondition:
      type: object
      additionalProperties: false
      properties:
        type: {type: string}
        status: {type: string, enum: ['True', 'False', Unknown]}
        reason: {type: string}
        message: {type: string}
      required: [type, status, reason, message]

    InferenceProvider:
      allOf:
      - $ref: '#/components/schemas/InferenceProviderReadFields'
      - $ref: '#/components/schemas/InferenceProviderReadDiscriminator'
      - type: object
        properties:
          id: {$ref: '#/components/schemas/InferenceProviderName'}
          scope: {$ref: '#/components/schemas/ResourceScope'}
          created_by: {$ref: '#/components/schemas/ResourceActor'}
          last_modified_by: {$ref: '#/components/schemas/ResourceActor'}
          resource_version: {type: string}
          state: {type: string, enum: [Accepted, Ready, Degraded]}
          conditions:
            type: array
            items: {$ref: '#/components/schemas/InferenceProviderCondition'}
          model_count: {type: integer, minimum: 0}
          usage_count: {type: integer, minimum: 0}
          can_modify: {type: boolean}
          can_delete: {type: boolean}
          created_at: {type: string, format: date-time}
          updated_at: {type: string, format: date-time}
        required: [id, scope, created_by, last_modified_by, resource_version, state, conditions, model_count, usage_count, can_modify, can_delete, created_at, updated_at]

    ListInferenceProvidersResponse:
      type: object
      additionalProperties: false
      properties:
        providers:
          type: array
          items: {$ref: '#/components/schemas/InferenceProvider'}
        next_page_token: {type: string}
      required: [providers, next_page_token]

    WatchInferenceProvidersRequest:
      type: object
      additionalProperties: false
      properties:
        providers:
          type: array
          maxItems: 200
          uniqueItems: true
          items: {$ref: '#/components/schemas/ResourceReference'}

    WatchInferenceProvidersEvent:
      type: object
      additionalProperties: false
      properties:
        providers:
          type: array
          items: {$ref: '#/components/schemas/InferenceProvider'}
      required: [providers]

    InferenceProviderUsage:
      type: object
      additionalProperties: false
      properties:
        provider: {$ref: '#/components/schemas/InferenceProviderName'}
        pools:
          type: array
          items: {$ref: '#/components/schemas/InferencePoolName'}
        sandboxes:
          type: array
          items: {$ref: '#/components/schemas/SandboxName'}
      required: [provider, pools, sandboxes]

    InferencePoolMember:
      type: object
      additionalProperties: false
      properties:
        scope: {$ref: '#/components/schemas/ResourceScope'}
        provider: {$ref: '#/components/schemas/InferenceProviderName'}
        model: {type: string, minLength: 1, maxLength: 512}
      required: [scope, provider, model]

    InferencePoolWrite:
      type: object
      additionalProperties: false
      properties:
        display_name: {type: string, minLength: 1, maxLength: 128}
        automatic_failover: {type: boolean}
        members:
          type: array
          minItems: 1
          maxItems: 8
          items: {$ref: '#/components/schemas/InferencePoolMember'}
      required: [display_name, automatic_failover, members]

    CreateInferencePoolRequest:
      $ref: '#/components/schemas/InferencePoolWrite'

    UpdateInferencePoolRequest:
      type: object
      additionalProperties: false
      properties:
        resource_version: {type: string, minLength: 1}
        pool: {$ref: '#/components/schemas/InferencePoolWrite'}
      required: [resource_version, pool]

    InferenceProtocol:
      type: string
      enum: [OpenAI, Anthropic]

    InferencePoolState:
      type: string
      enum: [Accepted, Ready, PartiallyDegraded, Degraded]

    InferencePoolContract:
      type: object
      additionalProperties: false
      properties:
        api: {$ref: '#/components/schemas/InferenceModelAPI'}
        capabilities: {$ref: '#/components/schemas/InferenceModelCapabilities'}
        modalities: {$ref: '#/components/schemas/InferenceModelModalities'}
        limits: {$ref: '#/components/schemas/InferenceModelLimits'}
      required: [api, capabilities, modalities, limits]

    InferencePoolWarning:
      type: object
      additionalProperties: false
      properties:
        code: {type: string, enum: [MixedProtocols]}
        message: {type: string}
      required: [code, message]

    InferencePoolMemberStatus:
      type: object
      additionalProperties: false
      properties:
        scope: {$ref: '#/components/schemas/ResourceScope'}
        provider: {$ref: '#/components/schemas/InferenceProviderName'}
        model: {type: string, minLength: 1, maxLength: 512}
        protocol: {$ref: '#/components/schemas/InferenceProtocol'}
        ready: {type: boolean}
        reason: {type: string}
        message: {type: string}
      required: [scope, provider, model, protocol, ready, reason, message]

    InferencePool:
      type: object
      additionalProperties: false
      properties:
        id: {$ref: '#/components/schemas/InferencePoolName'}
        display_name: {type: string, minLength: 1, maxLength: 128}
        resource_version: {type: string}
        automatic_failover: {type: boolean}
        members:
          type: array
          minItems: 1
          maxItems: 8
          items: {$ref: '#/components/schemas/InferencePoolMember'}
        state: {$ref: '#/components/schemas/InferencePoolState'}
        conditions:
          type: array
          items: {$ref: '#/components/schemas/InferenceProviderCondition'}
        contract: {$ref: '#/components/schemas/InferencePoolContract'}
        protocol: {$ref: '#/components/schemas/InferenceProtocol'}
        warnings:
          type: array
          items: {$ref: '#/components/schemas/InferencePoolWarning'}
        member_statuses:
          type: array
          items: {$ref: '#/components/schemas/InferencePoolMemberStatus'}
        usage_count: {type: integer, minimum: 0}
        can_modify: {type: boolean}
        can_delete: {type: boolean}
        created_at: {type: string, format: date-time}
        updated_at: {type: string, format: date-time}
      required: [id, display_name, resource_version, automatic_failover, members, state, conditions, warnings, member_statuses, usage_count, can_modify, can_delete, created_at, updated_at]

    ListInferencePoolsResponse:
      type: object
      additionalProperties: false
      properties:
        pools:
          type: array
          items: {$ref: '#/components/schemas/InferencePool'}
        next_page_token: {type: string}
      required: [pools, next_page_token]

    WatchInferencePoolsRequest:
      type: object
      additionalProperties: false
      properties:
        pool_ids:
          type: array
          maxItems: 200
          uniqueItems: true
          items: {$ref: '#/components/schemas/InferencePoolName'}

    WatchInferencePoolsEvent:
      type: object
      additionalProperties: false
      properties:
        pools:
          type: array
          items: {$ref: '#/components/schemas/InferencePool'}
      required: [pools]

    InferencePoolUsage:
      type: object
      additionalProperties: false
      properties:
        pool: {$ref: '#/components/schemas/InferencePoolName'}
        sandboxes:
          type: array
          items: {$ref: '#/components/schemas/SandboxName'}
      required: [pool, sandboxes]

    InferenceProviderCatalogEntry:
      type: object
      additionalProperties: false
      properties:
        provider_id: {type: string, minLength: 1, maxLength: 128}
        name: {type: string, minLength: 1, maxLength: 128}
        provider_kind: {$ref: '#/components/schemas/InferenceProviderKind'}
        base_url: {type: string, format: uri, maxLength: 2048}
        base_url_template: {type: string, maxLength: 2048}
        auth_header: {type: string, maxLength: 128}
        auth_prefix: {type: string, maxLength: 128}
        documentation_url: {type: string, format: uri, maxLength: 2048}
      required: [provider_id, name, provider_kind]

    InferenceProviderCatalog:
      type: object
      additionalProperties: false
      properties:
        commit: {type: string, minLength: 40, maxLength: 40}
        providers:
          type: array
          items: {$ref: '#/components/schemas/InferenceProviderCatalogEntry'}
      required: [commit, providers]

    InferenceModelSuggestion:
      allOf:
      - $ref: '#/components/schemas/InferenceModel'
      - type: object
        properties:
          catalog_provider: {type: string}
        required: [catalog_provider]

    InferenceModelSuggestionsProvenance:
      type: string
      enum: [live, cache, snapshot]

    InferenceModelSuggestions:
      type: object
      additionalProperties: false
      properties:
        provenance: {$ref: '#/components/schemas/InferenceModelSuggestionsProvenance'}
        models:
          type: array
          items: {$ref: '#/components/schemas/InferenceModelSuggestion'}
      required: [provenance, models]

    MCPConnectionRef:
      type: object
      additionalProperties: false
      properties:
        scope:
          $ref: '#/components/schemas/ResourceScope'
        tools:
          type: array
          items:
            $ref: '#/components/schemas/MCPConnectionToolRef'
          minItems: 1
        name:
          $ref: '#/components/schemas/MCPConnectionName'
      required: [scope, name, tools]

    MCPConnectionToolRef:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
        require_consent:
          type: boolean
      required: [name, require_consent]

    MCPConnectionTool:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
      required: [name]

    MCPConnectionDetail:
      type: object
      additionalProperties: false
      properties:
        can_delete:
          type: boolean
          description: Whether the current principal may delete this connection in the selected scope.
        name:
          $ref: '#/components/schemas/MCPConnectionName'
        scope:
          $ref: '#/components/schemas/ResourceScope'
        created_by:
          $ref: '#/components/schemas/ResourceActor'
        last_modified_by:
          $ref: '#/components/schemas/ResourceActor'
        endpoint:
          $ref: '#/components/schemas/MCPConnectionEndpoint'
        auth:
          $ref: '#/components/schemas/MCPConnectionAuth'
        created_at:
          type: string
          format: date-time
        status:
          $ref: '#/components/schemas/MCPConnectionLifecycle'
        reason:
          $ref: '#/components/schemas/MCPConnectionReason'
        message:
          type: string
        tool_catalog_ready:
          type: boolean
        tools:
          type: array
          items:
            $ref: '#/components/schemas/MCPConnectionTool'
      required: [name, scope, created_by, last_modified_by, endpoint, auth, created_at, status, reason, message, tool_catalog_ready, tools, can_delete]

    MCPConnectionSummary:
      type: object
      additionalProperties: false
      properties:
        can_delete:
          type: boolean
          description: Whether the current principal may delete this connection in the selected scope.
        name:
          $ref: '#/components/schemas/MCPConnectionName'
        scope:
          $ref: '#/components/schemas/ResourceScope'
        created_by:
          $ref: '#/components/schemas/ResourceActor'
        last_modified_by:
          $ref: '#/components/schemas/ResourceActor'
        auth_mode:
          type: string
        endpoint_url:
          type: string
        created_at:
          type: string
          format: date-time
        status:
          $ref: '#/components/schemas/MCPConnectionLifecycle'
        reason:
          $ref: '#/components/schemas/MCPConnectionReason'
        message:
          type: string
        tool_catalog_ready:
          type: boolean
        tool_count:
          type: integer
          format: int64
          minimum: 0
      required: [name, scope, created_by, last_modified_by, auth_mode, endpoint_url, created_at, status, reason, message, tool_catalog_ready, tool_count, can_delete]

    MCPConnectionEndpoint:
      type: object
      additionalProperties: false
      properties:
        url:
          type: string
          minLength: 1
        timeout:
          type: string
          minLength: 1
        insecure_skip_verify:
          type: boolean
        headers:
          type: object
          additionalProperties:
            type: string
      required: [url, insecure_skip_verify, headers]

    MCPConnectionAuth:
      type: object
      additionalProperties: false
      properties:
        bearer:
          $ref: '#/components/schemas/MCPConnectionBearerAuth'
        oauth:
          $ref: '#/components/schemas/MCPConnectionOAuthAuth'

    MCPConnectionBearerAuth:
      type: object
      additionalProperties: false
      properties:
        location:
          $ref: '#/components/schemas/MCPConnectionAuthLocation'

    MCPConnectionOAuthAuth:
      type: object
      additionalProperties: false
      properties:
        issuer:
          type: string
        authorization_endpoint:
          type: string
        token_endpoint:
          type: string
        registration_endpoint:
          type: string
        resource:
          type: string
        scopes:
          type: array
          items:
            type: string
            minLength: 1
        location:
          $ref: '#/components/schemas/MCPConnectionAuthLocation'

    MCPConnectionAuthLocation:
      type: object
      additionalProperties: false
      properties:
        header:
          $ref: '#/components/schemas/MCPConnectionHeaderLocation'
        query_parameter:
          $ref: '#/components/schemas/MCPConnectionQueryParameterLocation'
        cookie:
          $ref: '#/components/schemas/MCPConnectionCookieLocation'

    MCPConnectionHeaderLocation:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
        prefix:
          type: string
          minLength: 1
      required: [name]

    MCPConnectionQueryParameterLocation:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
      required: [name]

    MCPConnectionCookieLocation:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
      required: [name]

    MCPConnectionReason:
      type: string
      enum: [Ready, ProbePending, Unreachable, InvalidCredentials, ProtocolError, InternalError]

    MCPConnectionLifecycle:
      type: string
      enum: [Accepted, Ready, Error]

    ListMCPConnectionsResponse:
      type: object
      additionalProperties: false
      properties:
        mcp_connections:
          type: array
          items:
            $ref: '#/components/schemas/MCPConnectionSummary'
        next_page_token:
          type: string
      required: [mcp_connections, next_page_token]
    WatchMCPConnectionsRequest:
      type: object
      additionalProperties: false
      properties:
        connections:
          type: array
          items:
            $ref: '#/components/schemas/ResourceReference'
    WatchMCPConnectionsEvent:
      type: object
      additionalProperties: false
      properties:
        mcp_connections:
          type: array
          items:
            $ref: '#/components/schemas/MCPConnectionSummary'
      required: [mcp_connections]

    CreateMCPConnectionRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/MCPConnectionName'
        endpoint:
          $ref: '#/components/schemas/MCPConnectionEndpoint'
        auth:
          $ref: '#/components/schemas/MCPConnectionAuth'
        credentials:
          $ref: '#/components/schemas/MCPConnectionCredentials'
      required: [name, endpoint, auth, credentials]

    MCPConnectionCredentials:
      type: object
      additionalProperties: false
      properties:
        bearer:
          $ref: '#/components/schemas/MCPConnectionBearerCredentials'
        oauth:
          $ref: '#/components/schemas/MCPConnectionOAuthCredentials'

    MCPConnectionBearerCredentials:
      type: object
      additionalProperties: false
      properties:
        token:
          type: string
          minLength: 1
      required: [token]

    MCPConnectionOAuthCredentials:
      type: object
      additionalProperties: false
      properties:
        client_id:
          type: string
        client_secret:
          type: string
        refresh_token:
          type: string
        access_token:
          type: string
        expires_at:
          type: string
          format: date-time
        token_type:
          type: string
        scopes:
          type: array
          items:
            type: string
            minLength: 1
        registration:
          $ref: '#/components/schemas/JSONObject'
        revocation:
          $ref: '#/components/schemas/JSONObject'