openapi: 3.0.0
info:
  title: AI Security Gateway API
  version: 0.1.0
  description: |-
    The management API behind the SecureAuth Agent Authority console.

    Agent Authority governs how AI agents access your tools and services: it
    authenticates every agent and any user it acts for, authorizes each action
    against your policies, and audits every call, from one gateway endpoint. This
    API configures resources, policies, agents, and access, and reads the audit,
    analytics, and anomaly data the console displays.
tags:
  - name: Webhooks
    description: Delivery of audit events to systems outside the gateway, such as a SIEM or an internal service, the moment they happen. Each webhook subscribes to a set of event types.
  - name: Topology
    description: A graph of how agents, resources, and policies connect, showing which agents can reach which tools and why.
  - name: Features
    description: Per-organization feature flags that turn optional gateway capabilities on or off.
  - name: Telemetry
    description: 'Ingest keys for the OpenTelemetry data coding agents emit about their model usage: tokens, cost, sessions, and requests. This data powers the LLM usage analytics.'
  - name: Auth
    description: The current caller's identity and the permissions it grants in the workspace.
  - name: Groups
    description: Collections of users, used to scope a policy rule or access to a set of people at once.
  - name: Users
    description: The people in your organization who sign in to the workspace and whom agents act on behalf of.
  - name: Tags
    description: Named, colored labels attached to agents, resources, and tools, so a policy rule can match a class of entities instead of naming each one.
  - name: Anomaly
    description: "A triage queue of statistically unusual agent and user activity, scored against each subject's own history and its org peers: spend spikes, unusual tool volume, new tools or models, and off-hours activity."
  - name: Analytics
    description: Aggregated tool usage, LLM token spend, and policy-enforcement trends over time, for spotting cost and behavior patterns across agents, users, and resources.
  - name: AuditEvents
    description: 'The record of every action taken through the gateway: each tool call, allowed or denied, and every configuration change, with the reasoning behind each decision.'
  - name: UserConnections
    description: The links between a user's personal account and a third-party service. Each user authenticates separately, so every upstream call carries that user's own credentials.
  - name: DataProtection
    description: Response filters that rewrite the text of a tool's response, masking sensitive data such as SSNs or API keys, after a policy has already allowed the call. Every matching filter applies, not just the first.
  - name: Policies
    description: The rules that decide which tools an agent can call, for which users, under what conditions. Rules are evaluated top to bottom and the first match wins; a request that matches no rule is denied. Includes CEL condition validation and what-if evaluation.
  - name: Agents
    description: The AI coding tools and assistants connected to the gateway, and the individual agent instances registered to the users who authorized them. A policy scoped to an agent applies to every instance; one scoped to an instance applies to that connection alone.
  - name: MCPs
    x-displayName: MCPs
    description: The MCP servers (resources) that expose tools to your agents through the gateway. Add them from the built-in catalog or connect any custom MCP server.
