openapi: 3.1.0
info:
  title: Caylex API Service Documentation
  description: |
    Caylex API Service provides tenant, project, navigator, and analytics management.
    It supports authentication links, server instances, API keys, and member management.
  version: 1.0.0
  license:
    name: Proprietary
    url: https://caylex.ai/license
  x-logo:
    url: https://assets.caylex.ai/logos/caylex.svg
    altText: Caylex
    href: https://caylex.ai
servers:
  - url: https://api.caylex.ai/api/v1
    description: Production server
  - url: https://api.caylex.dev/api/v1
    description: Development server
security:
  - cookieAuth: []
tags:
  - name: Tenants
    description: Tenant information and settings for the authenticated organization
  - name: Navigators
    description: Navigator definitions and configuration
  - name: Navigator Instances
    description: Navigator instances (deployed navigators) within projects
  - name: Projects
    description: Projects, auth links, and project-scoped resources
  - name: Users
    description: User context and activity within projects
  - name: Servers
    description: MCP server definitions, configuration, and logo management
  - name: Server Instances
    description: Server instances connected to projects
  - name: Server Registry
    description: Browse and search available servers in the registry
  - name: API Keys
    description: Project and navigator instance API key management
  - name: Platform Access Tokens
    description: Platform-level access tokens for API authentication
  - name: Analytics
    description: Usage analytics, time series, and reporting endpoints
  - name: Browser Sessions
    description: Remote browser sessions for interactive cookie-based and trace authentication flows
  - name: Queries
    description: Saved and executed queries
  - name: System
    description: System health and deployment information
  - name: Documentation
    description: OpenAPI and documentation assets
  - name: Invite
    description: Invite link validation and acceptance
  - name: Settings
    description: Tenant and deployment settings
  - name: Members
    description: Tenant member management and search
  - name: Notifications
    description: In-app notification inbox, unread counts, and per-user watermarks
  - name: Webhooks
    description: Webhook metadata (event catalogs for outbound integrations)
