basePath: /api/v1
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
  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
      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
      lineage:
        items:
          $ref: '#/definitions/CreateLineageRequest'
        type: array
      pipeline_name:
        type: string
      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
  CreateDocRequest:
    properties:
      asset_mrn:
        type: string
      content:
        type: string
      type:
        type: string
    type: object
  CreateLineageRequest:
    properties:
      source:
        type: string
      target:
        type: string
      type:
        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
  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
  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:
        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
    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
  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:
      description:
        type: string
      id:
        type: string
      name:
        type: string
      permissions:
        items:
          $ref: '#/definitions/Permission'
        type: array
    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:
          type: string
        type: array
      tags:
        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_updated:
        type: integer
      documentation_added:
        type: integer
      duration_seconds:
        type: integer
      errors_count:
        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
  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
  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
  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
  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/Role'
        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
  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
info:
  contact: {}
  description: API for interacting with Marmot
  license:
    name: MIT
    url: https://opensource.org/license/MIT
  title: Marmot API
  version: '0.1'
paths:
  /admin/search/reindex:
    get:
      description: >-
        Check whether a search reindex is currently running and whether
        Elasticsearch is configured.
      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'
      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.
      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'
      summary: Start search reindex
      tags:
        - admin
  /agents/{asset_id}/activity:
    get:
      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'
      summary: Agent activity
      tags:
        - agents
  /agents/{asset_id}/runs:
    get:
      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'
      summary: List agent runs
      tags:
        - agents
  /agents/{asset_id}/stats:
    get:
      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'
      summary: Agent stats
      tags:
        - agents
  /agents/runs:
    post:
      consumes:
        - application/json
      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'
      summary: Record agent run
      tags:
        - agents
  /api/v1/assets/preview/{id}:
    get:
      description: >-
        Fetches sample data from the asset's data source. Requires
        assets:preview permission.
      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'
      summary: Get preview data for an asset
      tags:
        - assets
  /api/v1/ingestion/runs:
    get:
      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'
      summary: List ingestion job runs
      tags:
        - ingestion
  /api/v1/ingestion/runs/{id}:
    get:
      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'
      summary: Get a job run by ID
      tags:
        - ingestion
  /api/v1/ingestion/runs/{id}/cancel:
    post:
      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'
      summary: Cancel a running job
      tags:
        - ingestion
  /api/v1/ingestion/runs/{id}/entities:
    get:
      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'
      summary: Get entities for a job run
      tags:
        - ingestion
  /api/v1/ingestion/schedules:
    get:
      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'
      summary: List ingestion schedules
      tags:
        - ingestion
    post:
      consumes:
        - application/json
      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'
      summary: Create a new ingestion schedule
      tags:
        - ingestion
  /api/v1/ingestion/schedules/{id}:
    delete:
      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'
      summary: Delete an ingestion schedule
      tags:
        - ingestion
    get:
      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'
      summary: Get an ingestion schedule by ID
      tags:
        - ingestion
    put:
      consumes:
        - application/json
      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'
      summary: Update an ingestion schedule
      tags:
        - ingestion
  /api/v1/ingestion/schedules/{id}/trigger:
    post:
      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'
      summary: Manually trigger an ingestion schedule
      tags:
        - ingestion
  /api/v1/ingestion/validate:
    post:
      consumes:
        - application/json
      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'
      summary: Validate plugin configuration
      tags:
        - ingestion
  /api/v1/lineage:
    post:
      consumes:
        - application/json
      description: Process OpenLineage run events and update assets/lineage accordingly
      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'
      summary: Ingest OpenLineage event
      tags:
        - lineage
  /api/v1/plugins/aws/credentials/status:
    get:
      description: >-
        Detects if AWS credentials are available from environment or config
        files
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/AWSCredentialStatus'
      summary: Get AWS credential detection status
      tags:
        - plugins
  /asset-rules:
    post:
      consumes:
        - application/json
      description: Create a new asset rule that applies enrichments to matching assets
      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'
      summary: Create an asset rule
      tags:
        - asset-rules
  /asset-rules/{id}:
    delete:
      description: Delete an asset rule by ID
      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'
      summary: Delete an asset rule
      tags:
        - asset-rules
    get:
      description: Get an asset rule by ID
      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'
      summary: Get an asset rule
      tags:
        - asset-rules
    put:
      consumes:
        - application/json
      description: Update an existing asset rule
      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'
      summary: Update an asset rule
      tags:
        - asset-rules
  /asset-rules/assets/{id}:
    get:
      description: Get the list of asset IDs matched by an asset rule
      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'
      summary: Get assets matched by a rule
      tags:
        - asset-rules
  /asset-rules/list:
    get:
      description: List all asset rules with pagination
      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'
      summary: List asset rules
      tags:
        - asset-rules
  /asset-rules/preview:
    post:
      consumes:
        - application/json
      description: Preview which assets would match a rule configuration
      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'
      summary: Preview an asset rule
      tags:
        - asset-rules
  /asset-rules/search:
    get:
      description: Search asset rules by name
      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'
      summary: Search asset rules
      tags:
        - asset-rules
  /assets:
    post:
      consumes:
        - application/json
      description: Create a new asset in the system
      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'
      summary: Create a new asset
      tags:
        - assets
  /assets/{id}:
    delete:
      consumes:
        - application/json
      description: Delete an asset from the system
      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'
      summary: Delete an asset
      tags:
        - assets
    get:
      consumes:
        - application/json
      description: Get detailed information about a specific asset
      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'
      summary: Get an asset by ID
      tags:
        - assets
    put:
      consumes:
        - application/json
      description: Update an existing asset's information
      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'
      summary: Update an asset
      tags:
        - assets
  /assets/{id}/run-history:
    get:
      description: Get paginated run history for a specific asset
      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'
      summary: Get asset run history
      tags:
        - assets
  /assets/{id}/run-history/histogram:
    get:
      description: Get histogram data for asset run history over specified period
      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'
      summary: Get asset run history histogram
      tags:
        - assets
  /assets/by-glossary-term/{term_id}:
    get:
      description: Retrieve all assets associated with a specific glossary term
      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'
      summary: Get assets by glossary term
      tags:
        - assets
  /assets/documentation:
    post:
      consumes:
        - application/json
      description: Create or update documentation for an asset
      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'
      summary: Create asset documentation
      tags:
        - assets
  /assets/documentation/{mrn}:
    get:
      description: Get documentation for a specific asset
      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'
      summary: Get asset documentation
      tags:
        - assets
  /assets/documentation/batch:
    post:
      consumes:
        - application/json
      description: Create or update documentation for multiple assets
      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'
      summary: Batch create documentation
      tags:
        - assets
  /assets/lookup/{type}/{service}/{name}:
    get:
      description: Get an asset by its type, service (provider), and name
      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'
      summary: Lookup asset by type, service, and name
      tags:
        - assets
  /assets/match-pattern:
    get:
      description: Find assets matching a pattern
      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'
      summary: Match asset pattern
      tags:
        - assets
  /assets/my-assets:
    get:
      description: Get assets owned by the current user or their teams
      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'
      summary: Get user's assets
      tags:
        - assets
  /assets/qualified-name/{qualifiedName}:
    get:
      consumes:
        - application/json
      description: Get detailed information about a specific asset using its qualified name
      parameters:
        - description: Asset qualified name
          in: path
          name: qualifiedName
          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'
      summary: Get an asset by qualified name
      tags:
        - assets
  /assets/search:
    get:
      consumes:
        - application/json
      description: Search for assets using query string and filters
      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'
      summary: Search assets
      tags:
        - assets
  /assets/suggestions/metadata/fields:
    get:
      description: Get suggestions for metadata fields and their types
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            items:
              $ref: '#/definitions/MetadataFieldSuggestion'
            type: array
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      summary: Get metadata field suggestions
      tags:
        - assets
  /assets/suggestions/metadata/values:
    get:
      description: Get suggestions for values of a specific metadata field
      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'
      summary: Get metadata value suggestions
      tags:
        - assets
  /assets/suggestions/tags:
    get:
      description: Get suggestions for asset tags
      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'
      summary: Get tag suggestions
      tags:
        - assets
  /assets/summary:
    get:
      consumes:
        - application/json
      description: Get the total count of assets by type
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/AssetSummaryResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      summary: Get asset summary
      tags:
        - assets
  /assets/tags/{id}:
    delete:
      consumes:
        - application/json
      description: Remove a tag from an existing asset
      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'
      summary: Remove tag from asset
      tags:
        - assets
    post:
      consumes:
        - application/json
      description: Add a new tag to an existing asset
      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'
      summary: Add tag to asset
      tags:
        - assets
  /assets/terms/{id}:
    delete:
      consumes:
        - application/json
      description: Remove a glossary term association from an asset
      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'
      summary: Remove glossary term from asset
      tags:
        - assets
    get:
      description: Retrieve all glossary terms associated with an asset
      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'
      summary: Get asset's glossary terms
      tags:
        - assets
    post:
      consumes:
        - application/json
      description: Associate one or more glossary terms with an asset
      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'
      summary: Add glossary terms to asset
      tags:
        - assets
  /auth-providers:
    get:
      description: Returns the enabled auth providers without sensitive data
      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
      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
      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
  /glossary/:
    post:
      consumes:
        - application/json
      description: Create a new glossary term with name, definition, and optional metadata
      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'
      summary: Create glossary term
      tags:
        - glossary
  /glossary/{id}:
    delete:
      description: Delete a glossary term by its ID
      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'
      summary: Delete glossary term
      tags:
        - glossary
    get:
      description: Retrieve a glossary term by its ID
      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'
      summary: Get glossary term
      tags:
        - glossary
    put:
      consumes:
        - application/json
      description: Update an existing glossary term by its ID
      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'
      summary: Update glossary term
      tags:
        - glossary
  /glossary/ancestors/{id}:
    get:
      description: Retrieve all ancestor terms of a glossary term (parent chain)
      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'
      summary: Get ancestor terms
      tags:
        - glossary
  /glossary/children/{id}:
    get:
      description: Retrieve all child terms of a glossary term
      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'
      summary: Get child terms
      tags:
        - glossary
  /glossary/list:
    get:
      description: Retrieve a paginated list of all glossary terms
      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'
      summary: List glossary terms
      tags:
        - glossary
  /glossary/search:
    get:
      description: Search for glossary terms by query string and filters
      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'
      summary: Search glossary terms
      tags:
        - glossary
  /lineage/assets/{id}:
    get:
      consumes:
        - application/json
      description: Get upstream and downstream lineage for a specific asset
      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
      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'
      summary: Get asset lineage
      tags:
        - lineage
  /lineage/batch:
    post:
      consumes:
        - application/json
      description: Create lineage edges in batch
      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'
      summary: Batch create lineage edges
      tags:
        - lineage
  /lineage/direct:
    post:
      consumes:
        - application/json
      description: >-
        Create a direct lineage connection between two assets and returns the
        created edge
      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'
      summary: Create direct lineage
      tags:
        - lineage
  /lineage/direct/{id}:
    delete:
      consumes:
        - application/json
      description: Delete a direct lineage connection by its ID
      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'
      summary: Delete direct lineage
      tags:
        - lineage
    get:
      consumes:
        - application/json
      description: Get a specific direct lineage connection by its ID
      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'
      summary: Get direct lineage by ID
      tags:
        - lineage
  /metrics:
    get:
      consumes:
        - application/json
      description: Get aggregated metrics for dashboard display
      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'
      summary: Get metrics for UI
      tags:
        - metrics
  /metrics/assets/by-owner:
    get:
      description: Get asset counts grouped by owner
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/AssetsByOwnerResponse'
      summary: Get assets by owner
      tags:
        - metrics
  /metrics/assets/by-provider:
    get:
      description: Get asset counts grouped by provider
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/AssetsByProviderResponse'
      summary: Get assets by provider
      tags:
        - metrics
  /metrics/assets/by-type:
    get:
      description: Get asset counts grouped by type
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/AssetsByTypeResponse'
      summary: Get assets by type
      tags:
        - metrics
  /metrics/assets/total:
    get:
      description: Get the total number of assets
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/TotalAssetsResponse'
      summary: Get total assets count
      tags:
        - metrics
  /metrics/assets/with-schemas:
    get:
      description: Get the count of assets that have schemas defined
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/AssetsWithSchemasResponse'
      summary: Get assets with schemas count
      tags:
        - metrics
  /metrics/top-assets:
    get:
      description: Get the most viewed assets
      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
      summary: Get top viewed assets
      tags:
        - metrics
  /metrics/top-queries:
    get:
      description: Get the most popular search queries
      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
      summary: Get top search queries
      tags:
        - metrics
  /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.
      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
  /owners/search:
    get:
      consumes:
        - application/json
      description: Search for asset owners (users and teams)
      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'
      summary: Search owners
      tags:
        - owners
  /pipelines/{pipelineName}:
    delete:
      description: Delete all resources ever created by a pipeline (across all sources)
      parameters:
        - description: Pipeline Name
          in: path
          name: pipelineName
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/DestroyRunResponse'
      summary: Destroy pipeline
      tags:
        - pipelines
  /products/images/{id}:
    get:
      description: List all images for a data product
      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'
      summary: List product images
      tags:
        - products
  /products/images/{id}/{purpose}:
    delete:
      description: Delete an icon or header image for a data product
      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'
      summary: Delete product image
      tags:
        - products
    get:
      description: Get an icon or header image for a data product
      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'
      summary: Get product image
      tags:
        - products
    post:
      consumes:
        - multipart/form-data
      description: Upload an icon or header image for a data product
      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'
      summary: Upload product image
      tags:
        - products
  /runs:
    get:
      description: Get paginated list of runs with filtering
      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
      summary: List runs
      tags:
        - runs
  /runs/{id}:
    get:
      description: Get a specific run by ID
      parameters:
        - description: Run ID
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/PluginRun'
      summary: Get run
      tags:
        - runs
  /runs/{id}/entities:
    get:
      description: Get paginated list of entities for a specific run
      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'
      summary: Get run entities
      tags:
        - runs
  /runs/assets/batch:
    post:
      consumes:
        - application/json
      description: Create/update assets within a run
      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'
      summary: Batch create assets
      tags:
        - runs
  /runs/cleanup:
    post:
      description: Mark runs as failed if they've been running too long without updates
      responses:
        '200':
          description: OK
          schema:
            additionalProperties:
              type: integer
            type: object
      summary: Cleanup stale runs
      tags:
        - runs
  /runs/complete:
    post:
      consumes:
        - application/json
      description: Complete a run with results
      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
      summary: Complete run
      tags:
        - runs
  /runs/start:
    post:
      consumes:
        - application/json
      description: Start a new run for tracking
      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'
      summary: Start run
      tags:
        - runs
  /search:
    get:
      description: Search across assets, glossary terms, teams, and users
      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'
      summary: Unified search
      tags:
        - search
  /sso/team-mappings:
    get:
      consumes:
        - application/json
      description: Get a list of SSO group to team mappings
      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'
      summary: List SSO team mappings
      tags:
        - sso
    post:
      consumes:
        - application/json
      description: Create a new SSO group to team mapping
      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'
      summary: Create an SSO team mapping
      tags:
        - sso
  /sso/team-mappings/{id}:
    delete:
      consumes:
        - application/json
      description: Delete an SSO team mapping by its ID
      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'
      summary: Delete an SSO team mapping
      tags:
        - sso
    get:
      consumes:
        - application/json
      description: Get an SSO team mapping by its ID
      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'
      summary: Get an SSO team mapping
      tags:
        - sso
    put:
      consumes:
        - application/json
      description: Update an SSO team mapping by its ID
      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'
      summary: Update an SSO team mapping
      tags:
        - sso
  /teams:
    get:
      consumes:
        - application/json
      description: Get a paginated list of teams
      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'
      summary: List teams
      tags:
        - teams
    post:
      consumes:
        - application/json
      description: Create a new team
      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'
      summary: Create a team
      tags:
        - teams
  /teams/{id}:
    delete:
      consumes:
        - application/json
      description: Delete a team by its ID
      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'
      summary: Delete a team
      tags:
        - teams
    get:
      consumes:
        - application/json
      description: Get a team by its ID
      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'
      summary: Get a team
      tags:
        - teams
    put:
      consumes:
        - application/json
      description: Update a team's fields by its ID
      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'
      summary: Update a team
      tags:
        - teams
  /teams/{id}/members:
    get:
      consumes:
        - application/json
      description: Get the members of a team
      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'
      summary: List team members
      tags:
        - teams
    post:
      consumes:
        - application/json
      description: Add a user as a member of a team
      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'
      summary: Add a team member
      tags:
        - teams
  /teams/{id}/members/{userId}:
    delete:
      consumes:
        - application/json
      description: Remove a user from a team
      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'
      summary: Remove a team member
      tags:
        - teams
  /teams/{id}/members/{userId}/convert-to-manual:
    post:
      consumes:
        - application/json
      description: Convert an SSO-managed team member to a manually managed member
      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'
      summary: Convert member to manual
      tags:
        - teams
  /teams/{id}/members/{userId}/role:
    put:
      consumes:
        - application/json
      description: Update the role of a team member
      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'
      summary: Update member role
      tags:
        - teams
  /ui/config:
    get:
      description: Get UI configuration including banner settings
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/UIConfigResponse'
      summary: Get UI configuration
      tags:
        - ui
  /users:
    get:
      consumes:
        - application/json
      description: Get a list of users with optional filtering
      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'
      summary: List users
      tags:
        - users
    post:
      consumes:
        - application/json
      description: Create a new user in the system
      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'
      summary: Create a new user
      tags:
        - users
  /users/{id}:
    delete:
      consumes:
        - application/json
      description: Delete a user from the system
      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'
      summary: Delete a user
      tags:
        - users
    get:
      consumes:
        - application/json
      description: Get detailed information about a specific user
      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'
      summary: Get a user by ID
      tags:
        - users
    put:
      consumes:
        - application/json
      description: Update user information
      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'
      summary: Update a user
      tags:
        - users
  /users/apikeys:
    get:
      consumes:
        - application/json
      description: Get all API keys for a user
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            items:
              $ref: '#/definitions/APIKey'
            type: array
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      summary: List API keys
      tags:
        - users
    post:
      consumes:
        - application/json
      description: Create a new API key for a user
      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'
      summary: Create API key
      tags:
        - users
  /users/apikeys/{id}:
    delete:
      consumes:
        - application/json
      description: Delete an API key
      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'
      summary: Delete API key
      tags:
        - users
  /users/login:
    post:
      consumes:
        - application/json
      description: Authenticate a user with username/email and password
      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
  /users/me:
    get:
      consumes:
        - application/json
      description: Get detailed information about the currently authenticated user
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/User'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Get current user profile
      tags:
        - users
  /users/oauth/link:
    post:
      consumes:
        - application/json
      description: Link an OAuth account to an existing user
      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'
      summary: Link OAuth account
      tags:
        - users
  /users/oauth/unlink/{id}/{provider}:
    delete:
      consumes:
        - application/json
      description: Unlink an OAuth account from a user
      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'
      summary: Unlink OAuth account
      tags:
        - users
  /users/preferences:
    put:
      consumes:
        - application/json
      description: Update preferences for the current user
      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'
      summary: Update user preferences
      tags:
        - users
  /users/update-password:
    post:
      consumes:
        - application/json
      description: Update current user's password
      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'
      summary: Update user password
      tags:
        - users
swagger: '2.0'