definitions:
  APIKey:
    properties:
      created_at:
        type: string
      expires_at:
        type: string
      id:
        type: string
      key:
        type: string
      last_used_at:
        type: string
      name:
        type: string
      user_id:
        type: string
    type: object
  AWSCredentialStatus:
    properties:
      available:
        type: boolean
      error:
        type: string
      sources:
        items:
          type: string
        type: array
    type: object
  ActivityResponse:
    properties:
      buckets:
        items:
          $ref: '#/definitions/Bucket'
        type: array
    type: object
  AddDataProductAssetsRequest:
    properties:
      asset_ids:
        items:
          type: string
        minItems: 1
        type: array
    required:
      - asset_ids
    type: object
  AddMemberRequest:
    properties:
      role:
        type: string
      user_id:
        type: string
    type: object
  AddTermsRequest:
    properties:
      term_ids:
        items:
          type: string
        minItems: 1
        type: array
    required:
      - term_ids
    type: object
  AgentRun:
    properties:
      agent_id:
        type: string
      created_at:
        type: string
      duration_ms:
        type: integer
      ended_at:
        type: string
      error:
        type: string
      id:
        type: string
      model:
        type: string
      run_id:
        type: string
      started_at:
        type: string
      status:
        type: string
      tokens_in:
        type: integer
      tokens_out:
        type: integer
      tool_calls:
        items:
          $ref: '#/definitions/ToolCall'
        type: array
    type: object
  AggregatedMetric:
    properties:
      aggregation_type:
        type: string
      bucket_end:
        type: string
      bucket_size:
        type: integer
      bucket_start:
        type: string
      labels:
        additionalProperties:
          type: string
        type: object
      name:
        type: string
      value:
        type: number
    type: object
  Asset:
    properties:
      created_at:
        type: string
      created_by:
        type: string
      description:
        type: string
      environments:
        additionalProperties:
          $ref: '#/definitions/Environment'
        type: object
      external_links:
        items:
          $ref: '#/definitions/AssetExternalLink'
        type: array
      has_run_history:
        type: boolean
      id:
        type: string
      is_stub:
        type: boolean
      last_sync_at:
        type: string
      metadata:
        additionalProperties: true
        type: object
      mrn:
        type: string
      name:
        type: string
      parent_mrn:
        type: string
      providers:
        items:
          type: string
        type: array
      query:
        type: string
      query_language:
        type: string
      schema:
        additionalProperties:
          type: string
        type: object
      sources:
        items:
          $ref: '#/definitions/AssetSource'
        type: array
      tags:
        items:
          type: string
        type: array
      terms:
        description: |-
          Terms carries glossary term names a discovery assigned to this
          asset. It is input only: the links live in asset_terms, so reading
          an asset back from the database never fills this in.
        items:
          type: string
        type: array
      type:
        type: string
      updated_at:
        type: string
      user_description:
        type: string
    type: object
  AssetCount:
    properties:
      asset_id:
        type: string
      asset_name:
        type: string
      asset_provider:
        type: string
      asset_type:
        type: string
      count:
        type: integer
    type: object
  AssetExternalLink:
    properties:
      icon:
        type: string
      name:
        type: string
      url:
        type: string
    type: object
  AssetRule:
    properties:
      created_at:
        type: string
      created_by:
        type: string
      description:
        type: string
      id:
        type: string
      is_enabled:
        type: boolean
      last_reconciled_at:
        type: string
      links:
        items:
          $ref: '#/definitions/AssetRuleExternalLink'
        type: array
      membership_count:
        type: integer
      metadata_field:
        type: string
      name:
        type: string
      pattern_type:
        type: string
      pattern_value:
        type: string
      priority:
        type: integer
      query_expression:
        type: string
      reconciliation_hash:
        type: string
      rule_type:
        $ref: '#/definitions/RuleType'
      term_ids:
        items:
          type: string
        type: array
      updated_at:
        type: string
    type: object
  AssetRuleExternalLink:
    properties:
      icon:
        type: string
      name:
        type: string
      url:
        type: string
    type: object
  AssetRuleListResult:
    properties:
      asset_rules:
        items:
          $ref: '#/definitions/AssetRule'
        type: array
      total:
        type: integer
    type: object
  AssetSearchResponse:
    properties:
      assets:
        items:
          $ref: '#/definitions/Asset'
        type: array
      filters:
        $ref: '#/definitions/AvailableFilters'
      limit:
        type: integer
      offset:
        type: integer
      total:
        type: integer
    type: object
  AssetSource:
    properties:
      last_sync_at:
        type: string
      name:
        type: string
      priority:
        type: integer
      properties:
        additionalProperties: true
        type: object
    type: object
  AssetSummaryResponse:
    properties:
      providers:
        additionalProperties:
          type: integer
        type: object
      tags:
        additionalProperties:
          type: integer
        type: object
      types:
        additionalProperties:
          $ref: '#/definitions/AssetTypeSummary'
        type: object
    type: object
  AssetTerm:
    properties:
      created_at:
        type: string
      created_by:
        type: string
      created_by_username:
        type: string
      definition:
        type: string
      source:
        description: '"user" or "plugin:name"'
        type: string
      term_id:
        type: string
      term_name:
        type: string
    type: object
  AssetTypeSummary:
    properties:
      count:
        type: integer
      service:
        type: string
    type: object
  AssetsByOwnerResponse:
    properties:
      assets:
        additionalProperties:
          format: int64
          type: integer
        type: object
    type: object
  AssetsByProviderResponse:
    properties:
      assets:
        additionalProperties:
          format: int64
          type: integer
        type: object
    type: object
  AssetsByTypeResponse:
    properties:
      assets:
        additionalProperties:
          format: int64
          type: integer
        type: object
    type: object
  AssetsWithSchemasResponse:
    properties:
      count:
        type: integer
      percentage:
        type: number
      total:
        type: integer
    type: object
  AuthConfig:
    properties:
      enabled_providers:
        items:
          type: string
        type: array
    type: object
  AvailableFilters:
    properties:
      providers:
        additionalProperties:
          type: integer
        type: object
      tags:
        additionalProperties:
          type: integer
        type: object
      types:
        additionalProperties:
          type: integer
        type: object
    type: object
  BannerResponse:
    properties:
      dismissible:
        type: boolean
      enabled:
        type: boolean
      id:
        type: string
      message:
        type: string
      variant:
        type: string
    type: object
  BatchAssetResult:
    properties:
      asset: {}
      error:
        type: string
      mrn:
        type: string
      name:
        type: string
      provider:
        type: string
      status:
        type: string
      type:
        type: string
    type: object
  BatchCreateRequest:
    properties:
      assets:
        items:
          $ref: '#/definitions/RunCreateAssetRequest'
        minItems: 1
        type: array
      config:
        $ref: '#/definitions/RawPluginConfig'
      documentation:
        items:
          $ref: '#/definitions/CreateDocRequest'
        type: array
      glossary_terms:
        items:
          $ref: '#/definitions/CreateGlossaryTermRequest'
        type: array
      lineage:
        items:
          $ref: '#/definitions/CreateLineageRequest'
        type: array
      pipeline_name:
        type: string
      run_history:
        items:
          $ref: '#/definitions/CreateRunHistoryRequest'
        type: array
      run_id:
        type: string
      source_name:
        type: string
      statistics:
        items:
          $ref: '#/definitions/CreateStatRequest'
        type: array
    required:
      - assets
      - pipeline_name
      - run_id
      - source_name
    type: object
  BatchCreateResponse:
    properties:
      assets:
        items:
          $ref: '#/definitions/BatchAssetResult'
        type: array
      documentation:
        items:
          $ref: '#/definitions/DocumentationResult'
        type: array
      lineage:
        items:
          $ref: '#/definitions/LineageResult'
        type: array
      stale_entities_removed:
        items:
          type: string
        type: array
    type: object
  BatchDocumentationRequest:
    properties:
      documentation:
        items:
          $ref: '#/definitions/Documentation'
        minItems: 1
        type: array
    required:
      - documentation
    type: object
  BatchDocumentationResponse:
    properties:
      results:
        items:
          $ref: '#/definitions/BatchDocumentationResult'
        type: array
    type: object
  BatchDocumentationResult:
    properties:
      documentation:
        $ref: '#/definitions/Documentation'
      error:
        type: string
      status:
        type: string
    type: object
  BatchLineageResult:
    properties:
      edge:
        $ref: '#/definitions/LineageEdge'
      status:
        description: '"created", "duplicate", or "existing"'
        type: string
    type: object
  Bucket:
    properties:
      error:
        type: integer
      hour:
        type: string
      success:
        type: integer
    type: object
  CompleteRunRequest:
    properties:
      error:
        type: string
      run_id:
        type: string
      status:
        $ref: '#/definitions/RunStatus'
      summary:
        $ref: '#/definitions/RunSummary'
    required:
      - run_id
      - status
    type: object
  CreateAPIKeyRequest:
    properties:
      expires_in_days:
        type: integer
      name:
        type: string
    required:
      - name
    type: object
  CreateAssetRequest:
    properties:
      description:
        type: string
      environments:
        additionalProperties:
          $ref: '#/definitions/Environment'
        type: object
      external_links:
        items:
          $ref: '#/definitions/AssetExternalLink'
        type: array
      metadata:
        additionalProperties: true
        type: object
      name:
        type: string
      providers:
        items:
          type: string
        type: array
      schema:
        additionalProperties:
          type: string
        type: object
      sources:
        items:
          $ref: '#/definitions/AssetSource'
        type: array
      tags:
        items:
          type: string
        type: array
      type:
        type: string
    required:
      - name
      - providers
      - type
    type: object
  CreateAssetRuleRequest:
    properties:
      description:
        type: string
      is_enabled:
        type: boolean
      links:
        items:
          $ref: '#/definitions/AssetRuleExternalLink'
        type: array
      metadata_field:
        type: string
      name:
        type: string
      pattern_type:
        type: string
      pattern_value:
        type: string
      priority:
        type: integer
      query_expression:
        type: string
      rule_type:
        type: string
      term_ids:
        items:
          type: string
        type: array
    type: object
  CreateDataProductRequest:
    properties:
      description:
        type: string
      metadata:
        additionalProperties: true
        type: object
      name:
        type: string
      owners:
        items:
          $ref: '#/definitions/DataProductOwnerRequest'
        type: array
      rules:
        items:
          $ref: '#/definitions/DataProductRuleRequest'
        type: array
      tags:
        items:
          type: string
        type: array
    required:
      - name
    type: object
  CreateDocRequest:
    properties:
      asset_mrn:
        type: string
      content:
        type: string
      type:
        type: string
    type: object
  CreateGlossaryTermRequest:
    properties:
      definition:
        type: string
      description:
        type: string
      metadata:
        additionalProperties: true
        type: object
      name:
        type: string
      parent:
        type: string
      synonyms:
        items:
          type: string
        type: array
      tags:
        items:
          type: string
        type: array
    type: object
  CreateLineageRequest:
    properties:
      job_mrn:
        type: string
      source:
        type: string
      target:
        type: string
      type:
        type: string
    type: object
  CreateRunHistoryRequest:
    properties:
      asset_mrn:
        type: string
      event_time:
        type: string
      event_type:
        type: string
      job_facets:
        additionalProperties: true
        type: object
      job_name:
        type: string
      job_namespace:
        type: string
      run_facets:
        additionalProperties: true
        type: object
      run_id:
        type: string
    type: object
  CreateSSOMappingRequest:
    properties:
      member_role:
        type: string
      provider:
        type: string
      sso_group_name:
        type: string
      team_id:
        type: string
    type: object
  CreateScheduleRequest:
    properties:
      config:
        additionalProperties: true
        type: object
      cron_expression:
        type: string
      enabled:
        type: boolean
      name:
        type: string
      plugin_id:
        type: string
    type: object
  CreateServiceAccountAPIKeyRequest:
    properties:
      expires_in_days:
        type: integer
      name:
        type: string
    type: object
  CreateServiceAccountRequest:
    properties:
      description:
        type: string
      name:
        type: string
      role_ids:
        items:
          type: string
        type: array
    type: object
  CreateStatRequest:
    properties:
      asset_mrn:
        type: string
      metric_name:
        type: string
      value:
        type: number
    required:
      - asset_mrn
      - metric_name
      - value
    type: object
  CreateTeamRequest:
    properties:
      description:
        type: string
      name:
        type: string
    type: object
  CreateTermRequest:
    properties:
      definition:
        type: string
      description:
        type: string
      metadata:
        additionalProperties: true
        type: object
      name:
        type: string
      owners:
        items:
          $ref: '#/definitions/OwnerRequest'
        type: array
      parent_term_id:
        type: string
    required:
      - definition
      - name
    type: object
  CreateUserInput:
    properties:
      name:
        type: string
      oauth_provider:
        type: string
      oauth_provider_data:
        additionalProperties: true
        type: object
      oauth_provider_id:
        type: string
      password:
        minLength: 8
        type: string
      profile_picture:
        type: string
      role_names:
        items:
          type: string
        minItems: 1
        type: array
      username:
        maxLength: 255
        minLength: 3
        type: string
    required:
      - name
      - role_names
      - username
    type: object
  DataProduct:
    properties:
      asset_count:
        type: integer
      created_at:
        type: string
      created_by:
        type: string
      description:
        type: string
      icon_url:
        type: string
      id:
        type: string
      manual_asset_count:
        type: integer
      metadata:
        additionalProperties: true
        type: object
      name:
        type: string
      owners:
        items:
          $ref: '#/definitions/DataProductOwner'
        type: array
      rule_asset_count:
        type: integer
      rules:
        items:
          $ref: '#/definitions/DataProductRule'
        type: array
      tags:
        items:
          type: string
        type: array
      updated_at:
        type: string
    type: object
  DataProductAssetsResult:
    properties:
      asset_ids:
        items:
          type: string
        type: array
      total:
        type: integer
    type: object
  DataProductListResult:
    properties:
      data_products:
        items:
          $ref: '#/definitions/DataProduct'
        type: array
      total:
        type: integer
    type: object
  DataProductOwner:
    properties:
      email:
        type: string
      id:
        type: string
      name:
        type: string
      profile_picture:
        type: string
      type:
        type: string
      username:
        type: string
    type: object
  DataProductOwnerRequest:
    properties:
      id:
        type: string
      type:
        enum:
          - user
          - team
        type: string
    required:
      - id
      - type
    type: object
  DataProductResolvedAssets:
    properties:
      all_assets:
        items:
          type: string
        type: array
      dynamic_assets:
        items:
          type: string
        type: array
      manual_assets:
        items:
          type: string
        type: array
      total:
        type: integer
    type: object
  DataProductRule:
    properties:
      created_at:
        type: string
      data_product_id:
        type: string
      description:
        type: string
      id:
        type: string
      is_enabled:
        type: boolean
      matched_asset_count:
        type: integer
      metadata_field:
        type: string
      name:
        type: string
      pattern_type:
        type: string
      pattern_value:
        type: string
      priority:
        type: integer
      query_expression:
        type: string
      rule_type:
        $ref: '#/definitions/DataProductRuleType'
      updated_at:
        type: string
    type: object
  DataProductRulePreview:
    properties:
      asset_count:
        type: integer
      asset_ids:
        items:
          type: string
        type: array
      errors:
        items:
          type: string
        type: array
    type: object
  DataProductRuleRequest:
    properties:
      description:
        type: string
      is_enabled:
        type: boolean
      metadata_field:
        type: string
      name:
        type: string
      pattern_type:
        type: string
      pattern_value:
        type: string
      priority:
        type: integer
      query_expression:
        type: string
      rule_type:
        type: string
    required:
      - name
      - rule_type
    type: object
  DataProductRuleType:
    enum:
      - query
      - metadata_match
    type: string
    x-enum-varnames:
      - RuleTypeQuery
      - RuleTypeMetadataMatch
  DataProductRulesResponse:
    properties:
      rules:
        items:
          $ref: '#/definitions/DataProductRule'
        type: array
      total:
        type: integer
    type: object
  Dataset:
    properties:
      facets:
        additionalProperties: true
        type: object
      inputFacets:
        additionalProperties: true
        type: object
      name:
        type: string
      namespace:
        type: string
      outputFacets:
        additionalProperties: true
        type: object
    type: object
  DestroyRunResponse:
    properties:
      assets_deleted:
        type: integer
      deleted_entity_mrns:
        items:
          type: string
        type: array
      documentation_deleted:
        type: integer
      lineage_deleted:
        type: integer
    type: object
  Documentation:
    properties:
      content:
        type: string
      created_at:
        type: string
      global_docs:
        items:
          type: string
        type: array
      id:
        type: string
      mrn:
        type: string
      source:
        type: string
      updated_at:
        type: string
    type: object
  DocumentationCreateRequest:
    properties:
      content:
        type: string
      mrn:
        type: string
      source:
        type: string
    required:
      - content
      - mrn
      - source
    type: object
  DocumentationResult:
    properties:
      asset_mrn:
        type: string
      error:
        type: string
      status:
        type: string
      type:
        type: string
    type: object
  Environment:
    properties:
      metadata:
        additionalProperties: true
        type: object
      name:
        type: string
      path:
        type: string
    type: object
  ErrorResponse:
    properties:
      error:
        type: string
    type: object
  FacetValue:
    properties:
      count:
        type: integer
      value:
        type: string
    type: object
  Facets:
    properties:
      asset_types:
        items:
          $ref: '#/definitions/FacetValue'
        type: array
      providers:
        items:
          $ref: '#/definitions/FacetValue'
        type: array
      tags:
        items:
          $ref: '#/definitions/FacetValue'
        type: array
      types:
        additionalProperties:
          type: integer
        type: object
    type: object
  GetMetricsRequest:
    properties:
      aggregation:
        type: string
      bucket_size:
        type: string
      end:
        type: string
      labels:
        additionalProperties:
          type: string
        type: object
      metric_names:
        items:
          type: string
        type: array
      start:
        type: string
    type: object
  GetMetricsResponse:
    properties:
      metrics:
        items:
          $ref: '#/definitions/AggregatedMetric'
        type: array
      query:
        $ref: '#/definitions/GetMetricsRequest'
    type: object
  GlossaryListResult:
    properties:
      terms:
        items:
          $ref: '#/definitions/GlossaryTerm'
        type: array
      total:
        type: integer
    type: object
  GlossaryOwner:
    properties:
      email:
        type: string
      id:
        type: string
      name:
        type: string
      profile_picture:
        type: string
      type:
        description: '"user" or "team"'
        type: string
      username:
        description: Only for user owners
        type: string
    type: object
  GlossaryTerm:
    properties:
      created_at:
        type: string
      definition:
        description: |-
          Definition is what the last run wrote. On a term a person has
          worded themselves the read path serves UserDefinition here instead,
          so a caller always gets the wording the catalog stands behind.
        type: string
      deleted_at:
        type: string
      description:
        type: string
      id:
        type: string
      metadata:
        additionalProperties: true
        type: object
      name:
        type: string
      owners:
        items:
          $ref: '#/definitions/GlossaryOwner'
        type: array
      parent_term_id:
        type: string
      tags:
        items:
          type: string
        type: array
      updated_at:
        type: string
      user_definition:
        description: |-
          UserDefinition is the wording a person gave the term. Ingestion
          reads it and never writes it, so it survives every run.
        type: string
    type: object
  HistogramBucket:
    properties:
      abort:
        type: integer
      complete:
        type: integer
      date:
        type: string
      fail:
        type: integer
      other:
        type: integer
      running:
        type: integer
      total:
        type: integer
    type: object
  HistogramResponse:
    properties:
      buckets:
        items:
          $ref: '#/definitions/HistogramBucket'
        type: array
      period:
        type: string
    type: object
  ImagePurpose:
    enum:
      - icon
      - header
    type: string
    x-enum-varnames:
      - ImagePurposeIcon
      - ImagePurposeHeader
  Job:
    properties:
      facets:
        additionalProperties: true
        type: object
      name:
        type: string
      namespace:
        type: string
    type: object
  JobRun:
    properties:
      assets_created:
        type: integer
      assets_deleted:
        type: integer
      assets_updated:
        type: integer
      claimed_at:
        type: string
      claimed_by:
        type: string
      config:
        additionalProperties: true
        type: object
      created_at:
        type: string
      created_by:
        type: string
      documentation_added:
        type: integer
      error_message:
        type: string
      finished_at:
        type: string
      id:
        type: string
      lineage_created:
        type: integer
      log:
        type: string
      pipeline_name:
        type: string
      plugin_run_id:
        type: string
      run_id:
        type: string
      schedule_id:
        type: string
      source_name:
        type: string
      started_at:
        type: string
      status:
        type: string
      updated_at:
        type: string
    type: object
  LineageEdge:
    properties:
      id:
        type: string
      job_mrn:
        type: string
      last_seen_at:
        type: string
      observation_count:
        type: integer
      origin:
        type: string
      source:
        type: string
      target:
        type: string
      type:
        type: string
    type: object
  LineageNode:
    properties:
      asset:
        $ref: '#/definitions/Asset'
      depth:
        type: integer
      id:
        type: string
      type:
        type: string
    type: object
  LineageResponse:
    properties:
      edges:
        items:
          $ref: '#/definitions/LineageEdge'
        type: array
      nodes:
        items:
          $ref: '#/definitions/LineageNode'
        type: array
    type: object
  LineageResult:
    properties:
      error:
        type: string
      source:
        type: string
      status:
        type: string
      target:
        type: string
      type:
        type: string
    type: object
  LineageRun:
    properties:
      facets:
        additionalProperties: true
        type: object
      runId:
        type: string
    type: object
  ListJobRunsResponse:
    properties:
      limit:
        type: integer
      offset:
        type: integer
      runs:
        items:
          $ref: '#/definitions/JobRun'
        type: array
      total:
        type: integer
    type: object
  ListMembersResponse:
    properties:
      members:
        items:
          $ref: '#/definitions/TeamMemberWithUser'
        type: array
    type: object
  ListPluginsResponse:
    properties:
      loading:
        type: boolean
      plugins:
        items:
          $ref: '#/definitions/pluginsdk.Meta'
        type: array
    type: object
  ListSSOMappingsResponse:
    properties:
      mappings:
        items:
          $ref: '#/definitions/SSOTeamMapping'
        type: array
    type: object
  ListSchedulesResponse:
    properties:
      limit:
        type: integer
      offset:
        type: integer
      schedules:
        items:
          $ref: '#/definitions/Schedule'
        type: array
      total:
        type: integer
    type: object
  ListTeamsResponse:
    properties:
      limit:
        type: integer
      offset:
        type: integer
      teams:
        items:
          $ref: '#/definitions/Team'
        type: array
      total:
        type: integer
    type: object
  ListUsersResponse:
    properties:
      limit:
        type: integer
      offset:
        type: integer
      total:
        type: integer
      users:
        items:
          $ref: '#/definitions/User'
        type: array
    type: object
  LoginRequest:
    properties:
      password:
        type: string
      username:
        type: string
    required:
      - password
      - username
    type: object
  MessageResponse:
    properties:
      message:
        type: string
    type: object
  MetadataFieldSuggestion:
    properties:
      count:
        type: integer
      example: {}
      field:
        type: string
      path_parts:
        items:
          type: string
        type: array
      type:
        type: string
      types:
        items:
          type: string
        type: array
    type: object
  MetadataValueSuggestion:
    properties:
      count:
        type: integer
      example:
        $ref: '#/definitions/Asset'
      value:
        type: string
    type: object
  OAuthErrorResponse:
    properties:
      error:
        type: string
      error_description:
        type: string
    type: object
  OAuthLinkRequest:
    properties:
      provider:
        type: string
      provider_user_id:
        type: string
      user_id:
        type: string
      user_info:
        additionalProperties: true
        type: object
    required:
      - provider
      - provider_user_id
      - user_id
      - user_info
    type: object
  OwnerRequest:
    properties:
      id:
        type: string
      type:
        enum:
          - user
          - team
        type: string
    required:
      - id
      - type
    type: object
  Permission:
    properties:
      action:
        type: string
      description:
        type: string
      id:
        type: string
      name:
        type: string
      resource_type:
        type: string
    type: object
  PluginRun:
    properties:
      completed_at:
        type: string
      config:
        $ref: '#/definitions/RawPluginConfig'
      created_by:
        type: string
      error_message:
        type: string
      id:
        type: string
      pipeline_name:
        type: string
      run_id:
        type: string
      source_name:
        type: string
      started_at:
        type: string
      status:
        $ref: '#/definitions/RunStatus'
      summary:
        $ref: '#/definitions/RunSummary'
    type: object
  PreviewRequest:
    properties:
      limit:
        type: integer
      metadata_field:
        type: string
      pattern_type:
        type: string
      pattern_value:
        type: string
      query_expression:
        type: string
      rule_type:
        type: string
    type: object
  PreviewResponse:
    properties:
      column_names:
        items:
          type: string
        type: array
      rows:
        items:
          items: {}
          type: array
        type: array
      total_rows:
        type: integer
    type: object
  ProductImageMeta:
    properties:
      content_type:
        type: string
      created_at:
        type: string
      data_product_id:
        type: string
      filename:
        type: string
      id:
        type: string
      purpose:
        $ref: '#/definitions/ImagePurpose'
      size_bytes:
        type: integer
      url:
        type: string
    type: object
  QueryCount:
    properties:
      count:
        type: integer
      query:
        type: string
      query_type:
        type: string
    type: object
  RawPluginConfig:
    additionalProperties: true
    type: object
  RecordRunRequest:
    properties:
      agent_mrn:
        type: string
      ended_at:
        type: string
      error:
        type: string
      model:
        type: string
      observed_assets:
        items:
          type: string
        type: array
      run_id:
        type: string
      started_at:
        type: string
      status:
        type: string
      tokens_in:
        type: integer
      tokens_out:
        type: integer
      tool_calls:
        items:
          $ref: '#/definitions/ToolCallPayload'
        type: array
    type: object
  ReindexAcceptedResponse:
    properties:
      message:
        example: Reindex started
        type: string
      status:
        example: accepted
        type: string
    type: object
  ReindexStatusResponse:
    properties:
      es_configured:
        type: boolean
      running:
        type: boolean
    type: object
  RemoveTermRequest:
    properties:
      term_id:
        type: string
    required:
      - term_id
    type: object
  Result:
    properties:
      description:
        type: string
      id:
        type: string
      metadata:
        additionalProperties: true
        type: object
      name:
        type: string
      rank:
        type: number
      type:
        $ref: '#/definitions/ResultType'
      updated_at:
        type: string
      url:
        type: string
    type: object
  ResultType:
    enum:
      - asset
      - glossary
      - team
      - data_product
    type: string
    x-enum-varnames:
      - ResultTypeAsset
      - ResultTypeGlossary
      - ResultTypeTeam
      - ResultTypeDataProduct
  Role:
    properties:
      created_at:
        type: string
      deleted_at:
        type: string
      description:
        type: string
      id:
        type: string
      is_system:
        type: boolean
      name:
        type: string
      permissions:
        items:
          $ref: '#/definitions/RolePermission'
        type: array
      updated_at:
        type: string
      user_count:
        type: integer
    type: object
  RolePermission:
    properties:
      action:
        type: string
      description:
        type: string
      id:
        type: string
      name:
        type: string
      resource_type:
        type: string
    type: object
  RulePreview:
    properties:
      asset_count:
        type: integer
      asset_ids:
        items:
          type: string
        type: array
      errors:
        items:
          type: string
        type: array
    type: object
  RuleType:
    enum:
      - query
      - metadata_match
    type: string
    x-enum-varnames:
      - RuleTypeQuery
      - RuleTypeMetadataMatch
  RunCreateAssetRequest:
    properties:
      description:
        type: string
      external_links:
        items:
          additionalProperties:
            type: string
          type: object
        type: array
      metadata:
        additionalProperties: true
        type: object
      name:
        type: string
      providers:
        items:
          type: string
        type: array
      schema:
        additionalProperties: true
        type: object
      sources:
        items:
          $ref: '#/definitions/AssetSource'
        type: array
      tags:
        items:
          type: string
        type: array
      terms:
        description: Terms are the names of glossary terms assigned to this asset.
        items:
          type: string
        type: array
      type:
        type: string
    type: object
  RunEntitiesResponse:
    properties:
      entities:
        items:
          $ref: '#/definitions/RunEntity'
        type: array
      limit:
        type: integer
      offset:
        type: integer
      total:
        type: integer
    type: object
  RunEntity:
    properties:
      created_at:
        type: string
      entity_mrn:
        type: string
      entity_name:
        type: string
      entity_type:
        type: string
      error_message:
        type: string
      id:
        type: string
      run_id:
        type: string
      status:
        type: string
    type: object
  RunEvent:
    properties:
      eventTime:
        type: string
      eventType:
        type: string
      inputs:
        items:
          $ref: '#/definitions/Dataset'
        type: array
      job:
        $ref: '#/definitions/Job'
      outputs:
        items:
          $ref: '#/definitions/Dataset'
        type: array
      producer:
        type: string
      run:
        $ref: '#/definitions/LineageRun'
      schemaURL:
        type: string
    type: object
  RunHistory:
    properties:
      duration_ms:
        type: integer
      end_time:
        type: string
      event_time:
        type: string
      id:
        type: string
      job_name:
        type: string
      job_namespace:
        type: string
      run_id:
        type: string
      start_time:
        type: string
      status:
        type: string
      type:
        type: string
    type: object
  RunHistoryResponse:
    properties:
      limit:
        type: integer
      offset:
        type: integer
      run_history:
        items:
          $ref: '#/definitions/RunHistory'
        type: array
      total:
        type: integer
    type: object
  RunStatus:
    enum:
      - running
      - completed
      - failed
      - cancelled
    type: string
    x-enum-varnames:
      - StatusRunning
      - StatusCompleted
      - StatusFailed
      - StatusCancelled
  RunSummary:
    properties:
      assets_created:
        type: integer
      assets_deleted:
        type: integer
      assets_terms_linked:
        type: integer
      assets_updated:
        type: integer
      documentation_added:
        type: integer
      duration_seconds:
        type: integer
      errors_count:
        type: integer
      glossary_terms_created:
        description: |-
          Glossary counts are absent from runs that predate them, and from
          sources that curate no business terms.
        type: integer
      glossary_terms_updated:
        type: integer
      lineage_created:
        type: integer
      lineage_updated:
        type: integer
      total_entities:
        type: integer
    type: object
  RunsResponse:
    properties:
      runs:
        items:
          $ref: '#/definitions/AgentRun'
        type: array
      total:
        type: integer
    type: object
  SSOProvider:
    properties:
      issuer_url:
        type: string
      name:
        type: string
      type:
        type: string
    type: object
  SSOProvidersResponse:
    properties:
      providers:
        items:
          $ref: '#/definitions/SSOProvider'
        type: array
    type: object
  SSOTeamMapping:
    properties:
      created_at:
        type: string
      id:
        type: string
      member_role:
        type: string
      provider:
        type: string
      sso_group_name:
        type: string
      team_id:
        type: string
      updated_at:
        type: string
    type: object
  Schedule:
    properties:
      config:
        additionalProperties: true
        type: object
      created_at:
        type: string
      created_by:
        type: string
      cron_expression:
        type: string
      enabled:
        type: boolean
      id:
        type: string
      last_run_at:
        type: string
      last_run_status:
        type: string
      managed_by:
        type: string
      name:
        type: string
      next_run_at:
        type: string
      plugin_id:
        type: string
      updated_at:
        type: string
    type: object
  SearchOwnersResponse:
    properties:
      owners:
        items:
          $ref: '#/definitions/TeamOwner'
        type: array
    type: object
  SearchResponse:
    properties:
      facets:
        $ref: '#/definitions/Facets'
      limit:
        type: integer
      offset:
        type: integer
      results:
        items:
          $ref: '#/definitions/Result'
        type: array
      total:
        type: integer
    type: object
  ServiceAccount:
    properties:
      active:
        type: boolean
      created_at:
        type: string
      created_by:
        type: string
      description:
        type: string
      id:
        type: string
      name:
        type: string
      roles:
        items:
          $ref: '#/definitions/Role'
        type: array
      updated_at:
        type: string
    type: object
  ServiceAccountAPIKey:
    properties:
      created_at:
        type: string
      expires_at:
        type: string
      id:
        type: string
      key:
        type: string
      last_used_at:
        type: string
      name:
        type: string
      service_account_id:
        type: string
    type: object
  StartRunRequest:
    properties:
      config:
        $ref: '#/definitions/RawPluginConfig'
      pipeline_name:
        type: string
      source_name:
        type: string
    required:
      - pipeline_name
      - source_name
    type: object
  Stats:
    properties:
      median_latency_ms:
        type: integer
      p95_latency_ms:
        type: integer
      run_count:
        type: integer
      success_rate:
        type: number
      tokens_in:
        type: integer
      tokens_out:
        type: integer
    type: object
  TagRequest:
    properties:
      tag:
        type: string
    required:
      - tag
    type: object
  Team:
    properties:
      created_at:
        type: string
      created_by:
        type: string
      created_via_sso:
        type: boolean
      description:
        type: string
      id:
        type: string
      metadata:
        additionalProperties: true
        type: object
      name:
        type: string
      sso_provider:
        type: string
      tags:
        items:
          type: string
        type: array
      updated_at:
        type: string
    type: object
  TeamMemberWithUser:
    properties:
      email:
        type: string
      id:
        type: string
      joined_at:
        type: string
      name:
        type: string
      profile_picture:
        type: string
      role:
        type: string
      source:
        type: string
      sso_provider:
        type: string
      team_id:
        type: string
      user_id:
        type: string
      username:
        type: string
    type: object
  TeamOwner:
    properties:
      email:
        type: string
      id:
        type: string
      name:
        type: string
      profile_picture:
        type: string
      type:
        type: string
      username:
        type: string
    type: object
  TokenExchangeResponse:
    properties:
      access_token:
        type: string
      expires_in:
        type: integer
      issued_token_type:
        type: string
      token_type:
        type: string
    type: object
  TokenResponse:
    properties:
      access_token:
        type: string
      expires_in:
        type: integer
      requires_password_change:
        type: boolean
      token_type:
        type: string
    type: object
  ToolCall:
    properties:
      duration_ms:
        type: integer
      ordinal:
        type: integer
      started_at:
        type: string
      status:
        type: string
      target_mrn:
        type: string
      tool_name:
        type: string
    type: object
  ToolCallPayload:
    properties:
      duration_ms:
        type: integer
      started_at:
        type: string
      status:
        type: string
      target_mrn:
        type: string
      tool_name:
        type: string
    type: object
  TotalAssetsResponse:
    properties:
      count:
        type: integer
    type: object
  UIConfigResponse:
    properties:
      allow_unencrypted:
        type: boolean
      banner:
        $ref: '#/definitions/BannerResponse'
      encryption_configured:
        type: boolean
      table_preview_enabled:
        type: boolean
    type: object
  UpdateAssetRequest:
    properties:
      description:
        type: string
      environments:
        additionalProperties:
          $ref: '#/definitions/Environment'
        type: object
      external_links:
        items:
          $ref: '#/definitions/AssetExternalLink'
        type: array
      metadata:
        additionalProperties: true
        type: object
      name:
        type: string
      providers:
        items:
          type: string
        type: array
      schema:
        additionalProperties:
          type: string
        type: object
      sources:
        items:
          $ref: '#/definitions/AssetSource'
        type: array
      tags:
        items:
          type: string
        type: array
      type:
        type: string
      user_description:
        type: string
    type: object
  UpdateAssetRuleRequest:
    properties:
      description:
        type: string
      is_enabled:
        type: boolean
      links:
        items:
          $ref: '#/definitions/AssetRuleExternalLink'
        type: array
      metadata_field:
        type: string
      name:
        type: string
      pattern_type:
        type: string
      pattern_value:
        type: string
      priority:
        type: integer
      query_expression:
        type: string
      rule_type:
        type: string
      term_ids:
        items:
          type: string
        type: array
    type: object
  UpdateDataProductRequest:
    properties:
      description:
        type: string
      metadata:
        additionalProperties: true
        type: object
      name:
        type: string
      owners:
        items:
          $ref: '#/definitions/DataProductOwnerRequest'
        type: array
      tags:
        items:
          type: string
        type: array
    type: object
  UpdateMemberRoleRequest:
    properties:
      role:
        type: string
    type: object
  UpdatePasswordRequest:
    properties:
      new_password:
        minLength: 8
        type: string
    required:
      - new_password
    type: object
  UpdateSSOMappingRequest:
    properties:
      member_role:
        type: string
      team_id:
        type: string
    type: object
  UpdateScheduleRequest:
    properties:
      config:
        additionalProperties: true
        type: object
      cron_expression:
        type: string
      enabled:
        type: boolean
      name:
        type: string
      plugin_id:
        type: string
    type: object
  UpdateServiceAccountRequest:
    properties:
      active:
        type: boolean
      description:
        type: string
      name:
        type: string
      role_ids:
        items:
          type: string
        type: array
    type: object
  UpdateTeamRequest:
    properties:
      description:
        type: string
      metadata:
        additionalProperties: true
        type: object
      name:
        type: string
      tags:
        items:
          type: string
        type: array
    type: object
  UpdateTermRequest:
    properties:
      definition:
        type: string
      description:
        type: string
      metadata:
        additionalProperties: true
        type: object
      name:
        type: string
      owners:
        items:
          $ref: '#/definitions/OwnerRequest'
        type: array
      parent_term_id:
        type: string
    type: object
  UpdateUserInput:
    properties:
      active:
        type: boolean
      email:
        type: string
      name:
        type: string
      password:
        minLength: 8
        type: string
      preferences:
        additionalProperties: true
        type: object
      profile_picture:
        type: string
      role_names:
        items:
          type: string
        minItems: 1
        type: array
    type: object
  User:
    properties:
      active:
        type: boolean
      created_at:
        type: string
      id:
        type: string
      identities:
        items:
          $ref: '#/definitions/UserIdentity'
        type: array
      must_change_password:
        type: boolean
      name:
        type: string
      preferences:
        additionalProperties: true
        type: object
      profile_picture:
        type: string
      roles:
        items:
          $ref: '#/definitions/UserRole'
        type: array
      updated_at:
        type: string
      username:
        type: string
    type: object
  UserIdentity:
    properties:
      created_at:
        type: string
      id:
        type: string
      provider:
        type: string
      provider_data:
        additionalProperties: true
        type: object
      provider_email:
        type: string
      provider_user_id:
        type: string
      updated_at:
        type: string
      user_id:
        type: string
    type: object
  UserRole:
    properties:
      description:
        type: string
      id:
        type: string
      name:
        type: string
      permissions:
        items:
          $ref: '#/definitions/Permission'
        type: array
    type: object
  ValidateConfigRequest:
    properties:
      config:
        additionalProperties: true
        type: object
      plugin_id:
        type: string
    type: object
  ValidateConfigResponse:
    properties:
      errors:
        items:
          $ref: '#/definitions/ValidationErrorDetail'
        type: array
      valid:
        type: boolean
    type: object
  ValidationErrorDetail:
    properties:
      field:
        type: string
      message:
        type: string
    type: object
  pluginsdk.ConfigField:
    properties:
      default: {}
      description:
        type: string
      fields:
        items:
          $ref: '#/definitions/pluginsdk.ConfigField'
        type: array
      hidden:
        type: boolean
      is_array:
        type: boolean
      label:
        type: string
      name:
        type: string
      options:
        items:
          $ref: '#/definitions/pluginsdk.FieldOption'
        type: array
      placeholder:
        type: string
      required:
        type: boolean
      sensitive:
        type: boolean
      show_when:
        $ref: '#/definitions/pluginsdk.ShowWhen'
      type:
        $ref: '#/definitions/pluginsdk.FieldType'
      validation:
        $ref: '#/definitions/pluginsdk.Validation'
    type: object
  pluginsdk.FieldOption:
    properties:
      label:
        type: string
      value:
        type: string
    type: object
  pluginsdk.FieldType:
    enum:
      - string
      - int
      - bool
      - select
      - multiselect
      - password
      - object
    type: string
    x-enum-varnames:
      - FieldTypeString
      - FieldTypeInt
      - FieldTypeBool
      - FieldTypeSelect
      - FieldTypeMultiselect
      - FieldTypePassword
      - FieldTypeObject
  pluginsdk.Meta:
    properties:
      category:
        type: string
      config_spec:
        items:
          $ref: '#/definitions/pluginsdk.ConfigField'
        type: array
      description:
        type: string
      features:
        items:
          type: string
        type: array
      icon:
        type: string
      id:
        type: string
      name:
        type: string
      status:
        type: string
      supports_data_preview:
        type: boolean
    type: object
  pluginsdk.ShowWhen:
    properties:
      field:
        type: string
      value:
        type: string
    type: object
  pluginsdk.Validation:
    properties:
      max:
        type: integer
      max_len:
        type: integer
      min:
        type: integer
      min_len:
        type: integer
      pattern:
        type: string
    type: object
  v1_roles.createRoleRequest:
    properties:
      description:
        type: string
      name:
        type: string
      permission_ids:
        items:
          type: string
        type: array
    type: object
  v1_roles.replacePermissionsRequest:
    properties:
      permission_ids:
        items:
          type: string
        type: array
    type: object
  v1_roles.updateRoleRequest:
    properties:
      description:
        type: string
      name:
        type: string
    type: object