paths:
  /agent-instances:
    get:
      operationId: Agents_list
      summary: List agents
      description: List all agent instances in the organization.
      parameters:
        - $ref: '#/components/parameters/PaginationQuery.offset'
        - $ref: '#/components/parameters/PaginationQuery.limit'
        - $ref: '#/components/parameters/SearchQuery'
        - name: agent_slug
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
        - name: user_id
          in: query
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: sort_by
          in: query
          required: false
          schema:
            allOf:
              - $ref: '#/components/schemas/AgentInstanceSortBy'
            default: created_at
          explode: false
        - name: sort_order
          in: query
          required: false
          schema:
            allOf:
              - $ref: '#/components/schemas/SortOrder'
            default: desc
          explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentInstanceList'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Agents
    post:
      operationId: Agents_create
      summary: Create agent
      description: Create a new agent instance. Returns the instance with a plain API token.
      parameters: []
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentInstanceCreated'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Agents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentInstance'
  /agent-instances/{agent_instance_id}:
    get:
      operationId: Agents_read
      summary: Get agent
      description: Get an agent instance by ID.
      parameters:
        - name: agent_instance_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentInstance'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Agents
    patch:
      operationId: Agents_update
      summary: Update agent
      description: Update an existing agent instance.
      parameters:
        - name: agent_instance_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentInstance'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Agents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentInstanceUpdate'
    delete:
      operationId: Agents_remove
      summary: Delete agent
      description: Delete an agent instance.
      parameters:
        - name: agent_instance_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Agents
  /agent-instances/{agent_instance_id}/revoke:
    post:
      operationId: Agents_revoke
      summary: Revoke agent tokens
      description: Revoke all access tokens issued before now for this agent instance.
      parameters:
        - name: agent_instance_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentInstance'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Agents
  /agents/catalog:
    get:
      operationId: Agents_catalog
      summary: List agent catalog
      description: List available agents from the platform catalog.
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentCatalogList'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Agents
  /agents/instance-counts:
    get:
      operationId: Agents_instanceCounts
      summary: Count agent instances
      description: Count registered agent instances grouped by agent_slug. Only slugs with at least one instance are returned.
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentInstanceCountList'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Agents
  /analytics/active-agent-instances:
    get:
      operationId: Analytics_activeAgentInstances
      summary: Count active agent instances
      description: Count of distinct agent instances with activity in the given time range.
      parameters:
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: agent_slug
          in: query
          required: false
          description: Filter to agents by slug, the agent type such as `claude-code`.
          schema:
            type: array
            items:
              type: string
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
        - name: agent_tag_id
          in: query
          required: false
          description: Filter to agent instances carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: resource_tag_id
          in: query
          required: false
          description: Filter to MCP servers carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveAgentInstancesResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/active-users:
    get:
      operationId: Analytics_activeUsers
      summary: Count active users
      description: Count of distinct users with activity in the given time range.
      parameters:
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: agent_slug
          in: query
          required: false
          description: Filter to agents by slug, the agent type such as `claude-code`.
          schema:
            type: array
            items:
              type: string
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
        - name: agent_tag_id
          in: query
          required: false
          description: Filter to agent instances carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: resource_tag_id
          in: query
          required: false
          description: Filter to MCP servers carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveUsersResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/blocked-agent-instances-count:
    get:
      operationId: Analytics_blockedAgentInstancesCount
      summary: Count blocked agent instances
      description: Count of distinct agent instances with blocked tool calls.
      parameters:
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: agent_slug
          in: query
          required: false
          description: Filter to agents by slug, the agent type such as `claude-code`.
          schema:
            type: array
            items:
              type: string
        - name: mcp_id
          in: query
          required: false
          description: Filter to specific MCP servers by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: tool_name
          in: query
          required: false
          description: Filter to specific tool names.
          schema:
            type: array
            items:
              type: string
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
        - name: agent_tag_id
          in: query
          required: false
          description: Filter to agent instances carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: resource_tag_id
          in: query
          required: false
          description: Filter to MCP servers carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockedAgentInstancesCountResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/blocked-tools-count:
    get:
      operationId: Analytics_blockedToolsCount
      summary: Count blocked tools
      description: Total count of blocked tool calls in a time range.
      parameters:
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: agent_instance_id
          in: query
          required: false
          description: Filter to specific agent instances by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: agent_slug
          in: query
          required: false
          description: Filter to agents by slug, the agent type such as `claude-code`.
          schema:
            type: array
            items:
              type: string
        - name: mcp_id
          in: query
          required: false
          description: Filter to specific MCP servers by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
        - name: agent_tag_id
          in: query
          required: false
          description: Filter to agent instances carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: resource_tag_id
          in: query
          required: false
          description: Filter to MCP servers carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockedToolsCountResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/blocked-tools-over-time:
    get:
      operationId: Analytics_blockedToolsOverTime
      summary: Blocked tool time series
      description: Blocked tool calls over time.
      parameters:
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: interval
          in: query
          required: false
          description: 'Time bucket size for the series: `hour` or `day`.'
          schema:
            $ref: '#/components/schemas/AnalyticsInterval'
          explode: false
        - name: agent_instance_id
          in: query
          required: false
          description: Filter to specific agent instances by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: agent_slug
          in: query
          required: false
          description: Filter to agents by slug, the agent type such as `claude-code`.
          schema:
            type: array
            items:
              type: string
        - name: mcp_id
          in: query
          required: false
          description: Filter to specific MCP servers by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: tool_name
          in: query
          required: false
          description: Filter to specific tool names.
          schema:
            type: array
            items:
              type: string
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
        - name: agent_tag_id
          in: query
          required: false
          description: Filter to agent instances carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: resource_tag_id
          in: query
          required: false
          description: Filter to MCP servers carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeSeriesResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/blocked-unique-tools:
    get:
      operationId: Analytics_blockedUniqueTools
      summary: Count blocked unique tools
      description: Count of distinct tools blocked by policy in a time range.
      parameters:
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: agent_instance_id
          in: query
          required: false
          description: Filter to specific agent instances by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: agent_slug
          in: query
          required: false
          description: Filter to agents by slug, the agent type such as `claude-code`.
          schema:
            type: array
            items:
              type: string
        - name: mcp_id
          in: query
          required: false
          description: Filter to specific MCP servers by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
        - name: agent_tag_id
          in: query
          required: false
          description: Filter to agent instances carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: resource_tag_id
          in: query
          required: false
          description: Filter to MCP servers carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockedUniqueToolsResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/blocked-users-count:
    get:
      operationId: Analytics_blockedUsersCount
      summary: Count blocked users
      description: Count of distinct users with blocked tool calls.
      parameters:
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: agent_instance_id
          in: query
          required: false
          description: Filter to specific agent instances by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: agent_slug
          in: query
          required: false
          description: Filter to agents by slug, the agent type such as `claude-code`.
          schema:
            type: array
            items:
              type: string
        - name: mcp_id
          in: query
          required: false
          description: Filter to specific MCP servers by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: tool_name
          in: query
          required: false
          description: Filter to specific tool names.
          schema:
            type: array
            items:
              type: string
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
        - name: agent_tag_id
          in: query
          required: false
          description: Filter to agent instances carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: resource_tag_id
          in: query
          required: false
          description: Filter to MCP servers carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockedUsersCountResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/event-breakdown:
    get:
      operationId: Analytics_eventBreakdown
      summary: Event breakdown by action
      description: Audit event breakdown by action type.
      parameters:
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: agent_instance_id
          in: query
          required: false
          description: Filter to specific agent instances by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: agent_slug
          in: query
          required: false
          description: Filter to agents by slug, the agent type such as `claude-code`.
          schema:
            type: array
            items:
              type: string
        - name: mcp_id
          in: query
          required: false
          description: Filter to specific MCP servers by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
        - name: agent_tag_id
          in: query
          required: false
          description: Filter to agent instances carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: resource_tag_id
          in: query
          required: false
          description: Filter to MCP servers carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventBreakdownResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/hourly-distribution:
    get:
      operationId: Analytics_hourlyDistribution
      summary: Hourly tool distribution
      description: Tool execution counts grouped by hour of day (0-23 UTC).
      parameters:
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: agent_instance_id
          in: query
          required: false
          description: Filter to specific agent instances by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: agent_slug
          in: query
          required: false
          description: Filter to agents by slug, the agent type such as `claude-code`.
          schema:
            type: array
            items:
              type: string
        - name: mcp_id
          in: query
          required: false
          description: Filter to specific MCP servers by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: tool_name
          in: query
          required: false
          description: Filter to specific tool names.
          schema:
            type: array
            items:
              type: string
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
        - name: agent_tag_id
          in: query
          required: false
          description: Filter to agent instances carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: resource_tag_id
          in: query
          required: false
          description: Filter to MCP servers carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HourlyDistributionResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/llm-cost-over-time:
    get:
      operationId: Analytics_llmCostOverTime
      summary: LLM cost time series
      description: LLM cost over time (USD).
      parameters:
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: interval
          in: query
          required: false
          description: 'Time bucket size for the series: `hour` or `day`.'
          schema:
            $ref: '#/components/schemas/AnalyticsInterval'
          explode: false
        - name: provider
          in: query
          required: false
          description: Filter to specific LLM telemetry providers.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/LLMProvider'
        - name: model
          in: query
          required: false
          description: Filter to specific model names.
          schema:
            type: array
            items:
              type: string
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LLMCostSeriesResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/llm-cost-total:
    get:
      operationId: Analytics_llmCostTotal
      summary: Total LLM cost
      description: Total LLM cost (USD).
      parameters:
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: provider
          in: query
          required: false
          description: Filter to specific LLM telemetry providers.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/LLMProvider'
        - name: model
          in: query
          required: false
          description: Filter to specific model names.
          schema:
            type: array
            items:
              type: string
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LLMCostTotalResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/llm-facets:
    get:
      operationId: Analytics_llmFacets
      summary: List LLM facets
      description: Distinct models for filter dropdowns.
      parameters:
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: provider
          in: query
          required: false
          description: Filter to specific LLM telemetry providers.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/LLMProvider'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LLMFacetsResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/llm-models-count:
    get:
      operationId: Analytics_llmModelsCount
      summary: Count LLM models
      description: Count of distinct models with usage in a time range.
      parameters:
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: provider
          in: query
          required: false
          description: Filter to specific LLM telemetry providers.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/LLMProvider'
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LLMModelsCountResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/llm-session-activity:
    get:
      operationId: Analytics_llmSessionActivity
      summary: LLM session activity
      description: Time-bucketed token/cost activity and per-model rollup for one session.
      parameters:
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: session_key
          in: query
          required: true
          description: The session to report on, identified by its provider session key.
          schema:
            type: string
          explode: false
        - name: provider
          in: query
          required: true
          description: Telemetry provider of the session.
          schema:
            $ref: '#/components/schemas/LLMProvider'
          explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LLMSessionActivityResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/llm-session-rank:
    get:
      operationId: Analytics_llmSessionRank
      summary: LLM session rank
      description: Percentile ranks of one session (by key + provider) against all org sessions.
      parameters:
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: session_key
          in: query
          required: true
          description: The session to report on, identified by its provider session key.
          schema:
            type: string
          explode: false
        - name: provider
          in: query
          required: true
          description: Telemetry provider of the session.
          schema:
            $ref: '#/components/schemas/LLMProvider'
          explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LLMSessionRankResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/llm-session-stats:
    get:
      operationId: Analytics_llmSessionStats
      summary: LLM session stats
      description: Count, average, percentile bands and (optionally) the selected session's percentile ranks across sessions.
      parameters:
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: provider
          in: query
          required: false
          description: Filter to specific LLM telemetry providers.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/LLMProvider'
        - name: model
          in: query
          required: false
          description: Filter to specific model names.
          schema:
            type: array
            items:
              type: string
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LLMSessionStatsResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/llm-session-timeline:
    get:
      operationId: Analytics_llmSessionTimeline
      summary: LLM session timeline
      description: Paginated per-request timeline for one session, ordered by time.
      parameters:
        - $ref: '#/components/parameters/PaginationQuery.offset'
        - $ref: '#/components/parameters/PaginationQuery.limit'
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: session_key
          in: query
          required: true
          description: The session to report on, identified by its provider session key.
          schema:
            type: string
          explode: false
        - name: provider
          in: query
          required: true
          description: Telemetry provider of the session.
          schema:
            $ref: '#/components/schemas/LLMProvider'
          explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LLMSessionTimelineResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/llm-sessions:
    get:
      operationId: Analytics_llmSessions
      summary: List LLM sessions
      description: Sessions ranked by cost or tokens, with per-session usage.
      parameters:
        - $ref: '#/components/parameters/PaginationQuery.offset'
        - $ref: '#/components/parameters/PaginationQuery.limit'
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: sort
          in: query
          required: false
          description: 'Ordering for the session list: by `cost`, `tokens`, or `recent` activity.'
          schema:
            $ref: '#/components/schemas/LLMSessionSort'
          explode: false
        - name: provider
          in: query
          required: false
          description: Filter to specific LLM telemetry providers.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/LLMProvider'
        - name: model
          in: query
          required: false
          description: Filter to specific model names.
          schema:
            type: array
            items:
              type: string
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
        - name: session_key
          in: query
          required: false
          description: Restrict to a single session (for deep links).
          schema:
            type: string
          explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LLMSessionResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/llm-tokens-over-time:
    get:
      operationId: Analytics_llmTokensOverTime
      summary: LLM token time series
      description: LLM token usage over time.
      parameters:
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: interval
          in: query
          required: false
          description: 'Time bucket size for the series: `hour` or `day`.'
          schema:
            $ref: '#/components/schemas/AnalyticsInterval'
          explode: false
        - name: provider
          in: query
          required: false
          description: Filter to specific LLM telemetry providers.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/LLMProvider'
        - name: model
          in: query
          required: false
          description: Filter to specific model names.
          schema:
            type: array
            items:
              type: string
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeSeriesResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/llm-tokens-total:
    get:
      operationId: Analytics_llmTokensTotal
      summary: Total LLM tokens
      description: Total LLM tokens used, with per-type breakdown.
      parameters:
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: provider
          in: query
          required: false
          description: Filter to specific LLM telemetry providers.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/LLMProvider'
        - name: model
          in: query
          required: false
          description: Filter to specific model names.
          schema:
            type: array
            items:
              type: string
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LLMTokensTotalResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/llm-top-models-by-cost:
    get:
      operationId: Analytics_llmTopModelsByCost
      summary: Top models by cost
      description: Top models by cost (USD).
      parameters:
        - $ref: '#/components/parameters/PaginationQuery.offset'
        - $ref: '#/components/parameters/PaginationQuery.limit'
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: provider
          in: query
          required: false
          description: Filter to specific LLM telemetry providers.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/LLMProvider'
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LLMCostRankResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/llm-top-models-by-tokens:
    get:
      operationId: Analytics_llmTopModelsByTokens
      summary: Top models by tokens
      description: Top models by token usage.
      parameters:
        - $ref: '#/components/parameters/PaginationQuery.offset'
        - $ref: '#/components/parameters/PaginationQuery.limit'
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: provider
          in: query
          required: false
          description: Filter to specific LLM telemetry providers.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/LLMProvider'
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LLMTokenRankResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/llm-top-users-by-cost:
    get:
      operationId: Analytics_llmTopUsersByCost
      summary: Top users by cost
      description: Top users by cost (USD).
      parameters:
        - $ref: '#/components/parameters/PaginationQuery.offset'
        - $ref: '#/components/parameters/PaginationQuery.limit'
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: provider
          in: query
          required: false
          description: Filter to specific LLM telemetry providers.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/LLMProvider'
        - name: model
          in: query
          required: false
          description: Filter to specific model names.
          schema:
            type: array
            items:
              type: string
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LLMUserCostResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/llm-top-users-by-tokens:
    get:
      operationId: Analytics_llmTopUsersByTokens
      summary: Top users by tokens
      description: Top users by token usage.
      parameters:
        - $ref: '#/components/parameters/PaginationQuery.offset'
        - $ref: '#/components/parameters/PaginationQuery.limit'
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: provider
          in: query
          required: false
          description: Filter to specific LLM telemetry providers.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/LLMProvider'
        - name: model
          in: query
          required: false
          description: Filter to specific model names.
          schema:
            type: array
            items:
              type: string
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LLMUserTokenResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/tool-executions-over-time:
    get:
      operationId: Analytics_toolExecutionsOverTime
      summary: Tool execution time series
      description: Tool executions over time.
      parameters:
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: interval
          in: query
          required: false
          description: 'Time bucket size for the series: `hour` or `day`.'
          schema:
            $ref: '#/components/schemas/AnalyticsInterval'
          explode: false
        - name: agent_instance_id
          in: query
          required: false
          description: Filter to specific agent instances by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: agent_slug
          in: query
          required: false
          description: Filter to agents by slug, the agent type such as `claude-code`.
          schema:
            type: array
            items:
              type: string
        - name: mcp_id
          in: query
          required: false
          description: Filter to specific MCP servers by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: tool_name
          in: query
          required: false
          description: Filter to specific tool names.
          schema:
            type: array
            items:
              type: string
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
        - name: agent_tag_id
          in: query
          required: false
          description: Filter to agent instances carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: resource_tag_id
          in: query
          required: false
          description: Filter to MCP servers carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeSeriesResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/top-agent-instances:
    get:
      operationId: Analytics_topAgentInstances
      summary: List top agent instances
      description: Top agent instances by activity.
      parameters:
        - $ref: '#/components/parameters/PaginationQuery.offset'
        - $ref: '#/components/parameters/PaginationQuery.limit'
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: agent_slug
          in: query
          required: false
          description: Filter to agents by slug, the agent type such as `claude-code`.
          schema:
            type: array
            items:
              type: string
        - name: mcp_id
          in: query
          required: false
          description: Filter to specific MCP servers by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: tool_name
          in: query
          required: false
          description: Filter to specific tool names.
          schema:
            type: array
            items:
              type: string
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
        - name: agent_tag_id
          in: query
          required: false
          description: Filter to agent instances carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: resource_tag_id
          in: query
          required: false
          description: Filter to MCP servers carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopAgentInstancesResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/top-blocked-agent-instances:
    get:
      operationId: Analytics_topBlockedAgentInstances
      summary: List top blocked agent instances
      description: Top agent instances triggering blocked tool calls.
      parameters:
        - $ref: '#/components/parameters/PaginationQuery.offset'
        - $ref: '#/components/parameters/PaginationQuery.limit'
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: agent_slug
          in: query
          required: false
          description: Filter to agents by slug, the agent type such as `claude-code`.
          schema:
            type: array
            items:
              type: string
        - name: mcp_id
          in: query
          required: false
          description: Filter to specific MCP servers by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: tool_name
          in: query
          required: false
          description: Filter to specific tool names.
          schema:
            type: array
            items:
              type: string
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
        - name: agent_tag_id
          in: query
          required: false
          description: Filter to agent instances carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: resource_tag_id
          in: query
          required: false
          description: Filter to MCP servers carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopAgentInstancesResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/top-blocked-mcps:
    get:
      operationId: Analytics_topBlockedMcps
      summary: List top blocked MCPs
      description: Top MCPs with blocked tool calls.
      parameters:
        - $ref: '#/components/parameters/PaginationQuery.offset'
        - $ref: '#/components/parameters/PaginationQuery.limit'
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: agent_instance_id
          in: query
          required: false
          description: Filter to specific agent instances by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: agent_slug
          in: query
          required: false
          description: Filter to agents by slug, the agent type such as `claude-code`.
          schema:
            type: array
            items:
              type: string
        - name: tool_name
          in: query
          required: false
          description: Filter to specific tool names.
          schema:
            type: array
            items:
              type: string
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
        - name: agent_tag_id
          in: query
          required: false
          description: Filter to agent instances carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: resource_tag_id
          in: query
          required: false
          description: Filter to MCP servers carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopMcpsResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/top-blocked-tools:
    get:
      operationId: Analytics_topBlockedTools
      summary: List top blocked tools
      description: Top blocked tools by count.
      parameters:
        - $ref: '#/components/parameters/PaginationQuery.offset'
        - $ref: '#/components/parameters/PaginationQuery.limit'
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: agent_instance_id
          in: query
          required: false
          description: Filter to specific agent instances by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: agent_slug
          in: query
          required: false
          description: Filter to agents by slug, the agent type such as `claude-code`.
          schema:
            type: array
            items:
              type: string
        - name: mcp_id
          in: query
          required: false
          description: Filter to specific MCP servers by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
        - name: agent_tag_id
          in: query
          required: false
          description: Filter to agent instances carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: resource_tag_id
          in: query
          required: false
          description: Filter to MCP servers carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopToolsResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/top-blocked-users:
    get:
      operationId: Analytics_topBlockedUsers
      summary: List top blocked users
      description: Top users triggering blocked tool calls.
      parameters:
        - $ref: '#/components/parameters/PaginationQuery.offset'
        - $ref: '#/components/parameters/PaginationQuery.limit'
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: agent_instance_id
          in: query
          required: false
          description: Filter to specific agent instances by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: agent_slug
          in: query
          required: false
          description: Filter to agents by slug, the agent type such as `claude-code`.
          schema:
            type: array
            items:
              type: string
        - name: mcp_id
          in: query
          required: false
          description: Filter to specific MCP servers by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: tool_name
          in: query
          required: false
          description: Filter to specific tool names.
          schema:
            type: array
            items:
              type: string
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
        - name: agent_tag_id
          in: query
          required: false
          description: Filter to agent instances carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: resource_tag_id
          in: query
          required: false
          description: Filter to MCP servers carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopUsersResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/top-blocking-policies:
    get:
      operationId: Analytics_topBlockingPolicies
      summary: List top blocking policies
      description: Top policies by block count.
      parameters:
        - $ref: '#/components/parameters/PaginationQuery.offset'
        - $ref: '#/components/parameters/PaginationQuery.limit'
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: agent_instance_id
          in: query
          required: false
          description: Filter to specific agent instances by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: agent_slug
          in: query
          required: false
          description: Filter to agents by slug, the agent type such as `claude-code`.
          schema:
            type: array
            items:
              type: string
        - name: mcp_id
          in: query
          required: false
          description: Filter to specific MCP servers by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
        - name: agent_tag_id
          in: query
          required: false
          description: Filter to agent instances carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: resource_tag_id
          in: query
          required: false
          description: Filter to MCP servers carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopPoliciesResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/top-mcps:
    get:
      operationId: Analytics_topMcps
      summary: List top MCPs
      description: Top MCPs by tool execution count.
      parameters:
        - $ref: '#/components/parameters/PaginationQuery.offset'
        - $ref: '#/components/parameters/PaginationQuery.limit'
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: agent_instance_id
          in: query
          required: false
          description: Filter to specific agent instances by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: agent_slug
          in: query
          required: false
          description: Filter to agents by slug, the agent type such as `claude-code`.
          schema:
            type: array
            items:
              type: string
        - name: tool_name
          in: query
          required: false
          description: Filter to specific tool names.
          schema:
            type: array
            items:
              type: string
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
        - name: agent_tag_id
          in: query
          required: false
          description: Filter to agent instances carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: resource_tag_id
          in: query
          required: false
          description: Filter to MCP servers carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopMcpsResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/top-tools:
    get:
      operationId: Analytics_topTools
      summary: List top tools
      description: Top tools by execution count.
      parameters:
        - $ref: '#/components/parameters/PaginationQuery.offset'
        - $ref: '#/components/parameters/PaginationQuery.limit'
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: agent_instance_id
          in: query
          required: false
          description: Filter to specific agent instances by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: agent_slug
          in: query
          required: false
          description: Filter to agents by slug, the agent type such as `claude-code`.
          schema:
            type: array
            items:
              type: string
        - name: mcp_id
          in: query
          required: false
          description: Filter to specific MCP servers by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
        - name: agent_tag_id
          in: query
          required: false
          description: Filter to agent instances carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: resource_tag_id
          in: query
          required: false
          description: Filter to MCP servers carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopToolsResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/top-users:
    get:
      operationId: Analytics_topUsers
      summary: List top users
      description: Top users by activity.
      parameters:
        - $ref: '#/components/parameters/PaginationQuery.offset'
        - $ref: '#/components/parameters/PaginationQuery.limit'
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: agent_instance_id
          in: query
          required: false
          description: Filter to specific agent instances by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: agent_slug
          in: query
          required: false
          description: Filter to agents by slug, the agent type such as `claude-code`.
          schema:
            type: array
            items:
              type: string
        - name: mcp_id
          in: query
          required: false
          description: Filter to specific MCP servers by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: tool_name
          in: query
          required: false
          description: Filter to specific tool names.
          schema:
            type: array
            items:
              type: string
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
        - name: agent_tag_id
          in: query
          required: false
          description: Filter to agent instances carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: resource_tag_id
          in: query
          required: false
          description: Filter to MCP servers carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopUsersResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /analytics/unique-tools:
    get:
      operationId: Analytics_uniqueTools
      summary: Count unique tools
      description: Count of distinct tools executed in the given time range.
      parameters:
        - name: start_time
          in: query
          required: true
          description: Start of the time range to report on, inclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          description: End of the time range to report on, exclusive.
          schema:
            type: string
            format: date-time
          explode: false
        - name: agent_instance_id
          in: query
          required: false
          description: Filter to specific agent instances by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: agent_slug
          in: query
          required: false
          description: Filter to agents by slug, the agent type such as `claude-code`.
          schema:
            type: array
            items:
              type: string
        - name: mcp_id
          in: query
          required: false
          description: Filter to specific MCP servers by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_id
          in: query
          required: false
          description: Filter to specific users by id.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          description: Filter to users in specific groups.
          schema:
            type: array
            items:
              type: string
        - name: agent_tag_id
          in: query
          required: false
          description: Filter to agent instances carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: resource_tag_id
          in: query
          required: false
          description: Filter to MCP servers carrying specific tags.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UniqueToolsResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Analytics
  /anomaly/findings:
    get:
      operationId: Anomaly_findings
      summary: List findings
      description: List findings (SOC triage queue); start_time/end_time bound the finding's last active bucket (last_bucket).
      parameters:
        - $ref: '#/components/parameters/PaginationQuery.offset'
        - $ref: '#/components/parameters/PaginationQuery.limit'
        - name: status
          in: query
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/AnomalyFindingStatus'
        - name: severity
          in: query
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/AnomalySeverity'
        - name: detector
          in: query
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/AnomalyDetector'
        - name: subject_type
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/AnomalySubjectType'
          explode: false
        - name: subject_id
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
        - name: metric
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
        - name: start_time
          in: query
          required: false
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: false
          schema:
            type: string
            format: date-time
          explode: false
        - name: sort
          in: query
          required: false
          schema:
            allOf:
              - $ref: '#/components/schemas/AnomalyFindingSort'
            default: recent
          explode: false
        - name: sort_order
          in: query
          required: false
          schema:
            allOf:
              - $ref: '#/components/schemas/SortOrder'
            default: desc
          explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnomalyFindingList'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Anomaly
  /anomaly/findings-over-time:
    get:
      operationId: Anomaly_findingsOverTime
      summary: Get findings over time
      description: Findings per bucket grouped by severity, counted by the finding's last active bucket (last_bucket).
      parameters:
        - name: start_time
          in: query
          required: true
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          schema:
            type: string
            format: date-time
          explode: false
        - name: interval
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/AnalyticsInterval'
          explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnomalyOverTimeResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Anomaly
  /anomaly/findings/summary:
    get:
      operationId: Anomaly_findingsSummary
      summary: Get findings summary
      description: Status × severity counts for the header cards.
      parameters:
        - name: start_time
          in: query
          required: true
          schema:
            type: string
            format: date-time
          explode: false
        - name: end_time
          in: query
          required: true
          schema:
            type: string
            format: date-time
          explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnomalySummaryResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Anomaly
  /anomaly/findings/{id}:
    patch:
      operationId: Anomaly_findingUpdate
      summary: Triage finding
      description: Triage a finding (acknowledge / dismiss / reopen).
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnomalyFinding'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Anomaly
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnomalyFindingStatusUpdate'
    get:
      operationId: Anomaly_findingGet
      summary: Get finding
      description: Fetch one finding.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnomalyFinding'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Anomaly
  /anomaly/findings/{id}/series:
    get:
      operationId: Anomaly_findingSeries
      summary: Get finding series
      description: The subject's metric series around the finding's flagged bucket (evidence chart).
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnomalyFindingSeries'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Anomaly
  /audit-events:
    get:
      operationId: AuditEvents_list
      summary: List audit events
      description: List audit events for the organization.
      parameters:
        - name: action
          in: query
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/AuditEventAction'
        - name: mcp_id
          in: query
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: agent_instance_id
          in: query
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: agent_slug
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
        - name: user_id
          in: query
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: user_group
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
        - name: agent_tag_id
          in: query
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: resource_tag_id
          in: query
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/uuid'
        - name: connection_id
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/uuid'
          explode: false
        - name: policy_id
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/uuid'
          explode: false
        - name: cursor
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/uuid'
          explode: false
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 20
          explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditEventList'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - AuditEvents
  /auth/permissions:
    get:
      operationId: Auth_permissions
      summary: Get permissions
      description: Get the current user's effective permissions.
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Permissions'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Auth
  /dlp/judge/preview:
    post:
      operationId: Dlp_judgePreview
      description: Run the LLM judge once against a sample response (rule-editor sandbox).
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DlpJudgePreviewResult'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - DataProtection
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DlpJudgePreviewRequest'
  /dlp/rules:
    get:
      operationId: Dlp_list
      summary: List DLP rules
      description: List DLP rules. Optionally filtered by status.
      parameters:
        - name: status
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/DlpRuleStatus'
          explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DlpRuleList'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - DataProtection
    post:
      operationId: Dlp_create
      summary: Create DLP rule
      description: Create a DLP rule.
      parameters: []
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DlpRule'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - DataProtection
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DlpRule'
  /dlp/rules/{rule_id}:
    get:
      operationId: Dlp_read
      summary: Get DLP rule
      description: Get a DLP rule by ID.
      parameters:
        - name: rule_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DlpRule'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - DataProtection
    patch:
      operationId: Dlp_update
      summary: Update DLP rule
      description: Update an existing DLP rule.
      parameters:
        - name: rule_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DlpRule'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - DataProtection
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DlpRuleUpdate'
    delete:
      operationId: Dlp_remove
      summary: Delete DLP rule
      description: Delete a DLP rule.
      parameters:
        - name: rule_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - DataProtection
  /features:
    get:
      operationId: Features_read
      summary: Get feature flags
      description: Feature flags enabled for the current organization.
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureFlags'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Features
  /groups:
    get:
      operationId: Groups_list
      summary: List groups
      description: List groups in the organization.
      parameters:
        - $ref: '#/components/parameters/PaginationQuery.offset'
        - $ref: '#/components/parameters/PaginationQuery.limit'
        - $ref: '#/components/parameters/SearchQuery'
        - name: sort_by
          in: query
          required: false
          schema:
            allOf:
              - $ref: '#/components/schemas/GroupSortBy'
            default: created_at
          explode: false
        - name: sort_order
          in: query
          required: false
          schema:
            allOf:
              - $ref: '#/components/schemas/SortOrder'
            default: desc
          explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupList'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Groups
  /ingest-keys:
    get:
      operationId: IngestKeys_list
      summary: List ingest keys
      description: List ingest keys for the organization.
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestKeyList'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Telemetry
    post:
      operationId: IngestKeys_create
      summary: Create an ingest key
      description: Create an ingest key. Returns the full token once.
      parameters: []
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestKeyCreated'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Telemetry
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIngestKeyRequest'
  /ingest-keys/{key_id}:
    delete:
      operationId: IngestKeys_revoke
      summary: Revoke an ingest key
      description: Revoke an ingest key.
      parameters:
        - name: key_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Telemetry
  /mcps:
    get:
      operationId: Mcps_list
      summary: List MCPs
      description: List all MCPs in the organization.
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpList'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - MCPs
    post:
      operationId: Mcps_create
      summary: Create MCP
      description: Create an MCP. Set origin to "catalog" with a catalog_slug, or "custom" with full config.
      parameters: []
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mcp'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - MCPs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpCreate'
  /mcps/catalog:
    get:
      operationId: McpCatalog_list
      summary: List MCP catalog
      description: List available integrations from the platform catalog.
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpCatalogList'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - MCPs
  /mcps/{mcp_id}:
    get:
      operationId: Mcps_read
      summary: Get MCP
      description: Get an MCP by ID.
      parameters:
        - name: mcp_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mcp'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - MCPs
    patch:
      operationId: Mcps_update
      summary: Update MCP
      description: Update an existing MCP.
      parameters:
        - name: mcp_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mcp'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - MCPs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpUpdate'
    delete:
      operationId: Mcps_remove
      summary: Delete MCP
      description: Delete an MCP.
      parameters:
        - name: mcp_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - MCPs
  /policies:
    get:
      operationId: Policies_list
      summary: List policies
      description: List policies, ordered by priority. Optionally filtered by MCP, agent, agent instance, or status.
      parameters:
        - name: mcp_id
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/uuid'
          explode: false
        - name: agent_slug
          in: query
          required: false
          schema:
            type: string
          explode: false
        - name: agent_instance_id
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/uuid'
          explode: false
        - name: user_id
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/uuid'
          explode: false
        - name: group
          in: query
          required: false
          schema:
            type: string
          explode: false
        - name: status
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/PolicyStatus'
          explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyList'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Policies
    post:
      operationId: Policies_create
      summary: Create policy
      description: Create a policy.
      parameters: []
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Policies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Policy'
  /policies/cel/evaluate:
    post:
      operationId: Policies_celEvaluate
      summary: Evaluate CEL expression
      description: Evaluate a CEL expression against a sample context.
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CelEvaluateResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Policies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CelEvaluateRequest'
  /policies/cel/validate:
    post:
      operationId: Policies_celValidate
      summary: Validate CEL expression
      description: Validate a CEL expression.
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CelValidateResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Policies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CelValidateRequest'
  /policies/evaluate/agent-instances/{agent_instance_id}:
    get:
      operationId: Policies_evaluateAgentInstance
      summary: Evaluate agent instance access
      description: Evaluate effective access for an agent instance — what MCPs and tools it can use.
      parameters:
        - name: agent_instance_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyAgentAccess'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Policies
  /policies/evaluate/agents:
    get:
      operationId: Policies_evaluateAgents
      summary: Get agent access stats
      description: Aggregate policy evaluation stats for every catalog agent type.
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyAgentAccessStatsList'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Policies
  /policies/evaluate/agents/{agent_slug}:
    get:
      operationId: Policies_evaluateAgent
      summary: Evaluate agent access
      description: Evaluate hypothetical effective access for a catalog agent type by slug (no instance required).
      parameters:
        - name: agent_slug
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyAgentAccess'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Policies
  /policies/schema:
    get:
      operationId: Policies_schema
      summary: Get policy schema
      description: Get the policy evaluation schema — available variables and their fields.
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicySchemaResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Policies
  /policies/{policy_id}:
    get:
      operationId: Policies_read
      summary: Get policy
      description: Get a policy by ID.
      parameters:
        - name: policy_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Policies
    patch:
      operationId: Policies_update
      summary: Update policy
      description: Update an existing policy.
      parameters:
        - name: policy_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Policies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicyUpdate'
    delete:
      operationId: Policies_remove
      summary: Delete policy
      description: Delete a policy.
      parameters:
        - name: policy_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Policies
  /policies/{policy_id}/reorder:
    put:
      operationId: Policies_reorder
      summary: Reorder policy
      description: Move a policy to a new position. Specify after_id or before_id (not both). Omit both to move to the top.
      parameters:
        - name: policy_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Policies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicyReorderRequest'
  /tag-assignments/{target_type}:
    get:
      operationId: TagAssignments_list
      summary: List tag assignments
      description: List all tag assignments for a given target_type in the org.
      parameters:
        - name: target_type
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TagTargetType'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagAssignmentList'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Tags
  /tag-assignments/{target_type}/{target_key}:
    put:
      operationId: TagAssignments_set
      summary: Set target tags
      description: Replace the full set of tags assigned to a single target.
      parameters:
        - name: target_type
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TagTargetType'
        - name: target_key
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagAssignmentSet'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Tags
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagAssignmentSet'
  /tag-usage:
    get:
      operationId: TagUsages_list
      summary: List tag usage
      description: Per-tag usage counts grouped by target type, scoped to the org.
      parameters:
        - name: namespace
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/TagNamespace'
          explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagUsageList'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Tags
  /tags:
    get:
      operationId: Tags_list
      summary: List tags
      description: List tags in a namespace.
      parameters:
        - $ref: '#/components/parameters/PaginationQuery.offset'
        - $ref: '#/components/parameters/PaginationQuery.limit'
        - $ref: '#/components/parameters/SearchQuery'
        - name: namespace
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/TagNamespace'
          explode: false
        - name: sort_by
          in: query
          required: false
          schema:
            allOf:
              - $ref: '#/components/schemas/TagSortBy'
            default: name
          explode: false
        - name: sort_order
          in: query
          required: false
          schema:
            allOf:
              - $ref: '#/components/schemas/SortOrder'
            default: asc
          explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagList'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Tags
    post:
      operationId: Tags_create
      summary: Create tag
      description: Create a new tag.
      parameters: []
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Tags
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagCreate'
  /tags/{tag_id}:
    get:
      operationId: Tags_read
      summary: Get tag
      description: Get a tag by ID.
      parameters:
        - name: tag_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Tags
    patch:
      operationId: Tags_update
      summary: Update tag
      description: Update a tag's name and/or color. Namespace is immutable.
      parameters:
        - name: tag_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Tags
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagUpdate'
    delete:
      operationId: Tags_remove
      summary: Delete tag
      description: |-
        Delete a tag. Cascades to all assignments. Policies that match by the
        tag are NOT modified — their rules simply stop matching by it.
      parameters:
        - name: tag_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Tags
  /topology/graph:
    get:
      operationId: Topology_graph
      summary: Get topology graph
      description: 'Aggregated topology graph: nodes per tier with counts, and the edges between them.'
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopologyGraph'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Topology
  /user/connections:
    get:
      operationId: UserConnections_list
      summary: List user connections
      description: List the user's connectable MCPs with the current user's connection status.
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserMcpConnectionList'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - UserConnections
  /user/connections/authorize:
    post:
      operationId: UserConnections_authorize
      summary: Start OAuth authorization
      description: Start OAuth authorization flow. Returns URL to redirect the user to.
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpAuthorizeResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - UserConnections
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpAuthorizeRequest'
  /user/connections/{connection_id}:
    get:
      operationId: UserConnections_read
      summary: Get user connection
      description: Get a user connection by ID.
      parameters:
        - name: connection_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserMcpConnection'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - UserConnections
    delete:
      operationId: UserConnections_remove
      summary: Delete user connection
      description: Remove a user connection (revoke access).
      parameters:
        - name: connection_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - UserConnections
  /users:
    get:
      operationId: Users_list
      summary: List users
      description: List users in the organization.
      parameters:
        - $ref: '#/components/parameters/PaginationQuery.offset'
        - $ref: '#/components/parameters/PaginationQuery.limit'
        - $ref: '#/components/parameters/SearchQuery'
        - name: sort_by
          in: query
          required: false
          schema:
            allOf:
              - $ref: '#/components/schemas/UserSortBy'
            default: created_at
          explode: false
        - name: sort_order
          in: query
          required: false
          schema:
            allOf:
              - $ref: '#/components/schemas/SortOrder'
            default: desc
          explode: false
        - name: group
          in: query
          required: false
          description: Filter to users belonging to any of these groups (by group name).
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Users
  /users/{user_id}:
    get:
      operationId: Users_read
      summary: Get user
      description: Get a single user by id.
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Users
  /webhooks:
    get:
      operationId: Webhooks_list
      summary: List webhooks
      description: List webhooks. Config is masked (no header values).
      parameters:
        - $ref: '#/components/parameters/PaginationQuery.offset'
        - $ref: '#/components/parameters/PaginationQuery.limit'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookList'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Webhooks
    post:
      operationId: Webhooks_create
      summary: Create a webhook
      description: Create a webhook.
      parameters: []
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreate'
  /webhooks/{webhook_id}:
    get:
      operationId: Webhooks_read
      summary: Get a webhook
      description: Get a webhook by ID. Masked like list.
      parameters:
        - name: webhook_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Webhooks
    patch:
      operationId: Webhooks_update
      summary: Update a webhook
      description: Update a webhook, including status transitions (pause/resume).
      parameters:
        - name: webhook_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookUpdate'
    delete:
      operationId: Webhooks_delete
      summary: Delete a webhook
      description: Delete a webhook.
      parameters:
        - name: webhook_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Webhooks
  /webhooks/{webhook_id}/deliveries:
    get:
      operationId: WebhookDeliveries_list
      summary: List webhook deliveries
      description: List deliveries for a webhook, newest first, attempts embedded.
      parameters:
        - name: webhook_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
        - $ref: '#/components/parameters/PaginationQuery.offset'
        - $ref: '#/components/parameters/PaginationQuery.limit'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDeliveryList'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Webhooks
  /webhooks/{webhook_id}/deliveries/{delivery_id}/retry:
    post:
      operationId: WebhookDeliveryRetry
      description: |-
        Retry a delivery with a fresh set of attempts. Only a `failed` delivery on
        an `active` webhook can be retried.
      parameters:
        - name: webhook_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
        - name: delivery_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDelivery'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Webhooks