paths:
  /tenants:
    get:
      tags:
      - Tenants
      summary: Get Current Tenant Information
      operationId: get_tenant_tenants_get
      parameters:
      - name: descope_id
        in: query
        required: true
        schema:
          type: string
          title: Descope Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTenantResponse'
              example:
                id: 123e4567-e89b-12d3-a456-426614174001
                name: acme-corp
                descope_id: D12345678901234567890
                enabled: true
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Retrieve information about the authenticated user's tenant including
        name, plan, and creation date.
  /navigators:
    get:
      tags:
      - Navigators
      summary: List All Navigators
      operationId: list_navigators_navigators_get
      parameters:
      - name: include_analytics
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Include Analytics
      - name: sort_by
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/NavigatorSortBy'
          default: created_desc
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 20
          title: Size
        description: Items per page
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Pagination cursor
          title: Cursor
        description: Pagination cursor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_GetNavigatorResponse_'
              example:
                items:
                - id: 123e4567-e89b-12d3-a456-426614174002
                  name: Customer Support Navigator
                  description: AI navigator for customer support
                  api_name: customer-support-navigator
                  created_at: '2024-01-01T00:00:00Z'
                  updated_at: '2024-01-15T10:30:00Z'
                meta:
                  size: 20
                  total: 100
                  next_cursor: eyJzb3J0Ijog
                  has_next: true
                  has_prev: false
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Retrieve a paginated list of all AI navigators for the authenticated
        user's tenant. Supports filtering by name, sorting by creation date or name,
        and optional analytics inclusion.
    post:
      tags:
      - Navigators
      summary: Create New Navigator
      operationId: create_navigator_navigators_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNavigatorRequest'
            example:
              name: Sales Assistant
              description: AI navigator for sales automation
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateNavigatorResponse'
              example:
                id: 456e7890-e89b-12d3-a456-426614174013
                name: Sales Assistant
                api_name: sales-assistant
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Create a new AI navigator with specified configuration including name,
        description, system prompt, model selection, and temperature settings.
  /navigators/{navigator_id}:
    get:
      tags:
      - Navigators
      summary: Get Navigator Details
      description: Retrieve navigator identity details using a navigator ID.
      operationId: get_navigator_navigators__navigator_id__get
      parameters:
      - name: navigator_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Navigator Id
        description: The unique identifier of the navigator
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetNavigatorResponse'
              example:
                id: 123e4567-e89b-12d3-a456-426614174002
                name: Analytics Navigator
                description: AI navigator for analytics processing
                api_name: analytics-navigator
                created_at: '2024-01-01T00:00:00Z'
                updated_at: '2024-01-15T10:30:00Z'
                metadata: null
        '404':
          description: Navigator not found
          content:
            application/json:
              example:
                detail: Navigator not found
        '403':
          description: User not associated with a tenant
          content:
            application/json:
              example:
                detail: User not associated with a tenant
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Navigators
      summary: Update Navigator Configuration
      description: Update an existing navigator's configuration including name, description,
        system prompt, model, temperature, and other settings.
      operationId: update_navigator_navigators__navigator_id__patch
      parameters:
      - name: navigator_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Navigator Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNavigatorRequest'
            example:
              name: Updated Navigator Name
              description: Updated description
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetNavigatorResponse'
              example:
                id: 123e4567-e89b-12d3-a456-426614174002
                name: Updated Navigator Name
                description: Updated description
                api_name: customer-support-navigator
                created_at: '2024-01-01T00:00:00Z'
                updated_at: '2024-01-15T10:30:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Navigators
      summary: Delete Navigator
      operationId: delete_navigator_navigators__navigator_id__delete
      parameters:
      - name: navigator_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Navigator Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NavigatorModifiedResponse'
              example:
                id: 123e4567-e89b-12d3-a456-426614174002
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '404':
          description: Response
          content:
            application/json:
              example:
                detail: Navigator not found
      description: Permanently delete a navigator and all associated navigator instances,
        connections, and query history. This action cannot be undone.
  /navigators/{navigator_id}/connections:
    get:
      tags:
      - Navigators
      summary: Get Navigator Project Connections
      operationId: get_navigator_connections_navigators__navigator_id__connections_get
      parameters:
      - name: navigator_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Navigator Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetNavigatorConnectionsResponse'
              example:
                connections:
                - project_id: 123e4567-e89b-12d3-a456-426614174003
                  project_name: Production Project
                  navigator_instance_id: 456e7890-e89b-12d3-a456-426614174017
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Retrieve all project connections for a specific navigator, showing
        which projects have navigator instances.
    post:
      tags:
      - Navigators
      summary: Update Navigator Project Connections
      operationId: update_navigator_connections_navigators__navigator_id__connections_post
      parameters:
      - name: navigator_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Navigator Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNavigatorConnectionsRequest'
            example:
              project_ids:
              - 123e4567-e89b-12d3-a456-426614174003
              - 789e0123-e89b-12d3-a456-426614174016
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NavigatorModifiedResponse'
              example:
                id: 123e4567-e89b-12d3-a456-426614174002
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Update which projects a navigator is connected to. Creates or removes
        navigator instances as needed.
  /navigators/search:
    get:
      tags:
      - Navigators
      summary: Search Navigators
      description: Search for navigators by name or description using full-text search.
        Returns paginated results.
      operationId: search_agents_navigators_search_get
      parameters:
      - name: search
        in: query
        required: true
        schema:
          type: string
          title: Search
      - name: sort_by
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/NavigatorSortBy'
          default: created_desc
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 20
          title: Size
        description: Items per page
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Pagination cursor
          title: Cursor
        description: Pagination cursor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_GetNavigatorResponse_'
              example:
                items:
                - id: 123e4567-e89b-12d3-a456-426614174002
                  name: Customer Support Navigator
                  description: AI navigator for customer support
                  api_name: customer-support-navigator
                  created_at: '2024-01-01T00:00:00Z'
                  updated_at: '2024-01-15T10:30:00Z'
                meta:
                  size: 20
                  total: 100
                  next_cursor: eyJzb3J0Ijog
                  has_next: true
                  has_prev: false
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /navigator-instances:
    get:
      tags:
      - Navigator Instances
      summary: List Navigator Instances
      operationId: list_navigator_instances_navigator_instances__get
      parameters:
      - name: include_analytics
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Include Analytics
      - name: project_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
          title: Project Id
        description: Filter navigator instances by project ID
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 20
          title: Size
        description: Items per page
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Pagination cursor
          title: Cursor
        description: Pagination cursor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_GetNavigatorInstanceResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /navigator-instances/{navigator_instance_id}:
    get:
      tags:
      - Navigator Instances
      summary: Get Navigator Instance Details
      operationId: get_navigator_instance_navigator_instances__navigator_instance_id__get
      parameters:
      - name: navigator_instance_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Navigator Instance Id
      - name: include_config_metadata
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Include Config Metadata
        description: Whether to include configuration metadata such as extraction-enabled servers count and context maps availability
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetNavigatorInstanceResponse'
              examples:
                basic:
                  summary: Basic response without config metadata
                  value:
                    id: 123e4567-e89b-12d3-a456-426614174004
                    navigator_id: 789e0123-e89b-12d3-a456-426614174014
                    project_id: 456e7890-e89b-12d3-a456-426614174015
                    navigator_name: Analytics Navigator
                    api_name: analytics-navigator
                    project_name: Acme Analytics
                    created_at: '2024-01-10T08:00:00Z'
                    updated_at: '2024-01-15T10:30:00Z'
                    dynamic_suggestions_enabled: true
                    context_maps_enabled: false
                    metadata: null
                    config_metadata: null
                with_config_metadata:
                  summary: Response with config metadata (include_config_metadata=true)
                  value:
                    id: 123e4567-e89b-12d3-a456-426614174004
                    navigator_id: 789e0123-e89b-12d3-a456-426614174014
                    project_id: 456e7890-e89b-12d3-a456-426614174015
                    navigator_name: Analytics Navigator
                    api_name: analytics-navigator
                    project_name: Acme Analytics
                    created_at: '2024-01-10T08:00:00Z'
                    updated_at: '2024-01-15T10:30:00Z'
                    dynamic_suggestions_enabled: true
                    context_maps_enabled: false
                    metadata: null
                    config_metadata:
                      can_enable_context_maps: true
                      extraction_enabled_servers_count: 3
                      extraction_enabled_server_ids:
                        - 456e7890-e89b-12d3-a456-426614174016
                        - 567e8901-e89b-12d3-a456-426614174017
                        - 678e9012-e89b-12d3-a456-426614174018
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '404':
          description: Response
          content:
            application/json:
              example:
                detail: Navigator instance not found
      description: Retrieve detailed information about a specific navigator instance including
        associated navigator identity and project information.
  /navigator-instances/{navigator_instance_id}/tool-permissions:
    get:
      tags:
      - Navigator Instances
      summary: Get Tool Permissions for Navigator Instance
      operationId: get_tool_permissions_navigator_instances__navigator_instance_id__tool_permissions_get
      parameters:
      - name: navigator_instance_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Navigator Instance Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetToolPermissionsResponse'
              example:
                permissions:
                - tool_id: 123e4567-e89b-12d3-a456-426614174005
                  tool_name: create_issue
                  server_id: 123e4567-e89b-12d3-a456-426614174006
                  server_name: GitHub API
                  mode: always_execute
                  enabled: true
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Retrieve the list of tool permissions configured for this navigator
        instance, showing which tools are allowed/denied.
    put:
      tags:
      - Navigator Instances
      summary: Update Tool Permissions
      operationId: update_tool_permissions_navigator_instances__navigator_instance_id__tool_permissions_put
      parameters:
      - name: navigator_instance_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Navigator Instance Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateToolPermissionsRequest'
            example:
              permissions:
              - tool_id: 123e4567-e89b-12d3-a456-426614174005
                enabled: true
              - tool_id: 456e7890-e89b-12d3-a456-426614174018
                enabled: false
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NavigatorInstanceModifiedResponse'
              example:
                id: 123e4567-e89b-12d3-a456-426614174004
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Update tool permissions for a navigator instance. Control which tools
        the navigator can access and set rate limits.
  /projects:
    post:
      tags:
      - Projects
      summary: Create New Project
      operationId: create_project_projects_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
            example:
              name: Development Environment
              description: Development and testing project
              icon: project-icon.png
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModifiedProjectResponse'
              example:
                id: 456e7890-e89b-12d3-a456-426614174015
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Create a new project environment for deploying navigators and servers.
    get:
      tags:
      - Projects
      summary: List All Projects
      operationId: list_projects_projects_get
      parameters:
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 20
          title: Size
        description: Items per page
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Pagination cursor
          title: Cursor
        description: Pagination cursor
      - name: include_analytics
        in: query
        description: Include analytics data (active servers, navigators, query counts)
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_GetProjectResponse_'
              example:
                items:
                - id: 123e4567-e89b-12d3-a456-426614174003
                  name: Production Environment
                  description: Main production project
                  icon: production-icon.png
                  created_at: '2024-01-01T00:00:00Z'
                  updated_at: '2024-01-15T10:30:00Z'
                meta:
                  size: 20
                  total: 100
                  next_cursor: eyJzb3J0Ijog
                  has_next: true
                  has_prev: false
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Retrieve a paginated list of all projects for the authenticated
        user's tenant. Projects are environments where navigators and servers are deployed.
  /projects/{project_id}:
    patch:
      tags:
      - Projects
      summary: Update Project
      operationId: update_project_projects__project_id__patch
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProjectRequest'
            example:
              name: Updated Project Name
              description: Updated project description
              icon: updated-icon.png
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModifiedProjectResponse'
              example:
                id: 123e4567-e89b-12d3-a456-426614174003
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Update project name, description, or other configuration settings.
    get:
      tags:
      - Projects
      summary: Get Project Details
      operationId: get_project_projects__project_id__get
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetProjectResponse'
              example:
                id: 123e4567-e89b-12d3-a456-426614174003
                name: Production Environment
                description: Main production project
                icon: production-icon.png
                created_at: '2024-01-01T00:00:00Z'
                updated_at: '2024-01-15T10:30:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '404':
          description: Response
          content:
            application/json:
              example:
                detail: Project not found
      description: Retrieve detailed information about a specific project including
        active instances and statistics.
    delete:
      tags:
      - Projects
      summary: Delete Project
      operationId: delete_project_projects__project_id__delete
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModifiedProjectResponse'
              example:
                id: 123e4567-e89b-12d3-a456-426614174003
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Permanently delete a project and all associated navigator instances,
        server instances, and data. This action cannot be undone.
  /projects/{project_id}/api-keys:
    get:
      tags:
      - Projects
      summary: List Project API Keys
      operationId: get_api_keys_projects__project_id__api_keys_get
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GetApiKeyResponse'
                title: Response Get Api Keys Projects  Project Id  Api Keys Get
              example:
                - id: 123e4567-e89b-12d3-a456-426614174009
                  navigator_instance_id: 123e4567-e89b-12d3-a456-426614174004
                  name: Project API Key
                  key_prefix: sk_proj_1234
                  project_id: 123e4567-e89b-12d3-a456-426614174003
                  preview: sk_proj_1234
                  created_at: '2024-01-01T00:00:00Z'
                  updated_at: '2024-01-15T10:30:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Retrieve all API keys associated with this project.
  /projects/{project_id}/authenticate-servers:
    post:
      tags:
      - Projects
      summary: Authenticate Server Instances
      operationId: authenticate_servers_projects__project_id__authenticate_servers_post
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticateServersRequest'
            example:
              server_instances:
              - 123e4567-e89b-12d3-a456-426614174010
              - 456e7890-e89b-12d3-a456-426614174021
              link_expires_at: '2024-01-22T10:30:00Z'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticateServersResponse'
              example:
                user_invite_link: https://auth.caylex.ai/abc123
                user_invite_link_expires_at: '2024-01-22T10:30:00Z'
                project_invite_link: null
                project_invite_link_expires_at: null
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Provide authentication credentials for server instances within
        this project. Used for OAuth tokens, API keys, and other authentication methods.
  /projects/{project_id}/query-logs:
    get:
      tags:
      - Projects
      summary: Get Project Query Logs
      description: Retrieve query logs for all navigators and servers in this project.
        Supports filtering by date range, status, and search text.
      operationId: get_query_logs_projects__project_id__query_logs_get
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      - name: navigator_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Filter by navigator instance ID
          title: Navigator Instance Id
        description: Filter by navigator instance ID
      - name: server_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Filter by server instance ID
          title: Server Instance Id
        description: Filter by server instance ID
      - name: timestamp__gte
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Start timestamp (inclusive)
          title: Timestamp  Gte
        description: Start timestamp (inclusive)
      - name: timestamp__lte
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: End timestamp (inclusive)
          title: Timestamp  Lte
        description: End timestamp (inclusive)
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 20
          title: Size
        description: Items per page
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Pagination cursor
          title: Cursor
        description: Pagination cursor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_QueryLogResponse_'
              example:
                items:
                - id: 123e4567-e89b-12d3-a456-426614174011
                  query: Create a GitHub issue
                  num_tool_calls: 2
                  servers_invoked:
                  - 123e4567-e89b-12d3-a456-426614174006
                  server_logo_urls:
                  - https://storage.caylex.ai/logos/github.png
                  timestamp: '2024-01-15T10:30:00Z'
                  num_errors: 0
                  navigator_instance_id: 123e4567-e89b-12d3-a456-426614174004
                  navigator_name: GitHub Assistant
                meta:
                  size: 20
                  total: 100
                  next_cursor: eyJzb3J0Ijog
                  has_next: true
                  has_prev: false
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /projects/{project_id}/users:
    get:
      tags:
      - Users
      summary: List users with auth status and weekly metrics
      description: Get paginated list of users in a project with authentication status
        (which servers they've authenticated to) and weekly activity metrics (queries
        and tool calls from past 7 days). Supports filtering by email search and server
        instance IDs.
      operationId: list_users_projects__project_id__users_get
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by user email
          title: Search
        description: Filter by user email
      - name: server_instance_ids
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
              format: uuid
          - type: 'null'
          description: Filter by authenticated server instances
          title: Server Instance Ids
        description: Filter by authenticated server instances
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 20
          title: Size
        description: Items per page
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Pagination cursor
          title: Cursor
        description: Pagination cursor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_UserSummary_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /projects/{project_id}/users/{user_id}:
    get:
      tags:
      - Users
      summary: Get user authentication details
      description: Get detailed authentication information for a specific user including
        user email and list of all servers with auth method and timestamp.
      operationId: get_user_details_projects__project_id__users__user_id__get
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserAuthDetails'
              example:
                user_email: user@example.com
                servers:
                - server_instance_id: 123e4567-e89b-12d3-a456-426614174010
                  server_name: GitHub
                  logo_url: https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png
                  auth_method: oauth
                  authenticated_at: '2024-01-15T10:30:00Z'
        '404':
          description: User not found
          content:
            application/json:
              example:
                detail: User not found in this project
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Users
      summary: Revoke user access to specific server instances
      description: Revoke a user's access to specific server instances. This endpoint
        deletes authentication records from the database, removes the user's authorization
        for the specified server instances, deletes OAuth tokens from Descope (for OAuth-based
        servers), and removes stored secrets from AWS Parameter Store.
      operationId: revoke_user_access_projects__project_id__users__user_id__revoke_post
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: User Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RevokeUserAccessRequest'
            example:
              server_instance_ids:
              - 123e4567-e89b-12d3-a456-426614174010
              - 456e7890-e89b-12d3-a456-426614174021
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevokeUserAccessResponse'
              example:
                revoked_server_instance_ids:
                - 123e4567-e89b-12d3-a456-426614174010
                - 456e7890-e89b-12d3-a456-426614174021
                deleted_auth_count: 2
                descope_tokens_revoked: 1
        '404':
          description: User or project not found
          content:
            application/json:
              example:
                detail: User not found in this project
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Users
      summary: Delete a user from a project
      description: Delete a user from a project. This endpoint verifies the project belongs
        to the user's tenant, verifies the user token belongs to the project, deletes all
        authentication records and secrets from AWS Parameter Store, revokes OAuth tokens
        from Descope (for OAuth-based servers), and deletes the user token (cascade deletes
        related records). If the user is not associated with any other projects and has only
        the "user" role for this tenant with no other role for this tenant or any other
        tenant, the user will also be deleted from Descope.
      operationId: delete_user_projects__project_id__users__user_id__delete
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModifiedUserResponse'
              example:
                id: 123e4567-e89b-12d3-a456-426614174010
        '404':
          description: User or project not found
          content:
            application/json:
              example:
                detail: User not found in this project
        '403':
          description: User not associated with a tenant
          content:
            application/json:
              example:
                detail: User not associated with a tenant
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /projects/{project_id}/users/summary:
    get:
      tags:
      - Users
      summary: Get userbase aggregate statistics
      description: Get aggregate userbase statistics for a project including total
        users, WAU, MAU, inactive users, and WAU timeline over past 8 weeks.
      operationId: get_userbase_summary_projects__project_id__users_summary_get
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserbaseSummaryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /projects/{project_id}/users/{user_id}/analytics:
    get:
      tags:
      - Users
      summary: Get comprehensive user analytics
      description: Get comprehensive analytics for a single user including top navigators
        used, top tools and servers, query/tool call timelines, error rates and types.
        Used for analytics drawer/side panel.
      operationId: get_user_analytics_projects__project_id__users__user_id__analytics_get
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: User Id
      - name: window
        in: query
        required: false
        schema:
          type: string
          description: Time window (1h, 1d, 1w, 1mon)
          default: 1w
          pattern: '^[0-9]+(h|d|w|mon)$'
          title: Window
        description: Time window (1h, 1d, 1w, 1mon)
      - name: frequency
        in: query
        required: false
        schema:
          type: string
          description: Data point frequency
          default: 1d
          pattern: '^[0-9]+(m|h|d|w)$'
          title: Frequency
        description: Data point frequency
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserAnalyticsResponse'
        '404':
          description: User not found
          content:
            application/json:
              example:
                detail: User not found in this project
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /projects/{project_id}/auth-links:
    get:
      tags:
      - Projects
      summary: Get Auth Links
      operationId: get_auth_link_projects__project_id__auth_link_get
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - active
          - expired
          title: Status
        description: "Filter links by status: 'active' for non-expired links with remaining uses, 'expired' for expired links. If not provided, returns both active and expired links."
      - name: auth_credentials_level
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/InviteLinkType'
          - type: 'null'
        description: "Filter links by credentials level: 'user' for user-level links, 'project' for project-level links."
      - name: server_instance_ids
        in: query
        required: false
        style: form
        explode: true
        schema:
          anyOf:
          - type: array
            items:
              type: string
              format: uuid
          - type: 'null'
          title: Server Instance Ids
        description: "Filter links by server instance IDs. Returns links that are associated with any of the specified server instances. Can be specified multiple times."
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 20
          title: Size
        description: Items per page
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
        description: Pagination cursor for next/previous page
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_InviteLinkResponse_'
              example:
                items:
                - id: 123e4567-e89b-12d3-a456-426614174012
                  auth_link: https://auth.caylex.ai?auth_link_id=abc123def456
                  expires_at: '2024-01-22T10:30:00Z'
                  auth_credentials_level: project
                  created_at: '2024-01-20T10:30:00Z'
                  server_instances:
                  - id: 223e4567-e89b-12d3-a456-426614174099
                    name: GitHub Server
                    logo_url: https://example.com/github-logo.png
                    valid_for: example.com
                  - id: 323e4567-e89b-12d3-a456-426614174098
                    name: Slack Server
                    logo_url: https://example.com/slack-logo.png
                    valid_for: example.com
                  users:
                  - email: example.com
                    first_authenticated: '2024-01-21T08:00:00Z'
                    last_authenticated: '2024-01-21T10:00:00Z'
                - id: 223e4567-e89b-12d3-a456-426614174013
                  auth_link: https://auth.caylex.ai?auth_link_id=def456abc123
                  expires_at: '2024-01-22T10:30:00Z'
                  auth_credentials_level: user
                  created_at: '2024-01-21T10:30:00Z'
                  server_instances:
                  - id: 423e4567-e89b-12d3-a456-426614174097
                    name: Jira Server
                    logo_url: https://example.com/jira-logo.png
                    valid_for: user@example.com
                  users:
                  - email: user@example.com
                    first_authenticated: null
                    last_authenticated: null
                meta:
                  size: 20
                  total: 10
                  next_cursor: eyJzb3J0Ijog
                  has_next: false
                  has_prev: false
        '403':
          description: User not associated with a tenant
        '404':
          description: Project not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: |
        Get paginated auth invite links for a project.
        
        By default, returns both active and expired invite links.
        
        Use status='active' to return only active links (non-expired and with remaining uses).
        Use status='expired' to return only expired links.
        
        Use auth_credentials_level to filter by link type ('user' or 'project').
        
        Use server_instance_ids to filter by server instance IDs. Returns links associated with any of the specified server instances. Can be specified multiple times.
        
        Supports pagination with size (default 20, max 100) and cursor parameters.
        
        Returns invite links with their associated server instances from server_instance_invite_link and server_instance_invite_link_association tables.
  /projects/{project_id}/auth-links/user:
    post:
      tags:
      - Projects
      summary: Create User Auth Link
      operationId: create_user_auth_link_projects__project_id__auth_link_users_post
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserAuthLinkRequest'
            example:
              server_instances:
              - 123e4567-e89b-12d3-a456-426614174010
              - 456e7890-e89b-12d3-a456-426614174021
              domain: example.com
              link_expires_at: '2024-01-22T10:30:00Z'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAuthLinkResponse'
              example:
                invite_link: https://auth.caylex.ai?auth_link_id=abc123def456
                invite_link_expires_at: '2024-01-22T10:30:00Z'
        '403':
          description: User not associated with a tenant
        '404':
          description: Project not found or one or more server instances not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Create a USER type invite link with domain restriction. Users must login with an email from the specified domain.
  /projects/{project_id}/auth-link/project:
    post:
      tags:
      - Projects
      summary: Create Project Auth Link
      operationId: create_project_auth_link_projects__project_id__auth_link_project_post
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectAuthLinkRequest'
            example:
              server_instance_emails:
              - server_instance_id: 123e4567-e89b-12d3-a456-426614174010
                email: user1@example.com
              - server_instance_id: 456e7890-e89b-12d3-a456-426614174021
                email: user2@example.com
              link_expires_at: '2024-01-22T10:30:00Z'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAuthLinkResponse'
              example:
                invite_link: https://auth.caylex.ai?auth_link_id=def456abc123
                invite_link_expires_at: '2024-01-22T10:30:00Z'
        '400':
          description: Bad Request - Server instance not found in project
        '403':
          description: User not associated with a tenant
        '404':
          description: Project not found or one or more server instances not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Create a PROJECT type invite link with per-instance email restrictions. Each server instance is restricted to a specific email address.
  /projects/{project_id}/auth-links/user/{auth_link_id}:
    patch:
      tags:
      - Projects
      summary: Update User Auth Link
      operationId: update_user_auth_link_projects__project_id__auth_link_user__auth_link_id__patch
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      - name: auth_link_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Auth Link Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserAuthLinkRequest'
            example:
              link_expires_at: '2024-02-22T10:30:00Z'
              server_instances:
              - 123e4567-e89b-12d3-a456-426614174010
              - 456e7890-e89b-12d3-a456-426614174021
              domain: example.com
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InviteLinkResponse'
              example:
                id: 123e4567-e89b-12d3-a456-426614174012
                auth_link: https://auth.caylex.ai?auth_link_id=abc123def456
                expires_at: '2024-02-22T10:30:00Z'
                auth_credentials_level: user
                created_at: '2024-01-20T10:30:00Z'
                server_instances:
                - id: 223e4567-e89b-12d3-a456-426614174099
                  name: GitHub Server
                  logo_url: https://example.com/github-logo.png
                  valid_for: example.com
                - id: 323e4567-e89b-12d3-a456-426614174098
                  name: Slack Server
                  logo_url: https://example.com/slack-logo.png
                  valid_for: example.com
                users:
                - email: example.com
                  first_authenticated: '2024-01-21T08:00:00Z'
                  last_authenticated: '2024-01-21T10:00:00Z'
        '400':
          description: Bad Request - Invalid parameters (e.g., missing domain when updating server_instances)
        '403':
          description: User not associated with a tenant
        '404':
          description: Project not found, USER type auth link not found, or one or more server instances not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: |
        Update a USER type auth invite link for a project.
        
        Can update the expiry date and/or server instances associated with the link.
        When updating server_instances, provide a domain that applies to all server instances.
  /projects/{project_id}/auth-links/project/{auth_link_id}:
    patch:
      tags:
      - Projects
      summary: Update Project Auth Link
      operationId: update_project_auth_link_projects__project_id__auth_link_project__auth_link_id__patch
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      - name: auth_link_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Auth Link Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProjectAuthLinkRequest'
            example:
              link_expires_at: '2024-02-22T10:30:00Z'
              server_instance_emails:
              - server_instance_id: 123e4567-e89b-12d3-a456-426614174010
                email: user1@example.com
              - server_instance_id: 456e7890-e89b-12d3-a456-426614174021
                email: user2@example.com
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InviteLinkResponse'
              example:
                id: 123e4567-e89b-12d3-a456-426614174012
                auth_link: https://auth.caylex.ai?auth_link_id=abc123def456
                expires_at: '2024-02-22T10:30:00Z'
                auth_credentials_level: project
                created_at: '2024-01-20T10:30:00Z'
                server_instances:
                - id: 223e4567-e89b-12d3-a456-426614174099
                  name: GitHub Server
                  logo_url: https://example.com/github-logo.png
                  valid_for: user1@example.com
                - id: 323e4567-e89b-12d3-a456-426614174098
                  name: Slack Server
                  logo_url: https://example.com/slack-logo.png
                  valid_for: user2@example.com
                users:
                - email: user1@example.com
                  first_authenticated: '2024-01-21T08:00:00Z'
                  last_authenticated: '2024-01-21T10:00:00Z'
                - email: user2@example.com
                  first_authenticated: null
                  last_authenticated: null
        '400':
          description: Bad Request - Invalid parameters (e.g., server instance not found in project)
        '403':
          description: User not associated with a tenant
        '404':
          description: Project not found, PROJECT type auth link not found, or one or more server instances not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: |
        Update a PROJECT type auth invite link for a project.
        
        Can update the expiry date and/or server instances associated with the link.
        When updating server instances, provide server_instance_emails mapping for per-instance email restrictions.
  /projects/{project_id}/auth-links/{auth_link_id}:
    delete:
      tags:
      - Projects
      summary: Delete Auth Link
      operationId: delete_auth_link_projects__project_id__auth_link__auth_link_id__delete
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      - name: auth_link_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Auth Link Id
      responses:
        '204':
          description: Auth link deleted successfully
        '403':
          description: User not associated with a tenant
        '404':
          description: Project not found or Auth link not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: |
        Delete an auth invite link for a project.
        
        Verifies that the project exists and belongs to the user's tenant,
        and that the auth-link exists and belongs to the project.
    get:
      tags:
      - Projects
      summary: Get Auth Link Details
      operationId: get_auth_link_details_projects__project_id__auth_links__auth_link_id__get
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      - name: auth_link_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Auth Link Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthLinkDetailsResponse'
        '403':
          description: User not associated with a tenant
        '404':
          description: Project not found or Auth link not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: |
        Get detailed information about a specific auth invite link.
        
        Returns:
        - Auth link details (id, link, expiry, etc.)
        - Server instances associated with the link
        - User count for this invite link
  /projects/{project_id}/auth-links/{auth_link_id}/users:
    get:
      tags:
      - Projects
      summary: Get Auth Link Users
      operationId: get_auth_link_users_projects__project_id__auth_links__auth_link_id__users_get
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      - name: auth_link_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Auth Link Id
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 20
          title: Size
        description: Items per page
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
        description: Pagination cursor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_UserAuthenticationDetails_'
        '403':
          description: User not associated with a tenant
        '404':
          description: Project not found or Auth link not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: |
        Get paginated list of users who have authenticated using this auth invite link.
        
        Returns:
        - Paginated list of users with their authentication details
        - For each user: which servers they authenticated to and when
  /projects/{project_id}/auth-links/{auth_link_id}/users/search:
    get:
      tags:
      - Projects
      summary: Search Auth Link Users
      operationId: search_auth_link_users_projects__project_id__auth_links__auth_link_id__users_search_get
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      - name: auth_link_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Auth Link Id
      - name: search
        in: query
        required: true
        schema:
          type: string
          title: Search
        description: Search term for user email (case-insensitive partial match)
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 20
          title: Size
        description: Items per page
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
        description: Pagination cursor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_UserAuthenticationDetails_'
        '403':
          description: User not associated with a tenant
        '404':
          description: Project not found or Auth link not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: |
        Search for users who have authenticated using this auth invite link.
        
        Searches by user email using case-insensitive partial matching.
        Returns paginated list of matching users with their authentication details.
        
        **Search Parameters:**
        - `search`: Search term to match against user email addresses (required)
        - `size`: Number of items per page (default: 20, max: 100)
        - `cursor`: Pagination cursor for navigating through results
        
        **Returns:**
        - Paginated list of users matching the search criteria
        - For each user: which servers they authenticated to and when
  /projects/{project_id}/server-instances/status:
    get:
      tags:
      - Projects
      summary: Get Server Instance Status
      operationId: get_project_status_projects__project_id__server_instances_status_get
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetProjectStatusResponse'
              example:
                active_server_instances: 4
                disabled_server_instances: 1
                active_navigator_instances: 3
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Retrieve status information for all server instances in this project,
        including health and connectivity.
  /projects/search:
    get:
      tags:
      - Projects
      summary: Search Projects
      operationId: search_projects_projects_search_get
      parameters:
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 20
          title: Size
        description: Items per page
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Pagination cursor
          title: Cursor
        description: Pagination cursor
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Search
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_GetProjectResponse_'
              example:
                items:
                - id: 123e4567-e89b-12d3-a456-426614174003
                  name: Production Environment
                  description: Main production project
                  icon: production-icon.png
                  created_at: '2024-01-01T00:00:00Z'
                  updated_at: '2024-01-15T10:30:00Z'
                meta:
                  size: 20
                  total: 100
                  next_cursor: eyJzb3J0Ijog
                  has_next: true
                  has_prev: false
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Search for projects by name or description using full-text search.
  /webhooks/event-types:
    get:
      tags:
      - Webhooks
      summary: List Webhook Event Types by Scope
      operationId: get_webhook_event_types_webhooks_event_types_get
      parameters:
      - name: scope
        in: query
        required: false
        description: |
          Filter to one or more configuration scopes; repeat this query parameter
          (e.g. `?scope=project&scope=tenant`). Omit to return every known scope
          in a stable order. Unknown values return 400.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEventTypesByScopeResponse'
              example:
                scopes:
                - scope: project
                  event_types:
                  - query.created
                  - tool_call.completed
                  - tool_call.error
                  - tool_call.rejected
                  - credentials.resolve_failed
                  - proxy_tool.error
                - scope: tenant
                  event_types: []
                - scope: system
                  event_types: []
        '400':
          description: Unknown scope value in query
        '403':
          description: User not associated with a tenant
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: |
        Return canonical webhook event type strings grouped by configuration scope.

        **project** — types used with project `webhook_config` (matches notification worker defaults).

        **tenant** / **system** — reserved; may return empty `event_types` until supported.
  /servers:
    get:
      tags:
      - Servers
      summary: List All Servers
      operationId: list_servers_servers_get
      parameters:
      - name: include_analytics
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Include Analytics
      - name: sort_by
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ServerSortBy'
          default: created_desc
      - name: transport
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/ServerTransport'
          - type: 'null'
          title: Transport
        description: 'Filter by transport: streamable_http or sse'
      - name: auth_method
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/ServerAuthMethod'
          - type: 'null'
          title: Authentication Method
        description: 'Filter by authentication method: oauth, header, path, or query'
      - name: server_type
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/ServerType'
          - type: 'null'
          title: Server Type
        description: 'Filter by server type: external, foundry, or caylex'
      - name: auth_level
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/AuthLevel'
          - type: 'null'
          title: Authentication Level
        description: 'Filter by authentication level: project or user'
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 20
          title: Size
        description: Items per page
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Pagination cursor
          title: Cursor
        description: Pagination cursor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_GetServerResponse_'
              example:
                items:
                - id: 123e4567-e89b-12d3-a456-426614174006
                  registry_id: 789e0123-e89b-12d3-a456-426614174020
                  registry_name: Official MCP Registry
                  name: GitHub API Server
                  endpoint: mcp://acme-corp/github-api
                  description: Server for GitHub API integration
                  transport: streamable_http
                  auth_method: oauth
                  server_type: caylex
                  auth_level: user
                  logo_url: https://storage.caylex.ai/logos/github.png
                  health_check:
                    last_check: '2024-01-15T10:30:00Z'
                    status: up
                  metadata:
                    num_tools: 15
                    num_tool_calls: 1234
                    connected_projects: 3
                  active_instances: 5
                  created_at: '2024-01-10T08:00:00Z'
                  updated_at: '2024-01-15T10:30:00Z'
                meta:
                  size: 20
                  total: 100
                  next_cursor: eyJzb3J0Ijog
                  has_next: true
                  has_prev: false
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '403':
          description: Response
          content:
            application/json:
              example:
                detail: User not associated with a tenant
      description: Retrieve a paginated list of all MCP servers (both internal and
        external) for the authenticated user's tenant. Supports sorting, filtering,
        and optional analytics.
  /servers/{server_id}:
    get:
      tags:
      - Servers
      summary: Get Server Details
      operationId: get_server_servers__server_id__get
      parameters:
      - name: server_id
        in: path
        required: true
        schema:
          type: string
          title: Server Id
      - name: include_analytics
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Include Analytics
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetServerResponse'
              example:
                id: 123e4567-e89b-12d3-a456-426614174000
                registry_id: 789e0123-e89b-12d3-a456-426614174020
                name: GitHub API Server
                endpoint: mcp://acme-corp/github-api
                description: Server for GitHub API integration
                transport: streamable_http
                auth_method: oauth
                server_type: caylex
                auth_level: user
                logo_url: https://storage.caylex.ai/logos/github.png
                health_check:
                  last_check: '2024-01-15T10:30:00Z'
                  status: up
                metadata:
                  num_tools: 15
                  num_tool_calls: 1234
                  connected_projects: 3
                created_at: '2024-01-10T08:00:00Z'
                updated_at: '2024-01-15T10:30:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '404':
          description: Response
          content:
            application/json:
              example:
                detail: Server not found
      description: Retrieve detailed information about a specific MCP server including
        configuration, health status, and authentication details.
    patch:
      tags:
      - Servers
      summary: Update Server
      description: |
        Update a server by ID. Only provided fields are updated.
        Auth config shape matches POST requests.
        - name: allowed for all servers.
        - endpoint: MCP server URL (external header/path/query only).
        - oauth_config: same as POST /servers/oauth; manual_client_config null = Caylex (DCR), set = manual credentials.
        - headers / paths / params: same as POST /servers/header, /servers/path, /servers/query.
        Auth credentials level (auth_level) cannot be updated.
      operationId: patch_server_servers__server_id__patch
      parameters:
      - name: server_id
        in: path
        required: true
        schema:
          type: string
          title: Server Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchServerRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerModifiedResponse'
        '400':
          description: Bad Request (e.g. invalid endpoint, invalid OAuth fields)
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
        '403':
          description: User not associated with a tenant
          content:
            application/json:
              example:
                detail: User not associated with a tenant
        '404':
          description: Server not found
          content:
            application/json:
              example:
                detail: Server not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Servers
      summary: Delete Server
      description: Permanently delete a server. This endpoint checks if the server is
        associated with any projects via server instances and returns an error if associations
        exist. Stops the server if it's running (only for FOUNDRY servers), removes Kubernetes
        resources, deletes all server instances, query tool calls, context map tool calls,
        deletes SSM client secrets and Descope outbound apps for servers with OAuth config
        (any server type), and removes database records. This action cannot be undone.
      operationId: delete_server_servers__server_id__delete
      parameters:
      - name: server_id
        in: path
        required: true
        schema:
          type: string
          title: Server Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteServerResponse'
              example:
                server_id: 123e4567-e89b-12d3-a456-426614174000
                message: Successfully deleted server 'github-api'
        '400':
          description: Response
          content:
            application/json:
              example:
                detail: "Cannot delete server 'github-api' because it is associated with 2 project(s). Please disconnect the server from all projects before deleting. Associated project IDs: 123e4567-e89b-12d3-a456-426614174001, 789e0123-e89b-12d3-a456-426614174002"
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '404':
          description: Response
          content:
            application/json:
              example:
                detail: Server not found
  /servers/{server_id}/start:
    post:
      tags:
      - Servers
      summary: Start Internal Server
      description: Start a stopped internal MCP server. Deploys the server to Kubernetes
        in the tenant's namespace. Only works for internal (Caylex-generated) servers.
      operationId: start_server_servers__server_id__start_post
      parameters:
      - name: server_id
        in: path
        required: true
        schema:
          type: string
          title: Server Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartServerResponse'
              example:
                server_id: 123e4567-e89b-12d3-a456-426614174000
                server_name: github-api
                status: started
                message: Successfully started server 'github-api'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '404':
          description: Response
          content:
            application/json:
              example:
                detail: Server not found
        '400':
          description: Response
          content:
            application/json:
              example:
                detail: Only internal Caylex servers can be started via this endpoint
              examples:
                not_internal:
                  summary: Server is not internal
                  value:
                    detail: Only internal Caylex servers can be started via this endpoint
                missing_labels:
                  summary: Missing server labels
                  value:
                    detail: Server labels not found. Server may not have been generated
                      properly.
        '500':
          description: Failed to start server (internal details not exposed)
          content:
            application/json:
              example:
                detail: Failed to start server
  /servers/{server_id}/connections:
    post:
      tags:
      - Servers
      summary: Update Server Project Connections
      operationId: update_server_connections_servers__server_id__connections_post
      parameters:
      - name: server_id
        in: path
        required: true
        schema:
          type: string
          title: Server Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateServerConnectionsRequest'
            example:
              project_ids:
              - 123e4567-e89b-12d3-a456-426614174003
              - 789e0123-e89b-12d3-a456-426614174016
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerModifiedResponse'
              example:
                id: 123e4567-e89b-12d3-a456-426614174000
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '400':
          description: Response
          content:
            application/json:
              example:
                detail: Project proj-xyz not found or not accessible
      description: Update which projects a server is connected to. Creates or removes
        server instances as needed.
    get:
      tags:
      - Servers
      summary: Get Server Project Connections
      operationId: get_server_connections_servers__server_id__connections_get
      parameters:
      - name: server_id
        in: path
        required: true
        schema:
          type: string
          title: Server Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetServerConnectionsResponse'
              example:
                connections:
                - project_id: 123e4567-e89b-12d3-a456-426614174003
                  project_name: Production Project
                  server_instance_id: 456e7890-e89b-12d3-a456-426614174021
                  is_paused: false
                - project_id: 789e0123-e89b-12d3-a456-426614174016
                  project_name: Development Project
                  server_instance_id: 012e3456-e89b-12d3-a456-426614174022
                  is_paused: true
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Retrieve all project connections for a specific server, showing
        which projects have server instances.
  /servers/{server_id}/clone:
    post:
      tags:
      - Servers
      summary: Clone Server
      description: Clone a server with a new name and optional endpoint. Creates a
        new server copying the original's configuration (description, transport,
        auth_method, server_type, auth_level, logo_url, registry_id, auth_config).
        If endpoint is not provided, the original server's endpoint is used.
      operationId: clone_server_servers__server_id__clone_post
      parameters:
      - name: server_id
        in: path
        required: true
        schema:
          type: string
          title: Server Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CloneServerRequest'
            examples:
              name_only:
                summary: Clone with new name only (reuse original endpoint)
                value:
                  name: my-cloned-server
              name_and_endpoint:
                summary: Clone with new name and endpoint
                value:
                  name: my-cloned-server
                  endpoint: https://other.example.com/mcp
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerModifiedResponse'
              example:
                id: 456e7890-e89b-12d3-a456-426614174099
        '404':
          description: Server not found
          content:
            application/json:
              example:
                detail: Server not found
        '409':
          description: A server with the given name already exists in this tenant
          content:
            application/json:
              example:
                error:
                  message: "A server with the name 'Acme GitHub' already exists in this tenant"
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /servers/{server_id}/tools:
    get:
      tags:
      - Servers
      summary: Get Server Tools
      operationId: get_server_tools_servers__server_id__tools_get
      parameters:
      - name: server_id
        in: path
        required: true
        schema:
          type: string
          title: Server Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetServerToolsResponse'
              example:
                tools:
                - id: 123e4567-e89b-12d3-a456-426614174000
                  name: search_files
                  description: Search for files in the repository
                  input_schema:
                    type: object
                    properties:
                      query:
                        type: string
                        description: Search query
                      limit:
                        type: integer
                        description: Maximum number of results
                    required:
                    - query
                - id: 456e7890-e89b-12d3-a456-426614174001
                  name: read_file
                  description: Read the contents of a file
                  input_schema:
                    type: object
                    properties:
                      path:
                        type: string
                        description: File path to read
                    required:
                    - path
        '404':
          description: Server not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Get tools for a specific server. Returns the list of tools associated
        with a server, including their name, description, and input schema.
  /servers/{server_id}/tools/{tool_id}:
    patch:
      tags:
      - Servers
      summary: Patch Server Tool
      operationId: patch_server_tool_servers__server_id__tools__tool_id__patch
      parameters:
      - name: server_id
        in: path
        required: true
        schema:
          type: string
          title: Server Id
      - name: tool_id
        in: path
        required: true
        schema:
          type: string
          title: Tool Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchServerToolRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchServerToolResponse'
        '404':
          description: Server or tool not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Update user-editable fields on a server tool. Currently supports
        setting added_context, free-form context appended to the tool description and
        surfaced by the caylex navigator's suggest_tools.
  /servers/discover-oauth-metadata:
    get:
      tags:
      - Servers
      summary: Discover OAuth Metadata
      description: Automatically discover OAuth 2.0 metadata (authorization endpoint,
        token endpoint, registration endpoint) from a server URL using well-known
        discovery endpoints.
      operationId: discover_oauth_metadata_servers_discover_oauth_metadata_get
      parameters:
      - name: url
        in: query
        required: true
        schema:
          type: string
          title: Url
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoverOAuthMetadataResponse'
              examples:
                metadata_found:
                  summary: OAuth metadata successfully discovered
                  value:
                    found: true
                    auth_endpoint: https://github.com/login/oauth/authorize
                    token_endpoint: https://github.com/login/oauth/access_token
                    registration_endpoint: https://github.com/login/oauth/register
                metadata_not_found:
                  summary: OAuth metadata not found
                  value:
                    found: false
                    auth_endpoint: null
                    token_endpoint: null
                    registration_endpoint: null
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /servers/header:
    post:
      tags:
      - Servers
      summary: Add External Header-Auth Server
      description: Register an external MCP server that uses header-based authentication
        (API keys, bearer tokens, etc.).
      operationId: add_external_header_server_servers_header_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddExternalHeaderServerRequest'
            examples:
              with_endpoint:
                summary: Example with endpoint
                value:
                  name: Custom API Server
                  endpoint: https://api.example.com
                  description: Custom external API with header authentication
                  auth_level: user
                  transport: sse
                  headers:
                  - header_name: Authorization
                    header_value_prefix: Bearer
                  - header_name: X-API-Version
                    header_value_prefix: v1
              with_registry_id:
                summary: Example with registry_id
                value:
                  name: Pre-configured API Server
                  description: Server configured from registry
                  registry_id: 123e4567-e89b-12d3-a456-426614174000
                  auth_level: user
                  transport: sse
                  headers:
                  - header_name: Authorization
                    header_value_prefix: Bearer
              with_query_params:
                summary: Example with non-auth query params
                value:
                  name: Header Auth with Query Params
                  endpoint: https://api.example.com
                  description: Header auth server with additional query parameters
                  auth_level: user
                  transport: sse
                  headers:
                  - header_name: Authorization
                    header_value_prefix: Bearer
                  query_params:
                  - name: format
                    value: json
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerModifiedResponse'
              example:
                id: 012e3456-e89b-12d3-a456-426614174023
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /servers/oauth:
    post:
      tags:
      - Servers
      summary: Add External OAuth Server
      operationId: add_external_oauth_server_servers_oauth_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddExternalOAuthServerRequest'
            examples:
              with_endpoint:
                summary: Example with endpoint
                value:
                  name: External GitHub Integration
                  endpoint: https://api.github.com
                  description: External GitHub API integration
                  auth_level: user
                  transport: sse
                  metadata:
                    found: true
                    auth_endpoint: https://github.com/login/oauth/authorize
                    token_endpoint: https://github.com/login/oauth/access_token
                    redirect_url: https://api.caylex.ai/auth/callback
                    registration_endpoint: null
                  manual_client_config:
                    client_id: github_client_id_here
                    client_secret: github_client_secret_here
                  scopes:
                  - repo
                  - user:email
              with_registry_id:
                summary: Example with registry_id
                value:
                  name: External GitHub Integration
                  description: External GitHub API integration
                  registry_id: 123e4567-e89b-12d3-a456-426614174000
                  auth_level: user
                  transport: sse
                  metadata:
                    found: true
                    auth_endpoint: https://github.com/login/oauth/authorize
                    token_endpoint: https://github.com/login/oauth/access_token
                    redirect_url: https://api.caylex.ai/auth/callback
                    registration_endpoint: null
                  manual_client_config:
                    client_id: github_client_id_here
                    client_secret: github_client_secret_here
                  scopes:
                  - repo
                  - user:email
              with_query_params:
                summary: Example with non-auth query params
                value:
                  name: OAuth Server with Query Params
                  endpoint: https://api.github.com
                  description: OAuth server with additional query parameters
                  auth_level: user
                  transport: sse
                  metadata:
                    found: true
                    auth_endpoint: https://github.com/login/oauth/authorize
                    token_endpoint: https://github.com/login/oauth/access_token
                    redirect_url: https://api.caylex.ai/auth/callback
                    registration_endpoint: null
                  manual_client_config:
                    client_id: github_client_id_here
                    client_secret: github_client_secret_here
                  query_params:
                  - name: format
                    value: json
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerModifiedResponse'
              example:
                id: 789e0123-e89b-12d3-a456-426614174024
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Register an external MCP server that uses OAuth 2.0 authentication.
        Requires OAuth metadata and client credentials.
  /servers/path:
    post:
      tags:
      - Servers
      summary: Add External Path-Auth Server
      description: Register an external MCP server that uses path-based authentication
        (API keys in URL path).
      operationId: add_external_path_server_servers_path_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddExternalPathServerRequest'
            examples:
              with_endpoint:
                summary: Example with endpoint
                value:
                  name: Path Auth API Server
                  endpoint: https://api.example.com
                  description: API with path-based authentication
                  auth_level: user
                  transport: sse
                  paths:
                  - path_param_name: api_key
              with_registry_id:
                summary: Example with registry_id
                value:
                  name: Pre-configured Path Auth Server
                  description: Server configured from registry
                  registry_id: 123e4567-e89b-12d3-a456-426614174000
                  auth_level: user
                  transport: sse
                  paths:
                  - path_param_name: api_key
              with_query_params:
                summary: Example with non-auth query params
                value:
                  name: Path Auth with Query Params
                  endpoint: https://api.example.com
                  description: Path auth server with additional query parameters
                  auth_level: user
                  transport: sse
                  paths:
                  - path_param_name: api_key
                  query_params:
                  - name: format
                    value: json
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerModifiedResponse'
              example:
                id: 345e6789-e89b-12d3-a456-426614174025
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /servers/query:
    post:
      tags:
      - Servers
      summary: Add External Query-Auth Server
      description: Register an external MCP server that uses query parameter-based
        authentication (API keys in URL query string).
      operationId: add_external_query_server_servers_query_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddExternalQueryServerRequest'
            examples:
              with_endpoint:
                summary: Example with endpoint
                value:
                  name: Query Auth API Server
                  endpoint: https://api.example.com
                  description: API with query parameter authentication
                  auth_level: user
                  transport: sse
                  params:
                  - query_param_name: api_key
              with_registry_id:
                summary: Example with registry_id
                value:
                  name: Pre-configured Query Auth Server
                  description: Server configured from registry
                  registry_id: 123e4567-e89b-12d3-a456-426614174000
                  auth_level: user
                  transport: sse
                  params:
                  - query_param_name: api_key
              with_query_params:
                summary: Example with non-auth query_params
                value:
                  name: Query Auth with Extra Params
                  endpoint: https://api.example.com
                  description: API with query auth and additional query params
                  auth_level: user
                  transport: sse
                  params:
                  - query_param_name: api_key
                  query_params:
                  - name: format
                    value: json
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerModifiedResponse'
              example:
                id: 567e8901-e89b-12d3-a456-426614174027
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /servers/noauth:
    post:
      tags:
      - Servers
      summary: Add External No-Auth Server
      description: Register an external MCP server that does not require any authentication.
      operationId: add_external_noauth_server_servers_noauth_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddExternalNoAuthServerRequest'
            examples:
              with_endpoint:
                summary: Example with endpoint
                value:
                  name: Public API Server
                  endpoint: https://api.example.com
                  description: Public API without authentication
                  auth_level: user
                  transport: sse
              with_registry_id:
                summary: Example with registry_id
                value:
                  name: Pre-configured No-Auth Server
                  description: Server configured from registry
                  registry_id: 123e4567-e89b-12d3-a456-426614174000
                  auth_level: user
                  transport: sse
              with_query_params:
                summary: Example with non-auth query params
                value:
                  name: No-Auth Server with Query Params
                  endpoint: https://api.example.com
                  description: No-auth server with additional query parameters
                  auth_level: user
                  transport: sse
                  query_params:
                  - name: format
                    value: json
                  - name: version
                    value: "2"
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerModifiedResponse'
              example:
                id: 456e7890-e89b-12d3-a456-426614174026
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /servers/header/generate:
    post:
      tags:
      - Servers
      summary: Generate Internal Header-Auth Server
      description: 'Generate an internal MCP server with header authentication from
        a pre-analyzed OpenAPI spec. Creates server code, deploys to Kubernetes (if
        start_server=true), and registers in database. Note: Namespace is automatically
        inferred from tenant name.'
      operationId: generate_internal_header_server_servers_header_generate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateInternalHeaderServerWithAnalysisRequest'
            example:
              session_id: 98765432-abcd-1234-efgh-123456789abc
              server_name: custom-api
              description: Custom API MCP Server with header authentication
              transport: streamable_http
              tool_selection:
              - get_data
              - post_data
              - update_resource
              - delete_resource
              headers:
              - header_name: X-API-Key
                header_value_prefix: ''
              - header_name: X-App-Version
                header_value_prefix: 1.0.0
              - header_name: User-Agent
                header_value_prefix: CaylexMCP/1.0
              start_server: true
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerGenerationResponse'
              example:
                server_id: 456e7890-e89b-12d3-a456-426614174026
                session_id: 98765432-abcd-1234-efgh-123456789abc
                generation_status: completed
                message: Successfully generated internal header-auth server 'custom-api'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '400':
          description: Response
          content:
            application/json:
              example:
                detail: Server with name 'custom-api' already exists for this tenant.
  /servers/oauth/generate:
    post:
      tags:
      - Servers
      summary: (For future use. Do not use for v1 release.) Generate Internal OAuth Server
      description: 'Generate an internal MCP server with OAuth authentication from
        a pre-analyzed OpenAPI spec. Creates server code, deploys to Kubernetes (if
        start_server=true), and registers in database. Note: Namespace is automatically
        inferred from tenant name.'
      operationId: generate_internal_oauth_server_servers_oauth_generate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateInternalOAuthServerWithAnalysisRequest'
            example:
              session_id: 98765432-abcd-1234-efgh-123456789abc
              server_name: github-api
              description: GitHub API MCP Server
              transport: streamable_http
              tool_selection:
              - create_issue
              - get_user
              - list_repos
              - create_pull_request
              metadata:
                found: true
                auth_endpoint: https://github.com/login/oauth/authorize
                token_endpoint: https://github.com/login/oauth/access_token
                registration_endpoint: null
              manual_client_config:
                client_id: your_github_client_id
                client_secret: your_github_client_secret
              redirect_uris:
              - https://api.caylex.ai/auth/callback
              scopes:
              - repo
              - user
              - read:org
              start_server: true
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerGenerationResponse'
              example:
                server_id: 123e4567-e89b-12d3-a456-426614174000
                session_id: 98765432-abcd-1234-efgh-123456789abc
                generation_status: completed
                message: Successfully generated internal OAuth server 'github-api'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /servers/upload:
    post:
      tags:
      - Servers
      summary: Upload and Analyze OpenAPI Spec
      description: |
        Upload an OpenAPI specification file (JSON or YAML) for analysis. Returns an session_id
        that can be used to generate an internal MCP server from the spec.

        **File requirements:**
        - Accepted formats: .json, .yaml, .yml (OpenAPI spec or Postman Collection v2.1)
        - Maximum file size: 20 MB
      operationId: upload_and_analyze_spec_servers_upload_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_and_analyze_spec_servers_internal_upload_post'
            example:
              openapi_file: (binary file content - OpenAPI specification)
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadAnalysisResponse'
              example:
                session_id: 98765432-abcd-1234-efgh-123456789abc
                analysis_result:
                  endpoints_count: 25
                  tools_generated: 20
                  authentication_detected: oauth2
                  server_info:
                    title: GitHub API
                    version: v3
                message: 'Successfully analyzed OpenAPI spec: github-openapi.json'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '400':
          description: Bad Request - invalid file (wrong type, size exceeds 20 MB, or empty)
          content:
            application/json:
              example:
                error:
                  message: Upstream service returned 400 Bad Request
                  code: INTERNAL_SERVER_ERROR
                  status_code: 400
                  details: {}
        '500':
          description: Internal Server Error - upload/analysis failed
          content:
            application/json:
              examples:
                upload_error:
                  summary: Caylex error format
                  value:
                    error:
                      message: Upstream service returned 500 Internal Server Error
                      code: INTERNAL_SERVER_ERROR
                      status_code: 500
                      details: {}
                missing_uuid:
                  summary: Missing session ID
                  value:
                    detail: Failed to get session ID from upload response
  /servers/search:
    get:
      tags:
      - Servers
      summary: Search Servers
      operationId: search_servers_servers_search_get
      parameters:
      - name: sort_by
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ServerSortBy'
          default: created_desc
      - name: transport
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/ServerTransport'
          - type: 'null'
          title: Transport
        description: 'Filter by transport: streamable_http or sse'
      - name: auth_method
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/ServerAuthMethod'
          - type: 'null'
          title: Authentication Method
        description: 'Filter by authentication method: oauth, header, path, or query'
      - name: server_type
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/ServerType'
          - type: 'null'
          title: Server Type
        description: 'Filter by server type: external, foundry, or caylex'
      - name: auth_level
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/AuthLevel'
          - type: 'null'
          title: Authentication Level
        description: 'Filter by authentication level: project or user'
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 20
          title: Size
        description: Items per page
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Pagination cursor
          title: Cursor
        description: Pagination cursor
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Search
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_GetServerResponse_'
              example:
                items:
                - id: 123e4567-e89b-12d3-a456-426614174000
                  name: GitHub API Server
                  endpoint: mcp://acme-corp/github-api
                  description: Server for GitHub API integration
                  transport: streamable_http
                  auth_method: oauth
                  server_type: caylex
                  auth_level: user
                  logo_url: https://storage.caylex.ai/logos/github.png
                  health_check: null
                  metadata: null
                  created_at: '2024-01-10T08:00:00Z'
                  updated_at: '2024-01-15T10:30:00Z'
                meta:
                  size: 20
                  total: 100
                  next_cursor: eyJzb3J0Ijog
                  has_next: true
                  has_prev: false
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Search for servers by name, description, or tags using full-text
        search.
  /servers/upload-logo:
    post:
      tags:
      - Servers
      summary: Upload Server Logo
      operationId: upload_server_logo_servers_upload_logo_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_server_logo_servers_upload_logo_post'
            example:
              logo: (binary PNG file content)
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadLogoResponse'
              example:
                logo_url: https://storage.caylex.ai/logos/3f7c2b1a-b9e0-4a4b-9c33-2c0c7c2b1a3f/abc123def456.png
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '400':
          description: Response
          content:
            application/json:
              example:
                detail: File must be a PNG or JPEG image
      description: 'Upload a PNG logo image for a server. Maximum file size: 5MB.
        Returns the public URL of the uploaded logo.'
  /server-instances:
    get:
      tags:
      - Server Instances
      summary: List Server Instances
      operationId: list_server_instances_server_instances__get
      parameters:
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Filter by project ID
          title: Project Id
        description: Filter by project ID
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 20
          title: Size
        description: Items per page
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Pagination cursor
          title: Cursor
        description: Pagination cursor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_GetServerInstanceResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /server-instances/search:
    get:
      tags:
      - Server Instances
      summary: Search Server Instances
      description: Search server instances by server name or project name
      operationId: search_server_instances_server_instances_search__get
      parameters:
      - name: search
        in: query
        required: true
        schema:
          type: string
          title: Search
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Filter by project ID
          title: Project Id
        description: Filter by project ID
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 20
          title: Size
        description: Items per page
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Pagination cursor
          title: Cursor
        description: Pagination cursor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_GetServerInstanceResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /server-instances/{server_instance_id}/tools:
    get:
      tags:
      - Server Instances
      summary: Get Server Instance Tools
      description: |
        Get Tool Name, Description And Input_Schema For This Server Instance From The Server_Instance_Tool Table.
        Returns Tools Linked To This Server Instance. Returns 404 When The Server Instance Does Not
        Exist Or Has No Tools Yet.
      operationId: get_server_instance_tools_server_instances__server_instance_id__tools_get
      parameters:
      - name: server_instance_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Server Instance Id
        description: The Unique Identifier Of The Server Instance
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetServerInstanceToolsResponse'
              example:
                tools:
                - name: list_repos
                  description: List repositories for the authenticated user
                  input_schema:
                    type: object
                    properties:
                      query:
                        type: string
                    required:
                    - query
                - name: get_issue
                  description: Get an issue by number
                  input_schema: null
        '403':
          description: Forbidden - user not associated with a tenant
          content:
            application/json:
              example:
                detail: User not associated with a tenant
        '404':
          description: |
            Not Found. Either The Server Instance Does Not Exist (Detail "Server Instance Not Found"),
            Or Tool Listing Is Not Available (Detail "Tool Listing Is Not Yet Available For This Server. At Least One User Must Authenticate To Retrieve Tool Listings.").
          content:
            application/json:
              examples:
                instance_not_found:
                  summary: Server Instance Not Found
                  value:
                    detail: Server instance not found
                tool_listing_not_available:
                  summary: Server Instance Has No Tools Yet
                  value:
                    detail: "Tool listing is not yet available for this server. At least one user must authenticate to retrieve tool listings."
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /server-instances/{server_instance_id}:
    post:
      tags:
      - Server Instances
      summary: Update Server Instance Status
      description: Update the status of a server instance (pause or unpause)
      operationId: update_server_instance_status_server_instances__server_instance_id__post
      parameters:
      - name: server_instance_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Server Instance Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServerInstanceRequest'
            example:
              status: pause
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerInstanceResponse'
              examples:
                pause:
                  summary: Pause Response
                  value:
                    server_instance_id: 123e4567-e89b-12d3-a456-426614174000
                    server_id: 123e4567-e89b-12d3-a456-426614174001
                    server_name: github-api
                    status: paused
                    message: Successfully paused server instance 'github-api'
                unpause:
                  summary: Unpause Response
                  value:
                    server_instance_id: 123e4567-e89b-12d3-a456-426614174000
                    server_id: 123e4567-e89b-12d3-a456-426614174001
                    server_name: github-api
                    status: running
                    message: Successfully unpaused server instance 'github-api'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '404':
          description: Response
          content:
            application/json:
              example:
                detail: Server instance not found
        '400':
          description: Response
          content:
            application/json:
              examples:
                invalid_status:
                  summary: Invalid Status
                  value:
                    detail: Invalid status. Must be 'pause' or 'unpause'
    get:
      tags:
      - Server Instances
      summary: Get Server Instance
      description: Get server instance details including status
      operationId: get_server_instance_server_instances__server_instance_id__get
      parameters:
      - name: server_instance_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Server Instance Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetServerInstanceResponse'
              example:
                id: 123e4567-e89b-12d3-a456-426614174000
                server_id: 123e4567-e89b-12d3-a456-426614174001
                project_id: 123e4567-e89b-12d3-a456-426614174002
                paused: false
                created_at: '2024-01-15T10:30:00Z'
                updated_at: '2024-01-15T10:30:00Z'
                server_name: github-api
                project_name: My Project
                auth_method: oauth
                auth_credentials_level: user
                server_type: external
                transport: streamable_http
                logo_url: https://storage.caylex.ai/logos/github.png
                description: GitHub API MCP Server
                num_tools: 15
        '404':
          description: Not Found
          content:
            application/json:
              example:
                detail: Server instance not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /server-registry:
    get:
      tags:
      - Server Registry
      summary: List Servers from Registry
      operationId: get_server_registry_server_registry_get
      parameters:
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 20
          title: Size
        description: Items per page
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Pagination cursor
          title: Cursor
        description: Pagination cursor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_GetServerRegistryResponse_'
              example:
                items:
                - id: 123e4567-e89b-12d3-a456-426614174007
                  name: Github Server from Registry
                  description: Github Server from Registry
                  endpoint: https://github.com/mcp
                  transport: streamable_http
                  logo_url: https://github.com/github.svg
                  server_type: external
                  auth_methods: ["oauth"]
                  auth_config:
                    oauth_config:
                      authorization_endpoint: "https://github.com/login/oauth/authorize"
                      token_endpoint: "https://github.com/login/oauth/access_token"
                      scopes: ["repo", "user:email"]
                - id: 123e4567-e89b-12d3-a456-426614174008
                  name: API Server with Header Auth
                  description: API Server with Header Authentication
                  endpoint: https://api.example.com
                  transport: streamable_http
                  logo_url: https://api.example.com/logo.svg
                  server_type: external
                  auth_methods: ["header"]
                  auth_config:
                    header_config:
                      headers:
                        - header_name: "Authorization"
                          header_value_prefix: "Bearer "
                        - header_name: "X-API-Key"
                          header_value_prefix: "Key "
                meta:
                  size: 20
                  total: 100
                  next_cursor: eyJzb3J0Ijog
                  has_next: true
                  has_prev: false
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Retrieve a list of available MCP server registries. Registries
        contain pre-built servers that can be added to your tenant.
  /server-registry/search:
    get:
      tags:
      - Server Registry
      summary: Search Servers from Registry
      operationId: search_server_registry_server_registry_search_get
      parameters:
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 20
          title: Size
        description: Items per page
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Pagination cursor
          title: Cursor
        description: Pagination cursor
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Search
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_GetServerRegistryResponse_'
              example:
                items:
                - id: 123e4567-e89b-12d3-a456-426614174008
                  name: Github Server from Registry 
                  description: Github Server from Registry
                  endpoint: https://github.com/mcp
                  transport: streamable_http
                  logo_url: https://github.com/github.svg
                  server_type: external
                  auth_methods: ["oauth"]
                  auth_config:
                    oauth_config:
                      authorization_endpoint: "https://github.com/login/oauth/authorize"
                      token_endpoint: "https://github.com/login/oauth/access_token"
                      scopes: ["repo", "user:email"]
                meta:
                  size: 20
                  total: 100
                  next_cursor: eyJzb3J0Ijog
                  has_next: true
                  has_prev: false
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Search for servers in available registries by name, description,
        or category.
  /server-registry/{server_registry_id}/tools:
    get:
      tags:
      - Server Registry
      summary: Get tools for server from registry
      description: |
        Get tool names and descriptions for a server created from this registry.
        If the tenant has a server created from this registry with tools synced,
        returns the list of tools (name and description). Returns 404 when the
        registry does not exist, or when there is no server from this registry
        for the tenant, or when the server has no tools yet (same error message
        in all cases).
      operationId: get_server_registry_tools_server_registry__server_registry_id__tools_get
      parameters:
      - name: server_registry_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Server Registry Id
        description: The unique identifier of the server registry entry
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetServerRegistryToolsResponse'
              example:
                tools:
                - name: list_repos
                  description: List repositories for the authenticated user
                - name: get_issue
                  description: Get an issue by number
        '403':
          description: Forbidden - user not associated with a tenant
          content:
            application/json:
              example:
                detail: User not associated with a tenant
        '404':
          description: |
            Not found. Either the server registry entry does not exist (detail "Server registry entry not found"),
            or tool listing is not available (detail "Tool listing is not yet available for this server...").
          content:
            application/json:
              examples:
                registry_not_found:
                  summary: Server registry entry not found
                  value:
                    detail: Server registry entry not found
                tool_listing_not_available:
                  summary: No server for tenant or server has no tools
                  value:
                    detail: "Tool listing is not yet available for this server. You can still add this server to your library and authenticate to get tool listings."
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /server-registry/{server_registry_id}:
    get:
      tags:
      - Server Registry
      summary: Get Server from Registry by ID
      description: Retrieve a specific server from registry by its unique identifier.
        This endpoint returns detailed information about a single server from registry
        including its name, description, endpoint, logo, and server type.
      operationId: get_server_registry_by_id_server_registry__server_registry_id__get
      parameters:
      - name: server_registry_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Server Registry Id
        description: The unique identifier of the server registry entry
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetServerRegistryResponse'
              example:
                id: 123e4567-e89b-12d3-a456-426614174007
                name: Github Server from Registry
                description: Github Server from Registry
                endpoint: https://github.com/mcp
                transport: streamable_http
                logo_url: https://github.com/github.svg
                server_type: external
                auth_methods: ["oauth"]
                auth_config:
                  oauth_config:
                    authorization_endpoint: "https://github.com/login/oauth/authorize"
                    token_endpoint: "https://github.com/login/oauth/access_token"
                    scopes: ["repo", "user:email"]
        '404':
          description: Server from Registry Not Found
          content:
            application/json:
              example:
                detail: Server from registry not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /navigator-instances/{navigator_instance_id}/api-keys:
    get:
      tags:
      - API Keys
      summary: List API Keys
      description: Retrieve a paginated list of API keys for a specific navigator instance.
        API keys are used for programmatic access to the Caylex API.
      operationId: list_api_keys_navigator_instances__navigator_instance_id__api_keys_get
      parameters:
      - name: navigator_instance_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Navigator Instance Id
        description: The navigator instance ID to list API keys for
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 20
          title: Size
        description: Items per page
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Pagination cursor
          title: Cursor
        description: Pagination cursor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_GetApiKeyResponse_'
              example:
                items:
                - id: 123e4567-e89b-12d3-a456-426614174009
                  navigator_instance_id: 123e4567-e89b-12d3-a456-426614174010
                  navigator_instance_name: Customer Support Navigator
                  project_id: 123e4567-e89b-12d3-a456-426614174003
                  project_name: Acme Analytics
                  preview: sk_live_1234
                  name: Production API Key
                  created_at: '2024-01-01T00:00:00Z'
                  updated_at: '2024-01-15T10:30:00Z'
                meta:
                  size: 20
                  total: 100
                  next_cursor: eyJzb3J0Ijog
                  has_next: true
                  has_prev: false
        '404':
          description: Navigator instance not found
          content:
            application/json:
              example:
                detail: Navigator instance not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - API Keys
      summary: Create API Key
      description: Create a new API key for a navigator instance with specified name 
        and expiration. Returns the full API key value (only shown once).
      operationId: create_api_key_navigator_instances__navigator_instance_id__api_keys_post
      parameters:
      - name: navigator_instance_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Navigator Instance Id
        description: The navigator instance ID to create an API key for
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApiKeyRequest'
            example:
              name: Development API Key
              description: API key for development environment
              expires_at: '2024-04-15T10:30:00Z'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateApiKeyResponse'
              example:
                id: 456e7890-e89b-12d3-a456-426614174027
                preview: sk_test_1234
                key: sk_test_abcdefghijklmnopqrstuvwxyz1234567890
        '404':
          description: Navigator instance not found
          content:
            application/json:
              example:
                detail: Navigator instance not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /navigator-instances/{navigator_instance_id}/api-keys/search:
    get:
      tags:
      - API Keys
      summary: Search API Keys
      description: Search API keys for a navigator instance with case-insensitive partial matching.
        Supports searching by name and description. Supports pagination.
      operationId: search_api_keys_navigator_instances__navigator_instance_id__api_keys_search_get
      parameters:
      - name: navigator_instance_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Navigator Instance Id
        description: The navigator instance ID to search API keys for
      - name: q
        in: query
        required: false
        schema:
          type: string
          title: Query
          description: Search term for partial matching against name and description
        description: Optional search term for partial matching against name and description
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: Size
          description: "Number of items per page (default: 20, max: 100)"
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Pagination cursor
          title: Cursor
        description: Pagination cursor for navigating through results
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_GetApiKeyResponse_'
              example:
                items:
                - id: 123e4567-e89b-12d3-a456-426614174009
                  navigator_instance_id: 123e4567-e89b-12d3-a456-426614174010
                  navigator_instance_name: Customer Support Navigator
                  project_id: 123e4567-e89b-12d3-a456-426614174003
                  project_name: Acme Analytics
                  preview: sk_live_1234
                  key_prefix: sk_live_1234
                  name: Production API Key
                  description: Main production API key
                  expires_at: '2024-12-31T23:59:59Z'
                  created_at: '2024-01-01T00:00:00Z'
                  updated_at: '2024-01-15T10:30:00Z'
                meta:
                  size: 20
                  total: 100
                  next_cursor: eyJzb3J0Ijog
                  has_next: true
                  has_prev: false
        '404':
          description: Navigator instance not found
          content:
            application/json:
              example:
                detail: Navigator instance not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /navigator-instances/{navigator_instance_id}/api-keys/{api_key_id}:
    get:
      tags:
      - API Keys
      summary: Get API Key Details
      description: Retrieve details about a specific API key (does not include the
        actual key value).
      operationId: get_api_key_navigator_instances__navigator_instance_id__api_keys__api_key_id__get
      parameters:
      - name: navigator_instance_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Navigator Instance Id
        description: The navigator instance ID
      - name: api_key_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Api Key Id
        description: The API key ID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiKeyResponse'
              example:
                id: 123e4567-e89b-12d3-a456-426614174009
                navigator_instance_id: 123e4567-e89b-12d3-a456-426614174010
                navigator_instance_name: Customer Support Navigator
                project_id: 123e4567-e89b-12d3-a456-426614174003
                project_name: Acme Analytics
                preview: sk_live_1234
                name: Production API Key
                created_at: '2024-01-01T00:00:00Z'
                updated_at: '2024-01-15T10:30:00Z'
        '404':
          description: Navigator instance or API key not found
          content:
            application/json:
              example:
                detail: API key not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - API Keys
      summary: Update API Key
      description: Update API key name, description, or expiration date.
        Cannot change the actual key value.
      operationId: update_api_key_navigator_instances__navigator_instance_id__api_keys__api_key_id__patch
      parameters:
      - name: navigator_instance_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Navigator Instance Id
        description: The navigator instance ID
      - name: api_key_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Api Key Id
        description: The API key ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateApiKeyRequest'
            example:
              name: Updated API Key Name
              description: Updated description for the API key
              expires_at: '2025-06-01T00:00:00Z'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModifiedApiKeyResponse'
              example:
                id: 123e4567-e89b-12d3-a456-426614174009
        '404':
          description: Navigator instance or API key not found
          content:
            application/json:
              example:
                detail: API key not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - API Keys
      summary: Delete API Key
      description: Permanently delete an API key. Active integrations using this key
        will immediately stop working.
      operationId: delete_api_key_navigator_instances__navigator_instance_id__api_keys__api_key_id__delete
      parameters:
      - name: navigator_instance_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Navigator Instance Id
        description: The navigator instance ID
      - name: api_key_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Api Key Id
        description: The API key ID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModifiedApiKeyResponse'
              example:
                id: 123e4567-e89b-12d3-a456-426614174009
        '404':
          description: Navigator instance or API key not found
          content:
            application/json:
              example:
                detail: API key not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /notifications:
    get:
      tags:
      - Notifications
      summary: List notifications
      operationId: list_notifications_notifications_get
      parameters:
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Filter by project
          title: Project Id
        description: Filter by project
      - name: event_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by event type
          title: Event Type
        description: Filter by event type
      - name: severity
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by severity
          title: Severity
        description: Filter by severity
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Search body, severity, data (JSON), or actor_id
          title: Search
        description: Search body, severity, data (JSON), or actor_id
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 20
          title: Size
        description: Items per page
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Pagination cursor
          title: Cursor
        description: Pagination cursor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_NotificationResponse_'
              example:
                items:
                - id: 123e4567-e89b-12d3-a456-426614174099
                  project_id: 456e7890-e89b-12d3-a456-426614174015
                  event_type: project.created
                  title: Project created
                  body: Project 'Production' was created by admin@example.com in project Production.
                  severity: info
                  data:
                    project_name: Production
                  is_read: false
                  created_at: '2024-01-15T10:30:00Z'
                  target_type: project
                  target_id: 456e7890-e89b-12d3-a456-426614174015
                  actor_id: 789e0123-e89b-12d3-a456-426614174088
                meta:
                  size: 20
                  total: 1
                  next_cursor: null
                  has_next: false
                  has_prev: false
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: |
        Paginated notifications for the authenticated user's tenant.

        Rows hidden by the caller's `last_cleared_at` watermark are excluded.
        `is_read` is derived per user from `last_read_at`, not stored on the row.

        When `search` is set, matches body, severity, data (JSON), or actor_id
        (case-insensitive partial match).
  /notifications/unread-count:
    get:
      tags:
      - Notifications
      summary: Get unread notification count
      operationId: get_unread_count_notifications_unread_count_get
      parameters:
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Filter by project
          title: Project Id
        description: Filter by project
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnreadCountResponse'
              example:
                count: 3
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Count notifications newer than the user's `last_read_at` watermark.
  /notifications/read-all:
    post:
      tags:
      - Notifications
      summary: Mark all current notifications as read for the calling user
      operationId: read_all_notifications_read_all_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
              example:
                status: ok
      description: |
        Push the user's `last_read_at` watermark to now. Per-user; does not affect
        other admins. Platform tokens no-op.
  /notifications/clear-all:
    post:
      tags:
      - Notifications
      summary: Clear the inbox for the calling user
      operationId: clear_all_notifications_clear_all_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
              example:
                status: ok
      description: |
        Push the user's `last_cleared_at` watermark to now, hiding visible rows from
        this user's inbox. Also advances `last_read_at`. Platform tokens no-op.
  /platform-access-tokens:
    post:
      tags:
      - Platform Access Tokens
      summary: Create Platform Access Token
      description: Create a platform access token for the current tenant. The raw token
        is returned only in this response; store it securely. Only admin role is allowed;
        any other role returns 400. Requires cookie auth (admin).
      operationId: create_platform_access_token_platform_access_tokens_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePlatformAccessTokenRequest'
            example:
              name: CI token
              description: Token for CI/CD pipeline
              role: admin
              expires_at: '2026-12-31T23:59:59Z'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePlatformAccessTokenResponse'
              example:
                id: 550e8400-e29b-41d4-a716-446655440000
                name: CI token
                description: Token for CI/CD pipeline
                role: admin
                expires_at: '2026-12-31T23:59:59Z'
                token: xY7_kL2mN9pQ...
                preview: xY7_......
                created_at: '2026-02-01T12:00:00Z'
        '400':
          description: Only admin role is allowed
          content:
            application/json:
              example:
                detail: Only admin role is allowed for platform access tokens
        '403':
          description: User not associated with a tenant
          content:
            application/json:
              example:
                detail: User not associated with a tenant
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Platform Access Tokens
      summary: List Platform Access Tokens
      description: List platform access tokens for the current tenant (no secrets).
        Requires cookie auth (admin).
      operationId: list_platform_access_tokens_platform_access_tokens_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GetPlatformAccessTokenResponse'
              example:
              - id: 550e8400-e29b-41d4-a716-446655440000
                name: CI token
                description: Token for CI/CD pipeline
                preview: xY7_......
                role: admin
                expires_at: '2026-12-31T23:59:59Z'
                created_at: '2026-02-01T12:00:00Z'
        '403':
          description: User not associated with a tenant
          content:
            application/json:
              example:
                detail: User not associated with a tenant
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /platform-access-tokens/{token_id}:
    delete:
      tags:
      - Platform Access Tokens
      summary: Delete Platform Access Token
      description: Delete a platform access token. Token must belong to the current
        tenant. Requires cookie auth (admin).
      operationId: delete_platform_access_token_platform_access_tokens__token_id__delete
      parameters:
      - name: token_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Token Id
        description: The platform access token ID to delete
      responses:
        '204':
          description: No Content
        '404':
          description: Platform access token not found
          content:
            application/json:
              example:
                detail: Platform access token not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /analytics/navigator-tool-connections:
    get:
      tags:
      - Analytics
      summary: Get Navigator-Tool Connection Matrix
      description: Retrieve which navigators are using which tools with usage counts.
        Useful for understanding tool adoption.
      operationId: get_navigator_tool_connections_analytics_navigator_tool_connections_get
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          description: 'Time window (default: 24h)'
          default: 24h
          title: Window
        description: 'Time window (default: 24h)'
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by project ID
          title: Project Id
        description: Filter by project ID
      - name: navigator_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by navigator instance ID
          title: Navigator Instance Id
        description: Filter by navigator instance ID
      - name: server_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by server instance ID
          title: Server Instance Id
        description: Filter by server instance ID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NavigatorToolConnectionsResponse'
              example:
                success: true
                data:
                - navigator_instance_id: 123e4567-e89b-12d3-a456-426614174002
                  tool_id: 789e0123-e89b-12d3-a456-426614174019
                  connection_status: active
                  usage_count: 234
                  window: 24h
                  filters: {}
                  timestamp: '2024-01-15T10:30:00Z'
                timestamp: '2024-01-15T10:30:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /analytics/average-tool-call-latency:
    get:
      tags:
      - Analytics
      summary: Get Average Tool Call Latency
      description: Retrieve average latency metrics for tool calls including mean,
        p50, p95, and p99 percentiles.
      operationId: get_average_tool_call_latency_analytics_average_tool_call_latency_get
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          description: 'Time window (default: 24h)'
          default: 24h
          title: Window
        description: 'Time window (default: 24h)'
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by project ID
          title: Project Id
        description: Filter by project ID
      - name: navigator_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by navigator instance ID
          title: Navigator Instance Id
        description: Filter by navigator instance ID
      - name: server_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by server instance ID
          title: Server Instance Id
        description: Filter by server instance ID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AverageToolCallLatencyResponse'
              example:
                success: true
                data:
                  average_latency: 0.2505
                  total_calls: 5000
                  window: 24h
                  filters: {}
                  timestamp: '2024-01-15T10:30:00Z'
                timestamp: '2024-01-15T10:30:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /analytics/average-tool-call-latency-graph:
    get:
      tags:
      - Analytics
      summary: Get Average Tool Call Latency Graph
      description: Retrieve average tool call latency graph data with optional filters
      operationId: get_average_tool_call_latency_graph_analytics_average_tool_call_latency_graph_get
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          description: 'Time window (default: 1mon)'
          default: 1mon
          title: Window
        description: 'Time window (default: 1mon)'
      - name: view
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ViewType'
        description: View type for the graph
      - name: frequency
        in: query
        required: false
        schema:
          allOf:
          - $ref: '#/components/schemas/Frequency'
          - default: 1d
        description: 'Frequency of data aggregation (e.g., 1m, 2h, 3d, 1w, 1mo)'
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by project ID
          title: Project Id
        description: Filter by project ID
      - name: navigator_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by navigator instance ID
          title: Navigator Instance Id
        description: Filter by navigator instance ID
      - name: server_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by server instance ID
          title: Server Instance Id
        description: Filter by server instance ID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AverageToolCallLatencyGraphResponse'
              example:
                success: true
                data:
                  data_points:
                  - timestamp: '2024-01-01T00:00:00Z'
                    average_latency: 0.2505
                    total_calls: 100
                  - timestamp: '2024-01-01T01:00:00Z'
                    average_latency: 0.2301
                    total_calls: 150
                  view: timeseries
                  frequency: 1d
                  window: 1mon
                  filters: {}
                  timestamp: '2024-01-15T10:30:00Z'
                timestamp: '2024-01-15T10:30:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /analytics/average-tool-calls-per-query:
    get:
      tags:
      - Analytics
      summary: Get Average Tool Calls Per Query
      description: Retrieve the average number of tool calls made per query, useful
        for understanding navigator complexity.
      operationId: get_average_tool_calls_per_query_analytics_average_tool_calls_per_query_get
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          description: 'Lookback period (default: 24h)'
          default: 24h
          title: Window
        description: 'Lookback period (default: 24h)'
      - name: view
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ViewType'
          description: 'View type (default: timeseries)'
          default: timeseries
        description: 'View type (default: timeseries)'
      - name: frequency
        in: query
        required: false
        schema:
          allOf:
          - $ref: '#/components/schemas/Frequency'
          - default: 1h
        description: 'Frequency of aggregation (e.g., 1m, 2h, 3d, 1w, 1mo)'
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by project ID
          title: Project Id
        description: Filter by project ID
      - name: navigator_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by navigator instance ID
          title: Navigator Instance Id
        description: Filter by navigator instance ID
      - name: server_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by server instance ID
          title: Server Instance Id
        description: Filter by server instance ID
      - name: tool_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional tool ID filter
          title: Tool Id
        description: Optional tool ID filter
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolCallsPerQueryResponse'
              example:
                success: true
                data:
                  average_tool_calls_per_query: 3.7
                  total_queries: 12345
                  total_tool_calls: 45678
                  window: 24h
                  view: timeseries
                  frequency: 1h
                  filters: {}
                  timestamp: '2024-01-15T10:30:00Z'
                timestamp: '2024-01-15T10:30:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /analytics/average-tool-call-runtime:
    get:
      tags:
      - Analytics
      summary: Get Average Tool Procedure Runtime
      description: Retrieve average runtime metrics for complete tool procedures including
        mean, p50, p95, and p99 percentiles.
      operationId: get_average_tool_procedure_runtime_analytics_average_tool_procedure_runtime_get
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          description: 'Time window (default: 24h)'
          default: 24h
          title: Window
        description: 'Time window (default: 24h)'
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by project ID
          title: Project Id
        description: Filter by project ID
      - name: navigator_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by navigator instance ID
          title: Navigator Instance Id
        description: Filter by navigator instance ID
      - name: server_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by server instance ID
          title: Server Instance Id
        description: Filter by server instance ID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AverageToolCallRuntimeResponse'
              example:
                success: true
                data:
                  average_runtime: 1.2505
                  total_executions: 5000
                  window: 24h
                  filters: {}
                  timestamp: '2024-01-15T10:30:00Z'
                timestamp: '2024-01-15T10:30:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /analytics/average-tool-call-runtime-graph:
    get:
      tags:
      - Analytics
      summary: Get Average Tool Call Runtime Graph
      description: Retrieve average tool call runtime graph data with optional filters
      operationId: get_average_tool_call_runtime_graph_analytics_average_tool_call_runtime_graph_get
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          description: 'Time window (default: 1mon)'
          default: 1mon
          title: Window
        description: 'Time window (default: 1mon)'
      - name: view
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ViewType'
        description: View type for the graph
      - name: frequency
        in: query
        required: false
        schema:
          allOf:
          - $ref: '#/components/schemas/Frequency'
          - default: 1d
        description: 'Frequency of data aggregation (e.g., 1m, 2h, 3d, 1w, 1mo)'
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by project ID
          title: Project Id
        description: Filter by project ID
      - name: navigator_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by navigator instance ID
          title: Navigator Instance Id
        description: Filter by navigator instance ID
      - name: server_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by server instance ID
          title: Server Instance Id
        description: Filter by server instance ID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AverageToolCallRuntimeGraphResponse'
              example:
                success: true
                data:
                  data_points:
                  - timestamp: '2024-01-01T00:00:00Z'
                    average_runtime: 1.2505
                    total_executions: 100
                  - timestamp: '2024-01-01T01:00:00Z'
                    average_runtime: 1.2301
                    total_executions: 150
                  view: timeseries
                  frequency: 1d
                  window: 1mon
                  filters: {}
                  timestamp: '2024-01-15T10:30:00Z'
                timestamp: '2024-01-15T10:30:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /analytics/average-tool-calls-per-query-graph:
    get:
      tags:
      - Analytics
      summary: Get Average Tool Calls Per Query Graph
      description: Retrieve average tool calls per query graph data with optional filters
      operationId: get_average_tool_calls_per_query_graph_analytics_average_tool_calls_per_query_graph_get
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          description: 'Time window (default: 1mon)'
          default: 1mon
          title: Window
        description: 'Time window (default: 1mon)'
      - name: view
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ViewType'
        description: View type for the graph
      - name: frequency
        in: query
        required: false
        schema:
          allOf:
          - $ref: '#/components/schemas/Frequency'
          - default: 1d
        description: 'Frequency of data aggregation (e.g., 1m, 2h, 3d, 1w, 1mo)'
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by project ID
          title: Project Id
        description: Filter by project ID
      - name: navigator_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by navigator instance ID
          title: Navigator Instance Id
        description: Filter by navigator instance ID
      - name: server_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by server instance ID
          title: Server Instance Id
        description: Filter by server instance ID
      - name: tool_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional tool ID filter
          title: Tool Id
        description: Optional tool ID filter
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolCallsPerQueryGraphResponse'
              example:
                success: true
                data:
                  data_points:
                  - timestamp: '2024-01-01T00:00:00Z'
                    average_tool_calls_per_query: 2.5
                    total_queries: 100
                    total_tool_calls: 250
                  - timestamp: '2024-01-01T01:00:00Z'
                    average_tool_calls_per_query: 3.2
                    total_queries: 150
                    total_tool_calls: 480
                  view: timeseries
                  frequency: 1d
                  window: 1mon
                  filters: {}
                  timestamp: '2024-01-15T10:30:00Z'
                timestamp: '2024-01-15T10:30:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /analytics/error-rate-graph:
    get:
      tags:
      - Analytics
      summary: Get Error Rate Time Series Graph Data
      description: Retrieve time series data for error rates over a specified period.
        Shows percentage of failed queries/tool calls.
      operationId: get_error_rate_graph_analytics_error_rate_graph_get
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          description: 'Time window (default: 1mon)'
          default: 1mon
          title: Window
        description: 'Time window (default: 1mon)'
      - name: view
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ViewType'
          description: View type for the graph
          default: timeseries
        description: View type for the graph
      - name: frequency
        in: query
        required: false
        schema:
          allOf:
          - $ref: '#/components/schemas/Frequency'
          - default: 1d
        description: 'Frequency of data aggregation (e.g., 1m, 2h, 3d, 1w, 1mo)'
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by project ID
          title: Project Id
        description: Filter by project ID
      - name: navigator_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by navigator instance ID
          title: Navigator Instance Id
        description: Filter by navigator instance ID
      - name: server_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by server instance ID
          title: Server Instance Id
        description: Filter by server instance ID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRateGraphResponse'
              example:
                success: true
                data:
                  view_type: timeseries
                  frequency: 1d
                  time_series_data:
                  - timestamp: '2024-01-01T00:00:00Z'
                    value: 0.02
                  total_errors: 100
                  total_tool_calls: 5000
                  average_error_rate: 0.02
                  timestamp: '2024-01-15T10:30:00Z'
                timestamp: '2024-01-15T10:30:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /analytics/error-types-graph:
    get:
      tags:
      - Analytics
      summary: Get Error Types Distribution
      description: Retrieve a breakdown of error types (timeout, authentication, rate
        limit, etc.) with counts and percentages.
      operationId: get_error_types_graph_analytics_error_types_graph_get
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          description: 'Time window (default: 1mon)'
          default: 1mon
          title: Window
        description: 'Time window (default: 1mon)'
      - name: view
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ViewType'
          description: View type for the graph
          default: timeseries
        description: View type for the graph
      - name: frequency
        in: query
        required: false
        schema:
          allOf:
          - $ref: '#/components/schemas/Frequency'
          - default: 1d
        description: 'Frequency of data aggregation (e.g., 1m, 2h, 3d, 1w, 1mo)'
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by project ID
          title: Project Id
        description: Filter by project ID
      - name: navigator_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by navigator instance ID
          title: Navigator Instance Id
        description: Filter by navigator instance ID
      - name: server_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by server instance ID
          title: Server Instance Id
        description: Filter by server instance ID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorTypesGraphResponse'
              example:
                success: true
                data:
                  view_type: timeseries
                  frequency: 1d
                  time_series_data:
                  - error_type: caylex_timeout_errors_total
                    error_name: Timeout Errors
                    time_series_data:
                    - timestamp: '2024-01-01T00:00:00Z'
                      value: 15
                      labels:
                        error_type: caylex_timeout_errors_total
                        error_name: Timeout Errors
                    - timestamp: '2024-01-02T00:00:00Z'
                      value: 15
                      labels:
                        error_type: caylex_timeout_errors_total
                        error_name: Timeout Errors
                    - timestamp: '2024-01-03T00:00:00Z'
                      value: 15
                      labels:
                        error_type: caylex_timeout_errors_total
                        error_name: Timeout Errors
                    total_count: 45
                  - error_type: caylex_authentication_errors_total
                    error_name: Authentication Errors
                    time_series_data:
                    - timestamp: '2024-01-01T00:00:00Z'
                      value: 28
                      labels:
                        error_type: caylex_authentication_errors_total
                        error_name: Authentication Errors
                    - timestamp: '2024-01-02T00:00:00Z'
                      value: 28
                      labels:
                        error_type: caylex_authentication_errors_total
                        error_name: Authentication Errors
                    - timestamp: '2024-01-03T00:00:00Z'
                      value: 28
                      labels:
                        error_type: caylex_authentication_errors_total
                        error_name: Authentication Errors
                    total_count: 84
                  total_errors: 129
                  timestamp: '2024-01-15T10:30:00Z'
                timestamp: '2024-01-15T10:30:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /analytics/heroes/global/stats:
    get:
      tags:
      - Analytics
      summary: Get Global Statistics
      description: Retrieve high-level statistics including total queries and tool calls
        for both the current and previous comparison periods. Supports filtering by project,
        navigator instance, or server instance. The tenant ID is automatically determined from
        the authenticated user's context. All provided filter IDs are validated to ensure
        they belong to the authenticated user's tenant.
      operationId: get_global_stats_analytics_heroes_global_stats_get
      parameters:
      - name: comparison_period
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ComparisonPeriod'
        description: 'Comparison period (default: rolling_month). Returns stats for both current and previous periods'
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by project ID
          title: Project Id
        description: Filter by project ID
      - name: navigator_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by navigator instance ID
          title: Navigator Instance Id
        description: Filter by navigator instance ID
      - name: server_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by server instance ID
          title: Server Instance Id
        description: Filter by server instance ID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalStatsResponse'
              example:
                success: true
                data:
                  total_queries: 150000
                  total_tool_calls: 450000
                  previous_total_queries: 120000
                  previous_total_tool_calls: 380000
                  comparison_period: rolling_month
                  timestamp: '2024-01-15T10:30:00Z'
                timestamp: '2024-01-15T10:30:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /analytics/queries-processed:
    get:
      tags:
      - Analytics
      summary: Get Total Queries Processed
      description: Retrieve the total number of queries processed in a given time
        period with percentage change compared to previous period.
      operationId: get_queries_processed_analytics_queries_processed_get
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          description: 'Time window (default: 1mon)'
          default: 1mon
          title: Window
        description: 'Time window (default: 1mon)'
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by project ID
          title: Project Id
        description: Filter by project ID
      - name: navigator_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by navigator instance ID
          title: Navigator Instance Id
        description: Filter by navigator instance ID
      - name: server_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by server instance ID
          title: Server Instance Id
        description: Filter by server instance ID
      - name: tool_name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by tool name
          title: Tool Name
        description: Filter by tool name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueriesProcessedResponse'
              example:
                success: true
                data:
                  total_queries: 12345
                  window: 1mon
                  filters: {}
                  timestamp: '2024-01-15T10:30:00Z'
                timestamp: '2024-01-15T10:30:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /analytics/queries-processed-graph:
    get:
      tags:
      - Analytics
      summary: Get Queries Time Series Graph Data
      description: Retrieve time series data for queries over a specified period.
        Returns data points suitable for graphing.
      operationId: get_queries_processed_graph_analytics_queries_processed_graph_get
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          description: 'Time window (default: 1mon)'
          default: 1mon
          title: Window
        description: 'Time window (default: 1mon)'
      - name: view
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ViewType'
          description: View type for the graph
          default: timeseries
        description: View type for the graph
      - name: frequency
        in: query
        required: false
        schema:
          allOf:
          - $ref: '#/components/schemas/Frequency'
          - default: 1d
        description: 'Frequency of data aggregation (e.g., 1m, 2h, 3d, 1w, 1mo)'
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by project ID
          title: Project Id
        description: Filter by project ID
      - name: navigator_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by navigator instance ID
          title: Navigator Instance Id
        description: Filter by navigator instance ID
      - name: server_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by server instance ID
          title: Server Instance Id
        description: Filter by server instance ID
      - name: tool_name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by tool name
          title: Tool Name
        description: Filter by tool name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolCallsGraphResponse'
              example:
                success: true
                data:
                  data_points:
                  - timestamp: '2024-01-01T00:00:00Z'
                    count: 456
                  - timestamp: '2024-01-02T00:00:00Z'
                    count: 512
                  view: timeseries
                  frequency: 1d
                  window: 1mon
                  filters: {}
                  timestamp: '2024-01-15T10:30:00Z'
                timestamp: '2024-01-15T10:30:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /analytics/tool-calls-processed:
    get:
      tags:
      - Analytics
      summary: Get Total Tool Calls Processed
      description: Retrieve the total number of tool calls processed in a given time
        period with percentage change compared to previous period.
      operationId: get_tool_calls_processed_analytics_tool_calls_processed_get
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          description: 'Time window (default: 1mon)'
          default: 1mon
          title: Window
        description: 'Time window (default: 1mon)'
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by project ID
          title: Project Id
        description: Filter by project ID
      - name: navigator_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by navigator instance ID
          title: Navigator Instance Id
        description: Filter by navigator instance ID
      - name: server_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by server instance ID
          title: Server Instance Id
        description: Filter by server instance ID
      - name: tool_name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by tool name
          title: Tool Name
        description: Filter by tool name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolCallsProcessedResponse'
              example:
                success: true
                data:
                  total_tool_calls: 45678
                  window: 1mon
                  filters: {}
                  timestamp: '2024-01-15T10:30:00Z'
                timestamp: '2024-01-15T10:30:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /analytics/proxy-tools:
    get:
      tags:
      - Analytics
      summary: Get Proxy Tool Counts
      description: |
        Retrieve proxy tool counts with optional filters.
        
        This endpoint returns counts for suggest_tools, get_tool_schemas, and invoke_tools
        using the `caylex_proxy_tool_execution_total` metric from ClickHouse.
        
        Unlike other endpoints, this endpoint:
        - Does not support `server_instance_id` filter
        - Returns counts for proxy tool names
        
        The endpoint supports filtering by:
        - `project_id`: Filter results by a specific project
        - `navigator_instance_id`: Filter results by a specific navigator instance
        - `window`: Time window for the query (default: 1w)
        
        All filters are optional and can be combined. The tenant_id is automatically
        determined from the authenticated user's context.
      operationId: get_proxy_tool_efficiency_analytics_proxy_tools_get
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          description: 'Time window for the query. Supported formats: 1h, 24h, 1d, 7d, 1w, 1mon'
          default: 1w
          title: Window
          examples:
            - 1h
            - 24h
            - 1d
            - 1w
            - 1mon
        description: 'Time window for the query (default: 1w). Examples: 1h, 24h, 1d, 1w, 1mon'
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Filter by project ID (UUID)
          title: Project Id
        description: Filter results by a specific project ID. Must belong to the authenticated user's tenant.
        example: '550e8400-e29b-41d4-a716-446655440000'
      - name: navigator_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Filter by navigator instance ID (UUID)
          title: Navigator Instance Id
        description: Filter results by a specific navigator instance ID. Must belong to the authenticated user's tenant.
        example: '550e8400-e29b-41d4-a716-446655440001'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyToolEfficiencyResponse'
              examples:
                basic:
                  summary: Basic response without filters
                  value:
                    success: true
                    data:
                      suggest_tools_count: 1000
                      get_tool_schemas_count: 1500
                      invoke_tools_count: 1000
                      window: 1w
                      filters: {}
                      timestamp: '2024-01-15T10:30:00Z'
                    error: null
                    timestamp: '2024-01-15T10:30:00Z'
                with_filters:
                  summary: Response with multiple filters
                  value:
                    success: true
                    data:
                      suggest_tools_count: 500
                      get_tool_schemas_count: 1000
                      invoke_tools_count: 500
                      window: 24h
                      filters:
                        project_id: '550e8400-e29b-41d4-a716-446655440001'
                        navigator_instance_id: '550e8400-e29b-41d4-a716-446655440002'
                      timestamp: '2024-01-15T10:30:00Z'
                    error: null
                    timestamp: '2024-01-15T10:30:00Z'
        '403':
          description: Forbidden - User not associated with a tenant
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: 'User not associated with a tenant'
        '404':
          description: Not Found - Project or navigator instance not found or does not belong to tenant
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: 'Project 550e8400-e29b-41d4-a716-446655440000 not found or does not belong to this tenant'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error - Failed to retrieve proxy tool counts data
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 'Failed to retrieve proxy tool efficiency data'
                  details:
                    type: object
                    properties:
                      error:
                        type: string
                        example: 'ClickHouse connection error'
  /analytics/proxy-tools/suggest-tools:
    get:
      tags:
      - Analytics
      summary: Get Proxy Tool Suggestions
      description: |
        Retrieve tool suggestions count and total suggested tools with optional filters.
        
        This endpoint queries the `caylex_tool_suggestions_generated_total` metric from ClickHouse
        and returns:
        - `count`: The number of times the metric was recorded in the time window
        - `suggested_tools`: The sum of the `suggestions_count` attribute across all metric records
        
        Unlike other endpoints, this endpoint:
        - Does not support `server_instance_id` filter
        - Does not support `sort_order` or `limit` parameters
        
        The endpoint supports filtering by:
        - `project_id`: Filter results by a specific project
        - `navigator_instance_id`: Filter results by a specific navigator instance
        - `window`: Time window for the query (default: 1w)
        
        All filters are optional and can be combined. The tenant_id is automatically
        determined from the authenticated user's context.
      operationId: get_proxy_tool_suggestions_analytics_proxy_tools_suggest_tools_get
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          description: 'Time window for the query. Supported formats: 1h, 24h, 1d, 7d, 1w, 1mon'
          default: 1w
          title: Window
          examples:
            - 1h
            - 24h
            - 1d
            - 1w
            - 1mon
        description: 'Time window for the query (default: 1w). Examples: 1h, 24h, 1d, 1w, 1mon'
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Filter by project ID (UUID)
          title: Project Id
        description: Filter results by a specific project ID. Must belong to the authenticated user's tenant.
        example: '550e8400-e29b-41d4-a716-446655440000'
      - name: navigator_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Filter by navigator instance ID (UUID)
          title: Navigator Instance Id
        description: Filter results by a specific navigator instance ID. Must belong to the authenticated user's tenant.
        example: '550e8400-e29b-41d4-a716-446655440001'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyToolSuggestionsResponse'
              examples:
                basic:
                  summary: Basic response without filters
                  value:
                    success: true
                    data:
                      count: 150
                      suggested_tools: 450
                      window: 1w
                      filters: {}
                      timestamp: '2024-01-15T10:30:00Z'
                    error: null
                    timestamp: '2024-01-15T10:30:00Z'
                with_filters:
                  summary: Response with multiple filters
                  value:
                    success: true
                    data:
                      count: 75
                      suggested_tools: 225
                      window: 24h
                      filters:
                        project_id: '550e8400-e29b-41d4-a716-446655440001'
                        navigator_instance_id: '550e8400-e29b-41d4-a716-446655440002'
                      timestamp: '2024-01-15T10:30:00Z'
                    error: null
                    timestamp: '2024-01-15T10:30:00Z'
        '403':
          description: Forbidden - User not associated with a tenant
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: 'User not associated with a tenant'
        '404':
          description: Not Found - Project or navigator instance not found or does not belong to tenant
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: 'Project 550e8400-e29b-41d4-a716-446655440000 not found or does not belong to this tenant'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error - Failed to retrieve proxy tool suggestions data
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 'Failed to retrieve proxy tool suggestions data'
                  details:
                    type: object
                    properties:
                      error:
                        type: string
                        example: 'ClickHouse connection error'
  /analytics/tool-calls-processed-graph:
    get:
      tags:
      - Analytics
      summary: Get Tool Calls Time Series Graph Data
      description: Retrieve time series data for tool calls over a specified period.
        Returns data points suitable for graphing.
      operationId: get_tool_calls_processed_graph_analytics_tool_calls_processed_graph_get
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          description: 'Time window (default: 1mon)'
          default: 1mon
          title: Window
        description: 'Time window (default: 1mon)'
      - name: view
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ViewType'
          description: View type for the graph
          default: timeseries
        description: View type for the graph
      - name: frequency
        in: query
        required: false
        schema:
          allOf:
          - $ref: '#/components/schemas/Frequency'
          - default: 1d
        description: 'Frequency of data aggregation (e.g., 1m, 2h, 3d, 1w, 1mo)'
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by project ID
          title: Project Id
        description: Filter by project ID
      - name: navigator_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by navigator instance ID
          title: Navigator Instance Id
        description: Filter by navigator instance ID
      - name: server_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by server instance ID
          title: Server Instance Id
        description: Filter by server instance ID
      - name: tool_name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by tool name
          title: Tool Name
        description: Filter by tool name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolCallsGraphResponse'
              example:
                success: true
                data:
                  data_points:
                  - timestamp: '2024-01-01T00:00:00Z'
                    count: 1234
                  - timestamp: '2024-01-02T00:00:00Z'
                    count: 1456
                  view: timeseries
                  frequency: 1d
                  window: 1mon
                  filters: {}
                  timestamp: '2024-01-15T10:30:00Z'
                timestamp: '2024-01-15T10:30:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /analytics/tools:
    get:
      tags:
      - Analytics
      summary: Get Tools Invoked
      description: Retrieve list of distinct tool names invoked in a given time window
        with optional filters, sorted and limited
      operationId: get_tools_analytics_tools_get
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          description: 'Time window (default: 1w)'
          default: 1w
          title: Window
        description: 'Time window (default: 1w)'
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by project ID
          title: Project Id
        description: Filter by project ID
      - name: navigator_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by navigator instance ID
          title: Navigator Instance Id
        description: Filter by navigator instance ID
      - name: server_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by server instance ID
          title: Server Instance Id
        description: Filter by server instance ID
      - name: sort_order
        in: query
        required: false
        schema:
          type: string
          description: 'Sort order: ''asc'' or ''desc'' (default: asc)'
          default: asc
          title: Sort Order
        description: 'Sort order: ''asc'' or ''desc'' (default: asc)'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: 'Maximum number of tools to return (default: 100)'
          default: 100
          title: Limit
        description: 'Maximum number of tools to return (default: 100)'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolActivityResponse'
              example:
                success: true
                data:
                  tools:
                  - prompt
                  - resources_list
                  - resources_read
                  total_count: 3
                  window: 1w
                  filters: {}
                  sort_order: asc
                  limit: 100
                  timestamp: '2024-01-15T10:30:00Z'
                timestamp: '2024-01-15T10:30:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /analytics/servers:
    get:
      tags:
      - Analytics
      summary: Get Servers Used
      description: Retrieve list of servers used in a given time window with their call
        counts, sorted and limited
      operationId: get_servers_analytics_servers_get
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          description: 'Time window (default: 1w)'
          default: 1w
          title: Window
        description: 'Time window (default: 1w)'
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by project ID
          title: Project Id
        description: Filter by project ID
      - name: navigator_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by navigator instance ID
          title: Navigator Instance Id
        description: Filter by navigator instance ID
      - name: sort_order
        in: query
        required: false
        schema:
          type: string
          description: 'Sort order: ''asc'' or ''desc'' (default: desc)'
          default: desc
          title: Sort Order
        description: 'Sort order: ''asc'' or ''desc'' (default: desc)'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: 'Maximum number of servers to return (default: 100)'
          default: 100
          title: Limit
        description: 'Maximum number of servers to return (default: 100)'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerActivityResponse'
              example:
                success: true
                data:
                  servers:
                  - server_name: github
                    tool_count: 150
                  - server_name: gitlab
                    tool_count: 89
                  - server_name: jira
                    tool_count: 45
                  total_count: 3
                  window: 1w
                  filters: {}
                  sort_order: desc
                  limit: 100
                  timestamp: '2024-01-15T10:30:00Z'
                timestamp: '2024-01-15T10:30:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /analytics/top-servers:
    get:
      tags:
      - Analytics
      summary: Get Top Servers By Usage
      description: Retrieve top servers by tool call count and by queries processed (two maps)
      operationId: get_top_servers_analytics_top_servers_get
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          description: 'Time window (default: 1w)'
          default: 1w
          title: Window
        description: 'Time window (default: 1w)'
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by project ID
          title: Project Id
        description: Filter by project ID
      - name: navigator_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by navigator instance ID
          title: Navigator Instance Id
        description: Filter by navigator instance ID
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: 'Maximum number of servers to return (default: 5)'
          default: 5
          title: Limit
        description: 'Maximum number of servers to return (default: 5)'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopServersActivityResponse'
              example:
                success: true
                data:
                  tool_calls:
                    server_count: 3
                    servers:
                    - server_id: 123e4567-e89b-12d3-a456-426614174000
                      count: 150
                    - server_id: 223e4567-e89b-12d3-a456-426614174001
                      count: 89
                    - server_id: 323e4567-e89b-12d3-a456-426614174002
                      count: 45
                  queries_processed:
                    server_count: 3
                    servers:
                    - server_id: 123e4567-e89b-12d3-a456-426614174000
                      count: 42
                    - server_id: 223e4567-e89b-12d3-a456-426614174001
                      count: 28
                    - server_id: 323e4567-e89b-12d3-a456-426614174002
                      count: 12
                  window: 1w
                  filters: {}
                  limit: 5
                timestamp: '2024-01-15T10:30:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /analytics/top-projects:
    get:
      tags:
      - Analytics
      summary: Get Top Projects By Usage
      description: Retrieve top projects sorted by tool call count. No project_id or
        navigator_instance_id filters; results are scoped to the caller's tenant.
      operationId: get_top_projects_analytics_top_projects_get
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          description: 'Time window (default: 1w)'
          default: 1w
          title: Window
        description: 'Time window (default: 1w)'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: 'Maximum number of projects to return (default: 5)'
          default: 5
          title: Limit
        description: 'Maximum number of projects to return (default: 5)'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopProjectsActivityResponse'
              example:
                success: true
                data:
                  tool_calls:
                    project_count: 3
                    projects:
                    - project_id: 123e4567-e89b-12d3-a456-426614174000
                      count: 150
                    - project_id: 223e4567-e89b-12d3-a456-426614174001
                      count: 89
                    - project_id: 323e4567-e89b-12d3-a456-426614174002
                      count: 45
                  queries_processed:
                    project_count: 3
                    projects:
                    - project_id: 123e4567-e89b-12d3-a456-426614174000
                      count: 42
                    - project_id: 223e4567-e89b-12d3-a456-426614174001
                      count: 28
                    - project_id: 323e4567-e89b-12d3-a456-426614174002
                      count: 12
                  window: 1w
                  filters: {}
                  limit: 5
                timestamp: '2024-01-15T10:30:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /analytics/top-navigators:
    get:
      tags:
      - Analytics
      summary: Get Top Navigators By Usage
      description: Retrieve top navigators sorted by tool call count. Supports
        project_id filter only (no navigator_instance_id filter).
      operationId: get_top_navigators_analytics_top_navigators_get
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          description: 'Time window (default: 1w)'
          default: 1w
          title: Window
        description: 'Time window (default: 1w)'
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by project ID
          title: Project Id
        description: Filter by project ID
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: 'Maximum number of navigators to return (default: 5)'
          default: 5
          title: Limit
        description: 'Maximum number of navigators to return (default: 5)'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopNavigatorsActivityResponse'
              example:
                success: true
                data:
                  tool_calls:
                    navigator_count: 3
                    navigators:
                    - navigator_id: 123e4567-e89b-12d3-a456-426614174000
                      count: 150
                    - navigator_id: 223e4567-e89b-12d3-a456-426614174001
                      count: 89
                    - navigator_id: 323e4567-e89b-12d3-a456-426614174002
                      count: 45
                  queries_processed:
                    navigator_count: 3
                    navigators:
                    - navigator_id: 123e4567-e89b-12d3-a456-426614174000
                      count: 42
                    - navigator_id: 223e4567-e89b-12d3-a456-426614174001
                      count: 28
                    - navigator_id: 323e4567-e89b-12d3-a456-426614174002
                      count: 12
                  window: 1w
                  filters: {}
                  limit: 5
                timestamp: '2024-01-15T10:30:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /analytics/users:
    get:
      tags:
      - Analytics
      summary: Get Users Activity
      description: Retrieve list of users making proxy requests with their call counts,
        sorted and limited
      operationId: get_users_analytics_users_get
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          description: 'Time window (default: 1w)'
          default: 1w
          title: Window
        description: 'Time window (default: 1w)'
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by project ID
          title: Project Id
        description: Filter by project ID
      - name: navigator_instance_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by navigator instance ID
          title: Navigator Instance Id
        description: Filter by navigator instance ID
      - name: sort_order
        in: query
        required: false
        schema:
          type: string
          description: 'Sort order: ''asc'' or ''desc'' (default: desc)'
          default: desc
          title: Sort Order
        description: 'Sort order: ''asc'' or ''desc'' (default: desc)'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: 'Maximum number of users to return (default: 100)'
          default: 100
          title: Limit
        description: 'Maximum number of users to return (default: 100)'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsersActivityResponse'
              example:
                success: true
                data:
                  users:
                  - user_email: user1@example.com
                    tool_count: 150
                  - user_email: user2@example.com
                    tool_count: 89
                  - user_email: user3@example.com
                    tool_count: 45
                  total_count: 3
                  window: 1w
                  filters: {}
                  sort_order: desc
                  limit: 100
                  timestamp: '2024-01-15T10:30:00Z'
                timestamp: '2024-01-15T10:30:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /queries/query-logs/{query_id}:
    get:
      tags:
      - Queries
      summary: Get Query Log Details
      description: Retrieve detailed information about a specific query including
        input, output, status, latency, and tool calls made.
      operationId: get_query_queries_query_logs__query_id__get
      parameters:
      - name: query_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Query Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetQueryResponse'
              example:
                id: 123e4567-e89b-12d3-a456-426614174011
                token: null
                query: Create a GitHub issue for bug report
                navigator_instance_id: 789e0123-e89b-12d3-a456-426614174028
                project_id: 456e7890-e89b-12d3-a456-426614174015
                created_at: '2024-01-15T10:30:00Z'
                updated_at: '2024-01-15T10:30:01Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /queries/query-logs/{query_id}/trace:
    get:
      tags:
      - Queries
      summary: Get Query Execution Trace
      description: Retrieve the complete execution trace for a query showing all tool
        calls, their order, timing, and results. Useful for debugging and optimization.
      operationId: get_query_trace_queries_query_logs__query_id__trace_get
      parameters:
      - name: query_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Query Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetQueryTrace'
              example:
                query:
                  id: 123e4567-e89b-12d3-a456-426614174011
                  token: null
                  query: Create a GitHub issue for bug report
                  navigator_instance_id: 123e4567-e89b-12d3-a456-426614174004
                  project_id: 123e4567-e89b-12d3-a456-426614174003
                  created_at: '2024-01-15T10:30:00Z'
                  updated_at: '2024-01-15T10:30:01Z'
                tool_call_groups:
                - tool_calls:
                  - server_instance_id: 123e4567-e89b-12d3-a456-426614174010
                    tool:
                      server:
                        id: 123e4567-e89b-12d3-a456-426614174006
                        name: GitHub API
                      name: create_issue
                    latency: 0.8
                    success: true
                    error_message: null
                    created_at: '2024-01-15T10:30:00.600Z'
                  created_at: '2024-01-15T10:30:00Z'
                tool_schemas: []
                suggest_tools: []
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /analytics/health:
    get:
      tags:
      - Analytics
      summary: Analytics Service Health Check
      description: Check the health of the analytics service including InfluxDB and
        database connections.
      operationId: get_analytics_health_analytics_health_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
              example:
                status: healthy
                influxdb_connected: true
                database_connected: true
                last_check: '2024-01-15T10:30:00Z'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
              example:
                detail: Invalid request parameters
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                type: object
              example:
                status: unhealthy
                influxdb_connected: false
                database_connected: true
  /health:
    get:
      tags:
      - System
      summary: Service Health Check
      operationId: health_check_health_get
      responses:
        '200':
          description: Service is healthy and operational
          content:
            application/json:
              example:
                status: healthy
                timestamp: '2024-01-15T10:30:00Z'
                service: caylex-analytics
                version: 0.1.0
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
              example:
                detail: Invalid request parameters
        '503':
          description: Service Unavailable
          content:
            application/json:
              example:
                status: unhealthy
                timestamp: '2024-01-15T10:30:00Z'
                service: caylex-analytics
                version: 0.1.0
      description: Check the health status of the Caylex Analytics service. Returns
        service status, version, and timestamp.
  /docs:
    get:
      tags:
      - Documentation
      summary: Documentation index
      description: Get information about available documentation endpoints
      operationId: get_docs_index_docs__get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
              example:
                detail: Documentation not found
  /docs/openapi.json:
    get:
      tags:
      - Documentation
      summary: Get comprehensive OpenAPI specification (JSON)
      description: Retrieve the complete OpenAPI 3.0 specification for the Caylex
        Analytics Service in JSON format
      operationId: get_openapi_spec_json_docs_openapi_json_get
      responses:
        '200':
          description: Successful Response
          content:
            text/plain:
              schema:
                type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
              example:
                detail: OpenAPI specification not found
  /docs/openapi.yaml:
    get:
      tags:
      - Documentation
      summary: Get comprehensive OpenAPI specification
      description: Retrieve the complete OpenAPI 3.0 specification for the Caylex
        Analytics Service in YAML format
      operationId: get_openapi_spec_docs_openapi_yaml_get
      responses:
        '200':
          description: Successful Response
          content:
            text/plain:
              schema:
                type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
              example:
                detail: OpenAPI specification not found
  /invite/metadata:
    get:
      tags:
      - Invite
      summary: Get metadata for an invite link (no authentication required)
      operationId: get_metadata_invite_metadata_get
      parameters:
      - name: auth_link_id
        in: query
        required: true
        schema:
          type: string
          format: uuid
          title: Auth Link Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InviteMetadataResponse'
              example:
                tenant_name: "Example Tenant"
                project_name: "Example Project"
                expires_at: "2024-01-22T10:30:00Z"
                auth_link_type: "user"
                valid_for:
                - caylex.ai
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
              example:
                detail: "Invite is invalid"
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Get metadata for a given invite link. No authentication required. Returns tenant name, tenant Descope ID, project name, expiration date, auth link type, and valid_for values.
  /invite/config:
    get:
      tags:
      - Invite
      summary: Get configuration for an invite link
      operationId: get_config_invite_config_get
      parameters:
      - name: auth_link_id
        in: query
        required: true
        schema:
          type: string
          format: uuid
          title: Auth Link Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InviteConfigResponse'
              example:
                tenant_name: "Example Tenant"
                auth_scope: "project"
                oauth_servers:
                - name: "OAuth Server 1"
                  id: "123e4567-e89b-12d3-a456-426614174000"
                  descope_outbound_app_id: "app_123"
                header_servers:
                - name: "Header Server 1"
                  id: "123e4567-e89b-12d3-a456-426614174001"
                  headers:
                  - name: "Authorization"
                    prefix: "Bearer"
                path_servers:
                - name: "Path Server 1"
                  id: "123e4567-e89b-12d3-a456-426614174002"
                  paths:
                  - name: "api_key"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
              example:
                detail: "Invite is invalid"
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Retrieve configuration for an invite link including tenant information and server configurations.
  /invite/complete:
    post:
      tags:
      - Invite
      summary: Complete an invite link
      operationId: complete_invite_invite_complete_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompleteInviteRequest'
            example:
              auth_link_id: "123e4567-e89b-12d3-a456-426614174000"
              user_email: "user@example.com"
              descope_user_id: "D12345678901234567890"
              oauth_servers:
              - name: "OAuth Server 1"
                server_id: "123e4567-e89b-12d3-a456-426614174001"
                server_instance_id: "123e4567-e89b-12d3-a456-426614174002"
              header_servers:
              - name: "Header Server 1"
                server_id: "123e4567-e89b-12d3-a456-426614174003"
                server_instance_id: "123e4567-e89b-12d3-a456-426614174004"
                headers:
                - header_id: "123e4567-e89b-12d3-a456-426614174005"
                  header_name: "Authorization"
                  header_value: "Bearer token123"
              path_servers:
              - name: "Path Server 1"
                server_id: "123e4567-e89b-12d3-a456-426614174006"
                server_instance_id: "123e4567-e89b-12d3-a456-426614174007"
                paths:
                - path_id: "123e4567-e89b-12d3-a456-426614174008"
                  path_name: "api_key"
                  path_value: "key123"
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InviteCompleteResponse'
              example:
                is_new_user: true
                user_token: "token123.secret456"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
              example:
                detail: "Session token is required"
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Complete an invite link by providing authentication details for servers.
  /settings/general:
    get:
      tags:
      - Settings
      summary: Get user general settings
      description: Retrieve user information including name, role, email, timezone, tenant name, and tenant id
      operationId: get_general_settings_settings_general_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralSettingsResponse'
              example:
                name: "john.doe"
                role: "user"
                email: "john.doe@example.com"
                timezone: "UTC"
                tenant_name: "Acme Corporation"
                tenant_id: "123e4567-e89b-12d3-a456-426614174000"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
              example:
                detail: "Authentication required"
        '404':
          description: User not found
          content:
            application/json:
              schema:
                type: object
              example:
                detail: "User not found"
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Settings
      summary: Update user general settings
      description: Update user name and/or timezone settings. At least one field must be provided.
      operationId: update_general_settings_settings_general_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGeneralSettingsRequest'
            examples:
              both_fields:
                summary: Update both name and timezone
                value:
                  name: "John Doe"
                  timezone: "America/New_York"
              name_only:
                summary: Update only name
                value:
                  name: "Jane Smith"
              timezone_only:
                summary: Update only timezone
                value:
                  timezone: "Europe/London"
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralSettingsResponse'
              example:
                name: "John Doe"
                role: "user"
                email: "john.doe@example.com"
                timezone: "America/New_York"
                tenant_name: "Acme Corporation"
                tenant_id: "123e4567-e89b-12d3-a456-426614174000"
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
              examples:
                no_fields:
                  summary: No fields provided
                  value:
                    detail: "At least one field (name or timezone) must be provided"
                empty_name:
                  summary: Empty name provided
                  value:
                    detail: "Name value cannot be empty"
                empty_timezone:
                  summary: Empty timezone provided
                  value:
                    detail: "Timezone value cannot be empty"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
              example:
                detail: "Authentication required"
        '404':
          description: User not found
          content:
            application/json:
              schema:
                type: object
              example:
                detail: "User not found"
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /settings/avatar:
    post:
      tags:
      - Settings
      summary: Upload user avatar
      description: 'Upload a square PNG/JPEG (≥64×64, ≤5MB) and persist its URL on
        the user. Replaces any existing avatar; the previous object is deleted from
        storage on a best-effort basis.'
      operationId: upload_user_avatar_settings_avatar_post
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_user_avatar_settings_avatar_post'
            example:
              avatar: (binary PNG file content)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadAvatarResponse'
              example:
                avatar_url: https://storage.caylex.ai/avatars/3f7c2b1a-b9e0-4a4b-9c33-2c0c7c2b1a3f/abc123def456.png
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
              example:
                detail: File must be a PNG or JPEG image.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
              example:
                detail: Authentication required
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
              example:
                detail: User not associated with a tenant
        '404':
          description: User not found
          content:
            application/json:
              schema:
                type: object
              example:
                detail: User not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Settings
      summary: Remove user avatar
      description: Clear the user's avatar URL and delete the underlying object from
        storage on a best-effort basis.
      operationId: delete_user_avatar_settings_avatar_delete
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralSettingsResponse'
              example:
                name: John Doe
                role: admin
                email: john.doe@example.com
                timezone: UTC
                tenant_name: Acme Corporation
                tenant_id: 123e4567-e89b-12d3-a456-426614174000
                avatar_url: null
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
              example:
                detail: Authentication required
        '404':
          description: User not found
          content:
            application/json:
              schema:
                type: object
              example:
                detail: User not found
  /settings/password-reset:
    post:
      tags:
      - Settings
      summary: Send password reset link
      description: Send a password reset link to the user's email address using Descope
      operationId: send_password_reset_settings_password_reset_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasswordResetResponse'
              example:
                message: "Password reset link sent successfully"
                email: "user@example.com"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
              example:
                detail: "Authentication required"
        '404':
          description: User not found
          content:
            application/json:
              schema:
                type: object
              example:
                detail: "User not found"
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
              example:
                detail: "Failed to send password reset link. Please try again later."
  /settings/contact:
    post:
      tags:
      - Settings
      summary: Send contact message
      description: Send contact message from the Settings page with email and message
      operationId: send_contact_settings_contact_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactRequest'
            example:
              email: "user@example.com"
              message: "I have a question about the platform features and would like to get in touch with support."
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactResponse'
              example:
                message: "Thank you for your message! We'll review it and get back to you as soon as possible."
                email: "user@example.com"
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
              example:
                detail: "Please provide a valid email address"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
              example:
                detail: "Authentication required"
        '404':
          description: User not found
          content:
            application/json:
              schema:
                type: object
              example:
                detail: "User not found"
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
              example:
                detail: "Internal server error"
  /members:
    get:
      tags:
      - Members
      summary: Get Tenant Members
      description: Get paginated list of members for the authenticated user's tenant. Requires admin role.
      operationId: get_members_members_get
      parameters:
      - name: sort
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/MemberSortOption'
          default: created_desc
        description: Sort order for results
      - name: confirmed
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Confirmed
        description: Filter by confirmed status. true=only confirmed, false=only unconfirmed, null=all
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 20
          title: Size
        description: Items per page
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Pagination cursor
          title: Cursor
        description: Pagination cursor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_TenantUserResponse_'
              example:
                items:
                - id: 123e4567-e89b-12d3-a456-426614174001
                  email: admin@example.com
                  name: John Doe
                  role: admin
                  confirmed_at: '2024-01-15T10:30:00Z'
                  timezone: America/New_York
                  created_at: '2024-01-10T08:00:00Z'
                  updated_at: '2024-01-15T10:30:00Z'
                meta:
                  total: 10
                  size: 20
                  next_cursor: null
                  has_next: false
                  has_prev: false
        '403':
          description: Forbidden - Not an admin user or not associated with a tenant
          content:
            application/json:
              schema:
                type: object
              example:
                detail: "Only admin users can view tenant members"
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /members/search:
    get:
      tags:
      - Members
      summary: Search Tenant Members
      description: Search tenant members by email and/or name. At least one of email or name must be provided. Requires admin role.
      operationId: search_members_members_search_get
      parameters:
      - name: email
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
        description: Email address to search for (partial match, case-insensitive)
      - name: name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        description: Name to search for (partial match, case-insensitive)
      - name: sort
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/MemberSortOption'
          default: created_desc
        description: Sort order for results
      - name: confirmed
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Confirmed
        description: Filter by confirmed status. true=only confirmed, false=only unconfirmed, null=all
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 20
          title: Size
        description: Items per page
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Pagination cursor
          title: Cursor
        description: Pagination cursor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_TenantUserResponse_'
              example:
                items:
                - id: 123e4567-e89b-12d3-a456-426614174001
                  email: john@example.com
                  name: John Doe
                  role: user
                  confirmed_at: '2024-01-15T10:30:00Z'
                  timezone: America/New_York
                  created_at: '2024-01-10T08:00:00Z'
                  updated_at: '2024-01-15T10:30:00Z'
                meta:
                  total: 1
                  size: 20
                  next_cursor: null
                  has_next: false
                  has_prev: false
        '400':
          description: Bad Request - Neither email nor name provided
          content:
            application/json:
              schema:
                type: object
              example:
                detail: "At least one of 'email' or 'name' query parameter is required"
        '403':
          description: Forbidden - Not an admin user or not associated with a tenant
          content:
            application/json:
              schema:
                type: object
              example:
                detail: "Only admin users can search tenant members"
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /members/{member_id}:
    patch:
      tags:
      - Members
      summary: Update Tenant Member
      description: Update a tenant member's information. Requires admin role.
      operationId: update_member_members_member_id_patch
      parameters:
      - name: member_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Member Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTenantUserRequest'
            example:
              name: Updated Name
              role: admin
              timezone: America/Los_Angeles
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantUserResponse'
              example:
                id: 123e4567-e89b-12d3-a456-426614174001
                email: user@example.com
                name: Updated Name
                role: admin
                confirmed_at: '2024-01-15T10:30:00Z'
                timezone: America/Los_Angeles
                created_at: '2024-01-10T08:00:00Z'
                updated_at: '2024-01-20T14:00:00Z'
        '403':
          description: Forbidden - Not an admin user or not associated with a tenant
          content:
            application/json:
              schema:
                type: object
              example:
                detail: "Only admin users can update tenant members"
        '404':
          description: Not Found - Member not found
          content:
            application/json:
              schema:
                type: object
              example:
                detail: "Tenant member with id 123e4567-e89b-12d3-a456-426614174001 not found"
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Members
      summary: Delete Tenant Member
      description: Delete a tenant member. Requires admin role. Users cannot delete themselves.
      operationId: delete_member_members_member_id_delete
      parameters:
      - name: member_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Member Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteTenantUserResponse'
              example:
                id: 123e4567-e89b-12d3-a456-426614174001
                message: Successfully deleted tenant member user@example.com
        '400':
          description: Bad Request - Cannot delete self
          content:
            application/json:
              schema:
                type: object
              example:
                detail: "Users cannot delete themselves"
        '403':
          description: Forbidden - Not an admin user or not associated with a tenant
          content:
            application/json:
              schema:
                type: object
              example:
                detail: "Only admin users can delete tenant members"
        '404':
          description: Not Found - Member not found
          content:
            application/json:
              schema:
                type: object
              example:
                detail: "Tenant member with id 123e4567-e89b-12d3-a456-426614174001 not found"
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /members/{member_id}/approve:
    post:
      tags:
      - Members
      summary: Approve Tenant Member
      description: Approve a tenant member by setting their confirmed_at timestamp and assigning a role. Requires admin role.
      operationId: approve_member_members_member_id_approve_post
      parameters:
      - name: member_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Member Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApproveTenantUserRequest'
            example:
              role: member
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantUserResponse'
              example:
                id: 123e4567-e89b-12d3-a456-426614174001
                email: user@example.com
                name: John Doe
                role: user
                confirmed_at: '2024-01-20T14:30:00Z'
                timezone: America/New_York
                created_at: '2024-01-10T08:00:00Z'
                updated_at: '2024-01-20T14:30:00Z'
        '400':
          description: Bad Request - Member is already approved
          content:
            application/json:
              schema:
                type: object
              example:
                detail: "Member is already approved"
        '403':
          description: Forbidden - Not an admin user or not associated with a tenant
          content:
            application/json:
              schema:
                type: object
              example:
                detail: "Only admin users can approve tenant members"
        '404':
          description: Not Found - Member not found
          content:
            application/json:
              schema:
                type: object
              example:
                detail: "Tenant member with id 123e4567-e89b-12d3-a456-426614174001 not found"
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /browser-sessions:
    post:
      tags:
      - Browser Sessions
      summary: Create Remote Browser Session
      operationId: create_browser_session_browser_sessions_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBrowserSessionRequest'
            example:
              login_url: https://app.example.com/login
              session_type: cookie
              success_url_pattern: /dashboard
              app_domain: example.com
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateBrowserSessionResponse'
              example:
                session_id: a1b2c3d4e5f6
                ws_url: /api/v1/browser-sessions/a1b2c3d4e5f6/ws
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Too Many Requests — maximum concurrent browser sessions reached
          content:
            application/json:
              example:
                detail: Maximum concurrent sessions (10) reached
      description: |
        Start a server-side Chromium session navigated to the given login URL. Returns a
        `session_id` and `ws_url` for the WebSocket screencast and input relay. Cookie flows
        complete via `success_url_pattern` or a client `finish` message over the WebSocket.
        Trace mode records all network traffic and generates an OpenAPI spec on finish.
    get:
      tags:
      - Browser Sessions
      summary: List Remote Browser Sessions
      operationId: list_browser_sessions_browser_sessions_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BrowserSessionInfo'
              example:
                - session_id: a1b2c3d4e5f6
                  status: active
                  login_url: https://app.example.com/login
                  session_type: cookie
                  created_at: 1712100000.0
        '400':
          description: Invalid request
          content:
            application/json:
              example:
                detail: Invalid browser session list request
      description: List all active remote browser sessions on this service instance.
  /browser-sessions/{session_id}:
    get:
      tags:
      - Browser Sessions
      summary: Get Remote Browser Session
      operationId: get_browser_session_browser_sessions__session_id__get
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowserSessionInfo'
              example:
                session_id: a1b2c3d4e5f6
                status: active
                login_url: https://app.example.com/login
                session_type: cookie
                created_at: 1712100000.0
        '404':
          description: Session not found
          content:
            application/json:
              example:
                detail: Session not found
      description: Return status metadata for a single browser session.
    delete:
      tags:
      - Browser Sessions
      summary: Delete Remote Browser Session
      operationId: delete_browser_session_browser_sessions__session_id__delete
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      responses:
        '204':
          description: Session closed and resources released
        '404':
          description: Session not found
          content:
            application/json:
              example:
                detail: Session not found
      description: Tear down the browser for this session and remove it from the active pool.
  /browser-sessions/{session_id}/result:
    get:
      tags:
      - Browser Sessions
      summary: Get Captured Browser Session Auth Result
      operationId: get_browser_session_result_browser_sessions__session_id__result_get
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowserSessionResult'
              example:
                session_type: cookie
                cookies:
                  - name: session_id
                    value: abc123
                    domain: .example.com
                    path: /
                    httpOnly: true
                    secure: true
                headers:
                  Cookie: session_id=abc123
        '404':
          description: Session not found
          content:
            application/json:
              example:
                detail: Session not found
        '409':
          description: Authentication not yet complete for this session
          content:
            application/json:
              example:
                detail: Authentication not yet complete
      description: |
        Retrieve captured cookies and suggested HTTP headers after the session has
        completed (also delivered over the session WebSocket as `session_complete`).
  /browser-sessions/{session_id}/ws:
    get:
      tags:
      - Browser Sessions
      summary: WebSocket — Screencast and Input Relay
      operationId: browser_session_ws_browser_sessions__session_id__ws_get
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      responses:
        '200':
          description: |
            HTTP OK response used by some OpenAPI tooling; runtime clients should
            expect a WebSocket upgrade (`101 Switching Protocols`).
        '101':
          description: |
            Switching Protocols. After upgrade, the connection carries two frame
            types: binary frames (raw JPEG bytes for the screencast) and text
            frames (JSON control messages). See the operation description for the
            full protocol.
        '400':
          description: Invalid session or session not in active state
      description: |
        WebSocket endpoint for live viewport (JPEG screencast) and relaying pointer,
        keyboard, and wheel input to the remote browser.

        **Server → client (binary frames):**
        Raw JPEG bytes — each binary WebSocket message is one complete JPEG image.
        Clients should render the most recent binary message received and discard
        any that arrive while the previous frame is still being drawn.

        **Server → client (text frames, JSON):**
        - `{"type":"session_complete","result":{...}}` — `result` matches `BrowserSessionResult`
        - `{"type":"error","detail":"..."}` — e.g. session timed out

        **Client → server (text frames, JSON):**
        - `{"type":"mouse","action":"mousePressed|mouseReleased|mouseMoved","x":0,"y":0,"button":"left"}`
        - `{"type":"key","action":"keyDown|keyUp|char","key":"","code":"","text":""}`
        - `{"type":"scroll","x":0,"y":0,"delta_x":0,"delta_y":0}`
        - `{"type":"finish"}` — trigger cookie capture (cookie auth mode without success URL)
        - `{"type":"metrics","fps":30,"rtt_ms":42}` — optional client performance report

        The server performs frame coalescing: only the most recent CDP frame is
        delivered, so the client always receives the latest viewport regardless of
        network jitter. JPEG quality is adapted automatically based on send latency
        (range 30–90).

        Connect to the same host as the API, path `/api/v1/browser-sessions/{session_id}/ws`,
        using the `ws:` or `wss:` scheme. The `ws_url` from `POST /browser-sessions` is
        relative to the API server root.