info:
  contact: {}
  description: API for interacting with Marmot
  license:
    name: MIT
    url: https://opensource.org/license/MIT
  title: Marmot API
  version: '0.1'
paths:
  /api/v1/admin/search/reindex:
    get:
      description: >-
        Check whether a search reindex is currently running and whether
        Elasticsearch is configured.
      operationId: getAdminSearchReindex
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ReindexStatusResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get reindex status
      tags:
        - admin
    post:
      description: >-
        Trigger a full reindex from PostgreSQL to Elasticsearch. The reindex
        runs asynchronously in the background. Only one reindex can run at a
        time.
      operationId: postAdminSearchReindex
      produces:
        - application/json
      responses:
        '202':
          description: Accepted
          schema:
            $ref: '#/definitions/ReindexAcceptedResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/ErrorResponse'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/ErrorResponse'
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Start search reindex
      tags:
        - admin
  /api/v1/agents/{asset_id}/activity:
    get:
      operationId: getAgentsAssetIDActivity
      parameters:
        - description: Agent asset id
          in: path
          name: asset_id
          required: true
          type: string
        - description: Lookback window (e.g. 24h, 7d). Default 24h.
          in: query
          name: period
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ActivityResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Agent activity
      tags:
        - agents
  /api/v1/agents/{asset_id}/runs:
    get:
      operationId: getAgentsAssetIDRuns
      parameters:
        - description: Agent asset id
          in: path
          name: asset_id
          required: true
          type: string
        - description: Lookback window (e.g. 24h, 7d). Default 24h.
          in: query
          name: period
          type: string
        - description: Max number of runs to return
          in: query
          name: limit
          type: integer
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/RunsResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: List agent runs
      tags:
        - agents
  /api/v1/agents/{asset_id}/stats:
    get:
      operationId: getAgentsAssetIDStats
      parameters:
        - description: Agent asset id
          in: path
          name: asset_id
          required: true
          type: string
        - description: Lookback window (e.g. 24h, 7d). Default 24h.
          in: query
          name: period
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Stats'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Agent stats
      tags:
        - agents
  /api/v1/agents/runs:
    post:
      consumes:
        - application/json
      operationId: postAgentsRuns
      parameters:
        - description: Agent run record
          in: body
          name: request
          required: true
          schema:
            $ref: '#/definitions/RecordRunRequest'
      produces:
        - application/json
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/AgentRun'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Record agent run
      tags:
        - agents
  /api/v1/asset-rules/:
    post:
      consumes:
        - application/json
      description: Create a new asset rule that applies enrichments to matching assets
      operationId: postAssetRules
      parameters:
        - description: Asset rule creation request
          in: body
          name: rule
          required: true
          schema:
            $ref: '#/definitions/CreateAssetRuleRequest'
      produces:
        - application/json
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/AssetRule'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Create an asset rule
      tags:
        - asset-rules
  /api/v1/asset-rules/{id}:
    delete:
      description: Delete an asset rule by ID
      operationId: deleteAssetRulesID
      parameters:
        - description: Asset rule ID
          in: path
          name: id
          required: true
          type: string
      responses:
        '204':
          description: No Content
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Delete an asset rule
      tags:
        - asset-rules
    get:
      description: Get an asset rule by ID
      operationId: getAssetRulesID
      parameters:
        - description: Asset rule ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/AssetRule'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get an asset rule
      tags:
        - asset-rules
    put:
      consumes:
        - application/json
      description: Update an existing asset rule
      operationId: putAssetRulesID
      parameters:
        - description: Asset rule ID
          in: path
          name: id
          required: true
          type: string
        - description: Asset rule update request
          in: body
          name: rule
          required: true
          schema:
            $ref: '#/definitions/UpdateAssetRuleRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/AssetRule'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Update an asset rule
      tags:
        - asset-rules
  /api/v1/asset-rules/assets/{id}:
    get:
      description: Get the list of asset IDs matched by an asset rule
      operationId: getAssetRulesAssetsID
      parameters:
        - description: Asset rule ID
          in: path
          name: id
          required: true
          type: string
        - default: 50
          description: Number of items to return
          in: query
          name: limit
          type: integer
        - default: 0
          description: Number of items to skip
          in: query
          name: offset
          type: integer
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            additionalProperties: true
            type: object
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get assets matched by a rule
      tags:
        - asset-rules
  /api/v1/asset-rules/list:
    get:
      description: List all asset rules with pagination
      operationId: getAssetRulesList
      parameters:
        - default: 50
          description: Number of items to return
          in: query
          name: limit
          type: integer
        - default: 0
          description: Number of items to skip
          in: query
          name: offset
          type: integer
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/AssetRuleListResult'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: List asset rules
      tags:
        - asset-rules
  /api/v1/asset-rules/preview:
    post:
      consumes:
        - application/json
      description: Preview which assets would match a rule configuration
      operationId: postAssetRulesPreview
      parameters:
        - description: Rule preview request
          in: body
          name: rule
          required: true
          schema:
            $ref: '#/definitions/PreviewRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/RulePreview'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Preview an asset rule
      tags:
        - asset-rules
  /api/v1/asset-rules/search:
    get:
      description: Search asset rules by name
      operationId: getAssetRulesSearch
      parameters:
        - description: Search query
          in: query
          name: query
          type: string
        - default: 50
          description: Number of items to return
          in: query
          name: limit
          type: integer
        - default: 0
          description: Number of items to skip
          in: query
          name: offset
          type: integer
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/AssetRuleListResult'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Search asset rules
      tags:
        - asset-rules
  /api/v1/assets/:
    post:
      consumes:
        - application/json
      description: Create a new asset in the system
      operationId: postAssets
      parameters:
        - description: Asset creation request
          in: body
          name: asset
          required: true
          schema:
            $ref: '#/definitions/CreateAssetRequest'
      produces:
        - application/json
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/Asset'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Create a new asset
      tags:
        - assets
  /api/v1/assets/{id}:
    delete:
      consumes:
        - application/json
      description: Delete an asset from the system
      operationId: deleteAssetsID
      parameters:
        - description: Asset ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '204':
          description: No Content
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Delete an asset
      tags:
        - assets
    get:
      consumes:
        - application/json
      description: Get detailed information about a specific asset
      operationId: getAssetsID
      parameters:
        - description: Asset ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Asset'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get an asset by ID
      tags:
        - assets
    put:
      consumes:
        - application/json
      description: Update an existing asset's information
      operationId: putAssetsID
      parameters:
        - description: Asset ID
          in: path
          name: id
          required: true
          type: string
        - description: Asset update request
          in: body
          name: asset
          required: true
          schema:
            $ref: '#/definitions/UpdateAssetRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Asset'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Update an asset
      tags:
        - assets
  /api/v1/assets/by-glossary-term/{term_id}:
    get:
      description: Retrieve all assets associated with a specific glossary term
      operationId: getAssetsByGlossaryTermTermID
      parameters:
        - description: Glossary Term ID
          in: path
          name: term_id
          required: true
          type: string
        - default: 20
          description: Maximum number of assets
          in: query
          name: limit
          type: integer
        - default: 0
          description: Pagination offset
          in: query
          name: offset
          type: integer
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            additionalProperties: true
            type: object
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get assets by glossary term
      tags:
        - assets
  /api/v1/assets/documentation/:
    post:
      consumes:
        - application/json
      description: Create or update documentation for an asset
      operationId: postAssetsDocumentation
      parameters:
        - description: Documentation creation request
          in: body
          name: request
          required: true
          schema:
            $ref: '#/definitions/DocumentationCreateRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Documentation'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Create asset documentation
      tags:
        - assets
  /api/v1/assets/documentation/{mrn}:
    get:
      description: Get documentation for a specific asset
      operationId: getAssetsDocumentationMrn
      parameters:
        - description: Asset MRN
          format: url
          in: path
          name: mrn
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            items:
              $ref: '#/definitions/Documentation'
            type: array
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get asset documentation
      tags:
        - assets
  /api/v1/assets/documentation/batch:
    post:
      consumes:
        - application/json
      description: Create or update documentation for multiple assets
      operationId: postAssetsDocumentationBatch
      parameters:
        - description: Batch documentation request
          in: body
          name: request
          required: true
          schema:
            $ref: '#/definitions/BatchDocumentationRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/BatchDocumentationResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Batch create documentation
      tags:
        - assets
  /api/v1/assets/lookup/{type}/{service}/{name}:
    get:
      description: Get an asset by its type, service (provider), and name
      operationId: getAssetsLookupTypeServiceName
      parameters:
        - description: Asset type
          in: path
          name: type
          required: true
          type: string
        - description: Service/Provider name
          in: path
          name: service
          required: true
          type: string
        - description: Asset name
          in: path
          name: name
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Asset'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Lookup asset by type, service, and name
      tags:
        - assets
  /api/v1/assets/match-pattern/:
    get:
      description: Find assets matching a pattern
      operationId: getAssetsMatchPattern
      parameters:
        - description: Asset pattern to match
          in: query
          name: pattern
          required: true
          type: string
        - description: Asset type
          in: query
          name: type
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            items:
              $ref: '#/definitions/Asset'
            type: array
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Match asset pattern
      tags:
        - assets
  /api/v1/assets/my-assets:
    get:
      description: Get assets owned by the current user or their teams
      operationId: getAssetsMyAssets
      parameters:
        - default: 20
          description: Limit
          in: query
          name: limit
          type: integer
        - default: 0
          description: Offset
          in: query
          name: offset
          type: integer
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/AssetSearchResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get user's assets
      tags:
        - assets
  /api/v1/assets/preview/{id}:
    get:
      description: >-
        Fetches sample data from the asset's data source. Requires
        assets:preview permission.
      operationId: getAssetsPreviewID
      parameters:
        - description: Asset ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/PreviewResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '403':
          description: Missing assets:preview permission
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
        '501':
          description: Data preview not supported for this asset
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get preview data for an asset
      tags:
        - assets
  /api/v1/assets/qualified-name/{name}:
    get:
      consumes:
        - application/json
      description: Get detailed information about a specific asset using its qualified name
      operationId: getAssetsQualifiedNameQualifiedName
      parameters:
        - description: Asset qualified name
          in: path
          name: name
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Asset'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get an asset by qualified name
      tags:
        - assets
  /api/v1/assets/run-history-histogram/{id}:
    get:
      description: Get histogram data for asset run history over specified period
      operationId: getAssetsIDRunHistoryHistogram
      parameters:
        - description: Asset ID
          in: path
          name: id
          required: true
          type: string
        - default: 30d
          description: Time period (7d, 30d, 90d)
          in: query
          name: period
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/HistogramResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get asset run history histogram
      tags:
        - assets
  /api/v1/assets/run-history/{id}:
    get:
      description: Get paginated run history for a specific asset
      operationId: getAssetsIDRunHistory
      parameters:
        - description: Asset ID
          in: path
          name: id
          required: true
          type: string
        - default: 10
          description: Number of items per page
          in: query
          name: limit
          type: integer
        - default: 0
          description: Number of items to skip
          in: query
          name: offset
          type: integer
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/RunHistoryResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get asset run history
      tags:
        - assets
  /api/v1/assets/search:
    get:
      consumes:
        - application/json
      description: Search for assets using query string and filters
      operationId: getAssetsSearch
      parameters:
        - description: Search query
          in: query
          name: q
          type: string
        - collectionFormat: csv
          description: Filter by asset types
          in: query
          items:
            type: string
          name: types
          type: array
        - collectionFormat: csv
          description: Filter by services
          in: query
          items:
            type: string
          name: services
          type: array
        - collectionFormat: csv
          description: Filter by tags
          in: query
          items:
            type: string
          name: tags
          type: array
        - default: 50
          description: Number of items to return
          in: query
          name: limit
          type: integer
        - default: 0
          description: Number of items to skip
          in: query
          name: offset
          type: integer
        - default: false
          description: Calculate filter counts
          in: query
          name: calculateCounts
          type: boolean
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/AssetSearchResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Search assets
      tags:
        - assets
  /api/v1/assets/suggestions/metadata/fields:
    get:
      description: Get suggestions for metadata fields and their types
      operationId: getAssetsSuggestionsMetadataFields
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            items:
              $ref: '#/definitions/MetadataFieldSuggestion'
            type: array
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get metadata field suggestions
      tags:
        - assets
  /api/v1/assets/suggestions/metadata/values:
    get:
      description: Get suggestions for values of a specific metadata field
      operationId: getAssetsSuggestionsMetadataValues
      parameters:
        - description: Metadata field name
          in: query
          name: field
          required: true
          type: string
        - description: Value prefix to filter by
          in: query
          name: prefix
          type: string
        - default: 10
          description: Maximum number of suggestions
          in: query
          name: limit
          type: integer
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            items:
              $ref: '#/definitions/MetadataValueSuggestion'
            type: array
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get metadata value suggestions
      tags:
        - assets
  /api/v1/assets/suggestions/tags:
    get:
      description: Get suggestions for asset tags
      operationId: getAssetsSuggestionsTags
      parameters:
        - description: Tag prefix to filter by
          in: query
          name: prefix
          type: string
        - default: 10
          description: Maximum number of suggestions
          in: query
          name: limit
          type: integer
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            items:
              type: string
            type: array
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get tag suggestions
      tags:
        - assets
  /api/v1/assets/summary:
    get:
      consumes:
        - application/json
      description: Get the total count of assets by type
      operationId: getAssetsSummary
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/AssetSummaryResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get asset summary
      tags:
        - assets
  /api/v1/assets/tags/{id}:
    delete:
      consumes:
        - application/json
      description: Remove a tag from an existing asset
      operationId: deleteAssetsTagsID
      parameters:
        - description: Asset ID
          in: path
          name: id
          required: true
          type: string
        - description: Tag to remove
          in: body
          name: tag
          required: true
          schema:
            $ref: '#/definitions/TagRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Asset'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Remove tag from asset
      tags:
        - assets
    post:
      consumes:
        - application/json
      description: Add a new tag to an existing asset
      operationId: postAssetsTagsID
      parameters:
        - description: Asset ID
          in: path
          name: id
          required: true
          type: string
        - description: Tag to add
          in: body
          name: tag
          required: true
          schema:
            $ref: '#/definitions/TagRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Asset'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Add tag to asset
      tags:
        - assets
  /api/v1/assets/terms/{id}:
    delete:
      consumes:
        - application/json
      description: Remove a glossary term association from an asset
      operationId: deleteAssetsTermsID
      parameters:
        - description: Asset ID
          in: path
          name: id
          required: true
          type: string
        - description: Term ID to remove
          in: body
          name: term
          required: true
          schema:
            $ref: '#/definitions/RemoveTermRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            items:
              $ref: '#/definitions/AssetTerm'
            type: array
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Remove glossary term from asset
      tags:
        - assets
    get:
      description: Retrieve all glossary terms associated with an asset
      operationId: getAssetsTermsID
      parameters:
        - description: Asset ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            items:
              $ref: '#/definitions/AssetTerm'
            type: array
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get asset's glossary terms
      tags:
        - assets
    post:
      consumes:
        - application/json
      description: Associate one or more glossary terms with an asset
      operationId: postAssetsTermsID
      parameters:
        - description: Asset ID
          in: path
          name: id
          required: true
          type: string
        - description: Term IDs to add
          in: body
          name: terms
          required: true
          schema:
            $ref: '#/definitions/AddTermsRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            items:
              $ref: '#/definitions/AssetTerm'
            type: array
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Add glossary terms to asset
      tags:
        - assets
  /api/v1/glossary/:
    post:
      consumes:
        - application/json
      description: Create a new glossary term with name, definition, and optional metadata
      operationId: postGlossary
      parameters:
        - description: Glossary term to create
          in: body
          name: term
          required: true
          schema:
            $ref: '#/definitions/CreateTermRequest'
      produces:
        - application/json
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/GlossaryTerm'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Create glossary term
      tags:
        - glossary
  /api/v1/glossary/{id}:
    delete:
      description: Delete a glossary term by its ID
      operationId: deleteGlossaryID
      parameters:
        - description: Glossary Term ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            additionalProperties:
              type: string
            type: object
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Delete glossary term
      tags:
        - glossary
    get:
      description: Retrieve a glossary term by its ID
      operationId: getGlossaryID
      parameters:
        - description: Glossary Term ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/GlossaryTerm'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get glossary term
      tags:
        - glossary
    put:
      consumes:
        - application/json
      description: Update an existing glossary term by its ID
      operationId: putGlossaryID
      parameters:
        - description: Glossary Term ID
          in: path
          name: id
          required: true
          type: string
        - description: Glossary term update data
          in: body
          name: term
          required: true
          schema:
            $ref: '#/definitions/UpdateTermRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/GlossaryTerm'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Update glossary term
      tags:
        - glossary
  /api/v1/glossary/ancestors/{id}:
    get:
      description: Retrieve all ancestor terms of a glossary term (parent chain)
      operationId: getGlossaryAncestorsID
      parameters:
        - description: Term ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            additionalProperties: true
            type: object
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get ancestor terms
      tags:
        - glossary
  /api/v1/glossary/children/{id}:
    get:
      description: Retrieve all child terms of a glossary term
      operationId: getGlossaryChildrenID
      parameters:
        - description: Parent Term ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            additionalProperties: true
            type: object
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get child terms
      tags:
        - glossary
  /api/v1/glossary/list:
    get:
      description: Retrieve a paginated list of all glossary terms
      operationId: getGlossaryList
      parameters:
        - default: 20
          description: Maximum number of terms to return
          in: query
          name: limit
          type: integer
        - default: 0
          description: Number of terms to skip
          in: query
          name: offset
          type: integer
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/GlossaryListResult'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: List glossary terms
      tags:
        - glossary
  /api/v1/glossary/search:
    get:
      description: Search for glossary terms by query string and filters
      operationId: getGlossarySearch
      parameters:
        - description: Search query
          in: query
          name: q
          type: string
        - description: Filter by parent term ID
          in: query
          name: parent_term_id
          type: string
        - default: 20
          description: Maximum number of terms to return
          in: query
          name: limit
          type: integer
        - default: 0
          description: Number of terms to skip
          in: query
          name: offset
          type: integer
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/GlossaryListResult'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Search glossary terms
      tags:
        - glossary
  /api/v1/ingestion/runs:
    get:
      operationId: getIngestionRuns
      parameters:
        - description: Filter by schedule ID
          in: query
          name: schedule_id
          type: string
        - description: Filter by status
          in: query
          name: status
          type: string
        - description: Limit
          in: query
          name: limit
          type: integer
        - description: Offset
          in: query
          name: offset
          type: integer
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ListJobRunsResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: List ingestion job runs
      tags:
        - ingestion
  /api/v1/ingestion/runs/{id}:
    get:
      operationId: getIngestionRunsID
      parameters:
        - description: Job run ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/JobRun'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get a job run by ID
      tags:
        - ingestion
  /api/v1/ingestion/runs/{id}/cancel:
    post:
      operationId: postIngestionRunsIDCancel
      parameters:
        - description: Job run ID
          in: path
          name: id
          required: true
          type: string
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Cancel a running job
      tags:
        - ingestion
  /api/v1/ingestion/runs/{id}/entities:
    get:
      operationId: getIngestionRunsIDEntities
      parameters:
        - description: Job run ID
          in: path
          name: id
          required: true
          type: string
        - description: Limit
          in: query
          name: limit
          type: integer
        - description: Offset
          in: query
          name: offset
          type: integer
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            additionalProperties: true
            type: object
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get entities for a job run
      tags:
        - ingestion
  /api/v1/ingestion/schedules:
    get:
      operationId: getIngestionSchedules
      parameters:
        - description: Filter by enabled status
          in: query
          name: enabled
          type: boolean
        - description: Limit
          in: query
          name: limit
          type: integer
        - description: Offset
          in: query
          name: offset
          type: integer
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ListSchedulesResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: List ingestion schedules
      tags:
        - ingestion
    post:
      consumes:
        - application/json
      operationId: postIngestionSchedules
      parameters:
        - description: Schedule configuration
          in: body
          name: schedule
          required: true
          schema:
            $ref: '#/definitions/CreateScheduleRequest'
      produces:
        - application/json
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/Schedule'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Create a new ingestion schedule
      tags:
        - ingestion
  /api/v1/ingestion/schedules/{id}:
    delete:
      operationId: deleteIngestionSchedulesID
      parameters:
        - description: Schedule ID
          in: path
          name: id
          required: true
          type: string
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Delete an ingestion schedule
      tags:
        - ingestion
    get:
      operationId: getIngestionSchedulesID
      parameters:
        - description: Schedule ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Schedule'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get an ingestion schedule by ID
      tags:
        - ingestion
    put:
      consumes:
        - application/json
      operationId: putIngestionSchedulesID
      parameters:
        - description: Schedule ID
          in: path
          name: id
          required: true
          type: string
        - description: Updated schedule configuration
          in: body
          name: schedule
          required: true
          schema:
            $ref: '#/definitions/UpdateScheduleRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Schedule'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Update an ingestion schedule
      tags:
        - ingestion
  /api/v1/ingestion/schedules/{id}/trigger:
    post:
      operationId: postIngestionSchedulesIDTrigger
      parameters:
        - description: Schedule ID
          in: path
          name: id
          required: true
          type: string
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/JobRun'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Manually trigger an ingestion schedule
      tags:
        - ingestion
  /api/v1/ingestion/validate:
    post:
      consumes:
        - application/json
      operationId: postIngestionValidate
      parameters:
        - description: Config to validate
          in: body
          name: config
          required: true
          schema:
            $ref: '#/definitions/ValidateConfigRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ValidateConfigResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Validate plugin configuration
      tags:
        - ingestion
  /api/v1/lineage:
    post:
      consumes:
        - application/json
      description: Process OpenLineage run events and update assets/lineage accordingly
      operationId: postLineage
      parameters:
        - description: OpenLineage run event
          in: body
          name: event
          required: true
          schema:
            $ref: '#/definitions/RunEvent'
      produces:
        - application/json
      responses:
        '200':
          description: Event processed successfully
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Ingest OpenLineage event
      tags:
        - lineage
  /api/v1/lineage/assets/{id}:
    get:
      consumes:
        - application/json
      description: Get upstream and downstream lineage for a specific asset
      operationId: getLineageAssetsID
      parameters:
        - description: Asset ID
          format: uuid
          in: path
          name: id
          required: true
          type: string
        - default: 10
          description: Maximum depth of lineage graph
          in: query
          name: limit
          type: integer
        - default: both
          description: Direction of lineage (upstream, downstream, or both)
          enum:
            - upstream
            - downstream
            - both
          in: query
          name: direction
          type: string
        - description: >-
            Comma separated edge types to leave out, for example CONTAINS to see
            data flow without structure
          in: query
          name: exclude_types
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/LineageResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get asset lineage
      tags:
        - lineage
  /api/v1/lineage/batch:
    post:
      consumes:
        - application/json
      description: Create lineage edges in batch
      operationId: postLineageBatch
      parameters:
        - description: Array of lineage edges to create
          in: body
          name: edges
          required: true
          schema:
            items:
              $ref: '#/definitions/LineageEdge'
            type: array
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            items:
              $ref: '#/definitions/BatchLineageResult'
            type: array
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Batch create lineage edges
      tags:
        - lineage
  /api/v1/lineage/direct:
    post:
      consumes:
        - application/json
      description: >-
        Create a direct lineage connection between two assets and returns the
        created edge
      operationId: postLineageDirect
      parameters:
        - description: Lineage edge to create
          in: body
          name: edge
          required: true
          schema:
            $ref: '#/definitions/LineageEdge'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/LineageEdge'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Create direct lineage
      tags:
        - lineage
  /api/v1/lineage/direct/{id}:
    delete:
      consumes:
        - application/json
      description: Delete a direct lineage connection by its ID
      operationId: deleteLineageDirectID
      parameters:
        - description: Edge ID
          format: uuid
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Delete direct lineage
      tags:
        - lineage
    get:
      consumes:
        - application/json
      description: Get a specific direct lineage connection by its ID
      operationId: getLineageDirectID
      parameters:
        - description: Edge ID
          format: uuid
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/LineageEdge'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get direct lineage by ID
      tags:
        - lineage
  /api/v1/mcp:
    post:
      consumes:
        - application/json
      description: >-
        JSON-RPC 2.0 over the MCP Streamable HTTP transport. Requires
        assets:view, glossary:view and teams:view.
      operationId: postMcp
      parameters:
        - description: JSON-RPC 2.0 request
          in: body
          name: request
          required: true
          schema:
            additionalProperties: true
            type: object
      produces:
        - application/json
      responses:
        '200':
          description: JSON-RPC 2.0 response
          schema:
            additionalProperties: true
            type: object
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: MCP endpoint
      tags:
        - mcp
  /api/v1/metrics:
    get:
      consumes:
        - application/json
      description: Get aggregated metrics for dashboard display
      operationId: getMetrics
      parameters:
        - description: Start time (ISO 8601)
          in: query
          name: start
          required: true
          type: string
        - description: End time (ISO 8601)
          in: query
          name: end
          required: true
          type: string
        - collectionFormat: csv
          description: Filter by metric names
          in: query
          items:
            type: string
          name: metric_names
          type: array
        - default: avg
          description: Aggregation type
          enum:
            - avg
            - sum
            - max
            - min
          in: query
          name: aggregation
          type: string
        - description: Time bucket size
          enum:
            - 1m
            - 5m
            - 1h
            - 1d
          in: query
          name: bucket_size
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/GetMetricsResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get metrics for UI
      tags:
        - metrics
  /api/v1/metrics/assets/by-owner:
    get:
      description: Get asset counts grouped by owner
      operationId: getMetricsAssetsByOwner
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/AssetsByOwnerResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get assets by owner
      tags:
        - metrics
  /api/v1/metrics/assets/by-provider:
    get:
      description: Get asset counts grouped by provider
      operationId: getMetricsAssetsByProvider
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/AssetsByProviderResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get assets by provider
      tags:
        - metrics
  /api/v1/metrics/assets/by-type:
    get:
      description: Get asset counts grouped by type
      operationId: getMetricsAssetsByType
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/AssetsByTypeResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get assets by type
      tags:
        - metrics
  /api/v1/metrics/assets/total:
    get:
      description: Get the total number of assets
      operationId: getMetricsAssetsTotal
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/TotalAssetsResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get total assets count
      tags:
        - metrics
  /api/v1/metrics/assets/with-schemas:
    get:
      description: Get the count of assets that have schemas defined
      operationId: getMetricsAssetsWithSchemas
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/AssetsWithSchemasResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get assets with schemas count
      tags:
        - metrics
  /api/v1/metrics/top-assets:
    get:
      description: Get the most viewed assets
      operationId: getMetricsTopAssets
      parameters:
        - description: Start time (ISO 8601)
          in: query
          name: start
          required: true
          type: string
        - description: End time (ISO 8601)
          in: query
          name: end
          required: true
          type: string
        - default: 10
          description: Number of results
          in: query
          name: limit
          type: integer
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            items:
              $ref: '#/definitions/AssetCount'
            type: array
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get top viewed assets
      tags:
        - metrics
  /api/v1/metrics/top-queries:
    get:
      description: Get the most popular search queries
      operationId: getMetricsTopQueries
      parameters:
        - description: Start time (ISO 8601)
          in: query
          name: start
          required: true
          type: string
        - description: End time (ISO 8601)
          in: query
          name: end
          required: true
          type: string
        - default: 10
          description: Number of results
          in: query
          name: limit
          type: integer
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            items:
              $ref: '#/definitions/QueryCount'
            type: array
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get top search queries
      tags:
        - metrics
  /api/v1/owners/search:
    get:
      consumes:
        - application/json
      description: Search for asset owners (users and teams)
      operationId: getOwnersSearch
      parameters:
        - description: Search query
          in: query
          name: q
          required: true
          type: string
        - default: 20
          description: Maximum number of results
          in: query
          name: limit
          type: integer
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/SearchOwnersResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Search owners
      tags:
        - owners
  /api/v1/permissions:
    get:
      description: List all defined permissions grouped by resource type
      operationId: getPermissions
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            items:
              $ref: '#/definitions/RolePermission'
            type: array
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: List all permissions
      tags:
        - roles
  /api/v1/pipelines/{pipelineName}:
    delete:
      description: Delete all resources ever created by a pipeline (across all sources)
      operationId: deletePipelinesPipelineName
      parameters:
        - description: Pipeline Name
          in: path
          name: pipelineName
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/DestroyRunResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Destroy pipeline
      tags:
        - pipelines
  /api/v1/plugins:
    get:
      operationId: getPlugins
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ListPluginsResponse'
      summary: List registered plugins
      tags:
        - plugins
  /api/v1/plugins/aws/credentials/status:
    get:
      description: >-
        Detects if AWS credentials are available from environment or config
        files
      operationId: getPluginsAwsCredentialsStatus
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/AWSCredentialStatus'
      summary: Get AWS credential detection status
      tags:
        - plugins
  /api/v1/products/:
    post:
      consumes:
        - application/json
      description: Create a new data product with owners and optional membership rules
      operationId: postProducts
      parameters:
        - description: Data product to create
          in: body
          name: product
          required: true
          schema:
            $ref: '#/definitions/CreateDataProductRequest'
      produces:
        - application/json
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/DataProduct'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Create data product
      tags:
        - products
  /api/v1/products/{id}:
    delete:
      description: Delete a data product by ID
      operationId: deleteProductsID
      parameters:
        - description: Data Product ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            additionalProperties:
              type: string
            type: object
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Delete data product
      tags:
        - products
    get:
      description: Get a data product by ID
      operationId: getProductsID
      parameters:
        - description: Data Product ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/DataProduct'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get data product
      tags:
        - products
    put:
      consumes:
        - application/json
      description: Update an existing data product
      operationId: putProductsID
      parameters:
        - description: Data Product ID
          in: path
          name: id
          required: true
          type: string
        - description: Fields to update
          in: body
          name: product
          required: true
          schema:
            $ref: '#/definitions/UpdateDataProductRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/DataProduct'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Update data product
      tags:
        - products
  /api/v1/products/assets/{id}:
    get:
      description: Get the manually added assets of a data product
      operationId: getProductsAssetsID
      parameters:
        - description: Data Product ID
          in: path
          name: id
          required: true
          type: string
        - default: 20
          description: Maximum number of assets to return
          in: query
          name: limit
          type: integer
        - default: 0
          description: Number of assets to skip
          in: query
          name: offset
          type: integer
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/DataProductAssetsResult'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get data product assets
      tags:
        - products
    post:
      consumes:
        - application/json
      description: Manually add assets to a data product
      operationId: postProductsAssetsID
      parameters:
        - description: Data Product ID
          in: path
          name: id
          required: true
          type: string
        - description: Asset IDs to add
          in: body
          name: assets
          required: true
          schema:
            $ref: '#/definitions/AddDataProductAssetsRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            additionalProperties:
              type: string
            type: object
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Add data product assets
      tags:
        - products
  /api/v1/products/assets/{id}/{assetId}:
    delete:
      description: Remove a manually added asset from a data product
      operationId: deleteProductsAssetsIDAssetID
      parameters:
        - description: Data Product ID
          in: path
          name: id
          required: true
          type: string
        - description: Asset ID
          in: path
          name: assetId
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            additionalProperties:
              type: string
            type: object
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Remove data product asset
      tags:
        - products
  /api/v1/products/images/{id}:
    get:
      description: List all images for a data product
      operationId: getProductsImagesID
      parameters:
        - description: Data Product ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            additionalProperties: true
            type: object
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: List product images
      tags:
        - products
  /api/v1/products/images/{id}/{purpose}:
    delete:
      description: Delete an icon or header image for a data product
      operationId: deleteProductsImagesIDPurpose
      parameters:
        - description: Data Product ID
          in: path
          name: id
          required: true
          type: string
        - description: Image purpose (icon or header)
          in: path
          name: purpose
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            additionalProperties:
              type: string
            type: object
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Delete product image
      tags:
        - products
    get:
      description: Get an icon or header image for a data product
      operationId: getProductsImagesIDPurpose
      parameters:
        - description: Data Product ID
          in: path
          name: id
          required: true
          type: string
        - description: Image purpose (icon or header)
          in: path
          name: purpose
          required: true
          type: string
      produces:
        - image/jpeg
        - image/png
        - image/gif
        - image/webp
      responses:
        '200':
          description: OK
          schema:
            type: file
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get product image
      tags:
        - products
    post:
      consumes:
        - multipart/form-data
      description: Upload an icon or header image for a data product
      operationId: postProductsImagesIDPurpose
      parameters:
        - description: Data Product ID
          in: path
          name: id
          required: true
          type: string
        - description: Image purpose (icon or header)
          in: path
          name: purpose
          required: true
          type: string
        - description: Image file
          in: formData
          name: file
          required: true
          type: file
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ProductImageMeta'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Upload product image
      tags:
        - products
  /api/v1/products/list:
    get:
      description: Retrieve a paginated list of data products
      operationId: getProductsList
      parameters:
        - default: 20
          description: Maximum number of data products to return
          in: query
          name: limit
          type: integer
        - default: 0
          description: Number of data products to skip
          in: query
          name: offset
          type: integer
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/DataProductListResult'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: List data products
      tags:
        - products
  /api/v1/products/resolved-assets/{id}:
    get:
      description: >-
        Get all assets of a data product, both manually added and matched by
        rules
      operationId: getProductsResolvedAssetsID
      parameters:
        - description: Data Product ID
          in: path
          name: id
          required: true
          type: string
        - default: 20
          description: Maximum number of assets to return
          in: query
          name: limit
          type: integer
        - default: 0
          description: Number of assets to skip
          in: query
          name: offset
          type: integer
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/DataProductResolvedAssets'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get resolved data product assets
      tags:
        - products
  /api/v1/products/rule-preview:
    post:
      consumes:
        - application/json
      description: Preview which assets would match a rule configuration
      operationId: postProductsRulePreview
      parameters:
        - description: Rule to preview
          in: body
          name: rule
          required: true
          schema:
            $ref: '#/definitions/DataProductRuleRequest'
        - default: 20
          description: Maximum number of matching assets to return
          in: query
          name: limit
          type: integer
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/DataProductRulePreview'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Preview data product rule
      tags:
        - products
  /api/v1/products/rules/{id}:
    get:
      description: Get the membership rules of a data product
      operationId: getProductsRulesID
      parameters:
        - description: Data Product ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/DataProductRulesResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get data product rules
      tags:
        - products
    post:
      consumes:
        - application/json
      description: Create a membership rule for a data product
      operationId: postProductsRulesID
      parameters:
        - description: Data Product ID
          in: path
          name: id
          required: true
          type: string
        - description: Rule to create
          in: body
          name: rule
          required: true
          schema:
            $ref: '#/definitions/DataProductRuleRequest'
      produces:
        - application/json
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/DataProductRule'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Create data product rule
      tags:
        - products
  /api/v1/products/rules/{id}/{ruleId}:
    delete:
      description: Delete a membership rule from a data product
      operationId: deleteProductsRulesIDRuleID
      parameters:
        - description: Data Product ID
          in: path
          name: id
          required: true
          type: string
        - description: Rule ID
          in: path
          name: ruleId
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            additionalProperties:
              type: string
            type: object
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Delete data product rule
      tags:
        - products
    put:
      consumes:
        - application/json
      description: Update a membership rule of a data product
      operationId: putProductsRulesIDRuleID
      parameters:
        - description: Data Product ID
          in: path
          name: id
          required: true
          type: string
        - description: Rule ID
          in: path
          name: ruleId
          required: true
          type: string
        - description: Rule fields to update
          in: body
          name: rule
          required: true
          schema:
            $ref: '#/definitions/DataProductRuleRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/DataProductRule'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Update data product rule
      tags:
        - products
  /api/v1/products/search:
    get:
      description: Search data products by name, description, and tags
      operationId: getProductsSearch
      parameters:
        - description: Search query
          in: query
          name: q
          type: string
        - description: Comma-separated list of tags to filter by
          in: query
          name: tags
          type: string
        - default: 20
          description: Maximum number of data products to return
          in: query
          name: limit
          type: integer
        - default: 0
          description: Number of data products to skip
          in: query
          name: offset
          type: integer
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/DataProductListResult'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Search data products
      tags:
        - products
  /api/v1/roles:
    get:
      description: List all active roles with user counts and permissions
      operationId: getRoles
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            items:
              $ref: '#/definitions/Role'
            type: array
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: List roles
      tags:
        - roles
    post:
      consumes:
        - application/json
      description: Create a new role with optional initial permissions
      operationId: postRoles
      parameters:
        - description: Role creation request
          in: body
          name: role
          required: true
          schema:
            $ref: '#/definitions/v1_roles.createRoleRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Role'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Create a role
      tags:
        - roles
  /api/v1/roles/{id}:
    delete:
      description: >-
        Soft-delete a role. Fails if the role is a system role or has active
        user assignments.
      operationId: deleteRolesID
      parameters:
        - description: Role ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '204':
          description: No Content
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '422':
          description: Unprocessable Entity
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Delete a role
      tags:
        - roles
    get:
      description: Get a role by ID with its permissions
      operationId: getRolesID
      parameters:
        - description: Role ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Role'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get a role
      tags:
        - roles
    patch:
      consumes:
        - application/json
      description: Update a role's name or description. System roles cannot be renamed.
      operationId: patchRolesID
      parameters:
        - description: Role ID
          in: path
          name: id
          required: true
          type: string
        - description: Role update request
          in: body
          name: role
          required: true
          schema:
            $ref: '#/definitions/v1_roles.updateRoleRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Role'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '422':
          description: Unprocessable Entity
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Update a role
      tags:
        - roles
  /api/v1/roles/{id}/permissions:
    post:
      consumes:
        - application/json
      description: >-
        Atomically replace all permissions on a role. System roles enforce a
        minimum permission floor.
      operationId: postRolesIDPermissions
      parameters:
        - description: Role ID
          in: path
          name: id
          required: true
          type: string
        - description: Permission IDs to assign
          in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/v1_roles.replacePermissionsRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Role'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '422':
          description: Unprocessable Entity
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Replace role permissions
      tags:
        - roles
  /api/v1/runs:
    get:
      description: Get paginated list of runs with filtering
      operationId: getRuns
      parameters:
        - description: Comma-separated list of pipeline names
          in: query
          name: pipelines
          type: string
        - description: Comma-separated list of statuses
          in: query
          name: statuses
          type: string
        - default: 50
          description: Number of results per page
          in: query
          name: limit
          type: integer
        - default: 0
          description: Number of results to skip
          in: query
          name: offset
          type: integer
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            properties:
              limit:
                type: integer
              offset:
                type: integer
              pipelines:
                items:
                  type: string
                type: array
              runs:
                items:
                  $ref: '#/definitions/PluginRun'
                type: array
              total:
                type: integer
            type: object
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: List runs
      tags:
        - runs
  /api/v1/runs/{id}:
    get:
      description: Get a specific run by ID
      operationId: getRunsID
      parameters:
        - description: Run ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/PluginRun'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get run
      tags:
        - runs
  /api/v1/runs/{id}/entities:
    get:
      description: Get paginated list of entities for a specific run
      operationId: getRunsIDEntities
      parameters:
        - description: Run ID
          in: path
          name: id
          required: true
          type: string
        - description: Filter by entity type (asset, lineage, documentation)
          in: query
          name: entity_type
          type: string
        - description: Filter by status (created, updated, deleted, failed)
          in: query
          name: status
          type: string
        - default: 100
          description: Number of results per page
          in: query
          name: limit
          type: integer
        - default: 0
          description: Number of results to skip
          in: query
          name: offset
          type: integer
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/RunEntitiesResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get run entities
      tags:
        - runs
  /api/v1/runs/assets/batch:
    post:
      consumes:
        - application/json
      description: Create/update assets within a run
      operationId: postRunsAssetsBatch
      parameters:
        - description: Batch create request
          in: body
          name: request
          required: true
          schema:
            $ref: '#/definitions/BatchCreateRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/BatchCreateResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Batch create assets
      tags:
        - runs
  /api/v1/runs/cleanup:
    post:
      description: Mark runs as failed if they've been running too long without updates
      operationId: postRunsCleanup
      responses:
        '200':
          description: OK
          schema:
            additionalProperties:
              type: integer
            type: object
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Cleanup stale runs
      tags:
        - runs
  /api/v1/runs/complete:
    post:
      consumes:
        - application/json
      description: Complete a run with results
      operationId: postRunsComplete
      parameters:
        - description: Complete run request
          in: body
          name: request
          required: true
          schema:
            $ref: '#/definitions/CompleteRunRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            additionalProperties:
              type: string
            type: object
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Complete run
      tags:
        - runs
  /api/v1/runs/start:
    post:
      consumes:
        - application/json
      description: Start a new run for tracking
      operationId: postRunsStart
      parameters:
        - description: Start run request
          in: body
          name: request
          required: true
          schema:
            $ref: '#/definitions/StartRunRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/PluginRun'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Start run
      tags:
        - runs
  /api/v1/search:
    get:
      description: Search across assets, glossary terms, teams, and users
      operationId: getSearch
      parameters:
        - description: Search query
          in: query
          name: q
          required: true
          type: string
        - collectionFormat: csv
          description: Filter by result types (asset, glossary, team, user)
          in: query
          items:
            type: string
          name: types
          type: array
        - default: 20
          description: Limit
          in: query
          name: limit
          type: integer
        - default: 0
          description: Offset
          in: query
          name: offset
          type: integer
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/SearchResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Unified search
      tags:
        - search
  /api/v1/service-accounts:
    get:
      description: Get all service accounts
      operationId: getServiceAccounts
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            items:
              $ref: '#/definitions/ServiceAccount'
            type: array
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: List service accounts
      tags:
        - service_accounts
    post:
      consumes:
        - application/json
      description: Create a new service account
      operationId: postServiceAccounts
      parameters:
        - description: Service account
          in: body
          name: account
          required: true
          schema:
            $ref: '#/definitions/CreateServiceAccountRequest'
      produces:
        - application/json
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/ServiceAccount'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Create service account
      tags:
        - service_accounts
  /api/v1/service-accounts/{id}:
    delete:
      description: Soft-delete a service account
      operationId: deleteServiceAccountsID
      parameters:
        - description: Service account ID
          in: path
          name: id
          required: true
          type: string
      responses:
        '204':
          description: No Content
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Delete service account
      tags:
        - service_accounts
    get:
      description: Get a service account by ID
      operationId: getServiceAccountsID
      parameters:
        - description: Service account ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ServiceAccount'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get service account
      tags:
        - service_accounts
    patch:
      consumes:
        - application/json
      description: Update a service account
      operationId: patchServiceAccountsID
      parameters:
        - description: Service account ID
          in: path
          name: id
          required: true
          type: string
        - description: Update fields
          in: body
          name: account
          required: true
          schema:
            $ref: '#/definitions/UpdateServiceAccountRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ServiceAccount'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Update service account
      tags:
        - service_accounts
  /api/v1/service-accounts/{id}/api-keys:
    get:
      description: Get all API keys for a service account
      operationId: getServiceAccountsIDAPIKeys
      parameters:
        - description: Service account ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            items:
              $ref: '#/definitions/ServiceAccountAPIKey'
            type: array
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: List API keys for a service account
      tags:
        - service_accounts
    post:
      consumes:
        - application/json
      description: Create a new API key. The plaintext key is only returned once.
      operationId: postServiceAccountsIDAPIKeys
      parameters:
        - description: Service account ID
          in: path
          name: id
          required: true
          type: string
        - description: API key details
          in: body
          name: key
          required: true
          schema:
            $ref: '#/definitions/CreateServiceAccountAPIKeyRequest'
      produces:
        - application/json
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/ServiceAccountAPIKey'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Create API key for a service account
      tags:
        - service_accounts
  /api/v1/service-accounts/{id}/api-keys/{keyId}:
    delete:
      description: Delete an API key for a service account
      operationId: deleteServiceAccountsIDAPIKeysKeyID
      parameters:
        - description: Service account ID
          in: path
          name: id
          required: true
          type: string
        - description: API key ID
          in: path
          name: keyId
          required: true
          type: string
      responses:
        '204':
          description: No Content
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Delete an API key
      tags:
        - service_accounts
  /api/v1/sso-providers:
    get:
      description: >-
        Read-only view of SSO providers wired via server config. Editing is done
        in config.yaml.
      operationId: getSsoProviders
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/SSOProvidersResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: List configured SSO providers (admin)
      tags:
        - auth
  /api/v1/sso/team-mappings:
    get:
      consumes:
        - application/json
      description: Get a list of SSO group to team mappings
      operationId: getSsoTeamMappings
      parameters:
        - description: Filter by SSO provider
          in: query
          name: provider
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ListSSOMappingsResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: List SSO team mappings
      tags:
        - sso
    post:
      consumes:
        - application/json
      description: Create a new SSO group to team mapping
      operationId: postSsoTeamMappings
      parameters:
        - description: SSO mapping creation request
          in: body
          name: mapping
          required: true
          schema:
            $ref: '#/definitions/CreateSSOMappingRequest'
      produces:
        - application/json
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/SSOTeamMapping'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Create an SSO team mapping
      tags:
        - sso
  /api/v1/sso/team-mappings/{id}:
    delete:
      consumes:
        - application/json
      description: Delete an SSO team mapping by its ID
      operationId: deleteSsoTeamMappingsID
      parameters:
        - description: SSO mapping ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/MessageResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Delete an SSO team mapping
      tags:
        - sso
    get:
      consumes:
        - application/json
      description: Get an SSO team mapping by its ID
      operationId: getSsoTeamMappingsID
      parameters:
        - description: SSO mapping ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/SSOTeamMapping'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get an SSO team mapping
      tags:
        - sso
    put:
      consumes:
        - application/json
      description: Update an SSO team mapping by its ID
      operationId: putSsoTeamMappingsID
      parameters:
        - description: SSO mapping ID
          in: path
          name: id
          required: true
          type: string
        - description: SSO mapping update request
          in: body
          name: mapping
          required: true
          schema:
            $ref: '#/definitions/UpdateSSOMappingRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/MessageResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Update an SSO team mapping
      tags:
        - sso
  /api/v1/teams:
    get:
      consumes:
        - application/json
      description: Get a paginated list of teams
      operationId: getTeams
      parameters:
        - default: 50
          description: Number of items to return
          in: query
          name: limit
          type: integer
        - default: 0
          description: Number of items to skip
          in: query
          name: offset
          type: integer
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ListTeamsResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: List teams
      tags:
        - teams
    post:
      consumes:
        - application/json
      description: Create a new team
      operationId: postTeams
      parameters:
        - description: Team creation request
          in: body
          name: team
          required: true
          schema:
            $ref: '#/definitions/CreateTeamRequest'
      produces:
        - application/json
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/Team'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Create a team
      tags:
        - teams
  /api/v1/teams/{id}:
    delete:
      consumes:
        - application/json
      description: Delete a team by its ID
      operationId: deleteTeamsID
      parameters:
        - description: Team ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/MessageResponse'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Delete a team
      tags:
        - teams
    get:
      consumes:
        - application/json
      description: Get a team by its ID
      operationId: getTeamsID
      parameters:
        - description: Team ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Team'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get a team
      tags:
        - teams
    put:
      consumes:
        - application/json
      description: Update a team's fields by its ID
      operationId: putTeamsID
      parameters:
        - description: Team ID
          in: path
          name: id
          required: true
          type: string
        - description: Team update request
          in: body
          name: team
          required: true
          schema:
            $ref: '#/definitions/UpdateTeamRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/MessageResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Update a team
      tags:
        - teams
  /api/v1/teams/{id}/members:
    get:
      consumes:
        - application/json
      description: Get the members of a team
      operationId: getTeamsIDMembers
      parameters:
        - description: Team ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ListMembersResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: List team members
      tags:
        - teams
    post:
      consumes:
        - application/json
      description: Add a user as a member of a team
      operationId: postTeamsIDMembers
      parameters:
        - description: Team ID
          in: path
          name: id
          required: true
          type: string
        - description: Member addition request
          in: body
          name: member
          required: true
          schema:
            $ref: '#/definitions/AddMemberRequest'
      produces:
        - application/json
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/MessageResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/ErrorResponse'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Add a team member
      tags:
        - teams
  /api/v1/teams/{id}/members/{userId}:
    delete:
      consumes:
        - application/json
      description: Remove a user from a team
      operationId: deleteTeamsIDMembersUserID
      parameters:
        - description: Team ID
          in: path
          name: id
          required: true
          type: string
        - description: User ID
          in: path
          name: userId
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/MessageResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Remove a team member
      tags:
        - teams
  /api/v1/teams/{id}/members/{userId}/convert-to-manual:
    post:
      consumes:
        - application/json
      description: Convert an SSO-managed team member to a manually managed member
      operationId: postTeamsIDMembersUserIDConvertToManual
      parameters:
        - description: Team ID
          in: path
          name: id
          required: true
          type: string
        - description: User ID
          in: path
          name: userId
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/MessageResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Convert member to manual
      tags:
        - teams
  /api/v1/teams/{id}/members/{userId}/role:
    put:
      consumes:
        - application/json
      description: Update the role of a team member
      operationId: putTeamsIDMembersUserIDRole
      parameters:
        - description: Team ID
          in: path
          name: id
          required: true
          type: string
        - description: User ID
          in: path
          name: userId
          required: true
          type: string
        - description: Role update request
          in: body
          name: role
          required: true
          schema:
            $ref: '#/definitions/UpdateMemberRoleRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/MessageResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Update member role
      tags:
        - teams
  /api/v1/ui/config:
    get:
      description: Get UI configuration including banner settings
      operationId: getUIConfig
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/UIConfigResponse'
      summary: Get UI configuration
      tags:
        - ui
  /api/v1/users:
    get:
      consumes:
        - application/json
      description: Get a list of users with optional filtering
      operationId: getUsers
      parameters:
        - default: 50
          description: Number of items to return
          in: query
          name: limit
          type: integer
        - default: 0
          description: Number of items to skip
          in: query
          name: offset
          type: integer
        - description: Search query for username or email
          in: query
          name: query
          type: string
        - collectionFormat: csv
          description: Filter by role IDs
          in: query
          items:
            type: string
          name: role_ids
          type: array
        - description: Filter by active status
          in: query
          name: active
          type: boolean
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ListUsersResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: List users
      tags:
        - users
    post:
      consumes:
        - application/json
      description: Create a new user in the system
      operationId: postUsers
      parameters:
        - description: User creation request
          in: body
          name: user
          required: true
          schema:
            $ref: '#/definitions/CreateUserInput'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/User'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Create a new user
      tags:
        - users
  /api/v1/users/{id}:
    delete:
      consumes:
        - application/json
      description: Delete a user from the system
      operationId: deleteUsersID
      parameters:
        - description: User ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '204':
          description: No Content
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Delete a user
      tags:
        - users
    get:
      consumes:
        - application/json
      description: Get detailed information about a specific user
      operationId: getUsersID
      parameters:
        - description: User ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/User'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get a user by ID
      tags:
        - users
    put:
      consumes:
        - application/json
      description: Update user information
      operationId: putUsersID
      parameters:
        - description: User ID
          in: path
          name: id
          required: true
          type: string
        - description: User update request
          in: body
          name: user
          required: true
          schema:
            $ref: '#/definitions/UpdateUserInput'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/User'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Update a user
      tags:
        - users
  /api/v1/users/apikeys:
    get:
      consumes:
        - application/json
      description: Get all API keys for a user
      operationId: getUsersApikeys
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            items:
              $ref: '#/definitions/APIKey'
            type: array
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: List API keys
      tags:
        - users
    post:
      consumes:
        - application/json
      description: Create a new API key for a user
      operationId: postUsersApikeys
      parameters:
        - description: API key creation request
          in: body
          name: key
          required: true
          schema:
            $ref: '#/definitions/CreateAPIKeyRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/APIKey'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Create API key
      tags:
        - users
  /api/v1/users/apikeys/{id}:
    delete:
      consumes:
        - application/json
      description: Delete an API key
      operationId: deleteUsersApikeysID
      parameters:
        - description: API key ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Delete API key
      tags:
        - users
  /api/v1/users/login:
    post:
      consumes:
        - application/json
      description: Authenticate a user with username/email and password
      operationId: postUsersLogin
      parameters:
        - description: Login credentials
          in: body
          name: credentials
          required: true
          schema:
            $ref: '#/definitions/LoginRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/TokenResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
      summary: Login user
      tags:
        - users
  /api/v1/users/me:
    get:
      consumes:
        - application/json
      description: Get detailed information about the currently authenticated user
      operationId: getUsersMe
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/User'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Get current user profile
      tags:
        - users
  /api/v1/users/oauth/link:
    post:
      consumes:
        - application/json
      description: Link an OAuth account to an existing user
      operationId: postUsersOauthLink
      parameters:
        - description: OAuth account link request
          in: body
          name: link
          required: true
          schema:
            $ref: '#/definitions/OAuthLinkRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Link OAuth account
      tags:
        - users
  /api/v1/users/oauth/unlink/{id}/{provider}:
    delete:
      consumes:
        - application/json
      description: Unlink an OAuth account from a user
      operationId: deleteUsersOauthUnlinkIDProvider
      parameters:
        - description: User ID
          in: path
          name: id
          required: true
          type: string
        - description: OAuth provider
          in: path
          name: provider
          required: true
          type: string
      produces:
        - application/json
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Unlink OAuth account
      tags:
        - users
  /api/v1/users/preferences:
    put:
      consumes:
        - application/json
      description: Update preferences for the current user
      operationId: putUsersPreferences
      parameters:
        - description: User preferences
          in: body
          name: preferences
          required: true
          schema:
            additionalProperties: true
            type: object
      produces:
        - application/json
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Update user preferences
      tags:
        - users
  /api/v1/users/update-password:
    post:
      consumes:
        - application/json
      description: Update current user's password
      operationId: postUsersUpdatePassword
      parameters:
        - description: Password update request
          in: body
          name: request
          required: true
          schema:
            $ref: '#/definitions/UpdatePasswordRequest'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/TokenResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      summary: Update user password
      tags:
        - users
  /auth-providers:
    get:
      description: Returns the enabled auth providers without sensitive data
      operationId: getAuthProviders
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/AuthConfig'
      summary: Get auth configuration
      tags:
        - auth
  /auth/{provider}/callback:
    get:
      description: Processes the OAuth callback from any provider
      operationId: getAuthProviderCallback
      parameters:
        - description: OAuth provider (okta, google, github, etc.)
          in: path
          name: provider
          required: true
          type: string
        - description: Authorization code
          in: query
          name: code
          required: true
          type: string
        - description: State parameter for CSRF protection
          in: query
          name: state
          required: true
          type: string
      produces:
        - application/json
      responses:
        '307':
          description: Temporary Redirect
          schema:
            type: string
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      summary: Handle OAuth callback
      tags:
        - auth
  /auth/{provider}/login:
    get:
      description: Redirects the user to the OAuth provider for authentication
      operationId: getAuthProviderLogin
      parameters:
        - description: OAuth provider (okta, google, github, etc.)
          in: path
          name: provider
          required: true
          type: string
      produces:
        - application/json
      responses:
        '307':
          description: Temporary Redirect
          schema:
            type: string
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      summary: Initiate OAuth login
      tags:
        - auth
  /oauth/token:
    post:
      consumes:
        - application/x-www-form-urlencoded
      description: >-
        Handles authorization_code grants (with PKCE) and token exchange (RFC
        8693).

        For token-exchange, supported subject_token_type values are

        urn:ietf:params:oauth:token-type:id_token and
        urn:ietf:params:oauth:token-type:access_token.
      operationId: postOauthToken
      parameters:
        - description: >-
            authorization_code or
            urn:ietf:params:oauth:grant-type:token-exchange
          in: formData
          name: grant_type
          required: true
          type: string
        - description: Token to exchange (token-exchange grant only)
          in: formData
          name: subject_token
          type: string
        - description: id_token or access_token URI (token-exchange grant only)
          in: formData
          name: subject_token_type
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/TokenExchangeResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/OAuthErrorResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/OAuthErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/OAuthErrorResponse'
      summary: OAuth token endpoint
      tags:
        - auth
securityDefinitions:
  ApiKeyAuth:
    in: header
    name: X-API-Key
    type: apiKey
  BearerAuth:
    description: Type "Bearer" followed by a space and JWT.
    in: header
    name: Authorization
    type: apiKey
swagger: '2.0'