components:
  parameters:
    PaginationQuery.limit:
      name: limit
      in: query
      required: false
      description: Maximum number of items to return per page.
      schema:
        type: integer
        format: int32
        minimum: 0
        maximum: 20
        default: 10
      explode: false
    PaginationQuery.offset:
      name: offset
      in: query
      required: false
      description: Number of items to skip before returning results.
      schema:
        type: integer
        format: int32
        minimum: 0
        default: 0
      explode: false
    SearchQuery:
      name: search
      in: query
      required: false
      description: Free-text search term to filter results by name.
      schema:
        type: string
        maxLength: 255
      explode: false
  schemas:
    ActiveAgentInstancesResponse:
      type: object
      required:
        - count
      properties:
        count:
          type: integer
          format: int64
          description: Number of distinct agent instances with activity.
      description: Count of distinct active agent instances in a time range.
    ActiveUsersResponse:
      type: object
      required:
        - count
      properties:
        count:
          type: integer
          format: int64
          description: Number of distinct users with activity.
      description: Count of distinct active users in a time range.
    AgentCatalogItem:
      type: object
      required:
        - slug
        - display_name
        - description
        - user_setup_steps
      properties:
        slug:
          type: string
          minLength: 1
          maxLength: 255
          description: Stable identifier used as the instance's `agent_slug`.
        display_name:
          type: string
          minLength: 1
          maxLength: 255
          description: Name shown for the agent, for example `Claude Code`.
        description:
          type: string
          description: Summary of what the agent is and how it connects.
        user_setup_steps:
          type: array
          items:
            $ref: '#/components/schemas/AgentCatalogStep'
          description: Steps a developer follows to connect this agent to the gateway.
        admin_setup_steps:
          type: array
          items:
            $ref: '#/components/schemas/AgentCatalogStep'
          description: Steps an administrator must complete first, when the agent requires any.
      description: A connectable agent offered in the platform catalog.
    AgentCatalogList:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AgentCatalogItem'
    AgentCatalogStep:
      type: object
      required:
        - step
        - title
        - content
      properties:
        step:
          type: integer
          format: int32
          description: Position of this step in the sequence, starting at 1.
        title:
          type: string
          description: Short heading for the step.
        content:
          type: string
          description: Instructions for the step.
      description: One numbered step in an agent's setup instructions.
    AgentConnectedMCP:
      type: object
      required:
        - mcp_id
        - slug
      properties:
        mcp_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        slug:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all,own
        allowed_tools:
          type: array
          items:
            type: string
          description: Tools the agent instance may call outright.
          x-oapi-codegen-extra-tags:
            scope: all,own
        conditionally_allowed_tools:
          type: array
          items:
            type: string
          description: Tools the agent instance may call only when a policy condition holds at call time.
          x-oapi-codegen-extra-tags:
            scope: all,own
        denied_tools:
          type: array
          items:
            type: string
          description: Tools the agent instance may not call.
          x-oapi-codegen-extra-tags:
            scope: all,own
        upstreams:
          type: array
          items:
            $ref: '#/components/schemas/AgentConnectedUpstream'
          description: Backing upstream services and whether each connected.
          x-oapi-codegen-extra-tags:
            scope: all,own
      description: A resource made available to a connecting agent instance, with the tools it was allowed, denied, or allowed subject to conditions.
    AgentConnectedPayload:
      type: object
      required:
        - display_name
      properties:
        display_name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all,own
        client_name:
          type: string
          description: The connecting client application.
          x-oapi-codegen-extra-tags:
            scope: all,own
        client_version:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all,own
        protocol_version:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all,own
        allowed_mcps:
          type: array
          items:
            $ref: '#/components/schemas/AgentConnectedMCP'
          description: Resources the agent instance was granted access to.
          x-oapi-codegen-extra-tags:
            scope: all,own
        denied_mcps:
          type: array
          items:
            $ref: '#/components/schemas/AgentConnectedMCP'
          description: Resources the agent instance was denied access to.
          x-oapi-codegen-extra-tags:
            scope: all,own
        failed_mcps:
          type: array
          items:
            $ref: '#/components/schemas/AgentConnectedMCP'
          description: Resources that could not be reached during the connection.
          x-oapi-codegen-extra-tags:
            scope: all,own
      description: |-
        Recorded when an agent instance connects to the gateway. Captures the client
        and, for that session, which resources and tools it was allowed, denied, or
        could not reach.
    AgentConnectedUpstream:
      type: object
      required:
        - id
        - status
      properties:
        id:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all,own
        name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all,own
        status:
          allOf:
            - $ref: '#/components/schemas/AgentConnectedUpstreamStatus'
          x-oapi-codegen-extra-tags:
            scope: all,own
      description: A backing upstream service for a resource, and whether it connected.
    AgentConnectedUpstreamStatus:
      type: string
      enum:
        - connected
        - failed
      description: Whether an upstream service connected successfully.
    AgentCreatedPayload:
      type: object
      required:
        - display_name
      properties:
        display_name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all,own
      description: Recorded when an agent is added to the catalog.
    AgentDeletedPayload:
      type: object
      required:
        - display_name
      properties:
        display_name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all,own
      description: Recorded when an agent is removed from the catalog.
    AgentInstance:
      type: object
      required:
        - id
        - user_id
        - user_display_name
        - display_name
        - created_at
        - updated_at
        - agent_slug
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          readOnly: true
        user_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          readOnly: true
        user_display_name:
          type: string
          description: Display name of the owning user.
          readOnly: true
        display_name:
          type: string
          minLength: 1
          maxLength: 255
          description: Human-readable name for this connection, shown in the instance list.
        metadata:
          allOf:
            - $ref: '#/components/schemas/AgentInstanceMetadata'
          readOnly: true
        created_at:
          type: string
          format: date-time
          description: When the instance was first registered.
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
        last_used_at:
          type: string
          format: date-time
          description: When the instance last connected to the gateway; absent if it never has.
          readOnly: true
        revoked_at:
          type: string
          format: date-time
          description: When this instance's access was revoked; absent while it remains active.
          readOnly: true
        agent_slug:
          type: string
          description: Which agent this is an instance of, for example `claude-code` or `cursor`.
          readOnly: true
        external_id:
          type: string
          description: Identifier assigned by the client's own system, when it supplies one.
          readOnly: true
      description: |-
        One connected client of an agent, registered to the user who authorized it.
        A policy scoped to the agent applies to every instance; one scoped to an
        instance applies to that connection alone.
    AgentInstanceCountItem:
      type: object
      required:
        - slug
        - count
      properties:
        slug:
          type: string
          description: The agent's slug, for example `claude-code`.
        count:
          type: integer
          format: int64
          description: How many instances of this agent are registered.
      description: Number of registered instances for one agent.
    AgentInstanceCountList:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AgentInstanceCountItem'
      description: Wrapper for the instance-counts endpoint.
    AgentInstanceCreated:
      type: object
      required:
        - id
        - user_id
        - user_display_name
        - display_name
        - created_at
        - updated_at
        - agent_slug
        - token
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          readOnly: true
        user_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          readOnly: true
        user_display_name:
          type: string
          description: Display name of the owning user.
          readOnly: true
        display_name:
          type: string
          minLength: 1
          maxLength: 255
          description: Human-readable name for this connection, shown in the instance list.
        metadata:
          allOf:
            - $ref: '#/components/schemas/AgentInstanceMetadata'
          readOnly: true
        created_at:
          type: string
          format: date-time
          description: When the instance was first registered.
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
        last_used_at:
          type: string
          format: date-time
          description: When the instance last connected to the gateway; absent if it never has.
          readOnly: true
        revoked_at:
          type: string
          format: date-time
          description: When this instance's access was revoked; absent while it remains active.
          readOnly: true
        agent_slug:
          type: string
          description: Which agent this is an instance of, for example `claude-code` or `cursor`.
          readOnly: true
        external_id:
          type: string
          description: Identifier assigned by the client's own system, when it supplies one.
          readOnly: true
        token:
          type: string
          description: The plain API token. Only returned at creation time.
      description: Response for agent instance creation, includes the plain API token.
    AgentInstanceList:
      type: object
      required:
        - items
        - meta
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AgentInstance'
          description: The items in this page.
        meta:
          $ref: '#/components/schemas/PaginationMeta'
      description: A page of results together with its paging information.
    AgentInstanceMetadata:
      type: object
      properties:
        client_name:
          type: string
          description: Name the client identifies itself by, for example `claude-code`.
        client_version:
          type: string
          description: Version of the client software.
        protocol_version:
          type: string
          description: MCP protocol version the client negotiated.
        user_agent:
          type: string
          description: Raw user-agent string sent by the client.
        ip_address:
          type: string
          description: IP address the client last connected from.
      description: Connection details reported by the client the last time it connected.
    AgentInstanceRef:
      type: object
      required:
        - id
        - display_name
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        display_name:
          type: string
      description: An agent instance referenced by a policy, with its current display name.
    AgentInstanceSortBy:
      type: string
      enum:
        - created_at
        - display_name
        - last_used_at
      description: Field to sort a list of agent instances by.
    AgentInstanceUpdate:
      type: object
      properties:
        display_name:
          type: string
          minLength: 1
          maxLength: 255
          description: Human-readable name for this connection, shown in the instance list.
      description: |-
        One connected client of an agent, registered to the user who authorized it.
        A policy scoped to the agent applies to every instance; one scoped to an
        instance applies to that connection alone.
    AgentRevokedPayload:
      type: object
      required:
        - display_name
        - external_id
      properties:
        display_name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all,own
        external_id:
          type: string
          description: Identifier the client used to register the revoked agent instance.
          x-oapi-codegen-extra-tags:
            scope: all
      description: Recorded when an agent instance's access is revoked, cutting off a connected client.
    AgentTagAssignedPayload:
      type: object
      required:
        - agent_slug
        - tag_names
      properties:
        agent_slug:
          type: string
          description: The agent whose tags changed.
          x-oapi-codegen-extra-tags:
            scope: all
        tag_names:
          type: array
          items:
            type: string
          description: The full set of tag names on the agent after the change.
          x-oapi-codegen-extra-tags:
            scope: all
      description: |-
        Recorded when the set of tags on an agent changes. Lists the full tag set
        after the change, by name so the feed stays readable after a later rename or
        delete.
    AgentUpdatedPayload:
      type: object
      properties:
        display_name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all,own
      description: Recorded when an agent's configuration is changed.
    AnalyticsInterval:
      type: string
      enum:
        - hour
        - day
      description: Grouping interval for time series data.
    AnomalyBaselineStats:
      type: object
      required:
        - window_days
        - 'n'
        - mean
        - stddev
        - median
        - mad
        - mean_ad
      properties:
        window_days:
          type: integer
          format: int32
        'n':
          type: integer
          format: int64
          description: Number of baseline points (buckets) behind the stats.
        mean:
          type: number
          format: double
        stddev:
          type: number
          format: double
        median:
          type: number
          format: double
        mad:
          type: number
          format: double
        mean_ad:
          type: number
          format: double
      description: Rolling-baseline distribution the observation was scored against. Baseline-family findings only.
    AnomalyDetector:
      type: string
      enum:
        - llm_cost_spike
        - mcp_volume_spike
        - mcp_error_rate
        - mcp_blocked_spike
        - new_tool_for_user
        - new_mcp_for_user
        - new_model_for_user
        - off_hours_activity
      description: 'Detector that produced a finding: what kind of unusual activity was flagged.'
    AnomalyDetectorFamily:
      type: string
      enum:
        - baseline
        - threshold
        - off_hours
        - novelty
      description: Statistical family of a detector — which evidence fields a finding carries.
    AnomalyDispersionBasis:
      type: string
      enum:
        - mad
        - mean_ad
        - constant
      description: Which dispersion statistic the robust score was computed against.
    AnomalyFinding:
      type: object
      required:
        - id
        - detector
        - family
        - grain
        - metric
        - dimension
        - dimension_display
        - subject_type
        - subject_id
        - subject_display_name
        - bucket
        - last_bucket
        - severity
        - status
        - observed
        - evidence
        - created_at
        - updated_at
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        detector:
          $ref: '#/components/schemas/AnomalyDetector'
        family:
          $ref: '#/components/schemas/AnomalyDetectorFamily'
        grain:
          $ref: '#/components/schemas/AnomalyGrain'
        metric:
          type: string
          description: The measured quantity that was scored, e.g. `llm.cost_usd` or `mcp.tool_calls`.
        dimension:
          type: string
          description: The specific thing the finding is about within the subject, e.g. the tool, MCP, or model in question.
        dimension_display:
          type: string
          description: Human-readable `dimension` — ids resolved to their names; equals `dimension` when nothing resolves.
        subject_type:
          $ref: '#/components/schemas/AnomalySubjectType'
        subject_id:
          type: string
          description: Id of the flagged user or agent instance.
        subject_display_name:
          type: string
          description: Human-readable name of the subject.
        bucket:
          type: string
          format: date-time
          description: The time bucket where the anomaly was first observed.
        last_bucket:
          type: string
          format: date-time
          description: The most recent bucket in the episode; the triage queue and time filters key off this.
        severity:
          $ref: '#/components/schemas/AnomalySeverity'
        status:
          $ref: '#/components/schemas/AnomalyFindingStatus'
        observed:
          type: number
          format: double
          description: The flagged metric value, in `metric`'s unit.
        evidence:
          $ref: '#/components/schemas/AnomalyFindingEvidence'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        status_changed_at:
          type: string
          format: date-time
          description: When the finding was last triaged; absent while still `open`.
      description: One triageable anomaly episode.
    AnomalyFindingCreatedPayload:
      type: object
      required:
        - finding_id
        - detector
        - metric
        - subject
        - grain
        - bucket
        - severity
        - score
        - observed
      properties:
        finding_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        detector:
          type: string
          description: The detector that raised the finding.
          x-oapi-codegen-extra-tags:
            scope: all
        dimension:
          type: string
          description: The dimension the finding was grouped by, for example the tool or resource.
          x-oapi-codegen-extra-tags:
            scope: all
        metric:
          type: string
          description: The measure that looked unusual, for example call count or error rate.
          x-oapi-codegen-extra-tags:
            scope: all
        subject:
          allOf:
            - $ref: '#/components/schemas/AnomalySubject'
          x-oapi-codegen-extra-tags:
            scope: all
        grain:
          type: string
          description: The time window the activity was measured over, for example hourly or daily.
          x-oapi-codegen-extra-tags:
            scope: all
        bucket:
          type: string
          format: date-time
          description: The start of the time window the anomalous activity fell in.
          x-oapi-codegen-extra-tags:
            scope: all
        severity:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        score:
          type: number
          format: double
          description: How far the activity deviated from the expected baseline.
          x-oapi-codegen-extra-tags:
            scope: all
        observed:
          type: number
          format: double
          description: The measured value that triggered the finding.
          x-oapi-codegen-extra-tags:
            scope: all
      description: Recorded when an anomaly finding is raised for unusual activity.
    AnomalyFindingEscalatedPayload:
      type: object
      required:
        - finding_id
        - detector
        - metric
        - subject
        - grain
        - bucket
        - severity
        - prev_severity
        - score
        - observed
      properties:
        finding_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        detector:
          type: string
          description: The detector that raised the finding.
          x-oapi-codegen-extra-tags:
            scope: all
        dimension:
          type: string
          description: The dimension the finding was grouped by, for example the tool or resource.
          x-oapi-codegen-extra-tags:
            scope: all
        metric:
          type: string
          description: The measure that looked unusual, for example call count or error rate.
          x-oapi-codegen-extra-tags:
            scope: all
        subject:
          allOf:
            - $ref: '#/components/schemas/AnomalySubject'
          x-oapi-codegen-extra-tags:
            scope: all
        grain:
          type: string
          description: The time window the activity was measured over, for example hourly or daily.
          x-oapi-codegen-extra-tags:
            scope: all
        bucket:
          type: string
          format: date-time
          description: The start of the time window the anomalous activity fell in.
          x-oapi-codegen-extra-tags:
            scope: all
        severity:
          type: string
          description: The new, higher severity.
          x-oapi-codegen-extra-tags:
            scope: all
        prev_severity:
          type: string
          description: The severity before escalation.
          x-oapi-codegen-extra-tags:
            scope: all
        score:
          type: number
          format: double
          description: How far the activity deviated from the expected baseline.
          x-oapi-codegen-extra-tags:
            scope: all
        observed:
          type: number
          format: double
          description: The measured value that triggered the escalation.
          x-oapi-codegen-extra-tags:
            scope: all
      description: Recorded when an anomaly finding is escalated to a higher severity.
    AnomalyFindingEvidence:
      type: object
      properties:
        baseline:
          $ref: '#/components/schemas/AnomalyBaselineStats'
        scoring:
          $ref: '#/components/schemas/AnomalyScoring'
        peer:
          $ref: '#/components/schemas/AnomalyPeerContext'
        slice:
          $ref: '#/components/schemas/AnomalySliceContext'
        prior:
          $ref: '#/components/schemas/AnomalyPriorContext'
        novelty:
          $ref: '#/components/schemas/AnomalyNoveltyContext'
        threshold:
          $ref: '#/components/schemas/AnomalyThresholdFloor'
        off_hours:
          $ref: '#/components/schemas/AnomalyOffHoursContext'
      description: Typed "why" behind a finding — never a bare verdict. Every group is optional; a family carries only the groups it computes.
    AnomalyFindingList:
      type: object
      required:
        - items
        - meta
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AnomalyFinding'
          description: The items in this page.
        meta:
          $ref: '#/components/schemas/PaginationMeta'
      description: A page of results together with its paging information.
    AnomalyFindingPayloadBase:
      type: object
      required:
        - finding_id
        - detector
        - metric
        - subject
      properties:
        finding_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        detector:
          type: string
          description: The detector that raised the finding.
          x-oapi-codegen-extra-tags:
            scope: all
        dimension:
          type: string
          description: The dimension the finding was grouped by, for example the tool or resource.
          x-oapi-codegen-extra-tags:
            scope: all
        metric:
          type: string
          description: The measure that looked unusual, for example call count or error rate.
          x-oapi-codegen-extra-tags:
            scope: all
        subject:
          allOf:
            - $ref: '#/components/schemas/AnomalySubject'
          x-oapi-codegen-extra-tags:
            scope: all
      description: 'Fields common to every anomaly finding event: which detector fired, on what, and about whom.'
    AnomalyFindingResolvedPayload:
      type: object
      required:
        - finding_id
        - detector
        - metric
        - subject
        - severity
      properties:
        finding_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        detector:
          type: string
          description: The detector that raised the finding.
          x-oapi-codegen-extra-tags:
            scope: all
        dimension:
          type: string
          description: The dimension the finding was grouped by, for example the tool or resource.
          x-oapi-codegen-extra-tags:
            scope: all
        metric:
          type: string
          description: The measure that looked unusual, for example call count or error rate.
          x-oapi-codegen-extra-tags:
            scope: all
        subject:
          allOf:
            - $ref: '#/components/schemas/AnomalySubject'
          x-oapi-codegen-extra-tags:
            scope: all
        severity:
          type: string
          description: The severity the finding held when it was resolved.
          x-oapi-codegen-extra-tags:
            scope: all
      description: Recorded when an anomaly finding is resolved.
    AnomalyFindingSeries:
      type: object
      required:
        - series_metric
        - series
      properties:
        series_metric:
          type: string
          description: |-
            Metric `series[].value` is measured in. Differs from the finding's `metric` when the
            detector scores a derived value: `mcp_error_rate` observes a [0,1] rate, but its series
            is raw `mcp.tool_errors` counts. Empty when `series` is empty.
        series:
          type: array
          items:
            $ref: '#/components/schemas/AnomalySeriesPoint'
          description: |-
            30 days before the flagged bucket through the subject's last activity, zero-filled per
            bucket. Empty for novelty detectors, which have no metric.
      description: The subject's raw metric series around a finding's flagged bucket, for the evidence chart.
    AnomalyFindingSort:
      type: string
      enum:
        - recent
        - severity
        - score
    AnomalyFindingStatus:
      type: string
      enum:
        - open
        - acknowledged
        - dismissed
        - resolved
      description: Where a finding sits in the triage workflow.
    AnomalyFindingStatusChangedPayload:
      type: object
      required:
        - finding_id
        - detector
        - metric
        - subject
        - old_status
        - new_status
      properties:
        finding_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        detector:
          type: string
          description: The detector that raised the finding.
          x-oapi-codegen-extra-tags:
            scope: all
        dimension:
          type: string
          description: The dimension the finding was grouped by, for example the tool or resource.
          x-oapi-codegen-extra-tags:
            scope: all
        metric:
          type: string
          description: The measure that looked unusual, for example call count or error rate.
          x-oapi-codegen-extra-tags:
            scope: all
        subject:
          allOf:
            - $ref: '#/components/schemas/AnomalySubject'
          x-oapi-codegen-extra-tags:
            scope: all
        old_status:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        new_status:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
      description: Recorded when an anomaly finding's status changes, for example when it is acknowledged or dismissed.
    AnomalyFindingStatusUpdate:
      type: object
      properties:
        status:
          allOf:
            - $ref: '#/components/schemas/AnomalyFindingStatus'
          description: The new triage status to set. `resolved` is system-only and not accepted here.
    AnomalyFindingsSummaryCount:
      type: object
      required:
        - status
        - severity
        - count
      properties:
        status:
          $ref: '#/components/schemas/AnomalyFindingStatus'
        severity:
          $ref: '#/components/schemas/AnomalySeverity'
        count:
          type: integer
          format: int64
      description: 'One (status, severity) pair and how many findings fall in it. Sparse: a pair with no findings is absent, not zero.'
    AnomalyGrain:
      type: string
      enum:
        - hour
        - day
      description: The time resolution a finding is bucketed at.
    AnomalyNoveltyContext:
      type: object
      required:
        - new_for_org
        - dormancy_days
      properties:
        keys:
          type: array
          items:
            type: string
          description: The novel keys behind a roll-up finding (one episode per user+MCP, or per user); a per-key finding carries its key in `dimension` instead.
        keys_display:
          type: array
          items:
            type: string
          description: '`keys` rendered for display — ids resolved to their names; parallel to `keys`, each entry equal to its raw key when nothing resolves.'
        new_for_org:
          type: boolean
        dormancy_days:
          type: integer
          format: int32
          description: How long a key must be unseen before its next use counts as novel again.
      description: First-use context. Novelty-family findings only.
    AnomalyOffHoursContext:
      type: object
      required:
        - min_calls
        - history_days
      properties:
        min_calls:
          type: number
          format: double
          description: Minimum calls in the bucket for the hour to count as active.
        history_days:
          type: integer
          format: int32
          description: Days of history the hour-of-day activity histogram covers.
      description: Off-hours gate. off_hours_activity findings only.
    AnomalyOverTimeResponse:
      type: object
      required:
        - series
      properties:
        series:
          type: array
          items:
            $ref: '#/components/schemas/AnomalySeverityPoint'
    AnomalyPeerContext:
      type: object
      required:
        - rank
        - 'n'
      properties:
        rank:
          type: number
          format: double
          description: Percentile rank of the observation among peers, 0..1.
        'n':
          type: integer
          format: int64
          description: Peer population size.
      description: Standing among org peers in the same bucket; present only when the peer population is large enough to rank against.
    AnomalyPriorContext:
      type: object
      required:
        - max
        - p90
        - exceeded
      properties:
        max:
          type: number
          format: double
          description: The subject's own historical maximum.
        p90:
          type: number
          format: double
          description: The subject's own 90th-percentile historical value.
        exceeded:
          type: boolean
          description: False means the finding was demoted one severity band for not clearing the subject's own prior max.
      description: The subject's own historical distribution over the scored window. Generic baseline detectors only.
    AnomalyScoring:
      type: object
      required:
        - robust_score
        - z_score
        - dispersion_basis
      properties:
        robust_score:
          type: number
          format: double
        z_score:
          type: number
          format: double
        dispersion_basis:
          allOf:
            - $ref: '#/components/schemas/AnomalyDispersionBasis'
          description: How the spread used to score this finding was measured.
        threshold:
          type: number
          format: double
          description: Firing gate in dispersionBasis units. Absent for the constant basis, which gates on absDelta/relFactor instead.
        floor:
          type: number
          format: double
          description: Smallest observed value the detector scores at all; absent when the detector has no value floor (error rate gates on call/error counts).
        abs_delta:
          type: number
          format: double
          description: Present when the constant-baseline fallback branch fired.
        rel_factor:
          type: number
          format: double
          description: Present when the constant-baseline fallback branch fired.
      description: How the observation scored against its baseline. Baseline-family findings only.
    AnomalySeriesPoint:
      type: object
      required:
        - timestamp
        - value
      properties:
        timestamp:
          type: string
          format: date-time
        value:
          type: number
          format: double
      description: One bucket of the subject's raw metric series; `value` is in `seriesMetric`'s unit.
    AnomalySeverity:
      type: string
      enum:
        - low
        - medium
        - high
        - critical
      description: How much attention a finding needs, from lowest to highest priority.
    AnomalySeverityPoint:
      type: object
      required:
        - timestamp
        - severity
        - count
      properties:
        timestamp:
          type: string
          format: date-time
        severity:
          $ref: '#/components/schemas/AnomalySeverity'
        count:
          type: integer
          format: int64
    AnomalySliceContext:
      type: object
      required:
        - fell_back
      properties:
        hour:
          type: integer
          format: int32
          description: UTC hour of the flagged bucket, for hour-of-day-sliced detectors.
        dow_class:
          type: string
          description: weekday | weekend, for day-of-week-sliced detectors.
        fell_back:
          type: boolean
          description: True when the sliced baseline was too thin and the query fell back to the unsliced window.
      description: The hour-of-day / day-of-week slice the baseline was restricted to. Present only for detectors that slice their baseline.
    AnomalySubject:
      type: object
      required:
        - type
        - id
      properties:
        type:
          type: string
          description: Whether the subject is a user or an agent instance.
          x-oapi-codegen-extra-tags:
            scope: all
        id:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        display_name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        agent_slug:
          type: string
          description: The agent, when the subject is an agent instance.
          x-oapi-codegen-extra-tags:
            scope: all
        owner_user_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        owner_user_display_name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
      description: 'The entity an anomaly finding is about: the user, or the agent instance together with its owner.'
    AnomalySubjectType:
      type: string
      enum:
        - user
        - agent_instance
      description: 'What a finding is about: a person or a running agent.'
    AnomalySummaryResponse:
      type: object
      required:
        - counts
        - subjects_affected
      properties:
        counts:
          type: array
          items:
            $ref: '#/components/schemas/AnomalyFindingsSummaryCount'
        subjects_affected:
          type: integer
          format: int64
    AnomalyThresholdFloor:
      type: object
      required:
        - floor
      properties:
        floor:
          type: number
          format: double
          description: Observed value at or above this fires the finding.
      description: Fixed-floor gate. Threshold-family findings only.
    ApiKeyScope:
      type: string
      enum:
        - shared
        - per_user
      description: Whether an API-key resource uses one org-wide key or a key per user.
    AuditChange:
      type: object
      required:
        - type
        - path
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/ChangeType'
          x-oapi-codegen-extra-tags:
            scope: all
        path:
          type: string
          description: The field that changed, for example `name` or `effect`.
          x-oapi-codegen-extra-tags:
            scope: all
        from:
          description: The value before the change. Absent when the field was newly added.
          x-oapi-codegen-extra-tags:
            scope: all
        to:
          description: The value after the change. Absent when the field was removed.
          x-oapi-codegen-extra-tags:
            scope: all
      description: 'One field-level change in a configuration edit: what changed, and its before and after values.'
    AuditEvent:
      type: object
      required:
        - id
        - org_id
        - action
        - actor_type
        - resource_type
        - resources
        - payload
        - created_at
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all,own
        org_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all,own
        action:
          allOf:
            - $ref: '#/components/schemas/AuditEventAction'
          x-oapi-codegen-extra-tags:
            scope: all,own
        actor_type:
          allOf:
            - $ref: '#/components/schemas/AuditEventActorType'
          x-oapi-codegen-extra-tags:
            scope: all,own
        actor_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        actor_display_name:
          type: string
          description: Human-readable name of the actor, for display in an audit feed.
          x-oapi-codegen-extra-tags:
            scope: all
        resource_type:
          allOf:
            - $ref: '#/components/schemas/AuditEventResourceType'
          x-oapi-codegen-extra-tags:
            scope: all,own
        resource_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        resource_display_name:
          type: string
          description: Human-readable name of the entity acted on, frozen at the time of the event so the feed stays readable after later renames.
          x-oapi-codegen-extra-tags:
            scope: all,own
        resources:
          allOf:
            - $ref: '#/components/schemas/AuditEventResources'
          x-oapi-codegen-extra-tags:
            scope: all,own
        context:
          allOf:
            - $ref: '#/components/schemas/AuditEventContext'
          x-oapi-codegen-extra-tags:
            scope: all
        changes:
          type: array
          items:
            $ref: '#/components/schemas/AuditChange'
          description: The specific fields that changed, for configuration edits.
          x-oapi-codegen-extra-tags:
            scope: all
        payload:
          anyOf:
            - $ref: '#/components/schemas/McpCreatedPayload'
            - $ref: '#/components/schemas/McpUpdatedPayload'
            - $ref: '#/components/schemas/McpDeletedPayload'
            - $ref: '#/components/schemas/AgentCreatedPayload'
            - $ref: '#/components/schemas/AgentUpdatedPayload'
            - $ref: '#/components/schemas/AgentDeletedPayload'
            - $ref: '#/components/schemas/AgentRevokedPayload'
            - $ref: '#/components/schemas/PolicyCreatedPayload'
            - $ref: '#/components/schemas/PolicyUpdatedPayload'
            - $ref: '#/components/schemas/PolicyDeletedPayload'
            - $ref: '#/components/schemas/PolicyReorderedPayload'
            - $ref: '#/components/schemas/DlpRuleCreatedPayload'
            - $ref: '#/components/schemas/DlpRuleUpdatedPayload'
            - $ref: '#/components/schemas/DlpRuleDeletedPayload'
            - $ref: '#/components/schemas/GatewayToolExecutedPayload'
            - $ref: '#/components/schemas/GatewayToolErrorPayload'
            - $ref: '#/components/schemas/AgentConnectedPayload'
            - $ref: '#/components/schemas/ConnectionCreatedPayload'
            - $ref: '#/components/schemas/ConnectionRemovedPayload'
            - $ref: '#/components/schemas/ConnectionRevokedPayload'
            - $ref: '#/components/schemas/TagCreatedPayload'
            - $ref: '#/components/schemas/TagUpdatedPayload'
            - $ref: '#/components/schemas/TagDeletedPayload'
            - $ref: '#/components/schemas/McpTagAssignedPayload'
            - $ref: '#/components/schemas/ToolTagAssignedPayload'
            - $ref: '#/components/schemas/AgentTagAssignedPayload'
            - $ref: '#/components/schemas/IngestKeyCreatedPayload'
            - $ref: '#/components/schemas/IngestKeyRevokedPayload'
            - $ref: '#/components/schemas/AnomalyFindingCreatedPayload'
            - $ref: '#/components/schemas/AnomalyFindingEscalatedPayload'
            - $ref: '#/components/schemas/AnomalyFindingResolvedPayload'
            - $ref: '#/components/schemas/AnomalyFindingStatusChangedPayload'
            - $ref: '#/components/schemas/WebhookCreatedPayload'
            - $ref: '#/components/schemas/WebhookUpdatedPayload'
            - $ref: '#/components/schemas/WebhookDeletedPayload'
            - $ref: '#/components/schemas/WebhookDisabledPayload'
          description: Event-specific details, including the reasoning behind a policy decision. Its shape depends on `action`.
          x-oapi-codegen-extra-tags:
            scope: all,own
        created_at:
          type: string
          format: date-time
          description: When the action occurred.
          x-oapi-codegen-extra-tags:
            scope: all,own
      description: |-
        A single entry in the audit trail: one action taken through the gateway, who
        took it, what it acted on, when, and the reasoning behind the decision.
    AuditEventAction:
      type: string
      enum:
        - mcp.created
        - mcp.updated
        - mcp.deleted
        - agent.created
        - agent.updated
        - agent.deleted
        - agent.revoked
        - agent.connected
        - policy.created
        - policy.updated
        - policy.deleted
        - policy.reordered
        - dlp.rule.created
        - dlp.rule.updated
        - dlp.rule.deleted
        - gateway.tool.executed
        - gateway.tool.error
        - connection.created
        - connection.removed
        - connection.revoked
        - tag.created
        - tag.updated
        - tag.deleted
        - mcp.tag.assigned
        - tool.tag.assigned
        - agent.tag.assigned
        - ingest.key.created
        - ingest.key.revoked
        - anomaly_finding.created
        - anomaly_finding.escalated
        - anomaly_finding.resolved
        - anomaly_finding.status_changed
        - webhook.created
        - webhook.updated
        - webhook.deleted
        - webhook.disabled
      description: 'The action that was recorded: what happened, from a tool call to a configuration change.'
    AuditEventActorType:
      type: string
      enum:
        - user
        - agent
        - system
      description: Who or what performed the action.
    AuditEventContext:
      type: object
      properties:
        device:
          type: string
          description: The device type the action came from.
          x-oapi-codegen-extra-tags:
            scope: all
        os:
          type: string
          description: The operating system the action came from.
          x-oapi-codegen-extra-tags:
            scope: all
        browser:
          type: string
          description: The browser the action came from.
          x-oapi-codegen-extra-tags:
            scope: all
        ip:
          type: string
          description: The source IP address.
          x-oapi-codegen-extra-tags:
            scope: all
        city:
          type: string
          description: City derived from the source IP address.
          x-oapi-codegen-extra-tags:
            scope: all
        country:
          type: string
          description: Country derived from the source IP address.
          x-oapi-codegen-extra-tags:
            scope: all
        user_agent:
          type: string
          description: The raw user-agent string of the client that made the request.
          x-oapi-codegen-extra-tags:
            scope: all
        trace_id:
          type: string
          description: Trace identifier for correlating this event with distributed traces and logs.
          x-oapi-codegen-extra-tags:
            scope: all
      description: |-
        Where the action came from: the device, location, and network details of the
        actor, useful for spotting activity from unexpected places.
    AuditEventList:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AuditEvent'
        next_cursor:
          allOf:
            - $ref: '#/components/schemas/uuid'
          description: Pass as the cursor to fetch the next page; absent when there are no more results.
    AuditEventResourceType:
      type: string
      enum:
        - mcp
        - agent
        - policy
        - dlp_rule
        - connection
        - tag
        - ingest_key
        - anomaly_finding
        - webhook
      description: The kind of entity the action was performed on.
    AuditEventResources:
      type: object
      properties:
        mcp_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all,own
        mcp_display_name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all,own
        agent_instance_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all,own
        agent_instance_display_name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all,own
        agent_slug:
          type: string
          description: The agent the instance belongs to.
          x-oapi-codegen-extra-tags:
            scope: all,own
        user_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all,own
        user_display_name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all,own
        connection_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all,own
        policy_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        policy_display_name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        dlp_rule_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        dlp_rule_display_name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        tag_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        tag_display_name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        tool_key:
          type: string
          description: The specific tool involved, identified within its resource.
          x-oapi-codegen-extra-tags:
            scope: all,own
      description: |-
        The entities involved in an audit event, so an investigator can see at a
        glance which resource, agent, user, connection, or policy it concerned. Each
        carries a display name frozen at event time so the feed stays readable after
        later renames. Only the fields relevant to the event are present.
    BlockedAgentInstancesCountResponse:
      type: object
      required:
        - count
      properties:
        count:
          type: integer
          format: int64
          description: Number of distinct agent instances with a blocked tool call.
      description: Count of distinct agent instances with blocked tool calls in a time range.
    BlockedToolsCountResponse:
      type: object
      required:
        - count
      properties:
        count:
          type: integer
          format: int64
          description: Number of tool calls blocked by policy.
      description: Count of blocked tool calls.
    BlockedUniqueToolsResponse:
      type: object
      required:
        - count
      properties:
        count:
          type: integer
          format: int64
          description: Number of distinct tools blocked by policy.
      description: Count of distinct tools blocked by policy in a time range.
    BlockedUsersCountResponse:
      type: object
      required:
        - count
      properties:
        count:
          type: integer
          format: int64
          description: Number of distinct users with a blocked tool call.
      description: Count of distinct users with blocked tool calls in a time range.
    CatalogMcpConfig:
      type: object
      required:
        - catalog_slug
      properties:
        catalog_slug:
          type: string
          minLength: 1
          maxLength: 63
          pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
          description: Which catalog entry this resource is, e.g. `slack` or `jira`.
        mode:
          allOf:
            - $ref: '#/components/schemas/CatalogMcpMode'
          description: Which credential mode this catalog resource uses for user sign-in.
        byo_client_id:
          type: string
          maxLength: 255
          description: OAuth client ID supplied by the org. Required when mode = byo.
        token_endpoint_auth_method:
          allOf:
            - $ref: '#/components/schemas/OAuthTokenEndpointAuthMethod'
          description: How client credentials are sent to the token endpoint. Only for `byo` mode.
    CatalogMcpConfigCreate:
      type: object
      required:
        - catalog_slug
      properties:
        catalog_slug:
          type: string
          minLength: 1
          maxLength: 63
          pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
          description: Which catalog entry this resource is, e.g. `slack` or `jira`.
        mode:
          allOf:
            - $ref: '#/components/schemas/CatalogMcpMode'
          description: Which credential mode this catalog resource uses for user sign-in.
        byo_client_id:
          type: string
          maxLength: 255
          description: OAuth client ID supplied by the org. Required when mode = byo.
        byo_client_secret:
          type: string
          maxLength: 1000
          description: OAuth client secret supplied by the org. Write-only — never returned in read responses.
        token_endpoint_auth_method:
          allOf:
            - $ref: '#/components/schemas/OAuthTokenEndpointAuthMethod'
          description: How client credentials are sent to the token endpoint. Only for `byo` mode.
    CatalogMcpConfigUpdate:
      type: object
      properties:
        byo_client_id:
          type: string
          maxLength: 255
          description: OAuth client ID supplied by the org. Required when mode = byo.
        byo_client_secret:
          type: string
          maxLength: 1000
          description: OAuth client secret supplied by the org. Write-only — never returned in read responses.
        token_endpoint_auth_method:
          allOf:
            - $ref: '#/components/schemas/OAuthTokenEndpointAuthMethod'
          description: How client credentials are sent to the token endpoint. Only for `byo` mode.
    CatalogMcpMode:
      type: string
      enum:
        - embedded
        - dcr
        - byo
      description: How your org supplies the OAuth app for a catalog resource. Chosen once at install time.
    CelEvaluateRequest:
      type: object
      required:
        - expression
        - context
      properties:
        expression:
          type: string
          minLength: 1
          description: CEL expression to evaluate
        context:
          allOf:
            - $ref: '#/components/schemas/PolicyContext'
          description: The policy context to evaluate the expression against.
    CelEvaluateResponse:
      type: object
      required:
        - match
      properties:
        match:
          type: boolean
          description: Whether the expression matched (returned true)
        error:
          type: string
          description: Error message if evaluation failed
    CelValidateRequest:
      type: object
      required:
        - expression
      properties:
        expression:
          type: string
          minLength: 1
          description: CEL expression to validate
    CelValidateResponse:
      type: object
      required:
        - valid
      properties:
        valid:
          type: boolean
          description: Whether the expression is valid
        error:
          type: string
          description: Human-readable error message if invalid
        position:
          type: integer
          format: int32
          description: Character offset of the error in the expression
    ChangeType:
      type: string
      enum:
        - create
        - update
        - delete
      description: Whether a single field was added, changed, or removed.
    ConnectionCreatedPayload:
      type: object
      required:
        - connection_id
        - mcp_id
        - mcp_display_name
      properties:
        connection_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_display_name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all,own
      description: Recorded when a user connects their account to a third-party service.
    ConnectionEventPayload:
      type: object
      required:
        - connection_id
        - mcp_id
        - mcp_display_name
      properties:
        connection_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_display_name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all,own
      description: Identifies the connection and third-party service shared by all connection audit events.
    ConnectionRemovedPayload:
      type: object
      required:
        - connection_id
        - mcp_id
        - mcp_display_name
      properties:
        connection_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_display_name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all,own
      description: Recorded when a connection to a third-party service is removed.
    ConnectionRevokedPayload:
      type: object
      required:
        - connection_id
        - mcp_id
        - mcp_display_name
      properties:
        connection_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_display_name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all,own
      description: Recorded when a connection's access is revoked, invalidating its stored credentials.
    CreateIngestKeyRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
    CustomMcpConfig:
      type: object
      required:
        - slug
        - auth_type
        - auth
      properties:
        slug:
          type: string
          minLength: 1
          maxLength: 63
          pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
          description: URL-safe identifier for this custom server.
          example: my-mcp-server
        auth_type:
          $ref: '#/components/schemas/McpAuthType'
        auth:
          $ref: '#/components/schemas/McpAuthConfig'
    CustomMcpConfigCreate:
      type: object
      required:
        - slug
        - display_name
        - server_url
        - auth_type
        - auth
      properties:
        slug:
          type: string
          minLength: 1
          maxLength: 63
          pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
          description: URL-safe identifier for this custom server.
          example: my-mcp-server
        display_name:
          type: string
          minLength: 1
          maxLength: 255
          description: Display name. Present in create/update requests for custom MCPs.
        server_url:
          type: string
          maxLength: 2048
          format: uri
          description: Server URL. Present in create/update requests for custom MCPs.
        auth_type:
          $ref: '#/components/schemas/McpAuthType'
        auth:
          $ref: '#/components/schemas/McpAuthConfigCreate'
    CustomMcpConfigUpdate:
      type: object
      properties:
        slug:
          type: string
          minLength: 1
          maxLength: 63
          pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
          description: URL-safe identifier for this custom server.
          example: my-mcp-server
        display_name:
          type: string
          minLength: 1
          maxLength: 255
          description: Display name. Present in create/update requests for custom MCPs.
        server_url:
          type: string
          maxLength: 2048
          format: uri
          description: Server URL. Present in create/update requests for custom MCPs.
        auth_type:
          $ref: '#/components/schemas/McpAuthType'
        auth:
          $ref: '#/components/schemas/McpAuthConfigUpdate'
    DlpAction:
      type: string
      enum:
        - redact
      description: What the rule does to matched content.
    DlpFilter:
      type: object
      oneOf:
        - $ref: '#/components/schemas/DlpRegexFilter'
        - $ref: '#/components/schemas/DlpLlmJudgeFilter'
      discriminator:
        propertyName: type
        mapping:
          regex: '#/components/schemas/DlpRegexFilter'
          llm_judge: '#/components/schemas/DlpLlmJudgeFilter'
      description: One filter applied to a matching response. A rule can carry several, and every matching filter is applied.
    DlpFilterType:
      type: string
      enum:
        - regex
        - llm_judge
      description: How a filter recognizes content to redact.
    DlpJudgePreviewRequest:
      type: object
      required:
        - instruction
        - sample
      properties:
        instruction:
          type: string
          minLength: 1
          maxLength: 2000
        sample:
          type: string
          maxLength: 1048576
          description: Sample response text to judge; the server enforces the configured judge cap (default 128 KiB).
    DlpJudgePreviewResult:
      type: object
      required:
        - spans
        - redacted
        - judged
      properties:
        spans:
          type: array
          items:
            type: string
          description: Verbatim spans the judge flagged.
        redacted:
          type: string
          description: The judged document with every span replaced by [REDACTED].
        judged:
          type: string
          description: |-
            The document the judge actually received, built from the sample the same
            way a tool response is at runtime (a JSON sample is flattened to its
            values). Lets the tester show exactly what the model saw.
    DlpLlmJudgeFilter:
      type: object
      required:
        - type
        - instruction
      properties:
        type:
          type: string
          enum:
            - llm_judge
        instruction:
          type: string
          minLength: 1
          maxLength: 2000
          description: Admin-authored instruction describing what to flag.
      description: |-
        Sends the (post-regex) response content to the deployment-configured LLM
        judge with this instruction; every span the judge returns is redacted.
    DlpOnError:
      type: string
      enum:
        - block
        - allow
      description: What happens when a rule's filter fails (judge error/timeout, invalid regex).
    DlpRegexFilter:
      type: object
      required:
        - type
        - pattern
      properties:
        type:
          type: string
          enum:
            - regex
        pattern:
          type: string
          description: Regular expression matched against the response text.
        replacement:
          type: string
          description: Literal text put in place of each match. Defaults to `[REDACTED]` when empty.
      description: Redacts every match of a regular expression.
    DlpRule:
      type: object
      required:
        - id
        - name
        - scope
        - filters
        - created_at
        - updated_at
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          readOnly: true
        name:
          type: string
          description: Short label for the rule, shown in the rule list.
        description:
          type: string
          nullable: true
          description: Optional note explaining what the rule protects against.
        status:
          $ref: '#/components/schemas/DlpRuleStatus'
        target:
          $ref: '#/components/schemas/DlpTarget'
        scope:
          allOf:
            - $ref: '#/components/schemas/McpToolCallScope'
          description: Which agents, users, MCP servers, and tools this rule's filters apply to.
        action:
          $ref: '#/components/schemas/DlpAction'
        filters:
          type: array
          items:
            $ref: '#/components/schemas/DlpFilter'
          description: Filters run against each matching response. Every matching filter is applied.
        on_error:
          allOf:
            - $ref: '#/components/schemas/DlpOnError'
          description: Failure routing for this rule's filters. Treated as `block` when unset.
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
      description: |-
        A data-protection rule that rewrites tool responses after a policy has
        allowed the call. It never decides whether a call runs; it only redacts
        matching content on the way back to the agent. Every rule whose scope matches
        is applied, not just the first.
    DlpRuleCreatedPayload:
      type: object
      required:
        - rule_id
        - name
        - status
        - target
        - action
        - mcp_ids
        - agent_slugs
        - agent_instance_ids
        - user_ids
        - groups
        - agent_slug_tag_ids
        - mcp_tag_ids
        - tool_tag_ids
        - tool_patterns
        - filters
      properties:
        rule_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        description:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        status:
          allOf:
            - $ref: '#/components/schemas/DlpRuleStatus'
          x-oapi-codegen-extra-tags:
            scope: all
        target:
          allOf:
            - $ref: '#/components/schemas/DlpTarget'
          x-oapi-codegen-extra-tags:
            scope: all
        action:
          allOf:
            - $ref: '#/components/schemas/DlpAction'
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Resources the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_slugs:
          type: array
          items:
            type: string
          description: Agents the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_instance_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Specific agent instances the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        user_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Users the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        groups:
          type: array
          items:
            type: string
          description: User groups the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_slug_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Agents matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Resources matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        tool_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Tools matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        tool_patterns:
          type: array
          items:
            type: string
          description: Name patterns matching the tools the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        condition:
          type: string
          description: Additional condition that had to hold for the rule to apply.
          x-oapi-codegen-extra-tags:
            scope: all
        condition_description:
          type: string
          description: Human-readable explanation of the condition.
          x-oapi-codegen-extra-tags:
            scope: all
        filters:
          type: array
          items:
            $ref: '#/components/schemas/DlpFilter'
          description: The patterns the rule matched sensitive content against.
          x-oapi-codegen-extra-tags:
            scope: all
        on_error:
          allOf:
            - $ref: '#/components/schemas/DlpOnError'
          x-oapi-codegen-extra-tags:
            scope: all
      description: Recorded when a data-loss-prevention rule is created.
    DlpRuleDeletedPayload:
      type: object
      required:
        - rule_id
        - name
        - status
        - target
        - action
        - mcp_ids
        - agent_slugs
        - agent_instance_ids
        - user_ids
        - groups
        - agent_slug_tag_ids
        - mcp_tag_ids
        - tool_tag_ids
        - tool_patterns
        - filters
      properties:
        rule_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        description:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        status:
          allOf:
            - $ref: '#/components/schemas/DlpRuleStatus'
          x-oapi-codegen-extra-tags:
            scope: all
        target:
          allOf:
            - $ref: '#/components/schemas/DlpTarget'
          x-oapi-codegen-extra-tags:
            scope: all
        action:
          allOf:
            - $ref: '#/components/schemas/DlpAction'
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Resources the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_slugs:
          type: array
          items:
            type: string
          description: Agents the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_instance_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Specific agent instances the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        user_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Users the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        groups:
          type: array
          items:
            type: string
          description: User groups the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_slug_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Agents matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Resources matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        tool_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Tools matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        tool_patterns:
          type: array
          items:
            type: string
          description: Name patterns matching the tools the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        condition:
          type: string
          description: Additional condition that had to hold for the rule to apply.
          x-oapi-codegen-extra-tags:
            scope: all
        condition_description:
          type: string
          description: Human-readable explanation of the condition.
          x-oapi-codegen-extra-tags:
            scope: all
        filters:
          type: array
          items:
            $ref: '#/components/schemas/DlpFilter'
          description: The patterns the rule matched sensitive content against.
          x-oapi-codegen-extra-tags:
            scope: all
        on_error:
          allOf:
            - $ref: '#/components/schemas/DlpOnError'
          x-oapi-codegen-extra-tags:
            scope: all
      description: Recorded when a data-loss-prevention rule is deleted.
    DlpRuleEventPayload:
      type: object
      required:
        - rule_id
        - name
        - status
        - target
        - action
        - mcp_ids
        - agent_slugs
        - agent_instance_ids
        - user_ids
        - groups
        - agent_slug_tag_ids
        - mcp_tag_ids
        - tool_tag_ids
        - tool_patterns
        - filters
      properties:
        rule_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        description:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        status:
          allOf:
            - $ref: '#/components/schemas/DlpRuleStatus'
          x-oapi-codegen-extra-tags:
            scope: all
        target:
          allOf:
            - $ref: '#/components/schemas/DlpTarget'
          x-oapi-codegen-extra-tags:
            scope: all
        action:
          allOf:
            - $ref: '#/components/schemas/DlpAction'
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Resources the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_slugs:
          type: array
          items:
            type: string
          description: Agents the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_instance_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Specific agent instances the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        user_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Users the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        groups:
          type: array
          items:
            type: string
          description: User groups the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_slug_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Agents matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Resources matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        tool_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Tools matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        tool_patterns:
          type: array
          items:
            type: string
          description: Name patterns matching the tools the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        condition:
          type: string
          description: Additional condition that had to hold for the rule to apply.
          x-oapi-codegen-extra-tags:
            scope: all
        condition_description:
          type: string
          description: Human-readable explanation of the condition.
          x-oapi-codegen-extra-tags:
            scope: all
        filters:
          type: array
          items:
            $ref: '#/components/schemas/DlpFilter'
          description: The patterns the rule matched sensitive content against.
          x-oapi-codegen-extra-tags:
            scope: all
        on_error:
          allOf:
            - $ref: '#/components/schemas/DlpOnError'
          x-oapi-codegen-extra-tags:
            scope: all
      description: 'Snapshot of a data-loss-prevention rule shared by all DLP audit events: its identity, scope, and what it inspects and does.'
    DlpRuleList:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/DlpRule'
    DlpRuleStatus:
      type: string
      enum:
        - active
        - draft
        - disabled
      description: Whether a DLP rule takes part in filtering.
    DlpRuleUpdate:
      type: object
      properties:
        name:
          type: string
          description: Short label for the rule, shown in the rule list.
        description:
          type: string
          nullable: true
          description: Optional note explaining what the rule protects against.
        status:
          $ref: '#/components/schemas/DlpRuleStatus'
        target:
          $ref: '#/components/schemas/DlpTarget'
        scope:
          allOf:
            - $ref: '#/components/schemas/McpToolCallScope'
          description: Which agents, users, MCP servers, and tools this rule's filters apply to.
        action:
          $ref: '#/components/schemas/DlpAction'
        filters:
          type: array
          items:
            $ref: '#/components/schemas/DlpFilter'
          description: Filters run against each matching response. Every matching filter is applied.
        on_error:
          allOf:
            - $ref: '#/components/schemas/DlpOnError'
          description: Failure routing for this rule's filters. Treated as `block` when unset.
      description: |-
        A data-protection rule that rewrites tool responses after a policy has
        allowed the call. It never decides whether a call runs; it only redacts
        matching content on the way back to the agent. Every rule whose scope matches
        is applied, not just the first.
    DlpRuleUpdatedPayload:
      type: object
      required:
        - rule_id
        - name
        - status
        - target
        - action
        - mcp_ids
        - agent_slugs
        - agent_instance_ids
        - user_ids
        - groups
        - agent_slug_tag_ids
        - mcp_tag_ids
        - tool_tag_ids
        - tool_patterns
        - filters
      properties:
        rule_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        description:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        status:
          allOf:
            - $ref: '#/components/schemas/DlpRuleStatus'
          x-oapi-codegen-extra-tags:
            scope: all
        target:
          allOf:
            - $ref: '#/components/schemas/DlpTarget'
          x-oapi-codegen-extra-tags:
            scope: all
        action:
          allOf:
            - $ref: '#/components/schemas/DlpAction'
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Resources the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_slugs:
          type: array
          items:
            type: string
          description: Agents the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_instance_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Specific agent instances the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        user_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Users the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        groups:
          type: array
          items:
            type: string
          description: User groups the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_slug_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Agents matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Resources matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        tool_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Tools matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        tool_patterns:
          type: array
          items:
            type: string
          description: Name patterns matching the tools the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        condition:
          type: string
          description: Additional condition that had to hold for the rule to apply.
          x-oapi-codegen-extra-tags:
            scope: all
        condition_description:
          type: string
          description: Human-readable explanation of the condition.
          x-oapi-codegen-extra-tags:
            scope: all
        filters:
          type: array
          items:
            $ref: '#/components/schemas/DlpFilter'
          description: The patterns the rule matched sensitive content against.
          x-oapi-codegen-extra-tags:
            scope: all
        on_error:
          allOf:
            - $ref: '#/components/schemas/DlpOnError'
          x-oapi-codegen-extra-tags:
            scope: all
      description: Recorded when a data-loss-prevention rule is changed.
    DlpTarget:
      type: string
      enum:
        - mcp_tool_response
      description: Which responses the rule inspects.
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
          description: Human-readable explanation of what went wrong.
        validation_errors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationErrorDetail'
          description: Per-field validation failures, present when `code` is `bad_request`.
      description: Returned whenever a request fails.
    ErrorCode:
      type: string
      enum:
        - bad_request
        - unauthorized
        - not_found
        - forbidden
        - already_exists
        - conflict
        - method_not_allowed
        - payload_too_large
        - unsupported_media_type
        - unknown_error
      description: Machine-readable reason a request failed.
    EventBreakdownItem:
      type: object
      required:
        - action
        - count
      properties:
        action:
          type: string
          description: Audit action, such as `tool.call` or `tool.blocked`.
        count:
          type: integer
          format: int64
          description: Number of events of this action.
      description: Audit event count for a single action type.
    EventBreakdownResponse:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/EventBreakdownItem'
          description: One entry per action type.
      description: Audit events grouped by action type.
    FeatureFlag:
      type: string
      enum:
        - semantic_search
        - sandbox
        - llm_judge
        - webhooks
        - microsoft365_graph
      description: Optional gateway capabilities that can be turned on per organization.
    FeatureFlags:
      type: object
      required:
        - enabled
      properties:
        enabled:
          type: array
          items:
            $ref: '#/components/schemas/FeatureFlag'
          description: The feature flags enabled for the organization.
      description: The optional capabilities currently turned on for your organization.
    GatewayToolErrorPayload:
      type: object
      required:
        - tool_name
        - error_type
        - description
      properties:
        mcp_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_slug:
          type: string
          description: The resource the tool belongs to.
          x-oapi-codegen-extra-tags:
            scope: all,own
        tool_name:
          type: string
          description: The tool that was called.
          x-oapi-codegen-extra-tags:
            scope: all,own
        error_type:
          allOf:
            - $ref: '#/components/schemas/GatewayToolErrorType'
          x-oapi-codegen-extra-tags:
            scope: all,own
        description:
          type: string
          description: Human-readable explanation of why the call failed or was denied.
          x-oapi-codegen-extra-tags:
            scope: all,own
        redacted:
          type: boolean
          description: Whether data-loss-prevention redacted content before the error was recorded.
          x-oapi-codegen-extra-tags:
            scope: all,own
        redactions:
          type: array
          items:
            $ref: '#/components/schemas/RedactionRef'
          description: The data-loss-prevention rules that redacted content, if any.
          x-oapi-codegen-extra-tags:
            scope: all
      description: Recorded when a tool call fails or is denied. Carries the reason and, where the call was blocked, the reasoning behind the decision.
    GatewayToolErrorType:
      type: string
      enum:
        - tool_not_found
        - method_not_supported
        - resource_not_found
        - invalid_parameters
        - invalid_request
        - internal_error
        - upstream_error
        - tool_execution_error
        - blocked_by_policy
        - timeout
        - unknown
      description: Why a tool call failed or was denied.
    GatewayToolExecutedPayload:
      type: object
      required:
        - mcp_id
        - tool_name
        - mcp_slug
      properties:
        mcp_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        tool_name:
          type: string
          description: The tool that was called.
          x-oapi-codegen-extra-tags:
            scope: all,own
        mcp_slug:
          type: string
          description: The resource the tool belongs to.
          x-oapi-codegen-extra-tags:
            scope: all,own
        redacted:
          type: boolean
          description: Whether data-loss-prevention redacted content from the response.
          x-oapi-codegen-extra-tags:
            scope: all,own
        redactions:
          type: array
          items:
            $ref: '#/components/schemas/RedactionRef'
          description: The data-loss-prevention rules that redacted content, if any.
          x-oapi-codegen-extra-tags:
            scope: all
      description: Recorded when a tool call passes policy and runs successfully.
    Grant:
      type: object
      required:
        - permission
        - scope
      properties:
        permission:
          $ref: '#/components/schemas/Permission'
        scope:
          $ref: '#/components/schemas/Scope'
      description: A single permission the caller holds, together with how far it reaches.
    Group:
      type: object
      required:
        - id
        - name
        - created_at
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        name:
          type: string
          description: The group's name.
        created_at:
          type: string
          format: date-time
      description: A collection of users, used to scope policy rules and access.
    GroupList:
      type: object
      required:
        - items
        - meta
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Group'
          description: The items in this page.
        meta:
          $ref: '#/components/schemas/PaginationMeta'
      description: A page of results together with its paging information.
    GroupSortBy:
      type: string
      enum:
        - created_at
        - name
      description: Field to sort groups by.
    HourlyDistributionItem:
      type: object
      required:
        - hour
        - count
      properties:
        hour:
          type: integer
          format: int32
          minimum: 0
          maximum: 23
          description: Hour of day, 0-23 UTC
        count:
          type: integer
          format: int64
          description: Tool calls executed during this hour of day.
      description: Tool execution count for a single hour of day (UTC).
    HourlyDistributionResponse:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/HourlyDistributionItem'
          description: One entry per hour of day with a nonzero count.
      description: Tool executions grouped by hour of day (0-23 UTC).
    IngestKey:
      type: object
      required:
        - id
        - name
        - last_four
        - created_at
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        name:
          type: string
          description: A label to help you recognize the key.
        last_four:
          type: string
          description: Last four characters of the key, to identify it after creation.
        created_at:
          type: string
          format: date-time
      description: |-
        An ingest key. Coding agents point their OpenTelemetry model-usage data
        (tokens, cost, sessions, requests) at the gateway using this key.
    IngestKeyCreated:
      type: object
      required:
        - key
        - token
        - endpoint
      properties:
        key:
          $ref: '#/components/schemas/IngestKey'
        token:
          type: string
          description: The full ingest key. Shown only once.
        endpoint:
          type: string
          format: uri
          description: OTLP base endpoint; clients append the provider segment, e.g. /claude.
      description: Response for ingest key creation, includes the full token.
    IngestKeyCreatedPayload:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
      description: Recorded when an ingest key is created.
    IngestKeyList:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/IngestKey'
    IngestKeyRevokedPayload:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
      description: Recorded when an ingest key is revoked.
    LLMCostPoint:
      type: object
      required:
        - timestamp
        - cost
      properties:
        timestamp:
          type: string
          format: date-time
          description: Start of the time bucket this cost covers.
        cost:
          type: number
          format: double
          description: LLM token spend in USD for this bucket.
      description: A single cost data point in a time series (USD).
    LLMCostRankItem:
      type: object
      required:
        - name
        - cost
      properties:
        name:
          type: string
          description: Display name of the ranked user or model.
        cost:
          type: number
          format: double
          description: LLM token spend in USD, the value this ranking is sorted by.
      description: A user or model ranked by cost (USD).
    LLMCostRankResponse:
      type: object
      required:
        - items
        - meta
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/LLMCostRankItem'
          description: The items in this page.
        meta:
          $ref: '#/components/schemas/PaginationMeta'
      description: Ranked list by cost (USD).
    LLMCostSeriesResponse:
      type: object
      required:
        - series
      properties:
        series:
          type: array
          items:
            $ref: '#/components/schemas/LLMCostPoint'
          description: Ordered cost data points, one per time bucket.
      description: Time-bucketed cost (USD).
    LLMCostTotalResponse:
      type: object
      required:
        - total
      properties:
        total:
          type: number
          format: double
          description: Total LLM token spend in USD.
      description: Total cost in USD.
    LLMFacetsResponse:
      type: object
      required:
        - models
      properties:
        models:
          type: array
          items:
            type: string
          description: Model names with usage in the range, for filter dropdowns.
      description: Distinct models available for filtering in a time range.
    LLMMetricStats:
      type: object
      required:
        - avg
        - p50
        - p95
      properties:
        avg:
          type: number
          format: double
          description: Average value across sessions.
        p50:
          type: number
          format: double
          description: Median (50th percentile) value across sessions.
        p95:
          type: number
          format: double
          description: Peak (95th percentile) value across sessions.
      description: Average, median and peak (p95) for one session metric over the selected range.
    LLMModelsCountResponse:
      type: object
      required:
        - count
      properties:
        count:
          type: integer
          format: int64
          description: Number of distinct models with usage.
      description: Count of distinct models with usage in a time range.
    LLMProvider:
      type: string
      enum:
        - claude
        - codex
      description: LLM telemetry provider.
    LLMSessionActivityBucket:
      type: object
      required:
        - bucket_start
        - tokens
        - cost
      properties:
        bucket_start:
          type: string
          format: date-time
          description: Start of this activity bucket.
        tokens:
          type: integer
          format: int64
          description: Tokens used during the bucket.
        cost:
          type: number
          format: double
          description: LLM token spend in USD during the bucket.
      description: One equal-width time bucket of a session's activity.
    LLMSessionActivityResponse:
      type: object
      required:
        - buckets
        - models
      properties:
        buckets:
          type: array
          items:
            $ref: '#/components/schemas/LLMSessionActivityBucket'
          description: Token and cost activity over time.
        models:
          type: array
          items:
            $ref: '#/components/schemas/LLMSessionModelRollupItem'
          description: Per-model totals for the session.
      description: Time-bucketed usage plus a per-model rollup for one session.
    LLMSessionItem:
      type: object
      required:
        - session_key
        - provider
        - user_name
        - models
        - tokens
        - by_type
        - cost
        - request_count
        - started_at
        - last_activity_at
        - duration_ms
      properties:
        session_key:
          type: string
          description: Provider's session identifier, used to look up session detail.
        provider:
          $ref: '#/components/schemas/LLMProvider'
        user_id:
          $ref: '#/components/schemas/uuid'
        user_name:
          type: string
          description: Display name of the user who ran the session.
        models:
          type: array
          items:
            type: string
          description: Models used during the session.
        tokens:
          type: integer
          format: int64
          description: Total tokens used in the session.
        by_type:
          type: array
          items:
            $ref: '#/components/schemas/LLMTokenTypeItem'
          description: Token totals split by category (input, output, cache).
        cost:
          type: number
          format: double
          description: LLM token spend in USD for the session.
        request_count:
          type: integer
          format: int64
          description: Number of model requests in the session.
        started_at:
          type: string
          format: date-time
          description: When the session's first request occurred.
        last_activity_at:
          type: string
          format: date-time
          description: When the session's most recent request occurred.
        duration_ms:
          type: integer
          format: int64
          description: Elapsed time from first to last request, in milliseconds.
      description: A single LLM session, keyed by the provider's session identifier.
    LLMSessionModelRollupItem:
      type: object
      required:
        - model
        - calls
        - tokens
        - cost
        - duration_ms
      properties:
        model:
          type: string
          description: Model name.
        calls:
          type: integer
          format: int64
          description: Number of requests to this model in the session.
        tokens:
          type: integer
          format: int64
          description: Tokens used by this model in the session.
        cost:
          type: number
          format: double
          description: LLM token spend in USD for this model in the session.
        duration_ms:
          type: integer
          format: int64
          description: Total time spent on this model's requests, in milliseconds.
      description: A model's totals across one session.
    LLMSessionRankResponse:
      type: object
      required:
        - session_count
      properties:
        session_count:
          type: integer
          format: int64
          description: Number of org sessions the ranks are computed against.
        ranks:
          allOf:
            - $ref: '#/components/schemas/LLMSessionRanks'
          description: This session's rank by cost and tokens; absent when the session has no data in the range.
      description: How one session compares to all org sessions in the range.
    LLMSessionRanks:
      type: object
      required:
        - cost
        - tokens
        - duration
        - requests
      properties:
        cost:
          type: number
          format: double
          description: Percentile rank (0..1) of this session's cost.
        tokens:
          type: number
          format: double
          description: Percentile rank (0..1) of this session's token usage.
        duration:
          type: number
          format: double
          description: Percentile rank (0..1) of this session's duration.
        requests:
          type: number
          format: double
          description: Percentile rank (0..1) of this session's request count.
      description: Percentile rank (0..1) of one session for each metric, vs all org sessions.
    LLMSessionResponse:
      type: object
      required:
        - items
        - meta
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/LLMSessionItem'
          description: The items in this page.
        meta:
          $ref: '#/components/schemas/PaginationMeta'
      description: Ranked list of sessions.
    LLMSessionSort:
      type: string
      enum:
        - cost
        - tokens
        - recent
      description: Sort key for the sessions ranking.
    LLMSessionStatsResponse:
      type: object
      required:
        - session_count
        - cost
        - tokens
        - duration
        - requests
      properties:
        session_count:
          type: integer
          format: int64
          description: Number of sessions the statistics are computed over.
        cost:
          $ref: '#/components/schemas/LLMMetricStats'
        tokens:
          $ref: '#/components/schemas/LLMMetricStats'
        duration:
          $ref: '#/components/schemas/LLMMetricStats'
        requests:
          $ref: '#/components/schemas/LLMMetricStats'
      description: Aggregate session statistics over the sessions matching the filters.
    LLMSessionTimelineItem:
      type: object
      required:
        - occurred_at
        - model
        - cost
        - tokens
        - by_type
        - duration_ms
        - prompt_id
      properties:
        occurred_at:
          type: string
          format: date-time
          description: When the request occurred.
        model:
          type: string
          description: Model that served the request.
        cost:
          type: number
          format: double
          description: LLM token spend in USD for the request.
        tokens:
          type: integer
          format: int64
          description: Tokens used by the request.
        by_type:
          type: array
          items:
            $ref: '#/components/schemas/LLMTokenTypeItem'
          description: Token totals split by category (input, output, cache).
        duration_ms:
          type: integer
          format: int64
          description: Time the request took, in milliseconds.
        prompt_id:
          type: string
          description: Correlates requests belonging to one prompt; empty when the provider does not report it.
      description: A single request within a session's timeline.
    LLMSessionTimelineResponse:
      type: object
      required:
        - items
        - meta
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/LLMSessionTimelineItem'
          description: The items in this page.
        meta:
          $ref: '#/components/schemas/PaginationMeta'
      description: One page of a session's per-request timeline.
    LLMTokenRankItem:
      type: object
      required:
        - name
        - tokens
      properties:
        name:
          type: string
          description: Display name of the ranked user or model.
        tokens:
          type: integer
          format: int64
          description: Tokens used, the value this ranking is sorted by.
      description: A user or model ranked by token usage.
    LLMTokenRankResponse:
      type: object
      required:
        - items
        - meta
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/LLMTokenRankItem'
          description: The items in this page.
        meta:
          $ref: '#/components/schemas/PaginationMeta'
      description: Ranked list by token usage.
    LLMTokenTypeItem:
      type: object
      required:
        - type
        - tokens
      properties:
        type:
          type: string
          description: Token category, such as `input`, `output`, or `cache`.
        tokens:
          type: integer
          format: int64
          description: Tokens used in this category.
      description: Token usage broken down by token type.
    LLMTokensTotalResponse:
      type: object
      required:
        - total
        - by_type
      properties:
        total:
          type: integer
          format: int64
          description: Total tokens used across all matching telemetry.
        by_type:
          type: array
          items:
            $ref: '#/components/schemas/LLMTokenTypeItem'
          description: Token totals split by category (input, output, cache).
      description: Total token usage with per-type breakdown.
    LLMUserCostItem:
      type: object
      required:
        - name
        - cost
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        name:
          type: string
          description: User's display name.
        cost:
          type: number
          format: double
          description: LLM token spend in USD for this user.
      description: A gateway user ranked by cost (USD).
    LLMUserCostResponse:
      type: object
      required:
        - items
        - meta
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/LLMUserCostItem'
          description: The items in this page.
        meta:
          $ref: '#/components/schemas/PaginationMeta'
      description: Ranked list of users by cost (USD).
    LLMUserTokenItem:
      type: object
      required:
        - name
        - tokens
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        name:
          type: string
          description: User's display name.
        tokens:
          type: integer
          format: int64
          description: Tokens used by this user.
      description: A gateway user ranked by token usage.
    LLMUserTokenResponse:
      type: object
      required:
        - items
        - meta
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/LLMUserTokenItem'
          description: The items in this page.
        meta:
          $ref: '#/components/schemas/PaginationMeta'
      description: Ranked list of users by token usage.
    Mcp:
      type: object
      required:
        - id
        - origin
        - config
        - created_at
        - updated_at
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          readOnly: true
        origin:
          $ref: '#/components/schemas/McpOrigin'
        kind:
          allOf:
            - $ref: '#/components/schemas/McpKind'
          readOnly: true
        display_name:
          type: string
          description: Name shown for this resource. For catalog resources it comes from the catalog entry.
          readOnly: true
        server_url:
          type: string
          format: uri
          description: The upstream server's URL. For catalog resources it comes from the catalog entry.
          readOnly: true
        gateway_url:
          type: string
          format: uri
          description: Per-org gateway URL agents use to reach just this resource.
          readOnly: true
        available_tools:
          type: array
          items:
            $ref: '#/components/schemas/McpCatalogTool'
          description: Tools this resource exposes to agents.
          readOnly: true
        config:
          $ref: '#/components/schemas/McpConfig'
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
      description: An MCP (Model Context Protocol) server configuration.
    McpApiKeyAuth:
      type: object
      required:
        - key_scope
        - has_headers
      properties:
        key_scope:
          allOf:
            - $ref: '#/components/schemas/ApiKeyScope'
          description: Whether the key is shared across the org or each user provides their own.
          default: shared
        has_headers:
          type: boolean
          description: Whether an API key has been configured.
          readOnly: true
    McpApiKeyAuthCreate:
      type: object
      required:
        - key_scope
      properties:
        key_scope:
          allOf:
            - $ref: '#/components/schemas/ApiKeyScope'
          description: Whether the key is shared across the org or each user provides their own.
          default: shared
        headers:
          type: object
          additionalProperties:
            type: string
          description: Header names and values that carry the API key, sent with each request. Write-only.
    McpApiKeyAuthUpdate:
      type: object
      properties:
        key_scope:
          allOf:
            - $ref: '#/components/schemas/ApiKeyScope'
          description: Whether the key is shared across the org or each user provides their own.
          default: shared
        headers:
          type: object
          additionalProperties:
            type: string
          description: Header names and values that carry the API key, sent with each request. Write-only.
    McpAuthConfig:
      anyOf:
        - $ref: '#/components/schemas/McpOAuth2Auth'
        - $ref: '#/components/schemas/McpApiKeyAuth'
        - $ref: '#/components/schemas/McpNoAuth'
    McpAuthConfigCreate:
      anyOf:
        - $ref: '#/components/schemas/McpOAuth2AuthCreate'
        - $ref: '#/components/schemas/McpApiKeyAuthCreate'
        - $ref: '#/components/schemas/McpNoAuth'
    McpAuthConfigUpdate:
      anyOf:
        - $ref: '#/components/schemas/McpOAuth2AuthUpdate'
        - $ref: '#/components/schemas/McpApiKeyAuthUpdate'
        - $ref: '#/components/schemas/McpNoAuth'
    McpAuthType:
      type: string
      enum:
        - oauth2
        - api_key
        - none
      description: How the gateway authenticates to a resource.
    McpAuthorizeRequest:
      type: object
      required:
        - mcp_id
      properties:
        mcp_id:
          $ref: '#/components/schemas/uuid'
        redirect_to:
          type: string
          description: Where to send the user after they finish signing in.
    McpAuthorizeResponse:
      type: object
      required:
        - authorization_url
      properties:
        authorization_url:
          type: string
          format: uri
          description: URL to send the user to so they can sign in and grant access.
    McpCatalogCategory:
      type: string
      enum:
        - communication
        - project-management
        - developer-tools
        - productivity
        - knowledge
        - sales
        - testing
      description: Functional grouping used to browse the catalog.
    McpCatalogItem:
      type: object
      required:
        - slug
        - kind
        - category
        - display_name
        - description
        - scopes
        - available_tools
        - supported_modes
        - mode_setup
      properties:
        slug:
          type: string
          minLength: 1
          maxLength: 255
          description: Unique slug identifying this catalog integration (e.g. "slack", "jira").
        kind:
          $ref: '#/components/schemas/McpKind'
        category:
          $ref: '#/components/schemas/McpCatalogCategory'
        display_name:
          type: string
          minLength: 1
          maxLength: 255
          description: Name shown in the catalog.
        description:
          type: string
          description: What the service is.
        scopes:
          type: array
          items:
            type: string
          description: OAuth scopes the integration requests when a user connects.
        available_tools:
          type: array
          items:
            $ref: '#/components/schemas/McpCatalogTool'
          description: Tools this integration exposes to agents.
        supported_modes:
          type: array
          items:
            $ref: '#/components/schemas/CatalogMcpMode'
          description: Credential modes this entry can be installed with.
        mode_setup:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/McpCatalogModeSetup'
          description: Per-mode setup metadata. Keyed by CatalogMcpMode. Contains an entry for every mode in supportedModes.
    McpCatalogList:
      type: object
      required:
        - items
        - byo_redirect_uri
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/McpCatalogItem'
        byo_redirect_uri:
          type: string
          format: uri
          description: OAuth callback URL the gateway will use for catalog BYO installs. Same for every entry.
    McpCatalogModeSetup:
      type: object
      required:
        - docs_url
        - requires_setup
      properties:
        docs_url:
          type: string
          format: uri
          description: Deep link to the AISG docs anchor for this mode.
        requires_setup:
          type: boolean
          description: True when the admin must complete setup steps before users can connect.
    McpCatalogTool:
      type: object
      required:
        - name
        - description
      properties:
        name:
          type: string
          description: Tool name as exposed to agents.
        description:
          type: string
          description: What the tool does.
        input_schema:
          type: object
          additionalProperties: {}
          description: JSON Schema for the tool's input arguments (tools/call parameters).
    McpConfig:
      anyOf:
        - $ref: '#/components/schemas/CatalogMcpConfig'
        - $ref: '#/components/schemas/CustomMcpConfig'
    McpConfigCreate:
      anyOf:
        - $ref: '#/components/schemas/CatalogMcpConfigCreate'
        - $ref: '#/components/schemas/CustomMcpConfigCreate'
    McpConfigUpdate:
      anyOf:
        - $ref: '#/components/schemas/CatalogMcpConfigUpdate'
        - $ref: '#/components/schemas/CustomMcpConfigUpdate'
    McpCreate:
      type: object
      required:
        - origin
        - config
      properties:
        origin:
          $ref: '#/components/schemas/McpOrigin'
        config:
          $ref: '#/components/schemas/McpConfigCreate'
      description: An MCP (Model Context Protocol) server configuration.
    McpCreatedPayload:
      type: object
      required:
        - display_name
        - slug
        - origin
      properties:
        display_name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        slug:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        origin:
          allOf:
            - $ref: '#/components/schemas/McpOrigin'
          x-oapi-codegen-extra-tags:
            scope: all
      description: Recorded when a resource (MCP server) is added to the catalog.
    McpDeletedPayload:
      type: object
      required:
        - display_name
        - slug
      properties:
        display_name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        slug:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
      description: Recorded when a resource (MCP server) is removed from the catalog.
    McpKind:
      type: string
      enum:
        - builtin
        - external
      description: Where a resource comes from.
    McpList:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Mcp'
    McpNoAuth:
      type: object
    McpOAuth2Auth:
      type: object
      properties:
        dcr:
          type: boolean
          description: Let the gateway register its own OAuth client with the server automatically, instead of you supplying one.
        client_id:
          type: string
          maxLength: 255
          description: OAuth client ID from your own OAuth app.
        token_url:
          type: string
          maxLength: 2048
          format: uri
          description: The server's OAuth token endpoint.
        scopes:
          type: array
          items:
            $ref: '#/components/schemas/OAuthScope'
          maxItems: 50
          description: OAuth scopes to request from the server.
        grant_type:
          $ref: '#/components/schemas/OAuthGrantType'
        token_endpoint_auth_method:
          allOf:
            - $ref: '#/components/schemas/OAuthTokenEndpointAuthMethod'
          description: How client credentials are sent to the token endpoint.
        authorize_url:
          type: string
          maxLength: 2048
          format: uri
          description: The server's OAuth authorization endpoint.
        issuer_url:
          type: string
          maxLength: 2048
          format: uri
          description: The server's OAuth issuer, used to discover its endpoints automatically.
    McpOAuth2AuthCreate:
      type: object
      properties:
        dcr:
          type: boolean
          description: Let the gateway register its own OAuth client with the server automatically, instead of you supplying one.
        client_id:
          type: string
          maxLength: 255
          description: OAuth client ID from your own OAuth app.
        client_secret:
          type: string
          maxLength: 1000
          description: OAuth client secret from your own OAuth app. Write-only.
        token_url:
          type: string
          maxLength: 2048
          format: uri
          description: The server's OAuth token endpoint.
        scopes:
          type: array
          items:
            $ref: '#/components/schemas/OAuthScope'
          maxItems: 50
          description: OAuth scopes to request from the server.
        grant_type:
          $ref: '#/components/schemas/OAuthGrantType'
        token_endpoint_auth_method:
          allOf:
            - $ref: '#/components/schemas/OAuthTokenEndpointAuthMethod'
          description: How client credentials are sent to the token endpoint.
        authorize_url:
          type: string
          maxLength: 2048
          format: uri
          description: The server's OAuth authorization endpoint.
        issuer_url:
          type: string
          maxLength: 2048
          format: uri
          description: The server's OAuth issuer, used to discover its endpoints automatically.
    McpOAuth2AuthUpdate:
      type: object
      properties:
        client_id:
          type: string
          maxLength: 255
          description: OAuth client ID from your own OAuth app.
        client_secret:
          type: string
          maxLength: 1000
          description: OAuth client secret from your own OAuth app. Write-only.
        token_url:
          type: string
          maxLength: 2048
          format: uri
          description: The server's OAuth token endpoint.
        scopes:
          type: array
          items:
            $ref: '#/components/schemas/OAuthScope'
          maxItems: 50
          description: OAuth scopes to request from the server.
        grant_type:
          $ref: '#/components/schemas/OAuthGrantType'
        token_endpoint_auth_method:
          allOf:
            - $ref: '#/components/schemas/OAuthTokenEndpointAuthMethod'
          description: How client credentials are sent to the token endpoint.
        authorize_url:
          type: string
          maxLength: 2048
          format: uri
          description: The server's OAuth authorization endpoint.
        issuer_url:
          type: string
          maxLength: 2048
          format: uri
          description: The server's OAuth issuer, used to discover its endpoints automatically.
    McpOrigin:
      type: string
      enum:
        - catalog
        - custom
      description: How this resource was added to the gateway.
    McpTagAssignedPayload:
      type: object
      required:
        - mcp_id
        - mcp_display_name
        - tag_names
      properties:
        mcp_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_display_name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        tag_names:
          type: array
          items:
            type: string
          description: The full set of tag names on the resource after the change.
          x-oapi-codegen-extra-tags:
            scope: all
      description: |-
        Recorded when the set of tags on a resource (MCP server) changes. Lists the
        full tag set after the change, by name so the feed stays readable after a
        later rename or delete.
    McpToolCallScope:
      type: object
      properties:
        mcp_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          nullable: true
        agent_slugs:
          type: array
          items:
            type: string
          nullable: true
        agent_instance_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          nullable: true
        user_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          nullable: true
        groups:
          type: array
          items:
            type: string
          nullable: true
        agent_slug_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          nullable: true
        mcp_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          nullable: true
        tool_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          nullable: true
        tool_patterns:
          type: array
          items:
            type: string
          nullable: true
          description: 'Glob patterns for tool names. Empty or absent means any tool (access policies override this: they require a tool constraint).'
        condition:
          type: string
          nullable: true
          description: Optional CEL expression evaluated per call to narrow the match beyond the static selectors above. Its variables are the MCP tool-call context.
        condition_description:
          type: string
          nullable: true
          description: Human-readable summary of `condition`, shown in place of the raw CEL expression. Cleared whenever the expression changes.
      description: |-
        Selects MCP tool calls — the shared selector for access policies and DLP
        rules: which agents, users, groups, MCPs, and tools (the static fields),
        optionally narrowed by a per-call CEL `condition`. Empty static fields mean
        any. The selector is specific to the MCP tool-call execution context; an
        LLM-family selector (models, providers, with its own condition) will be a
        sibling model, not additional fields here.
    McpToolCallScopeSnapshot:
      type: object
      required:
        - mcp_ids
        - agent_slugs
        - agent_instance_ids
        - user_ids
        - groups
        - agent_slug_tag_ids
        - mcp_tag_ids
        - tool_tag_ids
        - tool_patterns
      properties:
        mcp_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Resources the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_slugs:
          type: array
          items:
            type: string
          description: Agents the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_instance_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Specific agent instances the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        user_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Users the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        groups:
          type: array
          items:
            type: string
          description: User groups the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_slug_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Agents matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Resources matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        tool_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Tools matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        tool_patterns:
          type: array
          items:
            type: string
          description: Name patterns matching the tools the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        condition:
          type: string
          description: Additional condition that had to hold for the rule to apply.
          x-oapi-codegen-extra-tags:
            scope: all
        condition_description:
          type: string
          description: Human-readable explanation of the condition.
          x-oapi-codegen-extra-tags:
            scope: all
      description: |-
        The set of agents, users, resources, and tools a rule applied to, captured as
        it stood at the time of the event. An empty list for a dimension means the
        rule was not narrowed by that dimension.
    McpUpdate:
      type: object
      properties:
        config:
          $ref: '#/components/schemas/McpConfigUpdate'
      description: An MCP (Model Context Protocol) server configuration.
    McpUpdatedPayload:
      type: object
      properties:
        display_name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        slug:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
      description: Recorded when a resource (MCP server) is changed.
    OAuthGrantType:
      type: string
      enum:
        - client_credentials
        - authorization_code
      description: Whether calls use a single org-wide credential or each user's own sign-in.
    OAuthScope:
      type: string
      maxLength: 255
    OAuthTokenEndpointAuthMethod:
      type: string
      enum:
        - client_secret_basic
        - client_secret_post
        - none
      description: How the client secret is presented to the OAuth token endpoint. Unset = auto-detect.
    PaginationMeta:
      type: object
      required:
        - total
        - offset
        - limit
      properties:
        total:
          type: integer
          format: int32
          description: Total number of items matching the query, across all pages.
        offset:
          type: integer
          format: int32
          description: Number of items skipped before this page.
        limit:
          type: integer
          format: int32
          description: Maximum number of items in this page.
      description: Paging information for a list response.
    Permission:
      type: string
      enum:
        - view_agents
        - view_agent_instances
        - manage_agent_instances
        - view_mcps
        - manage_mcps
        - view_policies
        - manage_policies
        - view_data_protection
        - manage_data_protection
        - view_topology
        - view_audit
        - view_tool_analytics
        - view_agent_analytics
        - view_user_analytics
        - view_mcp_analytics
        - view_policy_analytics
        - view_llm_analytics
        - view_anomaly_detection
        - manage_anomaly_detection
        - view_users
        - manage_connections
        - view_tags
        - manage_tags
        - manage_ingest_keys
        - view_webhooks
        - manage_webhooks
      description: An action the caller is allowed to perform in the workspace.
    Permissions:
      type: object
      required:
        - grants
        - user_id
      properties:
        grants:
          type: array
          items:
            $ref: '#/components/schemas/Grant'
          description: The permissions the caller holds.
        user_id:
          $ref: '#/components/schemas/uuid'
      description: The current caller's identity and everything they are allowed to do.
    Policy:
      type: object
      required:
        - id
        - priority
        - tool_patterns
        - effect
        - name
        - created_at
        - updated_at
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          readOnly: true
        priority:
          type: integer
          format: int32
          description: 'Position in the evaluation order: lower numbers are checked first. Set it with the reorder endpoint.'
          readOnly: true
        mcp_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          nullable: true
        agent_slugs:
          type: array
          items:
            type: string
          nullable: true
        agent_instance_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          nullable: true
        user_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          nullable: true
        groups:
          type: array
          items:
            type: string
          nullable: true
        agent_slug_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          nullable: true
        mcp_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          nullable: true
        tool_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          nullable: true
        condition:
          type: string
          nullable: true
          description: Optional CEL expression evaluated per call to narrow the match beyond the static selectors above. Its variables are the MCP tool-call context.
        condition_description:
          type: string
          nullable: true
          description: Human-readable summary of `condition`, shown in place of the raw CEL expression. Cleared whenever the expression changes.
        tool_patterns:
          type: array
          items:
            type: string
          description: 'Tool names or glob patterns this rule governs. Required: a rule must name the tools it covers.'
        effect:
          $ref: '#/components/schemas/PolicyEffect'
        status:
          $ref: '#/components/schemas/PolicyStatus'
        name:
          type: string
          description: Short label for the rule, shown in the policy list.
        description:
          type: string
          nullable: true
          description: Optional note explaining the rule's intent.
        agent_instance_refs:
          type: array
          items:
            $ref: '#/components/schemas/AgentInstanceRef'
          description: Running agent instances this rule's scope currently resolves to.
          readOnly: true
        user_refs:
          type: array
          items:
            $ref: '#/components/schemas/UserRef'
          description: Users this rule's scope currently resolves to.
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
      description: |-
        One rule in the ordered list that decides which tools an agent may call, for
        which users, under what conditions. Rules are evaluated top to bottom and the
        first match wins; a request that matches no rule is denied by default.
    PolicyAgentAccess:
      type: object
      required:
        - mcps
      properties:
        agent_instance_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          description: Present when the access was computed for a specific agent instance.
        agent_slug:
          type: string
          description: Present when the access was computed for a catalog agent type by slug.
        mcps:
          type: array
          items:
            $ref: '#/components/schemas/PolicyMcpAccess'
    PolicyAgentAccessStats:
      type: object
      required:
        - agent_slug
        - allowed
        - denied
        - conditional
      properties:
        agent_slug:
          type: string
        allowed:
          type: integer
          format: int32
          description: Number of tools the agent can call.
        denied:
          type: integer
          format: int32
          description: Number of tools blocked for the agent.
        conditional:
          type: integer
          format: int32
          description: Number of tools allowed only when a condition holds.
      description: Per-agent-type tally of how its tools resolve across all policies.
    PolicyAgentAccessStatsList:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/PolicyAgentAccessStats'
    PolicyContext:
      type: object
      required:
        - agent
        - user
        - mcp
      properties:
        agent:
          $ref: '#/components/schemas/PolicyContextAgent'
        user:
          $ref: '#/components/schemas/PolicyContextUser'
        mcp:
          $ref: '#/components/schemas/PolicyContextMcp'
        request:
          allOf:
            - $ref: '#/components/schemas/PolicyContextRequest'
          description: The request being authorized; tool arguments live under `args`.
      description: Runtime context available to policy condition expressions.
    PolicyContextAgent:
      type: object
      required:
        - id
        - name
        - slug
      properties:
        id:
          type: string
        name:
          type: string
        slug:
          type: string
          description: Catalog slug identifying the agent's product.
        tags:
          type: array
          items:
            type: string
          description: Tag names assigned to this agent's product slug.
      description: The calling agent, addressable as `agent.*` in CEL.
    PolicyContextMcp:
      type: object
      required:
        - id
        - name
        - slug
      properties:
        id:
          type: string
        name:
          type: string
        slug:
          type: string
        tags:
          type: array
          items:
            type: string
          description: Tag names assigned to this MCP server.
        tool:
          allOf:
            - $ref: '#/components/schemas/PolicyContextTool'
          description: The specific tool being called on this MCP server.
      description: The MCP server being called, addressable as `mcp.*` in CEL.
    PolicyContextRequest:
      type: object
      properties:
        args:
          type: object
          additionalProperties: {}
          description: Tool-call arguments — fields come from the matched tools' InputSchemas.
      description: Request-shaped context addressable as `request.*` in CEL.
    PolicyContextTool:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Name of the tool being called.
        tags:
          type: array
          items:
            type: string
          description: Tag names assigned to this specific tool.
      description: The specific tool being called, addressable as `mcp.tool.*` in CEL.
    PolicyContextUser:
      type: object
      required:
        - id
        - name
        - email
        - groups
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
        groups:
          type: array
          items:
            type: string
          description: Group memberships, for matching a rule to a set of users.
      description: The end user on whose behalf the agent is acting, addressable as `user.*` in CEL.
    PolicyCreatedPayload:
      type: object
      required:
        - policy_id
        - name
        - mcp_ids
        - agent_slugs
        - agent_instance_ids
        - user_ids
        - groups
        - agent_slug_tag_ids
        - mcp_tag_ids
        - tool_tag_ids
        - tool_patterns
        - effect
      properties:
        policy_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Resources the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_slugs:
          type: array
          items:
            type: string
          description: Agents the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_instance_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Specific agent instances the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        user_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Users the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        groups:
          type: array
          items:
            type: string
          description: User groups the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_slug_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Agents matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Resources matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        tool_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Tools matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        tool_patterns:
          type: array
          items:
            type: string
          description: Name patterns matching the tools the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        condition:
          type: string
          description: Additional condition that had to hold for the rule to apply.
          x-oapi-codegen-extra-tags:
            scope: all
        condition_description:
          type: string
          description: Human-readable explanation of the condition.
          x-oapi-codegen-extra-tags:
            scope: all
        effect:
          allOf:
            - $ref: '#/components/schemas/PolicyEffect'
          x-oapi-codegen-extra-tags:
            scope: all
      description: Recorded when a policy rule is created.
    PolicyDeletedPayload:
      type: object
      required:
        - policy_id
        - name
        - mcp_ids
        - agent_slugs
        - agent_instance_ids
        - user_ids
        - groups
        - agent_slug_tag_ids
        - mcp_tag_ids
        - tool_tag_ids
        - tool_patterns
        - effect
      properties:
        policy_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Resources the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_slugs:
          type: array
          items:
            type: string
          description: Agents the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_instance_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Specific agent instances the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        user_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Users the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        groups:
          type: array
          items:
            type: string
          description: User groups the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_slug_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Agents matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Resources matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        tool_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Tools matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        tool_patterns:
          type: array
          items:
            type: string
          description: Name patterns matching the tools the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        condition:
          type: string
          description: Additional condition that had to hold for the rule to apply.
          x-oapi-codegen-extra-tags:
            scope: all
        condition_description:
          type: string
          description: Human-readable explanation of the condition.
          x-oapi-codegen-extra-tags:
            scope: all
        effect:
          allOf:
            - $ref: '#/components/schemas/PolicyEffect'
          x-oapi-codegen-extra-tags:
            scope: all
      description: Recorded when a policy rule is deleted.
    PolicyEffect:
      type: string
      enum:
        - allow
        - deny
      description: Whether a matching rule permits or blocks the call.
    PolicyEventPayload:
      type: object
      required:
        - policy_id
        - name
        - mcp_ids
        - agent_slugs
        - agent_instance_ids
        - user_ids
        - groups
        - agent_slug_tag_ids
        - mcp_tag_ids
        - tool_tag_ids
        - tool_patterns
        - effect
      properties:
        policy_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Resources the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_slugs:
          type: array
          items:
            type: string
          description: Agents the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_instance_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Specific agent instances the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        user_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Users the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        groups:
          type: array
          items:
            type: string
          description: User groups the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_slug_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Agents matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Resources matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        tool_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Tools matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        tool_patterns:
          type: array
          items:
            type: string
          description: Name patterns matching the tools the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        condition:
          type: string
          description: Additional condition that had to hold for the rule to apply.
          x-oapi-codegen-extra-tags:
            scope: all
        condition_description:
          type: string
          description: Human-readable explanation of the condition.
          x-oapi-codegen-extra-tags:
            scope: all
        effect:
          allOf:
            - $ref: '#/components/schemas/PolicyEffect'
          x-oapi-codegen-extra-tags:
            scope: all
      description: 'Snapshot of a policy rule shared by all policy audit events: its identity, scope, and allow-or-deny effect.'
    PolicyList:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Policy'
    PolicyMcpAccess:
      type: object
      required:
        - mcp_id
        - slug
        - display_name
        - tools
      properties:
        mcp_id:
          $ref: '#/components/schemas/uuid'
        slug:
          type: string
        display_name:
          type: string
        tools:
          type: array
          items:
            $ref: '#/components/schemas/PolicyToolAccess'
      description: Access to one MCP server and its tools, as resolved for the agent.
    PolicyReorderRequest:
      type: object
      properties:
        after_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          description: Place this policy immediately after the policy with this ID.
        before_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          description: Place this policy immediately before the policy with this ID.
    PolicyReorderedPayload:
      type: object
      required:
        - policy_id
        - name
        - mcp_ids
        - agent_slugs
        - agent_instance_ids
        - user_ids
        - groups
        - agent_slug_tag_ids
        - mcp_tag_ids
        - tool_tag_ids
        - tool_patterns
        - effect
      properties:
        policy_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Resources the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_slugs:
          type: array
          items:
            type: string
          description: Agents the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_instance_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Specific agent instances the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        user_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Users the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        groups:
          type: array
          items:
            type: string
          description: User groups the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_slug_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Agents matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Resources matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        tool_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Tools matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        tool_patterns:
          type: array
          items:
            type: string
          description: Name patterns matching the tools the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        condition:
          type: string
          description: Additional condition that had to hold for the rule to apply.
          x-oapi-codegen-extra-tags:
            scope: all
        condition_description:
          type: string
          description: Human-readable explanation of the condition.
          x-oapi-codegen-extra-tags:
            scope: all
        effect:
          allOf:
            - $ref: '#/components/schemas/PolicyEffect'
          x-oapi-codegen-extra-tags:
            scope: all
      description: Recorded when policy rules are reordered, changing the order they are evaluated in.
    PolicySchemaField:
      type: object
      required:
        - type
        - description
      properties:
        type:
          type: string
          description: Field type (e.g. "string", "integer", "object").
        description:
          type: string
          description: Human-readable description.
        fields:
          allOf:
            - type: object
              additionalProperties:
                $ref: '#/components/schemas/PolicySchemaField'
          description: Nested fields when type is "object". Absent for primitive types.
    PolicySchemaResponse:
      type: object
      required:
        - variables
      properties:
        variables:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PolicySchemaVariable'
          description: Available variables and their fields.
    PolicySchemaVariable:
      type: object
      required:
        - description
        - fields
      properties:
        description:
          type: string
          description: Human-readable description of the variable.
        fields:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PolicySchemaField'
          description: 'Fields within this variable. Empty when `dynamic: true`.'
        dynamic:
          type: boolean
          description: If true, fields are resolved by the frontend from policy scope (matched tools' InputSchemas).
    PolicyStatus:
      type: string
      enum:
        - active
        - draft
        - disabled
      description: Whether a policy takes part in evaluation.
    PolicyToolAccess:
      type: object
      required:
        - name
        - description
        - status
      properties:
        name:
          type: string
        description:
          type: string
        status:
          $ref: '#/components/schemas/PolicyToolStatus'
        policy:
          allOf:
            - $ref: '#/components/schemas/Policy'
          description: The policy rule that decided this tool's access; absent when denied by default.
      description: Access to a single tool, as resolved for the agent.
    PolicyToolStatus:
      type: string
      enum:
        - allowed
        - denied
        - conditional
      description: Whether a tool is reachable for the agent, and whether that depends on a condition.
    PolicyUpdate:
      type: object
      properties:
        mcp_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          nullable: true
        agent_slugs:
          type: array
          items:
            type: string
          nullable: true
        agent_instance_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          nullable: true
        user_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          nullable: true
        groups:
          type: array
          items:
            type: string
          nullable: true
        agent_slug_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          nullable: true
        mcp_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          nullable: true
        tool_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          nullable: true
        condition:
          type: string
          nullable: true
          description: Optional CEL expression evaluated per call to narrow the match beyond the static selectors above. Its variables are the MCP tool-call context.
        condition_description:
          type: string
          nullable: true
          description: Human-readable summary of `condition`, shown in place of the raw CEL expression. Cleared whenever the expression changes.
        tool_patterns:
          type: array
          items:
            type: string
          description: 'Tool names or glob patterns this rule governs. Required: a rule must name the tools it covers.'
        effect:
          $ref: '#/components/schemas/PolicyEffect'
        status:
          $ref: '#/components/schemas/PolicyStatus'
        name:
          type: string
          description: Short label for the rule, shown in the policy list.
        description:
          type: string
          nullable: true
          description: Optional note explaining the rule's intent.
      description: |-
        One rule in the ordered list that decides which tools an agent may call, for
        which users, under what conditions. Rules are evaluated top to bottom and the
        first match wins; a request that matches no rule is denied by default.
    PolicyUpdatedPayload:
      type: object
      required:
        - policy_id
        - name
        - mcp_ids
        - agent_slugs
        - agent_instance_ids
        - user_ids
        - groups
        - agent_slug_tag_ids
        - mcp_tag_ids
        - tool_tag_ids
        - tool_patterns
        - effect
      properties:
        policy_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Resources the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_slugs:
          type: array
          items:
            type: string
          description: Agents the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_instance_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Specific agent instances the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        user_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Users the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        groups:
          type: array
          items:
            type: string
          description: User groups the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        agent_slug_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Agents matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Resources matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        tool_tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: Tools matched by tag rather than named directly.
          x-oapi-codegen-extra-tags:
            scope: all
        tool_patterns:
          type: array
          items:
            type: string
          description: Name patterns matching the tools the rule applied to.
          x-oapi-codegen-extra-tags:
            scope: all
        condition:
          type: string
          description: Additional condition that had to hold for the rule to apply.
          x-oapi-codegen-extra-tags:
            scope: all
        condition_description:
          type: string
          description: Human-readable explanation of the condition.
          x-oapi-codegen-extra-tags:
            scope: all
        effect:
          allOf:
            - $ref: '#/components/schemas/PolicyEffect'
          x-oapi-codegen-extra-tags:
            scope: all
      description: Recorded when a policy rule is changed.
    RedactionRef:
      type: object
      required:
        - rule_id
        - rule_name
        - matches
      properties:
        rule_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        rule_name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        matches:
          type: integer
          format: int32
          description: How many spans the rule redacted.
          x-oapi-codegen-extra-tags:
            scope: all
      description: A data-loss-prevention rule that redacted content from a tool response, with a count of matches but never the redacted text.
    Scope:
      type: string
      enum:
        - all
        - own
      description: How far a permission reaches.
    SortOrder:
      type: string
      enum:
        - asc
        - desc
      description: Direction to sort results.
    Tag:
      type: object
      required:
        - id
        - namespace
        - name
        - color
        - created_at
        - updated_at
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          readOnly: true
        namespace:
          $ref: '#/components/schemas/TagNamespace'
        name:
          type: string
          minLength: 1
          maxLength: 50
          description: Label text, unique within the namespace.
        color:
          $ref: '#/components/schemas/TagColor'
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
      description: |-
        A named, colored label attached to agents or resources, used to write policy
        rules that match a class of entities instead of naming each one. A tag's
        `name` must be unique within its namespace, and its namespace is fixed once
        created.
    TagAssignment:
      type: object
      required:
        - target_key
        - tag_ids
      properties:
        target_key:
          type: string
          description: Identifies the tagged entity within its target type.
        tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          description: IDs of the tags assigned to this target.
      description: The tags currently assigned to one target.
    TagAssignmentList:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/TagAssignment'
    TagAssignmentSet:
      type: object
      required:
        - tag_ids
      properties:
        tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/uuid'
          maxItems: 100
          description: IDs of the tags to assign. Replaces any tags already on the target.
      description: The complete set of tags to assign to a target.
    TagColor:
      type: string
      enum:
        - red
        - orange
        - amber
        - yellow
        - lime
        - green
        - emerald
        - teal
        - cyan
        - sky
        - blue
        - violet
      description: Color a tag is displayed with.
    TagCreate:
      type: object
      required:
        - namespace
        - name
        - color
      properties:
        namespace:
          $ref: '#/components/schemas/TagNamespace'
        name:
          type: string
          minLength: 1
          maxLength: 50
          description: Label text, unique within the namespace.
        color:
          $ref: '#/components/schemas/TagColor'
      description: Fields for creating a tag.
    TagCreatedPayload:
      type: object
      required:
        - tag_id
        - name
        - namespace
        - color
      properties:
        tag_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        namespace:
          allOf:
            - $ref: '#/components/schemas/TagNamespace'
          x-oapi-codegen-extra-tags:
            scope: all
        color:
          allOf:
            - $ref: '#/components/schemas/TagColor'
          x-oapi-codegen-extra-tags:
            scope: all
      description: Recorded when a tag is created.
    TagDeletedPayload:
      type: object
      required:
        - tag_id
        - name
        - namespace
        - color
      properties:
        tag_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        namespace:
          allOf:
            - $ref: '#/components/schemas/TagNamespace'
          x-oapi-codegen-extra-tags:
            scope: all
        color:
          allOf:
            - $ref: '#/components/schemas/TagColor'
          x-oapi-codegen-extra-tags:
            scope: all
      description: Recorded when a tag is deleted.
    TagEventPayload:
      type: object
      required:
        - tag_id
        - name
        - namespace
        - color
      properties:
        tag_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        namespace:
          allOf:
            - $ref: '#/components/schemas/TagNamespace'
          x-oapi-codegen-extra-tags:
            scope: all
        color:
          allOf:
            - $ref: '#/components/schemas/TagColor'
          x-oapi-codegen-extra-tags:
            scope: all
      description: Identity and appearance of a tag, shared by all tag audit events.
    TagList:
      type: object
      required:
        - items
        - meta
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
          description: The items in this page.
        meta:
          $ref: '#/components/schemas/PaginationMeta'
      description: A page of results together with its paging information.
    TagNamespace:
      type: string
      enum:
        - agent
        - resource
      description: Which kind of entity a tag can be applied to. A tag belongs to exactly one namespace.
    TagSortBy:
      type: string
      enum:
        - name
        - created_at
      description: Field to sort a list of tags by.
    TagTargetType:
      type: string
      enum:
        - agent_slug
        - mcp
        - tool
      description: The kind of entity a tag is assigned to.
    TagUpdate:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 50
          description: New label text, unique within the namespace.
        color:
          $ref: '#/components/schemas/TagColor'
      description: Fields for updating a tag. Omitted fields are left unchanged; namespace cannot be changed.
    TagUpdatedPayload:
      type: object
      required:
        - tag_id
        - name
        - namespace
        - color
      properties:
        tag_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        namespace:
          allOf:
            - $ref: '#/components/schemas/TagNamespace'
          x-oapi-codegen-extra-tags:
            scope: all
        color:
          allOf:
            - $ref: '#/components/schemas/TagColor'
          x-oapi-codegen-extra-tags:
            scope: all
      description: Recorded when a tag is changed.
    TagUsage:
      type: object
      required:
        - tag_id
        - mcp_count
        - tool_count
        - agent_slug_count
      properties:
        tag_id:
          $ref: '#/components/schemas/uuid'
        mcp_count:
          type: integer
          format: int32
          description: Number of MCPs the tag is assigned to.
        tool_count:
          type: integer
          format: int32
          description: Number of tools the tag is assigned to.
        agent_slug_count:
          type: integer
          format: int32
          description: Number of agents the tag is assigned to.
      description: How many entities of each type carry a given tag.
    TagUsageList:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/TagUsage'
    TimeSeriesPoint:
      type: object
      required:
        - timestamp
        - count
      properties:
        timestamp:
          type: string
          format: date-time
          description: Start of the time bucket this count covers.
        count:
          type: integer
          format: int64
          description: Number of events in this bucket.
      description: A single data point in a time series.
    TimeSeriesResponse:
      type: object
      required:
        - series
      properties:
        series:
          type: array
          items:
            $ref: '#/components/schemas/TimeSeriesPoint'
          description: Ordered data points, one per time bucket.
      description: Time-bucketed event counts.
    ToolTagAssignedPayload:
      type: object
      required:
        - mcp_id
        - mcp_display_name
        - tool_name
        - tag_names
      properties:
        mcp_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        mcp_display_name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        tool_name:
          type: string
          description: The tool whose tags changed.
          x-oapi-codegen-extra-tags:
            scope: all
        tag_names:
          type: array
          items:
            type: string
          description: The full set of tag names on the tool after the change.
          x-oapi-codegen-extra-tags:
            scope: all
      description: |-
        Recorded when the set of tags on a specific tool changes. Lists the full tag
        set after the change, by name so the feed stays readable after a later rename
        or delete.
    TopAgentInstanceItem:
      type: object
      required:
        - id
        - name
        - count
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        name:
          type: string
          description: Agent instance display name.
        user_name:
          type: string
          description: Display name of the user who authorized the instance.
        user_id:
          $ref: '#/components/schemas/uuid'
        count:
          type: integer
          format: int64
          description: Number of tool calls made by this agent instance.
      description: An agent instance ranked by activity count.
    TopAgentInstancesResponse:
      type: object
      required:
        - items
        - meta
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/TopAgentInstanceItem'
          description: The items in this page.
        meta:
          $ref: '#/components/schemas/PaginationMeta'
      description: Ranked list of agent instances by activity.
    TopMcpItem:
      type: object
      required:
        - id
        - name
        - slug
        - count
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        name:
          type: string
          description: MCP server display name.
        slug:
          type: string
        count:
          type: integer
          format: int64
          description: Number of tool calls served by this MCP.
      description: An MCP ranked by tool execution count.
    TopMcpsResponse:
      type: object
      required:
        - items
        - meta
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/TopMcpItem'
          description: The items in this page.
        meta:
          $ref: '#/components/schemas/PaginationMeta'
      description: Ranked list of MCPs by tool execution count.
    TopPoliciesResponse:
      type: object
      required:
        - items
        - meta
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/TopPolicyItem'
          description: The items in this page.
        meta:
          $ref: '#/components/schemas/PaginationMeta'
      description: Ranked list of policies by block count.
    TopPolicyItem:
      type: object
      required:
        - id
        - name
        - count
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        name:
          type: string
          description: Policy rule display name.
        count:
          type: integer
          format: int64
          description: Number of tool calls this policy rule blocked.
      description: A policy ranked by block count.
    TopToolItem:
      type: object
      required:
        - name
        - mcp_id
        - mcp_name
        - mcp_slug
        - count
      properties:
        name:
          type: string
          description: Tool name.
        mcp_id:
          $ref: '#/components/schemas/uuid'
        mcp_name:
          type: string
          description: Parent MCP display name, falling back to its slug.
        mcp_slug:
          type: string
        count:
          type: integer
          format: int64
          description: Number of times the tool was called.
      description: A tool ranked by execution count, with its parent MCP.
    TopToolsResponse:
      type: object
      required:
        - items
        - meta
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/TopToolItem'
          description: The items in this page.
        meta:
          $ref: '#/components/schemas/PaginationMeta'
      description: Ranked list of tools by execution count.
    TopUserItem:
      type: object
      required:
        - id
        - name
        - count
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        name:
          type: string
          description: User's display name.
        count:
          type: integer
          format: int64
          description: Number of tool calls made by this user.
      description: A user ranked by activity count.
    TopUsersResponse:
      type: object
      required:
        - items
        - meta
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/TopUserItem'
          description: The items in this page.
        meta:
          $ref: '#/components/schemas/PaginationMeta'
      description: Ranked list of users by activity.
    TopologyAccessEdge:
      type: object
      required:
        - agent_slug
        - policy_id
        - mcp_id
        - effect
      properties:
        agent_slug:
          type: string
        policy_id:
          type: string
        mcp_id:
          type: string
        effect:
          $ref: '#/components/schemas/TopologyEffect'
      description: 'Resolved access edge: agent type, the deciding policy, the MCP, outcome.'
    TopologyActivityEdge:
      type: object
      required:
        - subject_id
        - agent_slug
        - policy_id
        - mcp_id
        - calls
        - blocked
      properties:
        subject_id:
          type: string
          description: Originating subject id; matches a subjects[] node id (group / user / bucket).
        agent_slug:
          type: string
        policy_id:
          type: string
          description: Deciding policy, or "" when the rollup row carried no policy.
        mcp_id:
          type: string
        calls:
          type: integer
          format: int64
          description: Successful gateway.tool.executed events.
        blocked:
          type: integer
          format: int64
          description: gateway.tool.error events with error_type = blocked_by_policy.
      description: |-
        Real executed traffic for a (agent, policy, mcp) tuple over a recent window,
        split into successful calls and policy-blocked attempts. Drawn on top of the
        static reachability edges as flowing activity.
    TopologyAgent:
      type: object
      required:
        - slug
        - display_name
        - instance_count
        - tag_ids
      properties:
        slug:
          type: string
        display_name:
          type: string
        instance_count:
          type: integer
          format: int64
        tag_ids:
          type: array
          items:
            type: string
          description: Tags applied to this agent type, used to band it into tiers in the graph.
      description: An agent-type node sized by live instance count.
    TopologyEffect:
      type: string
      enum:
        - allow
        - conditional
        - deny
      description: Whether an agent is allowed to reach an MCP.
    TopologyGraph:
      type: object
      required:
        - subjects
        - agents
        - policies
        - mcps
        - subject_agent_edges
        - access_edges
        - activity_edges
        - tags
      properties:
        subjects:
          type: array
          items:
            $ref: '#/components/schemas/TopologySubject'
        agents:
          type: array
          items:
            $ref: '#/components/schemas/TopologyAgent'
        policies:
          type: array
          items:
            $ref: '#/components/schemas/TopologyPolicy'
        mcps:
          type: array
          items:
            $ref: '#/components/schemas/TopologyMcp'
        subject_agent_edges:
          type: array
          items:
            $ref: '#/components/schemas/TopologySubjectAgentEdge'
        access_edges:
          type: array
          items:
            $ref: '#/components/schemas/TopologyAccessEdge'
        activity_edges:
          type: array
          items:
            $ref: '#/components/schemas/TopologyActivityEdge'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/TopologyTag'
      description: The full aggregated topology graph for the caller's org.
    TopologyMcp:
      type: object
      required:
        - id
        - display_name
        - tag_ids
      properties:
        id:
          type: string
        display_name:
          type: string
        tag_ids:
          type: array
          items:
            type: string
          description: Tags applied to this MCP, used to band it into tiers in the graph.
      description: 'An MCP node: an upstream tool server agents can reach.'
    TopologyPolicy:
      type: object
      required:
        - id
        - name
        - effect
        - status
      properties:
        id:
          type: string
        name:
          type: string
        effect:
          $ref: '#/components/schemas/TopologyEffect'
        status:
          type: string
          description: Whether the policy is currently active.
      description: A policy gate, colored by effect.
    TopologySubject:
      type: object
      required:
        - id
        - name
        - kind
        - user_count
      properties:
        id:
          type: string
        name:
          type: string
        kind:
          $ref: '#/components/schemas/TopologySubjectKind'
        user_count:
          type: integer
          format: int64
      description: 'A subject node: a user or group sized by its membership.'
    TopologySubjectAgentEdge:
      type: object
      required:
        - subject_id
        - agent_slug
        - user_count
      properties:
        subject_id:
          type: string
        agent_slug:
          type: string
        user_count:
          type: integer
          format: int64
      description: 'Usage edge: users under a subject that run an agent type.'
    TopologySubjectKind:
      type: string
      enum:
        - group
        - user
        - ungrouped
        - all_users
      description: The kind of subject an origin node represents.
    TopologyTag:
      type: object
      required:
        - id
        - name
        - color
      properties:
        id:
          type: string
        name:
          type: string
        color:
          type: string
      description: 'A resolved tag: id, display name, and color for client-side tier banding.'
    UniqueToolsResponse:
      type: object
      required:
        - count
      properties:
        count:
          type: integer
          format: int64
          description: Number of distinct tools executed.
      description: Count of distinct tools executed in a time range.
    User:
      type: object
      required:
        - id
        - display_name
        - email
        - groups
        - created_at
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        display_name:
          type: string
          description: The user's name as shown in the workspace.
        email:
          type: string
          description: The user's email address.
        groups:
          type: array
          items:
            type: string
          description: Names of the groups the user belongs to.
        created_at:
          type: string
          format: date-time
      description: A person in your organization who signs in and whom agents act on behalf of.
    UserList:
      type: object
      required:
        - items
        - meta
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/User'
          description: The items in this page.
        meta:
          $ref: '#/components/schemas/PaginationMeta'
      description: A page of results together with its paging information.
    UserMcpConnection:
      type: object
      required:
        - id
        - mcp_id
        - status
        - granted_scopes
        - created_at
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          readOnly: true
        mcp_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          readOnly: true
        status:
          allOf:
            - $ref: '#/components/schemas/UserMcpConnectionStatus'
          readOnly: true
        granted_scopes:
          type: array
          items:
            type: string
          description: Scopes the user granted when they connected.
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        last_used_at:
          type: string
          format: date-time
          description: When the connection was last used to make a call.
          readOnly: true
        last_refreshed_at:
          type: string
          format: date-time
          description: When the connection's access was last renewed.
          readOnly: true
    UserMcpConnectionList:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/UserMcpConnectionListItem'
    UserMcpConnectionListItem:
      type: object
      required:
        - mcp_id
        - display_name
        - slug
      properties:
        mcp_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          readOnly: true
        display_name:
          type: string
          description: Name shown to the user.
          readOnly: true
        slug:
          type: string
          description: URL-safe identifier for the resource.
          readOnly: true
        connection:
          allOf:
            - $ref: '#/components/schemas/UserMcpConnection'
          description: The user's active connection to this resource, if they have connected.
          readOnly: true
    UserMcpConnectionStatus:
      type: string
      enum:
        - active
        - expired
        - revoked
      description: Whether a user's connection to a resource is usable.
    UserRef:
      type: object
      required:
        - id
        - display_name
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        display_name:
          type: string
      description: A user referenced by a policy, with their current display name.
    UserSortBy:
      type: string
      enum:
        - created_at
        - display_name
        - email
      description: Field to sort users by.
    ValidationErrorDetail:
      type: object
      required:
        - field
        - message
      properties:
        field:
          type: string
          description: JSON Pointer to the field, e.g. "/display_name"
        message:
          type: string
          description: Human-readable validation failure message
        rule:
          type: string
          description: Schema rule violated, e.g. "required", "minLength", "pattern"
      description: A single field-level validation failure.
    Webhook:
      type: object
      required:
        - id
        - name
        - url
        - events
        - status
        - has_custom_headers
        - created_at
        - updated_at
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        name:
          type: string
          minLength: 1
          maxLength: 255
        url:
          type: string
          description: The endpoint URL events are delivered to.
        events:
          type: array
          items:
            type: string
          description: Audit actions this webhook subscribes to, or `["*"]` for all of them.
        status:
          $ref: '#/components/schemas/WebhookStatus'
        disabled_reason:
          $ref: '#/components/schemas/WebhookDisabledReason'
        failing_since:
          type: string
          format: date-time
          description: When deliveries started failing continuously; cleared once a delivery succeeds.
        last_delivery_status:
          $ref: '#/components/schemas/WebhookDeliveryStatus'
        last_delivery_at:
          type: string
          format: date-time
          description: When the most recent delivery was attempted; absent until the first delivery.
        has_custom_headers:
          type: boolean
          description: Whether custom request headers are configured. The values themselves are never returned.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      description: |-
        A configured webhook. Custom header values are never returned.
        `events` is the set of subscribed audit actions, or `["*"]` for all of them.
    WebhookAuditPayload:
      type: object
      required:
        - webhook_id
        - name
        - url
        - events
      properties:
        webhook_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        url:
          type: string
          description: The endpoint events are delivered to.
          x-oapi-codegen-extra-tags:
            scope: all
        events:
          type: array
          items:
            type: string
          description: The event types the webhook is subscribed to.
          x-oapi-codegen-extra-tags:
            scope: all
      description: Webhook identity and delivery target, shared by the create and update audit events.
    WebhookCreate:
      type: object
      required:
        - name
        - url
        - events
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
        url:
          type: string
          maxLength: 2048
          description: Endpoint URL.
        events:
          type: array
          items:
            type: string
          minItems: 1
          description: Subscribed audit actions, or ["*"] for all. Validated server-side.
        headers:
          type: object
          additionalProperties:
            type: string
          description: Custom request headers; reserved transport names rejected.
      description: |-
        Request body for creating a webhook. Event membership and the
        reserved-header denylist are enforced server-side.
    WebhookCreatedPayload:
      type: object
      required:
        - webhook_id
        - name
        - url
        - events
      properties:
        webhook_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        url:
          type: string
          description: The endpoint events are delivered to.
          x-oapi-codegen-extra-tags:
            scope: all
        events:
          type: array
          items:
            type: string
          description: The event types the webhook is subscribed to.
          x-oapi-codegen-extra-tags:
            scope: all
      description: Recorded when a webhook is created.
    WebhookDeletedPayload:
      type: object
      required:
        - webhook_id
        - name
      properties:
        webhook_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
      description: Recorded when a webhook is deleted.
    WebhookDelivery:
      type: object
      required:
        - id
        - webhook_id
        - status
        - event_count
        - attempt_count
        - attempts
        - created_at
        - updated_at
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        webhook_id:
          $ref: '#/components/schemas/uuid'
        status:
          $ref: '#/components/schemas/WebhookDeliveryStatus'
        event_count:
          type: integer
          format: int32
          description: Number of audit events bundled into this delivery.
        attempt_count:
          type: integer
          format: int32
          description: How many times delivery has been attempted so far.
        attempts:
          type: array
          items:
            $ref: '#/components/schemas/WebhookDeliveryAttempt'
          description: The individual attempts, oldest first.
        next_retry_at:
          type: string
          format: date-time
          description: When the next automatic retry is scheduled; absent when no retry is pending.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      description: One message, sent or sending, bundling one or more audit events.
    WebhookDeliveryAttempt:
      type: object
      required:
        - at
        - duration_ms
      properties:
        at:
          type: string
          format: date-time
          description: When this attempt was made.
        status_code:
          type: integer
          format: int32
          description: HTTP status returned by the endpoint; absent if the endpoint could not be reached.
        error:
          type: string
          description: Reason the attempt failed; absent on success.
        duration_ms:
          type: integer
          format: int64
          description: How long the attempt took, in milliseconds.
        response_snippet:
          type: string
          description: Beginning of the endpoint's response body, kept for troubleshooting.
      description: A single attempt to deliver a message to the endpoint.
    WebhookDeliveryList:
      type: object
      required:
        - items
        - meta
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/WebhookDelivery'
          description: The items in this page.
        meta:
          $ref: '#/components/schemas/PaginationMeta'
      description: A page of results together with its paging information.
    WebhookDeliveryStatus:
      type: string
      enum:
        - pending
        - retrying
        - succeeded
        - failed
      description: Delivery outcome for a single message.
    WebhookDisabledPayload:
      type: object
      required:
        - webhook_id
        - name
        - reason
      properties:
        webhook_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        reason:
          allOf:
            - $ref: '#/components/schemas/WebhookDisabledReason'
          x-oapi-codegen-extra-tags:
            scope: all
      description: Recorded when the gateway disables a webhook automatically after repeated delivery failures.
    WebhookDisabledReason:
      type: string
      enum:
        - circuit_breaker
        - gone
      description: Why a webhook was turned off automatically.
    WebhookList:
      type: object
      required:
        - items
        - meta
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Webhook'
          description: The items in this page.
        meta:
          $ref: '#/components/schemas/PaginationMeta'
      description: A page of results together with its paging information.
    WebhookStatus:
      type: string
      enum:
        - active
        - paused
        - disabled
      description: Whether a webhook is currently delivering events.
    WebhookStatusUpdate:
      type: string
      enum:
        - active
        - paused
      description: Status values a client may PATCH. `disabled` is system-only.
    WebhookUpdate:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
        url:
          type: string
          maxLength: 2048
        events:
          type: array
          items:
            type: string
          minItems: 1
        status:
          $ref: '#/components/schemas/WebhookStatusUpdate'
        headers:
          type: object
          additionalProperties:
            type: string
      description: |-
        PATCH body. `status` covers pause/resume/re-enable (only `active` and
        `paused` are accepted; `disabled` is set by the system). Re-enabling clears
        `disabled_reason` and the failure streak.
    WebhookUpdatedPayload:
      type: object
      required:
        - webhook_id
        - name
        - url
        - events
      properties:
        webhook_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          x-oapi-codegen-extra-tags:
            scope: all
        name:
          type: string
          x-oapi-codegen-extra-tags:
            scope: all
        url:
          type: string
          description: The endpoint events are delivered to.
          x-oapi-codegen-extra-tags:
            scope: all
        events:
          type: array
          items:
            type: string
          description: The event types the webhook is subscribed to.
          x-oapi-codegen-extra-tags:
            scope: all
      description: Recorded when a webhook is changed.
    uuid:
      type: string
      format: uuid
servers:
  - url: '{baseUrl}/api/v1'
    description: API server
    variables:
      baseUrl:
        default: https://localhost:6443