components:
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: DS
      description: Descope session cookie authentication
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token authentication
  schemas:
    AddExternalHeaderServerRequest:
      properties:
        endpoint:
          anyOf:
          - type: string
          - type: 'null'
          title: Endpoint
          description: Server endpoint URL. When registry_id is set, required only if the registry endpoint is templated (contains '{}', e.g. http://{shop}.shopify.com/mcp); then provide the resolved URL here. Cannot be provided when registry_id is set and the registry endpoint is not templated. Either endpoint or registry_id must be provided.
        name:
          type: string
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        registry_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Registry Id
          description: Server registry ID. When provided, endpoint is taken from the registry unless the registry endpoint is templated (contains '{}'); then provide the resolved URL in endpoint. Either endpoint or registry_id must be provided.
        auth_level:
          $ref: '#/components/schemas/AuthLevel'
        query_params:
          items:
            $ref: '#/components/schemas/QueryParam'
          type: array
          title: Query Params
          default: []
          description: Non-auth query parameters to append to the server endpoint URL.
        logo_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Logo Url
          description: Optional logo path returned by POST /servers/upload-logo. When set, overrides any registry-provided logo. Omit to use the registry's logo (if any) or no logo.
        server_type:
          $ref: '#/components/schemas/ServerType'
        headers:
          items:
            $ref: '#/components/schemas/HeaderConfig'
          type: array
          title: Headers
        transport:
          $ref: '#/components/schemas/ServerTransport'
      type: object
      required:
      - name
      - description
      - auth_level
      - headers
      - transport
      title: AddExternalHeaderServerRequest
    AddExternalOAuthServerRequest:
      properties:
        endpoint:
          anyOf:
          - type: string
          - type: 'null'
          title: Endpoint
          description: Server endpoint URL. When registry_id is set, required only if the registry endpoint is templated (contains '{}', e.g. http://{shop}.shopify.com/mcp); then provide the resolved URL here. Cannot be provided when registry_id is set and the registry endpoint is not templated. Either endpoint or registry_id must be provided.
        name:
          type: string
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        registry_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Registry Id
          description: Server registry ID. When provided, endpoint is taken from the registry unless the registry endpoint is templated (contains '{}'); then provide the resolved URL in endpoint. Either endpoint or registry_id must be provided.
        auth_level:
          $ref: '#/components/schemas/AuthLevel'
        query_params:
          items:
            $ref: '#/components/schemas/QueryParam'
          type: array
          title: Query Params
          default: []
          description: Non-auth query parameters to append to the server endpoint URL.
        logo_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Logo Url
          description: Optional logo path returned by POST /servers/upload-logo. When set, overrides any registry-provided logo. Omit to use the registry's logo (if any) or no logo.
        server_type:
          $ref: '#/components/schemas/ServerType'
        metadata:
          $ref: '#/components/schemas/DiscoverOAuthMetadataResponse'
        manual_client_config:
          anyOf:
          - $ref: '#/components/schemas/ManualClientConfig'
          - type: 'null'
        transport:
          $ref: '#/components/schemas/ServerTransport'
        scopes:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Scopes
          description: OAuth2 scopes as list
      type: object
      required:
      - name
      - description
      - auth_level
      - metadata
      - manual_client_config
      - transport
      title: AddExternalOAuthServerRequest
    AddExternalPathServerRequest:
      properties:
        endpoint:
          anyOf:
          - type: string
          - type: 'null'
          title: Endpoint
          description: Server endpoint URL. When registry_id is set, required only if the registry endpoint is templated (contains '{}', e.g. http://{shop}.shopify.com/mcp); then provide the resolved URL here. Cannot be provided when registry_id is set and the registry endpoint is not templated. Either endpoint or registry_id must be provided.
        name:
          type: string
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        registry_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Registry Id
          description: Server registry ID. When provided, endpoint is taken from the registry unless the registry endpoint is templated (contains '{}'); then provide the resolved URL in endpoint. Either endpoint or registry_id must be provided.
        auth_level:
          $ref: '#/components/schemas/AuthLevel'
        query_params:
          items:
            $ref: '#/components/schemas/QueryParam'
          type: array
          title: Query Params
          default: []
          description: Non-auth query parameters to append to the server endpoint URL.
        logo_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Logo Url
          description: Optional logo path returned by POST /servers/upload-logo. When set, overrides any registry-provided logo. Omit to use the registry's logo (if any) or no logo.
        server_type:
          $ref: '#/components/schemas/ServerType'
        paths:
          items:
            $ref: '#/components/schemas/PathConfig'
          type: array
          title: Paths
        transport:
          $ref: '#/components/schemas/ServerTransport'
      type: object
      required:
      - name
      - description
      - auth_level
      - paths
      - transport
      title: AddExternalPathServerRequest
    AddExternalQueryServerRequest:
      properties:
        endpoint:
          anyOf:
          - type: string
          - type: 'null'
          title: Endpoint
          description: Server endpoint URL. When registry_id is set, required only if the registry endpoint is templated (contains '{}', e.g. http://{shop}.shopify.com/mcp); then provide the resolved URL here. Cannot be provided when registry_id is set and the registry endpoint is not templated. Either endpoint or registry_id must be provided.
        name:
          type: string
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        registry_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Registry Id
          description: Server registry ID. When provided, endpoint is taken from the registry unless the registry endpoint is templated (contains '{}'); then provide the resolved URL in endpoint. Either endpoint or registry_id must be provided.
        auth_level:
          $ref: '#/components/schemas/AuthLevel'
        query_params:
          items:
            $ref: '#/components/schemas/QueryParam'
          type: array
          title: Query Params
          default: []
          description: Non-auth query parameters to append to the server endpoint URL.
        logo_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Logo Url
          description: Optional logo path returned by POST /servers/upload-logo. When set, overrides any registry-provided logo. Omit to use the registry's logo (if any) or no logo.
        server_type:
          $ref: '#/components/schemas/ServerType'
        params:
          items:
            $ref: '#/components/schemas/QueryConfig'
          type: array
          title: Params
        transport:
          $ref: '#/components/schemas/ServerTransport'
      type: object
      required:
      - name
      - description
      - auth_level
      - params
      - transport
      title: AddExternalQueryServerRequest
    AddExternalNoAuthServerRequest:
      properties:
        endpoint:
          anyOf:
          - type: string
          - type: 'null'
          title: Endpoint
          description: Server endpoint URL. When registry_id is set, required only if the registry endpoint is templated (contains '{}', e.g. http://{shop}.shopify.com/mcp); then provide the resolved URL here. Cannot be provided when registry_id is set and the registry endpoint is not templated. Either endpoint or registry_id must be provided.
        name:
          type: string
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        registry_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Registry Id
          description: Server registry ID. When provided, endpoint is taken from the registry unless the registry endpoint is templated (contains '{}'); then provide the resolved URL in endpoint. Either endpoint or registry_id must be provided.
        auth_level:
          $ref: '#/components/schemas/AuthLevel'
        query_params:
          items:
            $ref: '#/components/schemas/QueryParam'
          type: array
          title: Query Params
          default: []
          description: Non-auth query parameters to append to the server endpoint URL.
        logo_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Logo Url
          description: Optional logo path returned by POST /servers/upload-logo. When set, overrides any registry-provided logo. Omit to use the registry's logo (if any) or no logo.
        transport:
          $ref: '#/components/schemas/ServerTransport'
      type: object
      required:
      - name
      - description
      - auth_level
      - transport
      title: AddExternalNoAuthServerRequest
    NavigatorInstanceModifiedResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
      type: object
      required:
      - id
      title: NavigatorInstanceModifiedResponse
    NavigatorModifiedResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
      type: object
      required:
      - id
      title: NavigatorModifiedResponse
    NavigatorSortBy:
      type: string
      enum:
      - name_asc
      - name_desc
      - created_asc
      - created_desc
      - updated_asc
      - updated_desc
      title: NavigatorSortBy
      description: Sorting options for navigator listing.
    NavigatorToolConnection:
      properties:
        navigator_instance_id:
          type: string
          title: Navigator Instance Id
          description: Navigator instance identifier
        tool_id:
          type: string
          title: Tool Id
          description: Tool identifier
        connection_status:
          type: string
          title: Connection Status
          description: Connection status
        last_used:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Used
          description: Last time the tool was used
        usage_count:
          type: integer
          title: Usage Count
          description: Number of times the tool was used
        window:
          type: string
          title: Window
          description: Time window for the data
        filters:
          additionalProperties:
            type: string
          type: object
          title: Filters
          description: Filters applied to the query
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when stats were calculated
      type: object
      required:
      - navigator_instance_id
      - tool_id
      - connection_status
      - usage_count
      - window
      - filters
      - timestamp
      title: NavigatorToolConnection
      description: Navigator-tool connection information with optional filters.
    NavigatorToolConnectionsResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the request was successful
        data:
          anyOf:
          - items:
              $ref: '#/components/schemas/NavigatorToolConnection'
            type: array
          - type: 'null'
          title: Data
          description: Analytics data
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if request failed
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when response was generated
      type: object
      required:
      - success
      - timestamp
      title: NavigatorToolConnectionsResponse
      description: Response model for navigator tool connections endpoint.
    ApproveMemberRole:
      type: string
      enum:
      - admin
      - member
      title: ApproveMemberRole
      description: Role options for approving a member
    ApproveTenantUserRequest:
      properties:
        role:
          $ref: '#/components/schemas/ApproveMemberRole'
      type: object
      required:
      - role
      title: ApproveTenantUserRequest
      description: Request model for approving tenant user
    AuthLevel:
      type: string
      enum:
      - project
      - user
      title: AuthLevel
    AuthenticateServersRequest:
      properties:
        server_instances:
          items:
            type: string
            format: uuid
          type: array
          title: Server Instances
        link_expires_at:
          type: string
          format: date-time
          title: Link Expires At
      type: object
      required:
      - server_instances
      - link_expires_at
      title: AuthenticateServersRequest
    AuthenticateServersResponse:
      properties:
        user_invite_link:
          anyOf:
          - type: string
          - type: 'null'
          title: User Invite Link
        user_invite_link_expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: User Invite Link Expires At
        project_invite_link:
          anyOf:
          - type: string
          - type: 'null'
          title: Project Invite Link
        project_invite_link_expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Project Invite Link Expires At
      type: object
      title: AuthenticateServersResponse
    BrowserSessionResult:
      properties:
        session_type:
          $ref: '#/components/schemas/BrowserSessionType'
        cookies:
          items:
            type: object
            additionalProperties: true
          type: array
          title: Cookies
          description: Browser cookies from the Playwright context
        headers:
          additionalProperties:
            type: string
          type: object
          title: Headers
          description: Suggested HTTP headers (e.g. Cookie)
      type: object
      required:
      - session_type
      - cookies
      - headers
      title: BrowserSessionResult
      description: Captured result from the remote browser session
    BrowserSessionType:
      type: string
      enum:
      - cookie
      - trace
      title: BrowserSessionType
      description: How the service detects completion — cookie capture or network trace
    BrowserSessionInfo:
      properties:
        session_id:
          type: string
          title: Session Id
        status:
          $ref: '#/components/schemas/BrowserSessionStatus'
        login_url:
          type: string
          title: Login Url
        session_type:
          $ref: '#/components/schemas/BrowserSessionType'
        created_at:
          type: number
          title: Created At
          description: Unix timestamp when the session was created
      type: object
      required:
      - session_id
      - status
      - login_url
      - session_type
      - created_at
      title: BrowserSessionInfo
    BrowserSessionStatus:
      type: string
      enum:
      - active
      - complete
      - timed_out
      - closed
      title: BrowserSessionStatus
    CreateBrowserSessionRequest:
      properties:
        login_url:
          type: string
          title: Login Url
          description: URL to open in the remote browser for login
        session_type:
          allOf:
          - $ref: '#/components/schemas/BrowserSessionType'
          default: cookie
        success_url_pattern:
          type: string
          title: Success Url Pattern
          description: URL substring indicating login completed (cookie session mode)
          default: ''
        app_domain:
          type: string
          title: App Domain
          description: Filter cookies to this domain (cookie session mode)
          default: ''
        viewport_width:
          anyOf:
          - type: integer
          - type: 'null'
          title: Viewport Width
        viewport_height:
          anyOf:
          - type: integer
          - type: 'null'
          title: Viewport Height
      type: object
      required:
      - login_url
      title: CreateBrowserSessionRequest
    CreateBrowserSessionResponse:
      properties:
        session_id:
          type: string
          title: Session Id
        ws_url:
          type: string
          title: Ws Url
          description: WebSocket path (prepend origin with ws/wss) for screencast and input
      type: object
      required:
      - session_id
      - ws_url
      title: CreateBrowserSessionResponse
    CreateUserAuthLinkRequest:
      properties:
        server_instances:
          items:
            type: string
            format: uuid
          type: array
          title: Server Instances
        domain:
          type: string
          title: Domain
          description: Domain name that applies to all users. Users must login with an email from this domain.
        link_expires_at:
          type: string
          format: date-time
          title: Link Expires At
      type: object
      required:
      - server_instances
      - domain
      - link_expires_at
      title: CreateUserAuthLinkRequest
    ServerInstanceEmailPair:
      properties:
        server_instance_id:
          type: string
          format: uuid
          title: Server Instance Id
        email:
          type: string
          format: email
          title: Email
          description: Email address that this server instance is restricted to
      type: object
      required:
      - server_instance_id
      - email
      title: ServerInstanceEmailPair
    CreateProjectAuthLinkRequest:
      properties:
        server_instance_emails:
          items:
            $ref: '#/components/schemas/ServerInstanceEmailPair'
          type: array
          title: Server Instance Emails
          description: Array of server instance ID and email pairs
        link_expires_at:
          type: string
          format: date-time
          title: Link Expires At
      type: object
      required:
      - server_instance_emails
      - link_expires_at
      title: CreateProjectAuthLinkRequest
    UpdateUserAuthLinkRequest:
      properties:
        link_expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Link Expires At
          description: New expiry date for the auth link
        server_instances:
          anyOf:
          - items:
              type: string
              format: uuid
            type: array
          - type: 'null'
          title: Server Instances
          description: List of server instance IDs to associate with the link
        domain:
          anyOf:
          - type: string
          - type: 'null'
          title: Domain
          description: Domain restriction. Required when updating server_instances.
      type: object
      title: UpdateUserAuthLinkRequest
    UpdateProjectAuthLinkRequest:
      properties:
        link_expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Link Expires At
          description: New expiry date for the auth link
        server_instance_emails:
          anyOf:
          - items:
              $ref: '#/components/schemas/ServerInstanceEmailPair'
            type: array
          - type: 'null'
          title: Server Instance Emails
          description: Server instance to email mapping. Required when updating server instances.
      type: object
      title: UpdateProjectAuthLinkRequest
    CreateAuthLinkResponse:
      properties:
        invite_link:
          type: string
          title: Invite Link
          description: The complete invite link URL
        invite_link_expires_at:
          type: string
          format: date-time
          title: Invite Link Expires At
      type: object
      required:
      - invite_link
      - invite_link_expires_at
      title: CreateAuthLinkResponse
    Body_upload_and_analyze_spec_servers_internal_upload_post:
      properties:
        openapi_file:
          type: string
          format: binary
          title: Openapi File
          description: OpenAPI specification (JSON/YAML) or Postman Collection v2.1. Max 20 MB.
      type: object
      required:
      - openapi_file
      title: Body_upload_and_analyze_spec_servers_internal_upload_post
    Body_upload_server_logo_servers_upload_logo_post:
      properties:
        logo:
          type: string
          format: binary
          title: Logo
      type: object
      required:
      - logo
      title: Body_upload_server_logo_servers_upload_logo_post
    Body_upload_user_avatar_settings_avatar_post:
      properties:
        avatar:
          type: string
          format: binary
          title: Avatar
      type: object
      required:
      - avatar
      title: Body_upload_user_avatar_settings_avatar_post
    ComparisonPeriod:
      type: string
      enum:
      - rolling_month
      - rolling_week
      - rolling_day
      - rolling_hour
      title: ComparisonPeriod
      description: Comparison period for analytics.
    CreateNavigatorRequest:
      properties:
        name:
          type: string
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
      additionalProperties: false
      type: object
      required:
      - name
      title: CreateNavigatorRequest
    CreateNavigatorResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        api_name:
          type: string
          title: Api Name
      type: object
      required:
      - id
      - name
      - api_name
      title: CreateNavigatorResponse
    CreateApiKeyRequest:
      properties:
        name:
          type: string
          title: Name
          description: Name for the API key
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Optional description for the API key
        expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
          description: Optional expiration date for the API key
      type: object
      required:
      - name
      title: CreateApiKeyRequest
    CreateApiKeyResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        preview:
          type: string
          title: Preview
        key:
          type: string
          title: Key
      type: object
      required:
      - id
      - preview
      - key
      title: CreateApiKeyResponse
    CreatePlatformAccessTokenRequest:
      properties:
        name:
          type: string
          minLength: 1
          title: Name
          description: Label for the token
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Optional description for the token
        role:
          type: string
          enum:
          - admin
          default: admin
          title: Role
          description: Only admin role is allowed for platform access tokens; any other role returns 400
        expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
          description: Optional expiry; null means no expiry
      type: object
      required:
      - name
      title: CreatePlatformAccessTokenRequest
    CreatePlatformAccessTokenResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        role:
          type: string
          enum:
          - admin
          - member
          title: Role
        expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
        token:
          type: string
          title: Token
          description: Raw token; returned only on create
        preview:
          type: string
          title: Preview
          description: Display preview e.g. abc...xyz
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - name
      - role
      - token
      - preview
      - created_at
      title: CreatePlatformAccessTokenResponse
    GetPlatformAccessTokenResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        preview:
          type: string
          title: Preview
        role:
          type: string
          enum:
          - admin
          - member
          title: Role
        expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - name
      - preview
      - role
      - created_at
      title: GetPlatformAccessTokenResponse
    CreateProjectRequest:
      properties:
        name:
          type: string
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        icon:
          anyOf:
          - type: string
          - type: 'null'
          title: Icon
        webhook_config:
          anyOf:
          - type: array
            items:
              type: object
              additionalProperties: true
            maxItems: 5
          - type: 'null'
          title: Webhook Config
          description: "Array of webhook configurations (max 5). Each item schema: {url: str, secret: str | None, events: list[str], enabled: bool, service: str ('generic' | 'slack', default: 'generic')}"
      type: object
      required:
      - name
      title: CreateProjectRequest
    DeleteServerResponse:
      properties:
        server_id:
          type: string
          format: uuid
          title: Server Id
        message:
          type: string
          title: Message
      type: object
      required:
      - server_id
      - message
      title: DeleteServerResponse
      description: Response from server deletion
    DeleteTenantUserResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        message:
          type: string
          title: Message
      type: object
      required:
      - id
      - message
      title: DeleteTenantUserResponse
      description: Response from tenant user deletion
    DiscoverOAuthMetadataResponse:
      properties:
        found:
          type: boolean
          title: Found
        auth_endpoint:
          anyOf:
          - type: string
          - type: 'null'
          title: Auth Endpoint
        token_endpoint:
          anyOf:
          - type: string
          - type: 'null'
          title: Token Endpoint
        registration_endpoint:
          anyOf:
          - type: string
          - type: 'null'
          title: Registration Endpoint
        redirect_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Redirect Url
      type: object
      required:
      - found
      - auth_endpoint
      - token_endpoint
      - registration_endpoint
      title: DiscoverOAuthMetadataResponse
    TenantUserResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        email:
          type: string
          title: Email
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        role:
          $ref: '#/components/schemas/TenantUserRole'
        confirmed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Confirmed At
        timezone:
          anyOf:
          - type: string
          - type: 'null'
          title: Timezone
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - id
      - email
      - role
      - created_at
      - updated_at
      title: TenantUserResponse
      description: Response model for tenant user information
    TenantUserRole:
      type: string
      enum:
      - admin
      - user
      - viewer
      title: TenantUserRole
      description: Role of a tenant user
    UpdateTenantUserRequest:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        role:
          anyOf:
          - $ref: '#/components/schemas/TenantUserRole'
          - type: 'null'
        timezone:
          anyOf:
          - type: string
          - type: 'null'
          title: Timezone
      type: object
      title: UpdateTenantUserRequest
      description: Request model for updating tenant user
    ToolActivity:
      properties:
        tools:
          items:
            type: string
          type: array
          title: Tools
          description: List of distinct tool names
        total_count:
          type: integer
          title: Total Count
          description: Total number of distinct tools
        window:
          type: string
          title: Window
          description: Time window for the data
        filters:
          additionalProperties:
            type: string
          type: object
          title: Filters
          description: Filters applied to the query
        sort_order:
          type: string
          title: Sort Order
          description: Sort order applied (asc or desc)
        limit:
          type: integer
          title: Limit
          description: Maximum number of tools returned
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when data was calculated
      type: object
      required:
      - tools
      - total_count
      - window
      - filters
      - sort_order
      - limit
      - timestamp
      title: ToolActivity
      description: Tool activity data in a time window.
    ToolActivityResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the request was successful
        data:
          anyOf:
          - $ref: '#/components/schemas/ToolActivity'
          - type: 'null'
          description: Analytics data
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if request failed
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when response was generated
      type: object
      required:
      - success
      - timestamp
      title: ToolActivityResponse
      description: Response model for tool activity endpoint.
    ServerActivityItem:
      properties:
        server_name:
          type: string
          title: Server Name
          description: Server name
        tool_count:
          type: integer
          title: Tool Count
          description: Number of tool calls made to the server
      type: object
      required:
      - server_name
      - tool_count
      title: ServerActivityItem
      description: Server activity information with call count.
    ServerActivity:
      properties:
        servers:
          items:
            $ref: '#/components/schemas/ServerActivityItem'
          type: array
          title: Servers
          description: List of servers with their call counts
        total_count:
          type: integer
          title: Total Count
          description: Total number of distinct servers
        window:
          type: string
          title: Window
          description: Time window for the data
        filters:
          additionalProperties:
            type: string
          type: object
          title: Filters
          description: Filters applied to the query
        sort_order:
          type: string
          title: Sort Order
          description: Sort order applied (asc or desc)
        limit:
          type: integer
          title: Limit
          description: Maximum number of servers returned
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when data was calculated
      type: object
      required:
      - servers
      - total_count
      - window
      - filters
      - sort_order
      - limit
      - timestamp
      title: ServerActivity
      description: Server activity data in a time window.
    ServerActivityResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the request was successful
        data:
          anyOf:
          - $ref: '#/components/schemas/ServerActivity'
          - type: 'null'
          description: Analytics data
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if request failed
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when response was generated
      type: object
      required:
      - success
      - timestamp
      title: ServerActivityResponse
      description: Response model for server activity endpoint.
    TopServerCountItem:
      properties:
        server_id:
          type: string
          title: Server Id
          description: Server ID (UUID)
        count:
          type: integer
          title: Count
          description: Count (tool calls or queries processed)
      type: object
      required:
      - server_id
      - count
      title: TopServerCountItem
      description: Server ID with count (tool calls or queries processed).
    TopServersCountMap:
      properties:
        server_count:
          type: integer
          title: Server Count
          description: Number of servers in the list
        servers:
          items:
            $ref: '#/components/schemas/TopServerCountItem'
          type: array
          title: Servers
          description: List of servers with their counts
      type: object
      required:
      - server_count
      - servers
      title: TopServersCountMap
      description: One of the two top-servers maps (tool_calls or queries_processed).
    TopServersActivity:
      properties:
        tool_calls:
          $ref: '#/components/schemas/TopServersCountMap'
        queries_processed:
          $ref: '#/components/schemas/TopServersCountMap'
        window:
          type: string
          title: Window
          description: Time window for the data
        filters:
          additionalProperties:
            type: string
          type: object
          title: Filters
          description: Filters applied to the query
        limit:
          type: integer
          title: Limit
          description: Maximum number of servers returned
      type: object
      required:
      - tool_calls
      - queries_processed
      - window
      - filters
      - limit
      title: TopServersActivity
      description: Top servers by tool calls and by queries processed.
    TopServersActivityResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the request was successful
        data:
          anyOf:
          - $ref: '#/components/schemas/TopServersActivity'
          - type: 'null'
          description: Analytics data
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if request failed
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when response was generated
      type: object
      required:
      - success
      - timestamp
      title: TopServersActivityResponse
      description: Response model for top servers activity endpoint.
    TopProjectCountItem:
      properties:
        project_id:
          type: string
          description: Project ID (UUID)
          title: Project Id
        count:
          type: integer
          title: Count
          description: Count (tool calls or queries processed)
      type: object
      required:
      - project_id
      - count
      title: TopProjectCountItem
      description: Project ID with count (tool calls or queries processed).
    TopProjectsCountMap:
      properties:
        project_count:
          type: integer
          title: Project Count
          description: Number of projects in the list
        projects:
          items:
            $ref: '#/components/schemas/TopProjectCountItem'
          type: array
          title: Projects
          description: List of projects with their counts
      type: object
      required:
      - project_count
      - projects
      title: TopProjectsCountMap
      description: One of the two top-projects maps (tool_calls or queries_processed).
    TopProjectsActivity:
      properties:
        tool_calls:
          $ref: '#/components/schemas/TopProjectsCountMap'
        queries_processed:
          $ref: '#/components/schemas/TopProjectsCountMap'
        window:
          type: string
          title: Window
          description: Time window for the data
        filters:
          additionalProperties:
            type: string
          type: object
          title: Filters
          description: Filters applied to the query
        limit:
          type: integer
          title: Limit
          description: Maximum number of projects returned
      type: object
      required:
      - tool_calls
      - queries_processed
      - window
      - filters
      - limit
      title: TopProjectsActivity
      description: Top projects by tool calls and by queries processed.
    TopProjectsActivityResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the request was successful
        data:
          anyOf:
          - $ref: '#/components/schemas/TopProjectsActivity'
          - type: 'null'
          description: Analytics data
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if request failed
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when response was generated
      type: object
      required:
      - success
      - timestamp
      title: TopProjectsActivityResponse
      description: Response model for top projects activity endpoint.
    TopNavigatorCountItem:
      properties:
        navigator_id:
          type: string
          description: Navigator identity ID (UUID)
          title: Navigator Id
        count:
          type: integer
          title: Count
          description: Count (tool calls or queries processed)
      type: object
      required:
      - navigator_id
      - count
      title: TopNavigatorCountItem
      description: Navigator identity ID with a count (tool calls or queries processed).
    TopNavigatorsCountMap:
      properties:
        navigator_count:
          type: integer
          title: Navigator Count
          description: Number of navigators in the list
        navigators:
          items:
            $ref: '#/components/schemas/TopNavigatorCountItem'
          type: array
          title: Navigators
          description: List of navigators with their counts
      type: object
      required:
      - navigator_count
      - navigators
      title: TopNavigatorsCountMap
      description: One of the two top-navigators maps (tool_calls or queries_processed).
    TopNavigatorsActivity:
      properties:
        tool_calls:
          $ref: '#/components/schemas/TopNavigatorsCountMap'
        queries_processed:
          $ref: '#/components/schemas/TopNavigatorsCountMap'
        window:
          type: string
          title: Window
          description: Time window for the data
        filters:
          additionalProperties:
            type: string
          type: object
          title: Filters
          description: Filters applied to the query
        limit:
          type: integer
          title: Limit
          description: Maximum number of navigators returned
      type: object
      required:
      - tool_calls
      - queries_processed
      - window
      - filters
      - limit
      title: TopNavigatorsActivity
      description: Top navigators activity by tool_calls and queries_processed.
    TopNavigatorsActivityResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the request was successful
        data:
          anyOf:
          - $ref: '#/components/schemas/TopNavigatorsActivity'
          - type: 'null'
          description: Analytics data
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if request failed
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when response was generated
      type: object
      required:
      - success
      - timestamp
      title: TopNavigatorsActivityResponse
      description: Response model for top navigators activity endpoint.
    UserActivity:
      properties:
        user_email:
          type: string
          title: User Email
          description: User email address
        tool_count:
          type: integer
          title: Tool Count
          description: Number of proxy tool calls made by the user
      type: object
      required:
      - user_email
      - tool_count
      title: UserActivity
      description: User activity information with call count.
    UsersActivity:
      properties:
        users:
          items:
            $ref: '#/components/schemas/UserActivity'
          type: array
          title: Users
          description: List of users with their call counts
        total_count:
          type: integer
          title: Total Count
          description: Total number of users
        window:
          type: string
          title: Window
          description: Time window for the data
        filters:
          additionalProperties:
            type: string
          type: object
          title: Filters
          description: Filters applied to the query
        sort_order:
          type: string
          title: Sort Order
          description: Sort order applied (asc or desc)
        limit:
          type: integer
          title: Limit
          description: Maximum number of users returned
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when data was calculated
      type: object
      required:
      - users
      - total_count
      - window
      - filters
      - sort_order
      - limit
      - timestamp
      title: UsersActivity
      description: Users activity data in a time window.
    UsersActivityResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the request was successful
        data:
          anyOf:
          - $ref: '#/components/schemas/UsersActivity'
          - type: 'null'
          description: Analytics data
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if request failed
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when response was generated
      type: object
      required:
      - success
      - timestamp
      title: UsersActivityResponse
      description: Response model for users activity endpoint.
    ErrorRateGraph:
      properties:
        view_type:
          $ref: '#/components/schemas/ViewType'
          description: View type for the graph
        frequency:
          $ref: '#/components/schemas/Frequency'
          example: 1d
        time_series_data:
          items:
            $ref: '#/components/schemas/TimeSeriesData'
          type: array
          title: Time Series Data
          description: Time series data points
        total_errors:
          type: integer
          title: Total Errors
          description: Total number of errors in the time window
        total_tool_calls:
          type: integer
          title: Total Tool Calls
          description: Total number of tool calls in the time window
        average_error_rate:
          type: number
          title: Average Error Rate
          description: Average error rate as percentage
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when data was calculated
      type: object
      required:
      - view_type
      - frequency
      - time_series_data
      - total_errors
      - total_tool_calls
      - average_error_rate
      - timestamp
      title: ErrorRateGraph
      description: Error rate graph data with time series information.
    ErrorRateGraphResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the request was successful
        data:
          anyOf:
          - $ref: '#/components/schemas/ErrorRateGraph'
          - type: 'null'
          description: Analytics data
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if request failed
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when response was generated
      type: object
      required:
      - success
      - timestamp
      title: ErrorRateGraphResponse
      description: Response model for error rate graph endpoint.
    ErrorTypeTimeSeries:
      properties:
        error_type:
          type: string
          title: Error Type
          description: Type of error (e.g., authentication_error, rate_limit_error)
        error_name:
          type: string
          title: Error Name
          description: Human-readable name of the error type
        time_series_data:
          items:
            $ref: '#/components/schemas/TimeSeriesData'
          type: array
          title: Time Series Data
          description: Time series data points for this error type
        total_count:
          type: integer
          title: Total Count
          description: Total count of this error type in the time window
      type: object
      required:
      - error_type
      - error_name
      - time_series_data
      - total_count
      title: ErrorTypeTimeSeries
      description: Time series data for a specific error type.
    ErrorTypesGraph:
      properties:
        view_type:
          $ref: '#/components/schemas/ViewType'
          description: View type for the graph
        frequency:
          $ref: '#/components/schemas/Frequency'
          example: 1d
        time_series_data:
          items:
            $ref: '#/components/schemas/ErrorTypeTimeSeries'
          type: array
          title: Time Series Data
          description: Time series data for each error type
        total_errors:
          type: integer
          title: Total Errors
          description: Total number of errors across all types
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when data was calculated
      type: object
      required:
      - view_type
      - frequency
      - time_series_data
      - total_errors
      - timestamp
      title: ErrorTypesGraph
      description: Error types graph data showing top error types over time.
    ErrorTypesGraphResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the request was successful
        data:
          anyOf:
          - $ref: '#/components/schemas/ErrorTypesGraph'
          - type: 'null'
          description: Analytics data
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if request failed
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when response was generated
      type: object
      required:
      - success
      - timestamp
      title: ErrorTypesGraphResponse
      description: Response model for error types graph endpoint.
    Frequency:
      type: string
      pattern: ^\d+[mhdw]$|^\d+mo$
      title: Frequency
      description: 'Frequency for time-based aggregations. Accepts flexible formats: number followed by unit, where unit is m (minutes), h (hours), d (days), w (weeks), or mo (months). Examples: 1m, 5m, 1h, 6h, 1d, 3d, 1w, 2w, 1mo, 3mo'
      example: 1d
    GenerateInternalHeaderServerWithAnalysisRequest:
      properties:
        session_id:
          type: string
          title: Session Id
        server_name:
          type: string
          title: Server Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        transport:
          $ref: '#/components/schemas/ServerTransport'
          default: streamable_http
        tool_selection:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Tool Selection
        headers:
          items:
            $ref: '#/components/schemas/HeaderConfig'
          type: array
          title: Headers
        start_server:
          type: boolean
          title: Start Server
          default: true
      type: object
      required:
      - session_id
      - server_name
      - headers
      title: GenerateInternalHeaderServerWithAnalysisRequest
      description: Request for generating internal server with header authentication
        using pre-analyzed spec
    GenerateInternalOAuthServerWithAnalysisRequest:
      properties:
        session_id:
          type: string
          title: Session Id
        server_name:
          type: string
          title: Server Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        transport:
          $ref: '#/components/schemas/ServerTransport'
          default: streamable_http
        tool_selection:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Tool Selection
        metadata:
          $ref: '#/components/schemas/DiscoverOAuthMetadataResponse'
        manual_client_config:
          $ref: '#/components/schemas/ManualClientConfig'
        redirect_uris:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Redirect Uris
        scopes:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Scopes
        start_server:
          type: boolean
          title: Start Server
          default: true
      type: object
      required:
      - session_id
      - server_name
      - metadata
      - manual_client_config
      title: GenerateInternalOAuthServerWithAnalysisRequest
      description: Request for generating internal server with OAuth authentication
        using pre-analyzed spec
    GetNavigatorConnectionsItem:
      properties:
        project_id:
          type: string
          format: uuid
          title: Project Id
        project_name:
          type: string
          title: Project Name
        navigator_instance_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Navigator Instance Id
      type: object
      required:
      - project_id
      - project_name
      - navigator_instance_id
      title: GetNavigatorConnectionsItem
    GetNavigatorConnectionsResponse:
      properties:
        connections:
          items:
            $ref: '#/components/schemas/GetNavigatorConnectionsItem'
          type: array
          title: Connections
      type: object
      required:
      - connections
      title: GetNavigatorConnectionsResponse
    GetNavigatorInstanceAnalytics:
      properties:
        servers_enabled:
          anyOf:
          - type: integer
          - type: 'null'
          title: Servers Enabled
        tools_enabled:
          anyOf:
          - type: integer
          - type: 'null'
          title: Tools Enabled
      type: object
      required:
      - servers_enabled
      - tools_enabled
      title: GetNavigatorInstanceAnalytics
    NavigatorInstanceConfigMetadata:
      description: Configuration metadata for a navigator instance (included when include_config_metadata=true).
      properties:
        can_enable_context_maps:
          type: boolean
          title: Can Enable Context Maps
          description: Whether context maps can be enabled for this navigator instance
        extraction_enabled_servers_count:
          type: integer
          title: Extraction Enabled Servers Count
          description: Number of server instances with extraction enabled
        extraction_enabled_server_ids:
          items:
            type: string
            format: uuid
          type: array
          title: Extraction Enabled Server Ids
          description: IDs of server instances with extraction enabled
      type: object
      title: NavigatorInstanceConfigMetadata
    GetNavigatorInstanceResponse:
      description: Detailed response for a single navigator instance.
      properties:
        id:
          type: string
          format: uuid
          title: Id
        navigator_id:
          type: string
          format: uuid
          title: Navigator Id
        project_id:
          type: string
          format: uuid
          title: Project Id
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        navigator_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Navigator Name
        api_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Api Name
        project_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Project Name
        dynamic_suggestions_enabled:
          type: boolean
          title: Dynamic Suggestions Enabled
          description: Whether dynamic suggestions are enabled for this navigator instance
        context_maps_enabled:
          type: boolean
          title: Context Maps Enabled
          description: Whether context maps are enabled for this navigator instance
        metadata:
          anyOf:
          - $ref: '#/components/schemas/GetNavigatorInstanceAnalytics'
          - type: 'null'
        config_metadata:
          anyOf:
          - $ref: '#/components/schemas/NavigatorInstanceConfigMetadata'
          - type: 'null'
          title: Config Metadata
          description: Configuration metadata (present when include_config_metadata=true)
      type: object
      required:
      - id
      - navigator_id
      - project_id
      - created_at
      - updated_at
      title: GetNavigatorInstanceResponse
    GetNavigatorResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        api_name:
          type: string
          title: Api Name
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        metadata:
          anyOf:
          - $ref: '#/components/schemas/GetNavigatorResponseAnalytics'
          - type: 'null'
      type: object
      required:
      - id
      - name
      - description
      - api_name
      - created_at
      - updated_at
      title: GetNavigatorResponse
    GetNavigatorResponseAnalytics:
      properties:
        enabled_servers_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Enabled Servers Count
        connected_projects_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Connected Projects Count
      type: object
      required:
      - enabled_servers_count
      - connected_projects_count
      title: GetNavigatorResponseAnalytics
    GetApiKeyResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        navigator_instance_id:
          type: string
          format: uuid
          title: Navigator Instance Id
          description: The navigator instance this API key belongs to
        navigator_instance_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Navigator Instance Name
          description: The name of the navigator identity associated with this API key
        project_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Project Id
          description: The project the navigator instance belongs to
        project_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Project Name
        preview:
          type: string
          title: Preview
        key_prefix:
          anyOf:
          - type: string
          - type: 'null'
          title: Key Prefix
        name:
          type: string
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - id
      - navigator_instance_id
      - preview
      - name
      - created_at
      - updated_at
      title: GetApiKeyResponse
    GetProjectResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        icon:
          anyOf:
          - type: string
          - type: 'null'
          title: Icon
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        active_server_instances:
          anyOf:
          - type: integer
          - type: 'null'
          title: Active Server Instances
          description: Number of active server instances
        active_navigators:
          anyOf:
          - type: integer
          - type: 'null'
          title: Active Navigators
          description: Number of active navigators
        webhook_config:
          anyOf:
          - type: array
            items:
              type: object
              additionalProperties: true
            maxItems: 5
          - type: 'null'
          title: Webhook Config
          description: "Array of webhook configurations (max 5). Each item schema: {url: str, secret: str | None, events: list[str], enabled: bool, service: str ('generic' | 'slack', default: 'generic')}"
      type: object
      required:
      - id
      - name
      - description
      - created_at
      - updated_at
      title: GetProjectResponse
    GetProjectStatusResponse:
      properties:
        active_server_instances:
          type: integer
          title: Active Server Instances
        disabled_server_instances:
          type: integer
          title: Disabled Server Instances
        active_navigator_instances:
          type: integer
          title: Active Navigator Instances
      type: object
      required:
      - active_server_instances
      - disabled_server_instances
      - active_navigator_instances
      title: GetProjectStatusResponse
    WebhookScopeEventTypes:
      properties:
        scope:
          type: string
          title: Scope
          description: Webhook configuration scope (e.g. project, tenant, system).
        event_types:
          items:
            type: string
          type: array
          title: Event Types
          description: Canonical event type strings for this scope.
      type: object
      required:
      - scope
      - event_types
      title: WebhookScopeEventTypes
    WebhookEventTypesByScopeResponse:
      properties:
        scopes:
          items:
            $ref: '#/components/schemas/WebhookScopeEventTypes'
          type: array
          title: Scopes
          description: |
            When `scope` query params are omitted, includes every known scope
            (reserved scopes may return empty `event_types`). When `scope` is
            provided, only those scopes are listed, in request order.
      type: object
      required:
      - scopes
      title: WebhookEventTypesByScopeResponse
    GetQueryResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        token:
          anyOf:
          - type: string
          - type: 'null'
          title: Token
        query:
          type: string
          title: Query
        navigator_instance_id:
          type: string
          format: uuid
          title: Navigator Instance Id
        project_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Project Id
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - id
      - token
      - query
      - navigator_instance_id
      - created_at
      - updated_at
      title: GetQueryResponse
    GetQueryTrace:
      properties:
        query:
          $ref: '#/components/schemas/GetQueryResponse'
        tool_call_groups:
          items:
            $ref: '#/components/schemas/TraceToolCallGroup'
          type: array
          title: Tool Call Groups
        tool_schemas:
          items:
            $ref: '#/components/schemas/TraceGetSchema'
          type: array
          title: Tool Schemas
        suggest_tools:
          items:
            $ref: '#/components/schemas/TraceSuggestTools'
          type: array
          title: Suggest Tools
      type: object
      required:
      - query
      - tool_call_groups
      - tool_schemas
      - suggest_tools
      title: GetQueryTrace
    GetServerConnectionsItem:
      properties:
        project_id:
          type: string
          format: uuid
          title: Project Id
        project_name:
          type: string
          title: Project Name
        server_instance_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Server Instance Id
        is_paused:
          type: boolean
          title: Is Paused
      type: object
      required:
      - project_id
      - project_name
      - server_instance_id
      - is_paused
      title: GetServerConnectionsItem
    GetServerConnectionsResponse:
      properties:
        connections:
          items:
            $ref: '#/components/schemas/GetServerConnectionsItem'
          type: array
          title: Connections
      type: object
      required:
      - connections
      title: GetServerConnectionsResponse
    GetServerHealthCheck:
      properties:
        last_check:
          type: string
          format: date-time
          title: Last Check
        status:
          $ref: '#/components/schemas/HealthCheckStatus'
      type: object
      required:
      - last_check
      - status
      title: GetServerHealthCheck
    ServerOAuthConfigForResponse:
      description: OAuth auth config in GET server response (scopes and provider only; no client_id/client_secret)
      properties:
        scopes:
          anyOf:
          - type: string
          - type: 'null'
          title: Scopes
        provider:
          anyOf:
          - type: string
            enum:
            - user
            - dcr
            - caylex
          - type: 'null'
          title: Provider
          description: Credentials provider; user = manual, dcr = Caylex DCR, caylex = Caylex pre-configured (no DCR)
      type: object
      title: ServerOAuthConfigForResponse
    GetServerAuthConfigResponse:
      description: Auth config in GET server response (OAuth excludes client_id and client_secret)
      properties:
        auth_method:
          $ref: '#/components/schemas/ServerAuthMethod'
        oauth:
          anyOf:
          - $ref: '#/components/schemas/ServerOAuthConfigForResponse'
          - type: 'null'
          title: Oauth
        headers:
          anyOf:
          - items:
              $ref: '#/components/schemas/HeaderConfig'
            type: array
          - type: 'null'
          title: Headers
        paths:
          anyOf:
          - items:
              $ref: '#/components/schemas/PathConfig'
            type: array
          - type: 'null'
          title: Paths
        params:
          anyOf:
          - items:
              $ref: '#/components/schemas/QueryConfig'
            type: array
          - type: 'null'
          title: Params
      type: object
      required:
      - auth_method
      title: GetServerAuthConfigResponse
    GetServerInstanceResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        server_id:
          type: string
          format: uuid
          title: Server Id
        project_id:
          type: string
          format: uuid
          title: Project Id
        paused:
          type: boolean
          title: Paused
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        server_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Server Name
        project_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Project Name
        auth_method:
          anyOf:
          - $ref: '#/components/schemas/ServerAuthMethod'
          - type: 'null'
          title: Auth Method
        auth_credentials_level:
          anyOf:
          - $ref: '#/components/schemas/AuthLevel'
          - type: 'null'
          title: Auth Credentials Level
        server_type:
          anyOf:
          - $ref: '#/components/schemas/ServerType'
          - type: 'null'
          title: Server Type
        transport:
          anyOf:
          - $ref: '#/components/schemas/ServerTransport'
          - type: 'null'
          title: Transport
        logo_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Logo Url
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        num_tools:
          anyOf:
          - type: integer
          - type: 'null'
          title: Num Tools
      type: object
      required:
      - id
      - server_id
      - project_id
      - paused
      - created_at
      - updated_at
      title: GetServerInstanceResponse
    GetServerRegistryResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        endpoint:
          type: string
          title: Endpoint
        logo_url:
          type: string
          title: Logo Url
        server_type:
          $ref: '#/components/schemas/ServerType'
        transport:
          $ref: '#/components/schemas/ServerTransport'
        auth_methods:
          items:
            $ref: '#/components/schemas/ServerAuthMethod'
          type: array
          title: Auth Methods
          description: Available authentication methods for this server registry
        auth_config:
          anyOf:
          - type: object
            additionalProperties: true
            description: Authentication configuration for the server registry
          - type: 'null'
          title: Auth Config
          description: Authentication configuration details for the server registry
      type: object
      required:
      - id
      - name
      - description
      - endpoint
      - logo_url
      - server_type
      - transport
      title: GetServerRegistryResponse
    GetServerResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        registry_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Registry Id
        registry_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Registry Name
        registry_endpoint:
          anyOf:
          - type: string
          - type: 'null'
          title: Registry Endpoint
        name:
          type: string
          title: Name
        endpoint:
          type: string
          title: Endpoint
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        transport:
          $ref: '#/components/schemas/ServerTransport'
        auth_method:
          $ref: '#/components/schemas/ServerAuthMethod'
        server_type:
          $ref: '#/components/schemas/ServerType'
        auth_level:
          $ref: '#/components/schemas/AuthLevel'
        logo_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Logo Url
        health_check:
          anyOf:
          - $ref: '#/components/schemas/GetServerHealthCheck'
          - type: 'null'
        metadata:
          anyOf:
          - $ref: '#/components/schemas/GetServerResponseAnalytics'
          - type: 'null'
        active_instances:
          anyOf:
          - type: integer
          - type: 'null'
          title: Active Instances
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        auth_config:
          anyOf:
          - $ref: '#/components/schemas/GetServerAuthConfigResponse'
          - type: 'null'
          title: Auth Config
          description: Server auth config (OAuth excludes client_id and client_secret)
      type: object
      required:
      - id
      - name
      - endpoint
      - description
      - transport
      - auth_method
      - server_type
      - auth_level
      - logo_url
      - health_check
      - metadata
      - created_at
      - updated_at
      title: GetServerResponse
    GetServerResponseAnalytics:
      properties:
        num_tools:
          anyOf:
          - type: integer
          - type: 'null'
          title: Num Tools
        num_tool_calls:
          anyOf:
          - type: integer
          - type: 'null'
          title: Num Tool Calls
        connected_projects:
          anyOf:
          - type: integer
          - type: 'null'
          title: Connected Projects
      type: object
      required:
      - num_tools
      - num_tool_calls
      - connected_projects
      title: GetServerResponseAnalytics
    GetTenantResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        descope_id:
          type: string
          title: Descope Id
        enabled:
          type: boolean
          title: Enabled
      type: object
      required:
      - id
      - name
      - descope_id
      - enabled
      title: GetTenantResponse
    GetToolPermissionsResponse:
      properties:
        permissions:
          items:
            $ref: '#/components/schemas/ToolPermissionItem'
          type: array
          title: Permissions
      type: object
      required:
      - permissions
      title: GetToolPermissionsResponse
    GlobalStats:
      properties:
        total_queries:
          type: integer
          title: Total Queries
          description: Total number of queries processed
        total_tool_calls:
          type: integer
          title: Total Tool Calls
          description: Total number of tool calls executed
        previous_total_queries:
          type: integer
          title: Previous Total Queries
          description: Total number of queries processed in the previous comparison period
        previous_total_tool_calls:
          type: integer
          title: Previous Total Tool Calls
          description: Total number of tool calls executed in the previous comparison period
        comparison_period:
          $ref: '#/components/schemas/ComparisonPeriod'
          description: Comparison period used
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when stats were calculated
      type: object
      required:
      - total_queries
      - total_tool_calls
      - previous_total_queries
      - previous_total_tool_calls
      - comparison_period
      - timestamp
      title: GlobalStats
      description: Global statistics for the Caylex platform.
    GlobalStatsResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the request was successful
        data:
          anyOf:
          - $ref: '#/components/schemas/GlobalStats'
          - type: 'null'
          description: Analytics data
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if request failed
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when response was generated
      type: object
      required:
      - success
      - timestamp
      title: GlobalStatsResponse
      description: Response model for global stats endpoint.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    HeaderConfig:
      properties:
        header_name:
          type: string
          title: Header Name
        header_value_prefix:
          type: string
          title: Header Value Prefix
      type: object
      required:
      - header_name
      - header_value_prefix
      title: HeaderConfig
    HealthCheckStatus:
      type: string
      enum:
      - up
      - down
      - creating
      - no_data
      title: HealthCheckStatus
    InternalServerGenerationResponse:
      properties:
        server_id:
          type: string
          format: uuid
          title: Server Id
        session_id:
          type: string
          title: Session Id
        generation_status:
          type: string
          title: Generation Status
        message:
          type: string
          title: Message
      type: object
      required:
      - server_id
      - session_id
      - generation_status
      - message
      title: InternalServerGenerationResponse
      description: Response from internal server generation
    ServerInstanceInfo:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        logo_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Logo Url
        valid_for:
          anyOf:
          - type: string
          - type: 'null'
          title: Valid For
          description: Domain or email address that this invite link is valid for
      type: object
      required:
      - id
      - name
      title: ServerInstanceInfo
    InviteLinkResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        auth_link:
          type: string
          format: uri
          title: Auth Link
          description: The full auth link URL that can be used to invite users
        expires_at:
          type: string
          format: date-time
          title: Expires At
        auth_credentials_level:
          $ref: '#/components/schemas/InviteLinkType'
        server_instances:
          items:
            $ref: '#/components/schemas/ServerInstanceInfo'
          type: array
          title: Server Instances
          default: []
        created_at:
          type: string
          format: date-time
          title: Created At
          description: UTC timestamp when the auth link was created
        users:
          items:
            $ref: '#/components/schemas/AuthenticatedUser'
          type: array
          title: Users
          description: |
            List of users. Behavior depends on auth_credentials_level:
            - For 'user' type links: Returns only authenticated users from user_invite_link_association table.
            - For 'project' type links: Returns all users from the valid_for column, with authentication timestamps if available.
          default: []
      type: object
      required:
      - id
      - auth_link
      - expires_at
      - auth_credentials_level
      - created_at
      title: InviteLinkResponse
    AuthLinkDetailsResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        auth_link:
          type: string
          format: uri
          title: Auth Link
          description: The full auth link URL that can be used to invite users
        expires_at:
          type: string
          format: date-time
          title: Expires At
        auth_credentials_level:
          $ref: '#/components/schemas/InviteLinkType'
        server_instances:
          items:
            $ref: '#/components/schemas/ServerInstanceInfo'
          type: array
          title: Server Instances
          default: []
        created_at:
          type: string
          format: date-time
          title: Created At
          description: UTC timestamp when the auth link was created
        user_count:
          type: integer
          title: User Count
          description: Number of users who have authenticated using this invite link
          default: 0
      type: object
      required:
      - id
      - auth_link
      - expires_at
      - auth_credentials_level
      - server_instances
      - created_at
      - user_count
      title: AuthLinkDetailsResponse
      description: Detailed response for a single auth link.
    AuthenticatedUser:
      properties:
        email:
          type: string
          title: Email
          description: User email address or domain from the valid_for column
        first_authenticated:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: First Authenticated
          description: UTC timestamp when the user first authenticated using this invite link. Null if the user has not authenticated yet.
        last_authenticated:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Authenticated
          description: UTC timestamp when the user last authenticated using this invite link. Null if the user has not authenticated yet.
      type: object
      required:
      - email
      title: AuthenticatedUser
    InviteLinkType:
      type: string
      enum:
      - user
      - project
      title: InviteLinkType
    ManualClientConfig:
      properties:
        client_id:
          type: string
          title: Client Id
        client_secret:
          type: string
          title: Client Secret
      type: object
      required:
      - client_id
      - client_secret
      title: ManualClientConfig
      description: Manual OAuth client configuration
    MemberSortOption:
      type: string
      enum:
      - email_desc
      - email_asc
      - created_desc
      - created_asc
      title: MemberSortOption
      description: Sort options for member listing endpoints
    NotificationResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        project_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Project Id
        event_type:
          type: string
          title: Event Type
        title:
          type: string
          title: Title
        body:
          anyOf:
          - type: string
          - type: 'null'
          title: Body
        severity:
          type: string
          title: Severity
        data:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Data
        is_read:
          type: boolean
          title: Is Read
          default: false
          description: Derived per user from last_read_at watermark at list time.
        created_at:
          type: string
          format: date-time
          title: Created At
        target_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Target Type
        target_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Target Id
        actor_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Actor Id
      type: object
      required:
      - id
      - project_id
      - event_type
      - title
      - body
      - severity
      - data
      - created_at
      title: NotificationResponse
      description: A single in-app notification for the tenant inbox.
    ModifiedApiKeyResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
      type: object
      required:
      - id
      title: ModifiedApiKeyResponse
    ModifiedProjectResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
      type: object
      required:
      - id
      title: ModifiedProjectResponse
    PageMeta:
      description: Metadata for paginated responses.
      properties:
        size:
          type: integer
          title: Size
          description: Number of items per page
        total:
          type: integer
          title: Total
          description: Total number of items available
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
          description: Opaque cursor for the next page; null when there is no next page
        has_next:
          type: boolean
          title: Has Next
          description: Whether another page of results exists after this one
        has_prev:
          type: boolean
          title: Has Prev
          description: Whether a previous page of results exists before this one
      type: object
      required:
      - size
      - total
      - has_next
      - has_prev
      title: PageMeta
    Page_GetNavigatorInstanceResponse_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/GetNavigatorInstanceResponse'
          type: array
          title: Items
        meta:
          $ref: '#/components/schemas/PageMeta'
      type: object
      required:
      - items
      - meta
      title: Page[GetNavigatorInstanceResponse]
    Page_GetNavigatorResponse_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/GetNavigatorResponse'
          type: array
          title: Items
        meta:
          $ref: '#/components/schemas/PageMeta'
      type: object
      required:
      - items
      - meta
      title: Page[GetNavigatorResponse]
    Page_GetApiKeyResponse_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/GetApiKeyResponse'
          type: array
          title: Items
        meta:
          $ref: '#/components/schemas/PageMeta'
      type: object
      required:
      - items
      - meta
      title: Page[GetApiKeyResponse]
    Page_GetProjectResponse_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/GetProjectResponse'
          type: array
          title: Items
        meta:
          $ref: '#/components/schemas/PageMeta'
      type: object
      required:
      - items
      - meta
      title: Page[GetProjectResponse]
    Page_InviteLinkResponse_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/InviteLinkResponse'
          type: array
          title: Items
        meta:
          $ref: '#/components/schemas/PageMeta'
      type: object
      required:
      - items
      - meta
      title: Page[InviteLinkResponse]
    Page_NotificationResponse_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/NotificationResponse'
          type: array
          title: Items
        meta:
          $ref: '#/components/schemas/PageMeta'
      type: object
      required:
      - items
      - meta
      title: Page[NotificationResponse]
    Page_GetServerInstanceResponse_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/GetServerInstanceResponse'
          type: array
          title: Items
        meta:
          $ref: '#/components/schemas/PageMeta'
      type: object
      required:
      - items
      - meta
      title: Page[GetServerInstanceResponse]
    Page_GetServerRegistryResponse_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/GetServerRegistryResponse'
          type: array
          title: Items
        meta:
          $ref: '#/components/schemas/PageMeta'
      type: object
      required:
      - items
      - meta
      title: Page[GetServerRegistryResponse]
    Page_GetServerResponse_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/GetServerResponse'
          type: array
          title: Items
        meta:
          $ref: '#/components/schemas/PageMeta'
      type: object
      required:
      - items
      - meta
      title: Page[GetServerResponse]
    Page_QueryLogResponse_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/QueryLogResponse'
          type: array
          title: Items
        meta:
          $ref: '#/components/schemas/PageMeta'
      type: object
      required:
      - items
      - meta
      title: Page[QueryLogResponse]
    Page_TenantUserResponse_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/TenantUserResponse'
          type: array
          title: Items
        meta:
          $ref: '#/components/schemas/PageMeta'
      type: object
      required:
      - items
      - meta
      title: Page[TenantUserResponse]
    PathConfig:
      properties:
        path_param_name:
          type: string
          title: Path Param Name
      type: object
      required:
      - path_param_name
      title: PathConfig
    QueryConfig:
      properties:
        query_param_name:
          type: string
          title: Query Param Name
      type: object
      required:
      - query_param_name
      title: QueryConfig
    QueryParam:
      properties:
        name:
          type: string
          title: Name
        value:
          type: string
          title: Value
      type: object
      required:
      - name
      - value
      title: QueryParam
    QueriesProcessed:
      properties:
        total_queries:
          type: integer
          title: Total Queries
          description: Total number of queries processed
        window:
          type: string
          title: Window
          description: Time window for the data
        filters:
          additionalProperties:
            type: string
          type: object
          title: Filters
          description: Filters applied to the query
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when stats were calculated
      type: object
      required:
      - total_queries
      - window
      - filters
      - timestamp
      title: QueriesProcessed
      description: Queries processed with optional filters.
    QueriesProcessedResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the request was successful
        data:
          anyOf:
          - $ref: '#/components/schemas/QueriesProcessed'
          - type: 'null'
          description: Analytics data
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if request failed
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when response was generated
      type: object
      required:
      - success
      - timestamp
      title: QueriesProcessedResponse
      description: Response model for queries processed endpoint.
    QueryLogResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        query:
          type: string
          title: Query
        num_tool_calls:
          type: integer
          title: Num Tool Calls
        servers_invoked:
          items:
            type: string
            format: uuid
          type: array
          title: Servers Invoked
        server_logo_urls:
          items:
            anyOf:
            - type: string
            - type: 'null'
          type: array
          title: Server Logo Urls
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        num_errors:
          type: integer
          title: Num Errors
        navigator_instance_id:
          type: string
          format: uuid
          title: Navigator Instance Id
        navigator_name:
          type: string
          title: Navigator Name
      type: object
      required:
      - id
      - query
      - num_tool_calls
      - servers_invoked
      - server_logo_urls
      - timestamp
      - num_errors
      - navigator_instance_id
      - navigator_name
      title: QueryLogResponse
    ServerAuthMethod:
      type: string
      enum:
      - header
      - oauth
      - path
      - none
      title: ServerAuthMethod
    StartServerResponse:
      properties:
        server_id:
          type: string
          format: uuid
          title: Server Id
        server_name:
          type: string
          title: Server Name
        status:
          type: string
          title: Status
        message:
          type: string
          title: Message
      type: object
      required:
      - server_id
      - server_name
      - status
      - message
      title: StartServerResponse
      description: Response for server start/stop actions
    ServerInstanceRequest:
      properties:
        status:
          type: string
          title: Status
          description: Status to set 'pause' or 'unpause'
      required:
      - status
      title: ServerInstanceRequest
      description: Request model for server instance actions
    ServerInstanceResponse:
      properties:
        server_instance_id:
          type: string
          format: uuid
          title: Server Instance Id
        server_id:
          type: string
          format: uuid
          title: Server Id
        server_name:
          type: string
          title: Server Name
        status:
          type: string
          title: Status
        message:
          type: string
          title: Message
      required:
      - server_instance_id
      - server_id
      - server_name
      - status
      - message
      title: ServerInstanceResponse
      description: Response for server instance actions
    ServerInstanceLatency:
      properties:
        average_latency:
          type: number
          title: Average Latency
          description: Average tool call latency in seconds
        total_calls:
          type: integer
          title: Total Calls
          description: Total number of tool calls
        window:
          type: string
          title: Window
          description: Time window for the data
        filters:
          additionalProperties:
            type: string
          type: object
          title: Filters
          description: Filters applied to the query
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when stats were calculated
      type: object
      required:
      - average_latency
      - total_calls
      - window
      - filters
      - timestamp
      title: ServerInstanceLatency
      description: Average tool call latency with optional filters.
    AverageToolCallLatencyResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the request was successful
        data:
          anyOf:
          - $ref: '#/components/schemas/ServerInstanceLatency'
          - type: 'null'
          description: Analytics data
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if request failed
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when response was generated
      type: object
      required:
      - success
      - timestamp
      title: AverageToolCallLatencyResponse
      description: Response model for server instance latency endpoint.
    AverageToolCallLatencyGraph:
      properties:
        data_points:
          type: array
          items:
            type: object
            additionalProperties: true
          title: Data Points
          description: Graph data points for latency over time
        view:
          $ref: '#/components/schemas/ViewType'
        frequency:
          $ref: '#/components/schemas/Frequency'
          example: 1d
        window:
          type: string
          title: Window
          description: Time window for the data
        filters:
          type: object
          additionalProperties:
            type: string
          title: Filters
          description: Filters applied to the query
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when stats were calculated
      type: object
      required:
      - data_points
      - view
      - frequency
      - window
      - filters
      - timestamp
      title: AverageToolCallLatencyGraph
      description: Average tool call latency graph data with optional filters.
    AverageToolCallLatencyGraphResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the request was successful
        data:
          anyOf:
          - $ref: '#/components/schemas/AverageToolCallLatencyGraph'
          - type: 'null'
          description: Analytics data
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if request failed
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when response was generated
      type: object
      required:
      - success
      - timestamp
      title: AverageToolCallLatencyGraphResponse
      description: Response model for average tool call latency graph endpoint.
    ServerInstanceRuntime:
      properties:
        average_runtime:
          type: number
          title: Average Runtime
          description: Average tool procedure runtime in seconds
        total_executions:
          type: integer
          title: Total Executions
          description: Total number of tool executions
        window:
          type: string
          title: Window
          description: Time window for the data
        filters:
          additionalProperties:
            type: string
          type: object
          title: Filters
          description: Filters applied to the query
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when stats were calculated
      type: object
      required:
      - average_runtime
      - total_executions
      - window
      - filters
      - timestamp
      title: ServerInstanceRuntime
      description: Average tool procedure runtime with optional filters.
    AverageToolCallRuntimeResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the request was successful
        data:
          anyOf:
          - $ref: '#/components/schemas/ServerInstanceRuntime'
          - type: 'null'
          description: Analytics data
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if request failed
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when response was generated
      type: object
      required:
      - success
      - timestamp
      title: AverageToolCallRuntimeResponse
      description: Response model for server instance runtime endpoint.
    AverageToolCallRuntimeGraph:
      properties:
        data_points:
          type: array
          items:
            type: object
            additionalProperties: true
          title: Data Points
          description: Graph data points for runtime over time
        view:
          $ref: '#/components/schemas/ViewType'
        frequency:
          $ref: '#/components/schemas/Frequency'
          example: 1d
        window:
          type: string
          title: Window
          description: Time window for the data
        filters:
          type: object
          additionalProperties:
            type: string
          title: Filters
          description: Filters applied to the query
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when stats were calculated
      type: object
      required:
      - data_points
      - view
      - frequency
      - window
      - filters
      - timestamp
      title: AverageToolCallRuntimeGraph
      description: Average tool call runtime graph data with optional filters.
    AverageToolCallRuntimeGraphResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the request was successful
        data:
          anyOf:
          - $ref: '#/components/schemas/AverageToolCallRuntimeGraph'
          - type: 'null'
          description: Analytics data
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if request failed
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when response was generated
      type: object
      required:
      - success
      - timestamp
      title: AverageToolCallRuntimeGraphResponse
      description: Response model for average tool call runtime graph endpoint.
    ServerModifiedResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
      type: object
      required:
      - id
      title: ServerModifiedResponse
    ServerSortBy:
      type: string
      enum:
      - name_asc
      - name_desc
      - created_asc
      - created_desc
      title: ServerSortBy
      description: Sorting options for server listing.
    ServerTransport:
      type: string
      enum:
      - sse
      - streamable_http
      title: ServerTransport
    ServerType:
      type: string
      enum:
      - caylex
      - external
      - foundry
      title: ServerType
    TimeSeriesData:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp of the data point
        value:
          type: number
          title: Value
          description: Value at this timestamp
        labels:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Labels
          description: Additional labels for the data point
      type: object
      required:
      - timestamp
      - value
      title: TimeSeriesData
      description: Time series data for analytics.
    ToolCallsGraph:
      properties:
        data_points:
          items:
            additionalProperties:
              anyOf:
              - type: string
              - type: integer
              - type: number
              - type: boolean
            type: object
          type: array
          title: Data Points
          description: Graph data points
        view:
          $ref: '#/components/schemas/ViewType'
          description: View type for the graph
        frequency:
          $ref: '#/components/schemas/Frequency'
          example: 1d
        window:
          type: string
          title: Window
          description: Time window for the data
        filters:
          additionalProperties:
            type: string
          type: object
          title: Filters
          description: Filters applied to the query
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when stats were calculated
      type: object
      required:
      - data_points
      - view
      - frequency
      - window
      - filters
      - timestamp
      title: ToolCallsGraph
      description: Tool calls processed graph data with optional filters.
    ToolCallsGraphResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the request was successful
        data:
          anyOf:
          - $ref: '#/components/schemas/ToolCallsGraph'
          - type: 'null'
          description: Analytics data
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if request failed
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when response was generated
      type: object
      required:
      - success
      - timestamp
      title: ToolCallsGraphResponse
      description: Response model for tool calls graph endpoint.
    ToolCallsPerQuery:
      properties:
        average_tool_calls_per_query:
          type: number
          title: Average Tool Calls Per Query
          description: Average tool calls per query
        total_queries:
          type: integer
          title: Total Queries
          description: Total number of queries
        total_tool_calls:
          type: integer
          title: Total Tool Calls
          description: Total number of tool calls
        window:
          type: string
          title: Window
          description: Window period
        view:
          $ref: '#/components/schemas/ViewType'
          description: View type
        frequency:
          $ref: '#/components/schemas/Frequency'
          example: 1h
        filters:
          additionalProperties:
            type: string
          type: object
          title: Filters
          description: Filters applied to the query
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when stats were calculated
      type: object
      required:
      - average_tool_calls_per_query
      - total_queries
      - total_tool_calls
      - window
      - view
      - frequency
      - filters
      - timestamp
      title: ToolCallsPerQuery
      description: Average tool calls per query with optional filters.
    ToolCallsPerQueryResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the request was successful
        data:
          anyOf:
          - $ref: '#/components/schemas/ToolCallsPerQuery'
          - type: 'null'
          description: Analytics data
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if request failed
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when response was generated
      type: object
      required:
      - success
      - timestamp
      title: ToolCallsPerQueryResponse
      description: Response model for tool calls per query endpoint.
    ToolCallsPerQueryGraph:
      properties:
        data_points:
          type: array
          items:
            type: object
            additionalProperties: true
          title: Data Points
          description: Graph data points for tool calls per query over time
        view:
          $ref: '#/components/schemas/ViewType'
        frequency:
          $ref: '#/components/schemas/Frequency'
          example: 1d
        window:
          type: string
          title: Window
          description: Time window for the data
        filters:
          type: object
          additionalProperties:
            type: string
          title: Filters
          description: Filters applied to the query
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when stats were calculated
      type: object
      required:
      - data_points
      - view
      - frequency
      - window
      - filters
      - timestamp
      title: ToolCallsPerQueryGraph
      description: Tool calls per query graph data with optional filters.
    ToolCallsPerQueryGraphResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the request was successful
        data:
          anyOf:
          - $ref: '#/components/schemas/ToolCallsPerQueryGraph'
          - type: 'null'
          description: Analytics data
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if request failed
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when response was generated
      type: object
      required:
      - success
      - timestamp
      title: ToolCallsPerQueryGraphResponse
      description: Response model for tool calls per query graph endpoint.
    ToolCallsProcessed:
      properties:
        total_tool_calls:
          type: integer
          title: Total Tool Calls
          description: Total number of tool calls processed
        window:
          type: string
          title: Window
          description: Time window for the data
        filters:
          additionalProperties:
            type: string
          type: object
          title: Filters
          description: Filters applied to the query
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when stats were calculated
      type: object
      required:
      - total_tool_calls
      - window
      - filters
      - timestamp
      title: ToolCallsProcessed
      description: Tool calls processed with optional filters.
    ToolCallsProcessedResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the request was successful
        data:
          anyOf:
          - $ref: '#/components/schemas/ToolCallsProcessed'
          - type: 'null'
          description: Analytics data
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if request failed
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when response was generated
      type: object
      required:
      - success
      - timestamp
      title: ToolCallsProcessedResponse
      description: Response model for tool calls processed endpoint.
    ProxyToolEfficiency:
      properties:
        suggest_tools_count:
          type: integer
          title: Suggest Tools Count
          description: Total number of suggest_tools calls
        get_tool_schemas_count:
          type: integer
          title: Get Tool Schemas Count
          description: Total number of get_tool_schemas calls
        invoke_tools_count:
          type: integer
          title: Invoke Tools Count
          description: Total number of invoke_tools calls
        window:
          type: string
          title: Window
          description: Time window for the data
        filters:
          type: object
          additionalProperties:
            type: string
          title: Filters
          description: Filters applied to the query
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when stats were calculated
      type: object
      required:
      - suggest_tools_count
      - get_tool_schemas_count
      - invoke_tools_count
      - window
      - filters
      - timestamp
      title: ProxyToolEfficiency
      description: Proxy tool counts with optional filters.
    ProxyToolEfficiencyResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the request was successful
        data:
          anyOf:
          - $ref: '#/components/schemas/ProxyToolEfficiency'
          - type: 'null'
          description: Analytics data
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if request failed
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when response was generated
      type: object
      required:
      - success
      - timestamp
      title: ProxyToolEfficiencyResponse
      description: Response model for proxy tool efficiency endpoint.
    ProxyToolSuggestions:
      properties:
        count:
          type: integer
          title: Count
          description: Total number of times caylex_tool_suggestions_generated_total metric was recorded
        suggested_tools:
          type: integer
          title: Suggested Tools
          description: Sum of suggestions_count attribute across all metric records
        window:
          type: string
          title: Window
          description: Time window for the data
        filters:
          type: object
          additionalProperties:
            type: string
          title: Filters
          description: Filters applied to the query
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when stats were calculated
      type: object
      required:
      - count
      - suggested_tools
      - window
      - filters
      - timestamp
      title: ProxyToolSuggestions
      description: Proxy tool suggestions data with optional filters.
    ProxyToolSuggestionsResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the request was successful
        data:
          anyOf:
          - $ref: '#/components/schemas/ProxyToolSuggestions'
          - type: 'null'
          description: Analytics data
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if request failed
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when response was generated
      type: object
      required:
      - success
      - timestamp
      title: ProxyToolSuggestionsResponse
      description: Response model for proxy tool suggestions endpoint.
    ToolPermissionMode:
      type: string
      enum:
        - always_execute
        - require_approval
        - disabled
      title: ToolPermissionMode
    ToolPermissionItem:
      properties:
        tool_id:
          type: string
          format: uuid
          title: Tool Id
        tool_name:
          type: string
          title: Tool Name
        server_id:
          type: string
          format: uuid
          title: Server Id
        server_name:
          type: string
          title: Server Name
        logo_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Logo Url
        mode:
          $ref: '#/components/schemas/ToolPermissionMode'
        impact_level:
          anyOf:
            - type: string
            - type: 'null'
          title: Impact Level
        enabled:
          type: boolean
          title: Enabled
          description: >-
            Deprecated: use `mode` instead. True when mode != disabled.
      type: object
      required:
      - tool_id
      - tool_name
      - server_id
      - server_name
      - mode
      title: ToolPermissionItem
    TraceGetSchema:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        tool:
          $ref: '#/components/schemas/TraceTool'
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - tool
      - created_at
      title: TraceGetSchema
    TraceServerMetadata:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
      type: object
      required:
      - id
      - name
      title: TraceServerMetadata
    TraceSuggestTools:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - created_at
      title: TraceSuggestTools
    TraceTool:
      properties:
        server:
          $ref: '#/components/schemas/TraceServerMetadata'
        name:
          type: string
          title: Name
      type: object
      required:
      - server
      - name
      title: TraceTool
    TraceToolCall:
      properties:
        server_instance_id:
          type: string
          format: uuid
          title: Server Instance Id
        tool:
          $ref: '#/components/schemas/TraceTool'
        latency:
          anyOf:
          - type: number
          - type: 'null'
          title: Latency
        success:
          type: boolean
          title: Success
        error_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Message
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - server_instance_id
      - tool
      - latency
      - success
      - error_message
      - created_at
      title: TraceToolCall
    TraceToolCallGroup:
      properties:
        tool_calls:
          items:
            $ref: '#/components/schemas/TraceToolCall'
          type: array
          title: Tool Calls
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - tool_calls
      - created_at
      title: TraceToolCallGroup
    UpdateNavigatorConnectionsRequest:
      properties:
        project_ids:
          items:
            type: string
            format: uuid
          type: array
          title: Project Ids
          description: List of project IDs to connect to this navigator
      type: object
      required:
      - project_ids
      title: UpdateNavigatorConnectionsRequest
    UpdateNavigatorRequest:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
      additionalProperties: false
      type: object
      title: UpdateNavigatorRequest
    UpdateApiKeyRequest:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
      type: object
      title: UpdateApiKeyRequest
    UpdateProjectRequest:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        icon:
          anyOf:
          - type: string
          - type: 'null'
          title: Icon
        webhook_config:
          anyOf:
          - type: array
            items:
              type: object
              additionalProperties: true
            maxItems: 5
          - type: 'null'
          title: Webhook Config
          description: "Array of webhook configurations (max 5). Each item schema: {url: str, secret: str | None, events: list[str], enabled: bool, service: str ('generic' | 'slack', default: 'generic')}"
      type: object
      title: UpdateProjectRequest
    CloneServerRequest:
      properties:
        name:
          type: string
          title: Name
          description: Name for the cloned server. Used as both name and display_name.
        endpoint:
          anyOf:
          - type: string
          - type: 'null'
          title: Endpoint
          description: Optional endpoint for the cloned server. If omitted, the
            original server's endpoint is used.
      type: object
      required:
      - name
      title: CloneServerRequest
    PatchOAuthConfig:
      description: |
        OAuth config update. Same shape as POST (AddExternalOAuthServerRequest) for credentials;
        manual_client_config null = use Caylex; set = manual client_id and client_secret.
        When null, stored provider is "caylex" if server has a registry with OAuth config (pre-configured),
        otherwise "dcr" (Dynamic Client Registration). Optional scopes replace stored scopes (triggers revoke).
      properties:
        manual_client_config:
          anyOf:
          - $ref: '#/components/schemas/ManualClientConfig'
          - type: 'null'
          title: Manual Client Config
          description: Null = switch to Caylex (DCR). Set = use/update manual credentials (same as POST).
        scopes:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Scopes
          description: Optional OAuth2 scopes; when provided, replaces stored scopes (triggers revoke).
      type: object
      required:
      - manual_client_config
      title: PatchOAuthConfig
    PatchServerRequest:
      description: |
        Request body for PATCH /servers/{server_id}. All fields optional. Auth config shape matches POST.
        - name: update server name.
        - endpoint: MCP server URL (external header/path/query only).
        - oauth_config: same as POST /servers/oauth; manual_client_config null = Caylex (provider "caylex" from registry or "dcr"), set = manual.
        - scopes: OAuth2 scopes (OAuth servers only); top-level convenience, replaces stored scopes (triggers revoke).
        - headers / paths / params: same as POST /servers/header, /servers/path, /servers/query.
        - auth_level: credentials level (user or project).
        - display_name: display name only (no normalization).
        - logo_url: logo path returned by POST /servers/upload-logo. Send a non-empty string to set, "" to clear, or omit to leave unchanged.
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: Server name (normalized); also sets display_name if different
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
          description: Display name only (no name normalization)
        endpoint:
          anyOf:
          - type: string
          - type: 'null'
          title: Endpoint
          description: MCP server URL (external header/path/query servers only)
        oauth_config:
          anyOf:
          - $ref: '#/components/schemas/PatchOAuthConfig'
          - type: 'null'
          title: Oauth Config
          description: OAuth credentials update (same shape as POST). manual_client_config null = Caylex, set = manual.
        scopes:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Scopes
          description: OAuth2 scopes (OAuth servers only). Replaces stored scopes; triggers revoke. Top-level convenience.
        headers:
          anyOf:
          - items:
              $ref: '#/components/schemas/HeaderConfig'
            type: array
          - type: 'null'
          title: Headers
          description: Header auth config (same as POST /servers/header)
        paths:
          anyOf:
          - items:
              $ref: '#/components/schemas/PathConfig'
            type: array
          - type: 'null'
          title: Paths
          description: Path auth config (same as POST /servers/path)
        params:
          anyOf:
          - items:
              $ref: '#/components/schemas/QueryConfig'
            type: array
          - type: 'null'
          title: Params
          description: Query param auth config (same as POST /servers/query)
        auth_level:
          anyOf:
          - $ref: '#/components/schemas/AuthLevel'
          - type: 'null'
          title: Auth Level
          description: Credentials level (user or project)
        logo_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Logo Url
          description: Logo path returned by POST /servers/upload-logo. Send a non-empty string to set, "" to clear, or omit to leave unchanged.
      type: object
      title: PatchServerRequest
    UpdateServerConnectionsRequest:
      properties:
        project_ids:
          items:
            type: string
            format: uuid
          type: array
          title: Project Ids
      type: object
      required:
      - project_ids
      title: UpdateServerConnectionsRequest
    UpdateToolPermissionRequest:
      properties:
        tool_id:
          type: string
          format: uuid
          title: Tool Id
        mode:
          anyOf:
            - $ref: '#/components/schemas/ToolPermissionMode'
            - type: 'null'
          description: >-
            Preferred new field. If provided, takes precedence over `enabled`.
        enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Enabled
          description: >-
            Deprecated legacy boolean. Accepted for backward compatibility.
            Mapped to mode as: true -> always_execute, false -> disabled.
      type: object
      required:
      - tool_id
      title: UpdateToolPermissionRequest
      description: >-
        Either `mode` or `enabled` must be provided. `mode` is the preferred
        field; `enabled` is kept for backward compatibility during rollout.
    UpdateToolPermissionsRequest:
      properties:
        permissions:
          items:
            $ref: '#/components/schemas/UpdateToolPermissionRequest'
          type: array
          title: Permissions
          description: List of tool permissions to update
      type: object
      required:
      - permissions
      title: UpdateToolPermissionsRequest
    UploadAnalysisResponse:
      properties:
        session_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Session Id
        analysis_result:
          additionalProperties: true
          type: object
          title: Analysis Result
        message:
          type: string
          title: Message
      type: object
      required:
      - session_id
      - analysis_result
      - message
      title: UploadAnalysisResponse
      description: Response from OpenAPI spec upload and analysis
    UploadLogoResponse:
      properties:
        logo_url:
          type: string
          title: Logo Url
      type: object
      required:
      - logo_url
      title: UploadLogoResponse
    UploadAvatarResponse:
      properties:
        avatar_url:
          type: string
          title: Avatar Url
          description: Public URL of the uploaded avatar
      type: object
      required:
      - avatar_url
      title: UploadAvatarResponse
    UnreadCountResponse:
      properties:
        count:
          type: integer
          title: Count
      type: object
      required:
      - count
      title: UnreadCountResponse
      description: Unread notification count for the calling user.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ViewType:
      type: string
      enum:
      - timeseries
      - bar
      - pie
      - heatmap
      title: ViewType
      description: View type for graph analytics.
    # Invite-related schemas
    OAuthServer:
      properties:
        name:
          type: string
          title: Name
        id:
          type: string
          format: uuid
          title: Id
        descope_outbound_app_id:
          type: string
          title: Descope Outbound App Id
      type: object
      required:
      - name
      - id
      - descope_outbound_app_id
      title: OAuthServer
    InviteHeaderConfig:
      properties:
        name:
          type: string
          title: Name
        prefix:
          anyOf:
          - type: string
          - type: 'null'
          title: Prefix
      type: object
      required:
      - name
      title: InviteHeaderConfig
    HeaderServer:
      properties:
        name:
          type: string
          title: Name
        id:
          type: string
          format: uuid
          title: Id
        headers:
          items:
            $ref: '#/components/schemas/InviteHeaderConfig'
          type: array
          title: Headers
      type: object
      required:
      - name
      - id
      - headers
      title: HeaderServer
    InvitePathConfig:
      properties:
        name:
          type: string
          title: Name
      type: object
      required:
      - name
      title: InvitePathConfig
    PathServer:
      properties:
        name:
          type: string
          title: Name
        id:
          type: string
          format: uuid
          title: Id
        paths:
          items:
            $ref: '#/components/schemas/InvitePathConfig'
          type: array
          title: Paths
      type: object
      required:
      - name
      - id
      - paths
      title: PathServer
    InviteConfigResponse:
      properties:
        tenant_name:
          type: string
          title: Tenant Name
        auth_scope:
          $ref: '#/components/schemas/InviteLinkType'
        oauth_servers:
          items:
            $ref: '#/components/schemas/OAuthServer'
          type: array
          title: Oauth Servers
        header_servers:
          items:
            $ref: '#/components/schemas/HeaderServer'
          type: array
          title: Header Servers
        path_servers:
          items:
            $ref: '#/components/schemas/PathServer'
          type: array
          title: Path Servers
      type: object
      required:
      - tenant_name
      - auth_scope
      - oauth_servers
      - header_servers
      - path_servers
      title: InviteConfigResponse
    InviteMetadataResponse:
      properties:
        tenant_name:
          type: string
          title: Tenant Name
        project_name:
          type: string
          title: Project Name
        expires_at:
          type: string
          format: date-time
          title: Expires At
        auth_link_type:
          type: string
          title: Auth Link Type
          description: Type of invite link - 'user' or 'project'
        valid_for:
          anyOf:
          - type: array
            items:
              type: string
            title: Valid For
          - type: 'null'
          description: List of valid_for values (e.g., ['caylex.ai'] for USER links or ['user@example.com'] for PROJECT links). None means no restrictions.
      type: object
      required:
      - tenant_name
      - project_name
      - expires_at
      - auth_link_type
      title: InviteMetadataResponse
    InviteCompleteResponse:
      properties:
        is_new_user:
          type: boolean
          title: Is New User
        user_token:
          anyOf:
          - type: string
          - type: 'null'
          title: User Token
      type: object
      required:
      - is_new_user
      title: InviteCompleteResponse
    HeaderPair:
      properties:
        header_id:
          type: string
          format: uuid
          title: Header Id
        header_name:
          type: string
          title: Header Name
        header_value:
          type: string
          title: Header Value
      type: object
      required:
      - header_id
      - header_name
      - header_value
      title: HeaderPair
    PathPair:
      properties:
        path_id:
          type: string
          format: uuid
          title: Path Id
        path_name:
          type: string
          title: Path Name
        path_value:
          type: string
          title: Path Value
      type: object
      required:
      - path_id
      - path_name
      - path_value
      title: PathPair
    AuthorizedOAuthServer:
      properties:
        name:
          type: string
          title: Name
        server_id:
          type: string
          format: uuid
          title: Server Id
        server_instance_id:
          type: string
          format: uuid
          title: Server Instance Id
      type: object
      required:
      - name
      - server_id
      - server_instance_id
      title: AuthorizedOAuthServer
    AuthorizedHeaderServer:
      properties:
        name:
          type: string
          title: Name
        server_id:
          type: string
          format: uuid
          title: Server Id
        server_instance_id:
          type: string
          format: uuid
          title: Server Instance Id
        headers:
          items:
            $ref: '#/components/schemas/HeaderPair'
          type: array
          title: Headers
      type: object
      required:
      - name
      - server_id
      - server_instance_id
      - headers
      title: AuthorizedHeaderServer
    AuthorizedPathServer:
      properties:
        name:
          type: string
          title: Name
        server_id:
          type: string
          format: uuid
          title: Server Id
        server_instance_id:
          type: string
          format: uuid
          title: Server Instance Id
        paths:
          items:
            $ref: '#/components/schemas/PathPair'
          type: array
          title: Paths
      type: object
      required:
      - name
      - server_id
      - server_instance_id
      - paths
      title: AuthorizedPathServer
    CompleteInviteRequest:
      properties:
        auth_link_id:
          type: string
          format: uuid
          title: Auth Link Id
        user_email:
          type: string
          title: User Email
        descope_user_id:
          type: string
          title: Descope User Id
        oauth_servers:
          items:
            $ref: '#/components/schemas/AuthorizedOAuthServer'
          type: array
          title: Oauth Servers
        header_servers:
          items:
            $ref: '#/components/schemas/AuthorizedHeaderServer'
          type: array
          title: Header Servers
        path_servers:
          items:
            $ref: '#/components/schemas/AuthorizedPathServer'
          type: array
          title: Path Servers
      type: object
      required:
      - auth_link_id
      - user_email
      - descope_user_id
      - oauth_servers
      - header_servers
      - path_servers
      title: CompleteInviteRequest
    GetServerToolResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        added_context:
          anyOf:
          - type: string
          - type: 'null'
          title: Added Context
        input_schema:
          anyOf:
          - type: object
          - type: 'null'
          title: Input Schema
      type: object
      required:
      - id
      - name
      title: GetServerToolResponse
    PatchServerToolRequest:
      properties:
        added_context:
          anyOf:
          - type: string
          - type: 'null'
          title: Added Context
      type: object
      title: PatchServerToolRequest
    PatchServerToolResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        added_context:
          anyOf:
          - type: string
          - type: 'null'
          title: Added Context
      type: object
      required:
      - id
      title: PatchServerToolResponse
    GetServerToolsResponse:
      properties:
        tools:
          items:
            $ref: '#/components/schemas/GetServerToolResponse'
          type: array
          title: Tools
      type: object
      required:
      - tools
      title: GetServerToolsResponse
    ServerRegistryToolResponse:
      properties:
        name:
          type: string
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
      type: object
      required:
      - name
      title: ServerRegistryToolResponse
      description: Tool name and description for server-registry tools endpoint
    GetServerRegistryToolsResponse:
      properties:
        tools:
          items:
            $ref: '#/components/schemas/ServerRegistryToolResponse'
          type: array
          title: Tools
      type: object
      required:
      - tools
      title: GetServerRegistryToolsResponse
      description: Response for GET /server-registry/{id}/tools
    ServerInstanceToolResponse:
      properties:
        name:
          type: string
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        input_schema:
          anyOf:
          - type: object
          - type: 'null'
          title: Input Schema
      type: object
      required:
      - name
      title: ServerInstanceToolResponse
      description: Tool name, description and input_schema for server instance tools endpoint
    GetServerInstanceToolsResponse:
      properties:
        tools:
          items:
            $ref: '#/components/schemas/ServerInstanceToolResponse'
          type: array
          title: Tools
      type: object
      required:
      - tools
      title: GetServerInstanceToolsResponse
      description: Response for GET /server-instances/{id}/tools
    GeneralSettingsResponse:
      properties:
        name:
          type: string
          title: Name
          description: User's display name
        role:
          type: string
          enum:
          - admin
          - user
          title: Role
          description: User's role in the tenant
        email:
          type: string
          title: Email
          description: User's email address
        timezone:
          type: string
          title: Timezone
          description: User's timezone (defaults to UTC)
        tenant_name:
          type: string
          title: Tenant Name
          description: Name of the tenant the user belongs to
        tenant_id:
          type: string
          format: uuid
          title: Tenant Id
          description: ID of the tenant the user belongs to
        avatar_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Avatar Url
          description: Public URL of the user's avatar image, if set
      type: object
      required:
      - name
      - role
      - email
      - timezone
      - tenant_name
      - tenant_id
      title: GeneralSettingsResponse
    UpdateGeneralSettingsRequest:
      properties:
        name:
          type: string
          title: Name
          description: User's display name
          maxLength: 100
        timezone:
          type: string
          title: Timezone
          description: User's timezone
          maxLength: 50
      type: object
      required: []
      title: UpdateGeneralSettingsRequest
    PasswordResetResponse:
      properties:
        message:
          type: string
          title: Message
          description: Success message
        email:
          type: string
          title: Email
          description: Email address the reset link was sent to
      type: object
      required:
      - message
      - email
      title: PasswordResetResponse
    ContactRequest:
      properties:
        email:
          type: string
          title: Email
          description: User's email address
          maxLength: 255
        message:
          type: string
          title: Message
          description: Detailed contact message
          maxLength: 5000
      type: object
      required:
      - email
      - message
      title: ContactRequest
    ContactResponse:
      properties:
        message:
          type: string
          title: Message
          description: Success message
        email:
          type: string
          title: Email
          description: Email address the contact message was sent from
      type: object
      required:
      - message
      - email
      title: ContactResponse
    UserServerAuthentication:
      properties:
        server_instance_id:
          type: string
          format: uuid
          title: Server Instance Id
        authenticated_at:
          type: string
          format: date-time
          title: Authenticated At
          description: When the user authenticated to this server
        current_auth_link:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Current Auth Link
          description: The invite link ID currently active for this server instance and user token (from user_server_authentication table). Null if no active authentication exists.
      type: object
      required:
      - server_instance_id
      - authenticated_at
      title: UserServerAuthentication
      description: Server that a user has authenticated to with timestamp.
    UserAuthenticationDetails:
      properties:
        user_email:
          type: string
          title: User Email
        authenticated_servers:
          items:
            $ref: '#/components/schemas/UserServerAuthentication'
          type: array
          title: Authenticated Servers
          description: List of servers this user has authenticated to
      type: object
      required:
      - user_email
      - authenticated_servers
      title: UserAuthenticationDetails
      description: User authentication details with list of servers they authenticated to.
    Page_UserAuthenticationDetails_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/UserAuthenticationDetails'
          type: array
          title: Items
        meta:
          $ref: '#/components/schemas/PageMeta'
      type: object
      required:
      - items
      - meta
      title: Page[UserAuthenticationDetails]
    UserAuthServerItem:
      properties:
        server_instance_id:
          type: string
          format: uuid
          title: Server Instance Id
          description: Server instance ID for API operations like revoke
        server_name:
          type: string
          title: Server Name
        logo_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Logo Url
        auth_method:
          $ref: '#/components/schemas/ServerAuthMethod'
        authenticated_at:
          type: string
          format: date-time
          title: Authenticated At
          description: When the user authenticated to this server
      type: object
      required:
      - server_instance_id
      - server_name
      - auth_method
      - authenticated_at
      title: UserAuthServerItem
      description: Single server auth record for a user
    UserAuthDetails:
      properties:
        user_email:
          type: string
          title: User Email
        servers:
          items:
            $ref: '#/components/schemas/UserAuthServerItem'
          type: array
          title: Servers
          description: All servers this user has authenticated to
      type: object
      required:
      - user_email
      - servers
      title: UserAuthDetails
      description: Detailed auth info for one user
    UserSummary:
      properties:
        user_email:
          type: string
          title: User Email
        user_token_id:
          type: string
          format: uuid
          title: User Token Id
          description: Internal ID for API calls (not displayed to user)
        authenticated_servers_count:
          type: integer
          title: Authenticated Servers Count
        total_project_server_instances:
          type: integer
          title: Total Project Server Instances
          description: Total number of server instances in this project
        server_logos:
          items:
            anyOf:
            - type: string
            - type: 'null'
          type: array
          title: Server Logos
          description: Server logo URLs for avatar preview
        last_authentication_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Authentication At
          description: Most recent authentication timestamp
        weekly_queries:
          type: integer
          default: 0
          title: Weekly Queries
          description: Number of queries in past 7 days
        weekly_tool_calls:
          type: integer
          default: 0
          title: Weekly Tool Calls
          description: Number of tool calls in past 7 days
      type: object
      required:
      - user_email
      - user_token_id
      - authenticated_servers_count
      - total_project_server_instances
      - server_logos
      title: UserSummary
      description: Summary row for users table with auth status and activity metrics
    Page_UserSummary_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/UserSummary'
          type: array
          title: Items
        meta:
          $ref: '#/components/schemas/PageMeta'
      type: object
      required:
      - items
      - meta
      title: Page[UserSummary]
    RevokeUserAccessRequest:
      properties:
        server_instance_ids:
          items:
            type: string
            format: uuid
          type: array
          minItems: 1
          title: Server Instance Ids
          description: List of server instance IDs to revoke access for
      type: object
      required:
      - server_instance_ids
      title: RevokeUserAccessRequest
      description: Request model for revoking user access to specific server instances
    RevokeUserAccessResponse:
      properties:
        revoked_server_instance_ids:
          items:
            type: string
            format: uuid
          type: array
          title: Revoked Server Instance Ids
          description: List of server instance IDs that were successfully revoked
        deleted_auth_count:
          type: integer
          title: Deleted Auth Count
          description: Number of authentication records deleted from the database
        descope_tokens_revoked:
          type: integer
          title: Descope Tokens Revoked
          description: Number of OAuth tokens revoked from Descope
      type: object
      required:
      - revoked_server_instance_ids
      - deleted_auth_count
      - descope_tokens_revoked
      title: RevokeUserAccessResponse
      description: Response model for revoking user access
    ModifiedUserResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: ID of the deleted user
      type: object
      required:
      - id
      title: ModifiedUserResponse
      description: Response model for user deletion
    UserbaseSummary:
      properties:
        total_users:
          type: integer
          title: Total Users
        weekly_active_users:
          type: integer
          title: Weekly Active Users
        monthly_active_users:
          type: integer
          title: Monthly Active Users
        inactive_users:
          type: integer
          title: Inactive Users
        wau_timeline:
          items:
            $ref: '#/components/schemas/TimeSeriesPoint'
          type: array
          title: Wau Timeline
        window:
          type: string
          title: Window
        calculated_at:
          type: string
          format: date-time
          title: Calculated At
      type: object
      required:
      - total_users
      - weekly_active_users
      - monthly_active_users
      - inactive_users
      - wau_timeline
      - window
      - calculated_at
      title: UserbaseSummary
    UserbaseSummaryResponse:
      properties:
        success:
          type: boolean
          title: Success
        data:
          $ref: '#/components/schemas/UserbaseSummary'
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        timestamp:
          type: string
          format: date-time
          title: Timestamp
      type: object
      required:
      - success
      - data
      - timestamp
      title: UserbaseSummaryResponse
    UserAnalytics:
      properties:
        user_email:
          type: string
          title: User Email
        user_token_id:
          type: string
          format: uuid
          title: User Token Id
        total_queries:
          type: integer
          title: Total Queries
        total_tool_calls:
          type: integer
          title: Total Tool Calls
        avg_tool_calls_per_query:
          type: number
          title: Avg Tool Calls Per Query
        top_navigators:
          items:
            $ref: '#/components/schemas/NavigatorUsageItem'
          type: array
          title: Top Navigators
        top_tools:
          items:
            $ref: '#/components/schemas/ToolUsageItem'
          type: array
          title: Top Tools
        top_servers:
          items:
            $ref: '#/components/schemas/ServerUsageItem'
          type: array
          title: Top Servers
        queries_timeline:
          items:
            $ref: '#/components/schemas/TimeSeriesPoint'
          type: array
          title: Queries Timeline
        tool_calls_timeline:
          items:
            $ref: '#/components/schemas/TimeSeriesPoint'
          type: array
          title: Tool Calls Timeline
        error_rate_data:
          $ref: '#/components/schemas/ErrorRateData'
        error_types_data:
          $ref: '#/components/schemas/ErrorTypesData'
        window:
          type: string
          title: Window
        frequency:
          type: string
          title: Frequency
        calculated_at:
          type: string
          format: date-time
          title: Calculated At
      type: object
      required:
      - user_email
      - user_token_id
      - total_queries
      - total_tool_calls
      - avg_tool_calls_per_query
      - top_navigators
      - top_tools
      - top_servers
      - queries_timeline
      - tool_calls_timeline
      - error_rate_data
      - error_types_data
      - window
      - frequency
      - calculated_at
      title: UserAnalytics
    UserAnalyticsResponse:
      properties:
        success:
          type: boolean
          title: Success
        data:
          $ref: '#/components/schemas/UserAnalytics'
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        timestamp:
          type: string
          format: date-time
          title: Timestamp
      type: object
      required:
      - success
      - data
      - timestamp
      title: UserAnalyticsResponse
    TimeSeriesPoint:
      properties:
        timestamp:
          type: string
          title: Timestamp
          description: ISO 8601 timestamp
        value:
          anyOf:
          - type: integer
          - type: number
          title: Value
          description: Metric value at this timestamp
      type: object
      required:
      - timestamp
      - value
      title: TimeSeriesPoint
      description: Single time series data point
    NavigatorUsageItem:
      properties:
        navigator_instance_id:
          type: string
          format: uuid
          title: Navigator Instance Id
          description: Navigator instance ID
        navigator_name:
          type: string
          title: Navigator Name
          description: Human-readable navigator name
        tool_count:
          type: integer
          title: Tool Count
          description: Number of tool calls to this navigator
      type: object
      required:
      - navigator_instance_id
      - navigator_name
      - tool_count
      title: NavigatorUsageItem
      description: Navigator usage statistics for a specific user
    ToolUsageItem:
      properties:
        tool_name:
          type: string
          title: Tool Name
          description: Tool name
        server_name:
          type: string
          title: Server Name
          description: Server providing the tool
        call_count:
          type: integer
          title: Call Count
          description: Number of calls to this tool
      type: object
      required:
      - tool_name
      - server_name
      - call_count
      title: ToolUsageItem
      description: Tool usage statistics
    ServerUsageItem:
      properties:
        server_name:
          type: string
          title: Server Name
          description: Server name
        tool_count:
          type: integer
          title: Tool Count
          description: Total tool calls to this server
      type: object
      required:
      - server_name
      - tool_count
      title: ServerUsageItem
      description: Server usage statistics
    ErrorRateData:
      properties:
        average_error_rate:
          type: number
          title: Average Error Rate
          description: Average error rate as percentage
        total_errors:
          type: integer
          title: Total Errors
          description: Total number of errors
        total_tool_calls:
          type: integer
          title: Total Tool Calls
          description: Total number of tool calls
        time_series_data:
          items:
            type: object
          type: array
          title: Time Series Data
          description: Time series data points with timestamps and values
      type: object
      required:
      - average_error_rate
      - total_errors
      - total_tool_calls
      - time_series_data
      title: ErrorRateData
      description: Error rate metrics with time series data
    ErrorTypesData:
      properties:
        view_type:
          type: string
          title: View Type
          description: View type (timeseries, bar, etc.)
        frequency:
          type: string
          title: Frequency
          description: Data point frequency
        total_errors:
          type: integer
          title: Total Errors
          description: Total errors across all types
        time_series_data:
          items:
            type: object
          type: array
          title: Time Series Data
          description: Error type breakdown with time series
      type: object
      required:
      - view_type
      - frequency
      - total_errors
      - time_series_data
      title: ErrorTypesData
      description: Error types breakdown with time series data