{
  "openapi": "3.1.0",
  "info": {
    "title": "Knowledge Hub API",
    "description": "REST API for managing Knowledge Hub entities: Repositories, Knowledge Bases, Sources, Schema Mappings, and Ingestion Jobs, plus consumption usage reporting.",
    "contact": {
      "name": "Knowledge Hub Team"
    },
    "version": "2.0.0"
  },
  "servers": [
    {
      "url": "https://management-api.prod.kh.boomi.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/v1/data-providers": {
      "get": {
        "tags": [
          "data-providers"
        ],
        "summary": "List data providers",
        "description": "List enabled data providers.\n\nReturns list of enabled data providers that can be used to bring data into Knowledge Hub.\n\nRequires a valid Boomi platform JWT (Bearer token); the token's ``account`` claim\nscopes results to the caller's Boomi tenant.\n\nRequired privileges: `KNOWLEDGE_HUB_DATA_PROVIDER_READ`.",
        "operationId": "list_data_providers_api_v1_data_providers_get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "maximum": 1000,
              "minimum": 1,
              "description": "Maximum results to return",
              "default": 50,
              "title": "Limit"
            },
            "description": "Maximum results to return"
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "description": "Pagination offset",
              "default": 0,
              "title": "Offset"
            },
            "description": "Pagination offset"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DataProviderListResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/data-providers/{provider_id}": {
      "get": {
        "tags": [
          "data-providers"
        ],
        "summary": "Get data provider",
        "description": "Get a data provider by ID.\n\nRequired privileges: `KNOWLEDGE_HUB_DATA_PROVIDER_READ`.",
        "operationId": "get_data_provider_api_v1_data_providers__provider_id__get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "provider_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "ID of the data provider",
              "title": "Provider Id"
            },
            "description": "ID of the data provider"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DataProviderResponse"
                }
              }
            }
          },
          "404": {
            "description": "Data provider not found"
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/embedding-models": {
      "get": {
        "tags": [
          "embedding-models"
        ],
        "summary": "List embedding models",
        "description": "List available embedding models.\n\nReturns list of embedding models available for use when creating Knowledge Bases.\nEach model has specific dimensions and is backed by a specific provider (e.g., Bedrock).\n\nRequired privileges: `KNOWLEDGE_HUB_DATA_PROVIDER_READ`.",
        "operationId": "list_embedding_models_api_v1_embedding_models_get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "maximum": 1000,
              "minimum": 1,
              "description": "Maximum results to return",
              "default": 50,
              "title": "Limit"
            },
            "description": "Maximum results to return"
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "description": "Pagination offset",
              "default": 0,
              "title": "Offset"
            },
            "description": "Pagination offset"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmbeddingModelListResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/supported-staging-providers": {
      "get": {
        "tags": [
          "staging-providers"
        ],
        "summary": "List supported staging providers",
        "description": "List supported staging providers.\n\nReturns list of cloud storage providers that KH can read staged data from.\nCalled by Data Integration to determine valid staging destinations.\n\nRequired privileges: `KNOWLEDGE_HUB_STAGING_PROVIDER_READ`.",
        "operationId": "list_supported_staging_providers_api_v1_supported_staging_providers_get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "maximum": 1000,
              "minimum": 1,
              "description": "Maximum results to return",
              "default": 50,
              "title": "Limit"
            },
            "description": "Maximum results to return"
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "description": "Pagination offset",
              "default": 0,
              "title": "Offset"
            },
            "description": "Pagination offset"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StagingProviderListResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/repositories": {
      "get": {
        "tags": [
          "repositories"
        ],
        "summary": "List repositories",
        "description": "List repositories with optional filtering.\n\nReturns list of repositories with pagination, optional filtering, and knowledge base counts.\nDefaults to ENABLED repositories; pass a ``status`` filter to see others. Results are\nscoped to the caller's Boomi tenant via the token's ``account`` claim.\n\nRequired privileges: `KNOWLEDGE_HUB_REPO_READ`.",
        "operationId": "list_repositories_api_v1_repositories_get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "maximum": 1000,
              "minimum": 1,
              "description": "Maximum results to return",
              "default": 50,
              "title": "Limit"
            },
            "description": "Maximum results to return"
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "description": "Pagination offset",
              "default": 0,
              "title": "Offset"
            },
            "description": "Pagination offset"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "$ref": "#/components/schemas/RepositoryStatus"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter by repository status",
              "title": "Status"
            },
            "description": "Filter by repository status"
          },
          {
            "name": "repository_type",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "$ref": "#/components/schemas/RepositoryType"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter by repository type",
              "title": "Repository Type"
            },
            "description": "Filter by repository type"
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter by repository name",
              "title": "Name"
            },
            "description": "Filter by repository name"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RepositoryListResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "repositories"
        ],
        "summary": "Create repository",
        "description": "Create a new repository.\n\nCreates a repository with the given configuration. Status is automatically\nset to 'enabled' on creation. The repository is created under the caller's\nBoomi tenant.\n\nRequired privileges: `KNOWLEDGE_HUB_REPO_WRITE`.",
        "operationId": "create_repository_api_v1_repositories_post",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RepositoryCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RepositoryCreateResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/repositories/{repository_id}": {
      "get": {
        "tags": [
          "repositories"
        ],
        "summary": "Get repository",
        "description": "Get a repository by ID, including its knowledge base count.\n\nRequired privileges: `KNOWLEDGE_HUB_REPO_READ`.",
        "operationId": "get_repository_api_v1_repositories__repository_id__get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "repository_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the repository",
              "title": "Repository Id"
            },
            "description": "UUID of the repository"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RepositoryResponse"
                }
              }
            }
          },
          "404": {
            "description": "Repository not found"
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "repositories"
        ],
        "summary": "Update repository",
        "description": "Update a repository.\n\nOnly fields present in the request body are changed.\n\nRequired privileges: `KNOWLEDGE_HUB_REPO_WRITE`.",
        "operationId": "update_repository_api_v1_repositories__repository_id__put",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "repository_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the repository",
              "title": "Repository Id"
            },
            "description": "UUID of the repository"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RepositoryUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "404": {
            "description": "Repository not found"
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "repositories"
        ],
        "summary": "Delete repository",
        "description": "Archive a repository and cascade the archive to its Knowledge Bases.\n\nSoft delete: the repository's status is set to 'archived' and it no longer\nappears in default listings, but the record is retained. Every non-archived\nchild Knowledge Base (status='archived') is also archived and its index\nscheduled for deferred deletion (index_deletion_due_at = now +\nINDEX_DELETION_GRACE_HOURS) \u2014 the index itself is never touched here; the\nkh-worker sweep deletes it after the grace window elapses. Already-archived\nKBs are left untouched. One shared timestamp stamps the repository's own\nDeleted event, every cascaded KB's Deleted event, and every cascaded KB's\nindex_deletion_due_at.\n\nRequired privileges: `KNOWLEDGE_HUB_REPO_DELETE`.",
        "operationId": "delete_repository_api_v1_repositories__repository_id__delete",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "repository_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the repository",
              "title": "Repository Id"
            },
            "description": "UUID of the repository"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArchiveRepositoryResponse"
                }
              }
            }
          },
          "404": {
            "description": "Repository not found"
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/repositories/{repository_id}/knowledge-bases": {
      "get": {
        "tags": [
          "repositories"
        ],
        "summary": "List knowledge bases in repository",
        "description": "List a repository's enabled knowledge bases.\n\nReturns only knowledge bases whose status is ``enabled`` \u2014 draft, disabled and\narchived ones are excluded. (The account-wide ``GET /knowledge-bases`` listing\nis broader: it excludes only archived.)\n\nRequired privileges: `KNOWLEDGE_HUB_KB_LIST`.",
        "operationId": "list_knowledge_bases_in_repository_api_v1_repositories__repository_id__knowledge_bases_get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "repository_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the repository",
              "title": "Repository Id"
            },
            "description": "UUID of the repository"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "maximum": 1000,
              "minimum": 1,
              "description": "Maximum results to return",
              "default": 50,
              "title": "Limit"
            },
            "description": "Maximum results to return"
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "description": "Pagination offset",
              "default": 0,
              "title": "Offset"
            },
            "description": "Pagination offset"
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter by knowledge base name",
              "title": "Name"
            },
            "description": "Filter by knowledge base name"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeBaseListResponse"
                }
              }
            }
          },
          "404": {
            "description": "Repository not found"
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/knowledge-bases": {
      "get": {
        "tags": [
          "knowledge-bases"
        ],
        "summary": "List knowledge bases",
        "description": "List knowledge bases with optional filtering.\n\nReturns list of knowledge bases with pagination and optional filtering by repository and\nstatus. Archived knowledge bases are excluded unless explicitly requested via the ``status``\nfilter. Results are scoped to the caller's Boomi tenant via the token's ``account`` claim.\n\nRequired privileges: `KNOWLEDGE_HUB_KB_LIST`.",
        "operationId": "list_knowledge_bases_api_v1_knowledge_bases_get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "maximum": 1000,
              "minimum": 1,
              "description": "Maximum results to return",
              "default": 50,
              "title": "Limit"
            },
            "description": "Maximum results to return"
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "description": "Pagination offset",
              "default": 0,
              "title": "Offset"
            },
            "description": "Pagination offset"
          },
          {
            "name": "repository_id",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string",
                  "format": "uuid"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter by repository",
              "title": "Repository Id"
            },
            "description": "Filter by repository"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "$ref": "#/components/schemas/KnowledgeBaseStatus"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter by status",
              "title": "Status"
            },
            "description": "Filter by status"
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter by knowledge base name",
              "title": "Name"
            },
            "description": "Filter by knowledge base name"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeBaseListResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "knowledge-bases"
        ],
        "summary": "Create knowledge base",
        "description": "Create a new knowledge base.\n\nCreates a knowledge base with the given configuration. Status is automatically\nset to 'draft' on creation.\n\nIf collection_name is not provided, it is auto-generated from the KB name.\nA provided collection_name is used as the base; either way a unique suffix\nderived from the KB id is appended so no two KBs share a vector index.\nIf kb_schema is not provided, an empty metadata schema is created.\n\nRequired privileges: `KNOWLEDGE_HUB_KB_CREATE`.",
        "operationId": "create_knowledge_base_api_v1_knowledge_bases_post",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/KnowledgeBaseCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeBaseCreateResponse"
                }
              }
            }
          },
          "404": {
            "description": "Repository or embedding model not found"
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/knowledge-bases/{knowledge_base_id}": {
      "get": {
        "tags": [
          "knowledge-bases"
        ],
        "summary": "Get knowledge base",
        "description": "Get a knowledge base by ID.\n\nIncludes the live source count, per-field source counts, and the resolved\nembedding model details.\n\nRequired privileges: `KNOWLEDGE_HUB_KB_READ`.",
        "operationId": "get_knowledge_base_api_v1_knowledge_bases__knowledge_base_id__get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "knowledge_base_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the knowledge base",
              "title": "Knowledge Base Id"
            },
            "description": "UUID of the knowledge base"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeBaseResponse"
                }
              }
            }
          },
          "404": {
            "description": "Knowledge base not found"
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "knowledge-bases"
        ],
        "summary": "Update knowledge base",
        "description": "Update a knowledge base.\n\nWhen kb_schema is provided, detects field renames and deletions using stable\nfield IDs. Renames cascade to mapping target_fields. Deletions remove affected\nFieldMapping entries and disable affected sources and their mappings.\nBlocked (409) if PENDING/RUNNING jobs exist, or if a field type changes on a\nKB with ingest history (schema_type_immutable).\n\nWhen dry_run=true, runs the cascade inside a savepoint and rolls back,\nreturning the cascade summary without persisting any changes.\n\nRequired privileges: `KNOWLEDGE_HUB_KB_WRITE`.",
        "operationId": "update_knowledge_base_api_v1_knowledge_bases__knowledge_base_id__put",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "knowledge_base_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the knowledge base",
              "title": "Knowledge Base Id"
            },
            "description": "UUID of the knowledge base"
          },
          {
            "name": "dry_run",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "description": "Preview cascade effects without applying changes",
              "default": false,
              "title": "Dry Run"
            },
            "description": "Preview cascade effects without applying changes"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/KnowledgeBaseUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpdateKnowledgeBaseResponse"
                }
              }
            }
          },
          "404": {
            "description": "Knowledge base not found"
          },
          "409": {
            "description": "Conflict: ingestion jobs are running (active_jobs), or field types cannot be changed on a knowledge base with ingest history (schema_type_immutable)"
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "knowledge-bases"
        ],
        "summary": "Delete knowledge base",
        "description": "Archive a knowledge base (soft delete).\n\nSets status to 'archived'. If purge_data=true, also schedules the KB's\nvector index for deletion after a grace window \u2014 the index itself is\nnever touched here; the background sweep deletes it once the grace\nperiod elapses.\n\nRequired privileges: `KNOWLEDGE_HUB_KB_DELETE`.",
        "operationId": "delete_knowledge_base_api_v1_knowledge_bases__knowledge_base_id__delete",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "knowledge_base_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the knowledge base",
              "title": "Knowledge Base Id"
            },
            "description": "UUID of the knowledge base"
          },
          {
            "name": "purge_data",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "description": "If true, schedules the KB's index for deferred deletion (index_deletion_due_at = now + INDEX_DELETION_GRACE_HOURS) \u2014 never deletes it directly",
              "default": false,
              "title": "Purge Data"
            },
            "description": "If true, schedules the KB's index for deferred deletion (index_deletion_due_at = now + INDEX_DELETION_GRACE_HOURS) \u2014 never deletes it directly"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArchiveKnowledgeBaseResponse"
                }
              }
            }
          },
          "404": {
            "description": "Knowledge base not found"
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/knowledge-bases/{knowledge_base_id}/schema": {
      "get": {
        "tags": [
          "knowledge-bases"
        ],
        "summary": "Get knowledge base schema",
        "description": "Get only a knowledge base's metadata schema.\n\nReturns the schema alone, without the config payload the full GET\ncarries \u2014 the minimal surface retrieval-side consumers need.\n\nRequired privileges: `KNOWLEDGE_HUB_KB_SCHEMA_READ`.",
        "operationId": "get_knowledge_base_schema_api_v1_knowledge_bases__knowledge_base_id__schema_get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "knowledge_base_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the knowledge base",
              "title": "Knowledge Base Id"
            },
            "description": "UUID of the knowledge base"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeBaseSchemaResponse"
                }
              }
            }
          },
          "404": {
            "description": "Knowledge base not found"
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/knowledge-bases/{knowledge_base_id}/status": {
      "patch": {
        "tags": [
          "knowledge-bases"
        ],
        "summary": "Update knowledge base status",
        "description": "Transition a knowledge base's status.\n\nValid transitions:\n- DRAFT -> ENABLED (requires repo available + at least one active source)\n- ENABLED -> DISABLED (takes the KB out of service; no preconditions)\n- DISABLED -> ENABLED (same preconditions as DRAFT -> ENABLED)\n\nA disabled KB is rejected by retrieval (403 kb_inactive) and by job creation\n(422 invalid_state), but stays listable and editable. Jobs already enqueued when\nthe KB is disabled are not cancelled.\n\nTo archive a KB, use DELETE /knowledge-bases/{id} instead.\n\nRequired privileges: `KNOWLEDGE_HUB_KB_WRITE`.",
        "operationId": "update_knowledge_base_status_api_v1_knowledge_bases__knowledge_base_id__status_patch",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "knowledge_base_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the knowledge base",
              "title": "Knowledge Base Id"
            },
            "description": "UUID of the knowledge base"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/KnowledgeBaseStatusUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeBaseResponse"
                }
              }
            }
          },
          "404": {
            "description": "Knowledge base not found"
          },
          "409": {
            "description": "Invalid status transition"
          },
          "422": {
            "description": "Precondition for enabling failed (repo unavailable or no active sources)"
          }
        }
      }
    },
    "/api/v1/knowledge-bases/{knowledge_base_id}/sources": {
      "get": {
        "tags": [
          "knowledge-bases"
        ],
        "summary": "List sources for knowledge base",
        "description": "List sources connected to a knowledge base via schema mappings.\n\nReturns sources that have a schema mapping to this KB, excluding archived sources.\nEach source includes its schema_mapping_id for use in job creation.\n\nRequired privileges: `KNOWLEDGE_HUB_SOURCE_READ`.",
        "operationId": "list_sources_for_knowledge_base_api_v1_knowledge_bases__knowledge_base_id__sources_get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "knowledge_base_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the knowledge base",
              "title": "Knowledge Base Id"
            },
            "description": "UUID of the knowledge base"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "maximum": 1000,
              "minimum": 1,
              "description": "Maximum results to return",
              "default": 50,
              "title": "Limit"
            },
            "description": "Maximum results to return"
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "description": "Pagination offset",
              "default": 0,
              "title": "Offset"
            },
            "description": "Pagination offset"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeBaseSourcesListResponse"
                }
              }
            }
          },
          "404": {
            "description": "Knowledge base not found"
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "knowledge-bases"
        ],
        "summary": "Create source for knowledge base",
        "description": "Create sources directly inside a knowledge base.\n\nEach source is created already linked to this KB through a DISABLED schema\nmapping \u2014 atomic: a failure leaves no unassociated source behind.\n\nAn unstructured source (is_unstructured true, or a known unstructured file\ntype) may be created with an empty source_schema; kh-api stores the fixed\nworker field list plus `_content_` \u2014 same contract as POST /sources.\n\nRequired privileges: `KNOWLEDGE_HUB_SOURCE_WRITE`.",
        "operationId": "create_source_for_knowledge_base_api_v1_knowledge_bases__knowledge_base_id__sources_post",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "knowledge_base_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the knowledge base",
              "title": "Knowledge Base Id"
            },
            "description": "UUID of the knowledge base"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSourcesRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateSourcesWithMappingsResponse"
                }
              }
            }
          },
          "403": {
            "description": "Missing KH access privilege"
          },
          "404": {
            "description": "Knowledge base not found"
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/sources": {
      "get": {
        "tags": [
          "sources"
        ],
        "summary": "List sources",
        "description": "List sources with optional filtering.\n\nReturns list of sources with pagination and optional filtering by name and status.\nEach source includes its latest ingestion job summary. Results are scoped to the\ncaller's Boomi tenant via the token's ``account`` claim.\n\nRequired privileges: `KNOWLEDGE_HUB_SOURCE_READ`.",
        "operationId": "list_sources_api_v1_sources_get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "maximum": 1000,
              "minimum": 1,
              "description": "Maximum results to return",
              "default": 50,
              "title": "Limit"
            },
            "description": "Maximum results to return"
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "description": "Pagination offset",
              "default": 0,
              "title": "Offset"
            },
            "description": "Pagination offset"
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter by source name",
              "title": "Name"
            },
            "description": "Filter by source name"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "$ref": "#/components/schemas/SourceStatus"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter by status",
              "title": "Status"
            },
            "description": "Filter by status"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SourceListResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "sources"
        ],
        "summary": "Create sources",
        "description": "Create sources (batch).\n\nCreates one or more standalone Sources. Sources are created in 'draft' status.\nConnection to Knowledge Bases is established through SchemaMapping.\n\nAll-or-nothing: if any source fails validation, none are created.\n\nEmits one Created audit event per Source in the batch \u2014 each is its own\nauditable entity, distinct from a single-entity create call.\n\nAn unstructured source (is_unstructured true, or a known unstructured file type)\nmay be created with an empty source_schema; kh-api stores the fixed worker field\nlist plus `_content_`.\n\nRequired privileges: `KNOWLEDGE_HUB_SOURCE_WRITE`.",
        "operationId": "create_sources_api_v1_sources_post",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSourcesRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateSourcesResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/sources/{source_id}": {
      "get": {
        "tags": [
          "sources"
        ],
        "summary": "Get source",
        "description": "Get a source by ID.\n\nIncludes the latest ingestion job summary.\n\nRequired privileges: `KNOWLEDGE_HUB_SOURCE_READ`.",
        "operationId": "get_source_api_v1_sources__source_id__get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "source_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the source",
              "title": "Source Id"
            },
            "description": "UUID of the source"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SourceResponse"
                }
              }
            }
          },
          "404": {
            "description": "Source not found"
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "sources"
        ],
        "summary": "Update source",
        "description": "Update a source.\n\nAll fields can be updated regardless of status (except archived sources \u2192 404).\nAn ACTIVE source on a published (ENABLED) KB must be disabled before editing \u2192 409.\nOnly fields present in the request body are changed.\n\nRequired privileges: `KNOWLEDGE_HUB_SOURCE_WRITE`.",
        "operationId": "update_source_api_v1_sources__source_id__put",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "source_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the source",
              "title": "Source Id"
            },
            "description": "UUID of the source"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SourceUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "404": {
            "description": "Source not found"
          },
          "409": {
            "description": "Source not editable on published KB"
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "sources"
        ],
        "summary": "Delete source",
        "description": "Archive a source (soft delete).\n\nSets status to 'archived' (terminal). The associated schema mapping, if any,\nis disabled.\n\nRequired privileges: `KNOWLEDGE_HUB_SOURCE_DELETE`.",
        "operationId": "delete_source_api_v1_sources__source_id__delete",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "source_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the source",
              "title": "Source Id"
            },
            "description": "UUID of the source"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "404": {
            "description": "Source not found"
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/sources/{source_id}/status": {
      "patch": {
        "tags": [
          "sources"
        ],
        "summary": "Update source status",
        "description": "Transition a source's status.\n\nValid transitions:\n- DRAFT -> ACTIVE\n- ACTIVE -> DISABLED\n- DISABLED -> ACTIVE\n- ARCHIVED -> (none, terminal)\n\nTo archive a source, use DELETE /sources/{source_id} instead.\n\nTransitioning to ACTIVE requires an associated schema mapping with at\nleast one field with query_order set; otherwise 422 is returned.\n\nWhen transitioning to ACTIVE or DISABLED, the associated schema mapping\nstatus is cascaded (ACTIVE->ACTIVE, DISABLED->DISABLED).\n\nRequired privileges: `KNOWLEDGE_HUB_SOURCE_WRITE`.",
        "operationId": "update_source_status_api_v1_sources__source_id__status_patch",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "source_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the source",
              "title": "Source Id"
            },
            "description": "UUID of the source"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SourceStatusUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SourceResponse"
                }
              }
            }
          },
          "404": {
            "description": "Source not found"
          },
          "409": {
            "description": "Invalid status transition"
          },
          "422": {
            "description": "Activation requirements not met"
          }
        }
      }
    },
    "/api/v1/schema-mappings/source/{source_id}/knowledge-base/{knowledge_base_id}": {
      "get": {
        "tags": [
          "schema-mappings"
        ],
        "summary": "Get schema mapping",
        "description": "Get schema mapping for a source-to-KB relationship.\n\nRetrieves the field mapping that connects a source to a knowledge base.\n\nRequired privileges: `KNOWLEDGE_HUB_SSM_READ`.",
        "operationId": "get_schema_mapping_api_v1_schema_mappings_source__source_id__knowledge_base__knowledge_base_id__get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "source_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the source",
              "title": "Source Id"
            },
            "description": "UUID of the source"
          },
          {
            "name": "knowledge_base_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the knowledge base",
              "title": "Knowledge Base Id"
            },
            "description": "UUID of the knowledge base"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SchemaMappingResponse"
                }
              }
            }
          },
          "404": {
            "description": "Knowledge base, source, or schema mapping not found"
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "schema-mappings"
        ],
        "summary": "Upsert schema mapping",
        "description": "Create or update schema mapping for a source-to-KB relationship.\n\nIf a mapping exists for this source+KB pair, updates it (200).\nOtherwise creates a new mapping (201).\n\nExisting mappings must be DISABLED to update.\n\nRequired privileges: `KNOWLEDGE_HUB_SSM_WRITE`.",
        "operationId": "upsert_schema_mapping_api_v1_schema_mappings_source__source_id__knowledge_base__knowledge_base_id__put",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "source_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the source",
              "title": "Source Id"
            },
            "description": "UUID of the source"
          },
          {
            "name": "knowledge_base_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the knowledge base",
              "title": "Knowledge Base Id"
            },
            "description": "UUID of the knowledge base"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SchemaMappingUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SchemaMappingResponse"
                }
              }
            }
          },
          "404": {
            "description": "Knowledge base or source not found"
          },
          "409": {
            "description": "Mapping not editable or source already linked to another KB"
          },
          "422": {
            "description": "Duplicate target field, unknown target_field, unrecognized target_field_type, or '_content_' used with an order not allowed for this source. An empty mappings list on an unstructured source (is_unstructured true, or a known unstructured file type) whose stored schema declares the default source fields is auto-replaced by the default mapping (unknown-target 422 still applies on an ENABLED KB); otherwise it keeps the empty mapping"
          }
        }
      },
      "delete": {
        "tags": [
          "schema-mappings"
        ],
        "summary": "Delete schema mapping",
        "description": "Delete schema mapping for a source-to-KB relationship.\n\nRemoves the field mapping that connects a source to a knowledge base.\nThis is a hard delete of the mapping only \u2014 the source and knowledge base\nare untouched.\n\nRequired privileges: `KNOWLEDGE_HUB_SSM_DELETE`.",
        "operationId": "delete_schema_mapping_api_v1_schema_mappings_source__source_id__knowledge_base__knowledge_base_id__delete",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "source_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the source",
              "title": "Source Id"
            },
            "description": "UUID of the source"
          },
          {
            "name": "knowledge_base_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the knowledge base",
              "title": "Knowledge Base Id"
            },
            "description": "UUID of the knowledge base"
          }
        ],
        "responses": {
          "204": {
            "description": "Successful Response"
          },
          "404": {
            "description": "Knowledge base, source, or schema mapping not found"
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/schema-mappings/source/{source_id}/knowledge-base/{knowledge_base_id}/status": {
      "patch": {
        "tags": [
          "schema-mappings"
        ],
        "summary": "Update schema mapping status",
        "description": "Transition a schema mapping's status.\n\nValid transitions:\n- ACTIVE -> DISABLED\n- DISABLED -> ACTIVE\n\nActivation is blocked (422) if the mapping references knowledge base fields\nthat no longer exist.\n\nRequired privileges: `KNOWLEDGE_HUB_SSM_WRITE`.",
        "operationId": "update_schema_mapping_status_api_v1_schema_mappings_source__source_id__knowledge_base__knowledge_base_id__status_patch",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "source_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the source",
              "title": "Source Id"
            },
            "description": "UUID of the source"
          },
          {
            "name": "knowledge_base_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the knowledge base",
              "title": "Knowledge Base Id"
            },
            "description": "UUID of the knowledge base"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SchemaMappingStatusUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SchemaMappingResponse"
                }
              }
            }
          },
          "404": {
            "description": "Knowledge base, source, or schema mapping not found"
          },
          "409": {
            "description": "Invalid status transition"
          },
          "422": {
            "description": "Mapping references knowledge base fields that no longer exist"
          }
        }
      }
    },
    "/api/v1/schema-mappings/source/{source_id}/knowledge-base/{knowledge_base_id}/suggest": {
      "post": {
        "tags": [
          "schema-mappings"
        ],
        "summary": "Suggest schema mapping",
        "description": "Suggest a schema mapping for a source-to-KB relationship. Read-only; writes nothing.\n\nIf the response's would_create_kb_fields is non-empty, the subsequent PUT must set\nensure_target_fields=true for those fields to actually be created.\n\nFields are skipped (reported unmapped with a reason) if they are:\n\n- id-like (name ends in 'id'/'_id'/'ids', other than the match key 'id'): 'excluded_field'\n- malformed schema entries: 'malformed_field'\n\n(Both checked after type resolution and case-fold collision detection, so either of those\ncan report its own reason first.)\n\nIf the source has 10 or more fields, only fields matching common patterns are kept:\nstrings like status/stage/type/category/priority/owner/assignee/author/created_by, and\ndatetimes like created/updated/modified. Others are reported as 'no_pattern_match'.\n\nAt most 20 fields are mapped or created; extras are reported as 'suggestion_limit_exceeded'.\nThe id, content, description, and title fields are always kept, regardless of pattern or cap.\n\nA mapping that would need a new KB field is reported unmapped as 'kb_not_editable'\ninstead of would_create_kb_fields when the KB isn't draft or disabled.\n\nRequired privileges: `KNOWLEDGE_HUB_SSM_READ`.",
        "operationId": "suggest_schema_mapping_api_v1_schema_mappings_source__source_id__knowledge_base__knowledge_base_id__suggest_post",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "source_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the source",
              "title": "Source Id"
            },
            "description": "UUID of the source"
          },
          {
            "name": "knowledge_base_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the knowledge base",
              "title": "Knowledge Base Id"
            },
            "description": "UUID of the knowledge base"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuggestSchemaMappingResponse"
                }
              }
            }
          },
          "404": {
            "description": "Knowledge base or source not found"
          },
          "409": {
            "description": "Source is active (not suggestable), or the schema mapping already has one or more configured field mappings"
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/jobs": {
      "get": {
        "tags": [
          "jobs"
        ],
        "summary": "List jobs",
        "description": "List jobs with optional filtering.\n\nEach filter accepts one or more values (OR'd within the filter); multiple filters\nare AND'd together, e.g. ?status=running&status=pending&source_id=X returns jobs\nfor source X that are running OR pending.\n\nResults are scoped to the caller's Boomi tenant via the token's ``account`` claim.\n\nRequired privileges: `KNOWLEDGE_HUB_JOB_READ`.",
        "operationId": "list_jobs_api_v1_jobs_get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "source_id",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "maxItems": 100
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter by Source ID(s)",
              "title": "Source Id"
            },
            "description": "Filter by Source ID(s)"
          },
          {
            "name": "knowledge_base_id",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "maxItems": 100
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter by Knowledge Base ID(s)",
              "title": "Knowledge Base Id"
            },
            "description": "Filter by Knowledge Base ID(s)"
          },
          {
            "name": "repository_id",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "maxItems": 100
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter by repository ID(s)",
              "title": "Repository Id"
            },
            "description": "Filter by repository ID(s)"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/JobStatusEnum"
                  },
                  "maxItems": 100
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter by status(es)",
              "title": "Status"
            },
            "description": "Filter by status(es)"
          },
          {
            "name": "created_after",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string",
                  "format": "date-time"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter by created at/after (ISO-8601, UTC offset required)",
              "title": "Created After"
            },
            "description": "Filter by created at/after (ISO-8601, UTC offset required)"
          },
          {
            "name": "created_before",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string",
                  "format": "date-time"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter by created at/before (ISO-8601, UTC offset required)",
              "title": "Created Before"
            },
            "description": "Filter by created at/before (ISO-8601, UTC offset required)"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "maximum": 1000,
              "minimum": 1,
              "description": "Maximum results to return",
              "default": 50,
              "title": "Limit"
            },
            "description": "Maximum results to return"
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "description": "Pagination offset",
              "default": 0,
              "title": "Offset"
            },
            "description": "Pagination offset"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobsListResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "jobs"
        ],
        "summary": "Create job",
        "description": "Create an ingestion job.\n\nCalled by Data Integration (or any external provider) to create an ingestion job.\nCreates a job record and queues it for processing. The source must be active,\nthe knowledge base enabled, and the schema mapping active (422 otherwise).\n\nRequired privileges: `KNOWLEDGE_HUB_JOB_EXECUTE`.",
        "operationId": "create_job_api_v1_jobs_post",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateJobRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateJobResponse"
                }
              }
            }
          },
          "404": {
            "description": "Schema mapping, source, or knowledge base not found"
          },
          "422": {
            "description": "Source inactive, knowledge base not enabled, repository unavailable, or schema mapping not active"
          }
        }
      }
    },
    "/api/v1/jobs/{job_id}": {
      "get": {
        "tags": [
          "jobs"
        ],
        "summary": "Get job",
        "description": "Get a job by ID.\n\nRequired privileges: `KNOWLEDGE_HUB_JOB_READ`.",
        "operationId": "get_job_api_v1_jobs__job_id__get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the job",
              "title": "Job Id"
            },
            "description": "UUID of the job"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobResponse"
                }
              }
            }
          },
          "404": {
            "description": "Job not found"
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "jobs"
        ],
        "summary": "Cancel job",
        "description": "Cancel a pending or running job.\n\nJobs in terminal states (success, failed, partial, cancelled) cannot be cancelled.\nCancellation is cooperative: a RUNNING job stops at the worker's next per-file\nboundary; a job whose finalize already committed keeps its final status.\n\nRequired privileges: `KNOWLEDGE_HUB_JOB_DELETE`.",
        "operationId": "cancel_job_api_v1_jobs__job_id__delete",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the job",
              "title": "Job Id"
            },
            "description": "UUID of the job"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancelJobResponse"
                }
              }
            }
          },
          "400": {
            "description": "Job is in a terminal state and cannot be cancelled"
          },
          "404": {
            "description": "Job not found"
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/jobs/{job_id}/log": {
      "get": {
        "tags": [
          "jobs"
        ],
        "summary": "Get job log",
        "description": "Download a job's ingestion log as CSV (columns: timestamp,level,msg).\n\nTime window is derived from the job's own started_at/completed_at \u2014 a still-running\njob's window extends to \"now\". A job that hasn't started yet returns an empty log.\n\nReturned as raw `text/csv`, not a JSON envelope: this is a file download, and\nwrapping the CSV text in JSON would double its memory footprint (once raw, once\nJSON-escaped) for no benefit. The truncation flag travels as an `X-Truncated`\nheader instead of a JSON field.\n\nRequired privileges: `KNOWLEDGE_HUB_JOB_READ`.",
        "operationId": "get_job_log_api_v1_jobs__job_id__log_get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the job",
              "title": "Job Id"
            },
            "description": "UUID of the job"
          }
        ],
        "responses": {
          "200": {
            "description": "Job's ingestion log as CSV (columns: timestamp,level,msg)",
            "content": {
              "application/json": {
                "schema": {}
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Job not found"
          },
          "503": {
            "description": "Log service is not configured or unavailable"
          },
          "504": {
            "description": "Timed out waiting for the log service"
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/consumption/usage": {
      "get": {
        "tags": [
          "consumption"
        ],
        "summary": "Get usage",
        "description": "Return every metering dimension's total for the requested scope.\n\nEach of ``repository_id``, ``knowledge_base_id`` and ``source_id`` is a repeatable\nfilter (repeated values are OR'd together); leave all three unset for account-wide\ntotals. ``date_from``/``date_to`` bound the range and default to the last 7 local\ndays; ``timezone`` (IANA name) governs those defaults and the daily bucket\nboundaries. The response carries totals plus per-day series for data ingested\n(bytes and document count), retrieval calls, and persisted storage, along with\nthe previous period's totals for comparison.\n\nResults are scoped to the caller's Boomi tenant via the token's ``account`` claim.\n\nRequired privileges: `KNOWLEDGE_HUB_CONSUMPTION_READ`.",
        "operationId": "get_usage_api_v1_consumption_usage_get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "repository_id",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                {
                  "type": "null"
                }
              ],
              "description": "Repository filter; repeatable, OR'd",
              "title": "Repository Id"
            },
            "description": "Repository filter; repeatable, OR'd"
          },
          {
            "name": "knowledge_base_id",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                {
                  "type": "null"
                }
              ],
              "description": "KB filter; repeatable, OR'd",
              "title": "Knowledge Base Id"
            },
            "description": "KB filter; repeatable, OR'd"
          },
          {
            "name": "source_id",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                {
                  "type": "null"
                }
              ],
              "description": "Source filter; repeatable, OR'd",
              "title": "Source Id"
            },
            "description": "Source filter; repeatable, OR'd"
          },
          {
            "name": "date_from",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string",
                  "format": "date-time"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Range start; defaults to 7 local days back",
              "title": "Date From"
            },
            "description": "Range start; defaults to 7 local days back"
          },
          {
            "name": "date_to",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string",
                  "format": "date-time"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Range end; defaults to now, in `timezone`",
              "title": "Date To"
            },
            "description": "Range end; defaults to now, in `timezone`"
          },
          {
            "name": "timezone",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "IANA timezone name governing date-range defaults and daily-bucket boundaries",
              "default": "UTC",
              "title": "Timezone"
            },
            "description": "IANA timezone name governing date-range defaults and daily-bucket boundaries"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "maximum": 1000,
              "minimum": 1,
              "description": "Page size shared by daily_ingestion_volume, daily_retrieval_calls and daily_persisted_storage",
              "default": 500,
              "title": "Limit"
            },
            "description": "Page size shared by daily_ingestion_volume, daily_retrieval_calls and daily_persisted_storage"
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "description": "Page offset shared by daily_ingestion_volume, daily_retrieval_calls and daily_persisted_storage",
              "default": 0,
              "title": "Offset"
            },
            "description": "Page offset shared by daily_ingestion_volume, daily_retrieval_calls and daily_persisted_storage"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsumptionUsageResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "tags": [
          "health"
        ],
        "summary": "Health check",
        "description": "Health check endpoint.\n\nReturns the health status of the API service.",
        "operationId": "health_check_health_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ArchiveKnowledgeBaseResponse": {
        "properties": {
          "status": {
            "type": "string",
            "title": "Status",
            "default": "ok"
          },
          "knowledge_base_id": {
            "type": "string",
            "format": "uuid",
            "title": "Knowledge Base Id"
          },
          "archived_sources": {
            "type": "integer",
            "title": "Archived Sources",
            "default": 0
          },
          "embeddings_purged": {
            "type": "boolean",
            "title": "Embeddings Purged",
            "description": "Mirrors purge_data ('scheduled' semantics): True means the index deletion was scheduled (index_deletion_due_at stamped; the worker sweep performs the actual delete after the grace window), not that it already happened. False when purge_data was false.",
            "default": false
          },
          "index_deletion_due_at": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ],
            "title": "Index Deletion Due At",
            "description": "UTC timestamp when the KB's index becomes eligible for deletion by the worker sweep. Set only when purge_data=true; None otherwise."
          }
        },
        "type": "object",
        "required": [
          "knowledge_base_id"
        ],
        "title": "ArchiveKnowledgeBaseResponse",
        "description": "Response schema for archiving a knowledge base.",
        "example": {
          "archived_sources": 0,
          "embeddings_purged": true,
          "index_deletion_due_at": "2026-02-08T09:00:00Z",
          "knowledge_base_id": "10000000-0000-0000-0000-000000000001",
          "status": "ok"
        }
      },
      "ArchiveRepositoryResponse": {
        "properties": {
          "status": {
            "type": "string",
            "title": "Status",
            "default": "ok"
          },
          "repository_id": {
            "type": "string",
            "format": "uuid",
            "title": "Repository Id"
          },
          "archived_knowledge_bases": {
            "type": "integer",
            "title": "Archived Knowledge Bases",
            "default": 0
          }
        },
        "type": "object",
        "required": [
          "repository_id"
        ],
        "title": "ArchiveRepositoryResponse",
        "description": "Response schema for archiving a repository.\n\nCascades the archive to every non-archived child Knowledge Base; the index\ndeletion itself is only scheduled (index_deletion_due_at stamped on each KB),\nnever performed here \u2014 same \"scheduled, not executed\" semantics as\nArchiveKnowledgeBaseResponse. archived_knowledge_bases counts how many KBs\nthis call archived; already-archived KBs are excluded and not recounted.",
        "example": {
          "archived_knowledge_bases": 2,
          "repository_id": "00000000-0000-0000-0000-000000000001",
          "status": "ok"
        }
      },
      "ByteSizeDisplay": {
        "properties": {
          "value": {
            "type": "number",
            "minimum": 0.0,
            "title": "Value",
            "description": "Magnitude in the chosen unit"
          },
          "unit": {
            "$ref": "#/components/schemas/ByteUnitEnum",
            "description": "Unit chosen by magnitude (B, KiB, MiB, GiB, TiB)"
          }
        },
        "type": "object",
        "required": [
          "value",
          "unit"
        ],
        "title": "ByteSizeDisplay",
        "description": "A human-readable magnitude + unit pair."
      },
      "ByteSizeInfo": {
        "properties": {
          "bytes": {
            "type": "integer",
            "minimum": 0.0,
            "title": "Bytes",
            "description": "Exact byte count, never rounded (source of truth)"
          },
          "display": {
            "$ref": "#/components/schemas/ByteSizeDisplay",
            "description": "Human-readable value+unit pair for UI display"
          }
        },
        "type": "object",
        "required": [
          "bytes",
          "display"
        ],
        "title": "ByteSizeInfo",
        "description": "Exact byte count paired with its human-readable display.\n\nNamed ``ByteSizeInfo`` rather than ``ByteSize`` to avoid shadowing\n``pydantic.ByteSize`` (a built-in int subclass with its own ``.human_readable()``),\nwhich would otherwise collide for any consumer importing both."
      },
      "ByteUnitEnum": {
        "type": "string",
        "enum": [
          "B",
          "KiB",
          "MiB",
          "GiB",
          "TiB"
        ],
        "title": "ByteUnitEnum",
        "description": "Unit for a human-readable byte-size display (see kh_commons.utils.byte_size_utils).\n\nBinary units (base 1024) with binary labels, per KH-436 \u2014 KiB/MiB/GiB/TiB."
      },
      "CancelJobResponse": {
        "properties": {
          "job_id": {
            "type": "string",
            "format": "uuid",
            "title": "Job Id",
            "description": "Job ID"
          },
          "status": {
            "type": "string",
            "title": "Status",
            "description": "New job status"
          },
          "message": {
            "type": "string",
            "title": "Message",
            "description": "Cancellation message"
          }
        },
        "type": "object",
        "required": [
          "job_id",
          "status",
          "message"
        ],
        "title": "CancelJobResponse",
        "description": "Response schema for cancelling a job.",
        "example": {
          "job_id": "01920f4a-0000-7000-8000-000000000001",
          "message": "Cancellation requested",
          "status": "cancelled"
        }
      },
      "CascadeSummary": {
        "properties": {
          "fields_renamed": {
            "type": "integer",
            "title": "Fields Renamed",
            "description": "Number of KB schema fields that were renamed",
            "default": 0
          },
          "fields_deleted": {
            "type": "integer",
            "title": "Fields Deleted",
            "description": "Number of KB schema fields that were deleted",
            "default": 0
          },
          "mappings_updated": {
            "type": "integer",
            "title": "Mappings Updated",
            "description": "Schema mappings whose target_field was renamed",
            "default": 0
          },
          "mappings_cleaned": {
            "type": "integer",
            "title": "Mappings Cleaned",
            "description": "Live sources (DRAFT/ACTIVE/DISABLED) that had field mapping entries removed. Archived sources are still cleaned but excluded from this count.",
            "default": 0
          },
          "sources_disabled": {
            "type": "integer",
            "title": "Sources Disabled",
            "description": "Sources disabled due to deleted field references",
            "default": 0
          },
          "disabled_source_names": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Disabled Source Names",
            "description": "Names of the disabled sources"
          }
        },
        "type": "object",
        "title": "CascadeSummary",
        "description": "Summary of cascade effects from a KB schema update.\n\nReturned by ``cascade_schema_changes()`` and used directly in the\n``UpdateKnowledgeBaseResponse`` API response.",
        "example": {
          "disabled_source_names": [],
          "fields_deleted": 0,
          "fields_renamed": 1,
          "mappings_cleaned": 0,
          "mappings_updated": 1,
          "sources_disabled": 0
        }
      },
      "ChunkingConfig": {
        "properties": {
          "strategy": {
            "type": "string",
            "title": "Strategy",
            "description": "Chunking strategy: 'fixed' or 'structural'",
            "default": "fixed"
          },
          "chunk_size": {
            "type": "integer",
            "exclusiveMinimum": 0.0,
            "title": "Chunk Size",
            "description": "Maximum chunk size in characters",
            "default": 4000
          },
          "overlap_percent": {
            "type": "integer",
            "maximum": 30.0,
            "minimum": 10.0,
            "title": "Overlap Percent",
            "description": "Overlap percentage between chunks",
            "default": 20
          },
          "strategy_config": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Strategy Config",
            "description": "Strategy-specific configuration overrides. Fixed: {separators: [...]}. Structural: not needed."
          }
        },
        "type": "object",
        "title": "ChunkingConfig",
        "description": "Chunking configuration for schema mappings.\n\nUsed as a JSONB column type in SchemaMapping."
      },
      "ConsumptionUsageResponse": {
        "properties": {
          "account": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Account"
          },
          "repository_ids": {
            "anyOf": [
              {
                "items": {
                  "type": "string",
                  "format": "uuid"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Repository Ids"
          },
          "knowledge_base_ids": {
            "anyOf": [
              {
                "items": {
                  "type": "string",
                  "format": "uuid"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Knowledge Base Ids"
          },
          "source_ids": {
            "anyOf": [
              {
                "items": {
                  "type": "string",
                  "format": "uuid"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Source Ids"
          },
          "date_from_ms": {
            "type": "integer",
            "title": "Date From Ms"
          },
          "date_to_ms": {
            "type": "integer",
            "title": "Date To Ms"
          },
          "timezone": {
            "type": "string",
            "title": "Timezone"
          },
          "data_ingested": {
            "$ref": "#/components/schemas/ByteSizeInfo"
          },
          "data_ingested_period_over_period": {
            "$ref": "#/components/schemas/PeriodOverPeriodDelta"
          },
          "data_persisted": {
            "$ref": "#/components/schemas/ByteSizeInfo"
          },
          "data_persisted_period_over_period": {
            "$ref": "#/components/schemas/PeriodOverPeriodDelta"
          },
          "retrieval_calls": {
            "type": "integer",
            "title": "Retrieval Calls"
          },
          "retrieval_calls_period_over_period": {
            "$ref": "#/components/schemas/PeriodOverPeriodDelta"
          },
          "embedding_model_calls": {
            "type": "integer",
            "title": "Embedding Model Calls"
          },
          "embedding_model_calls_period_over_period": {
            "$ref": "#/components/schemas/PeriodOverPeriodDelta"
          },
          "ai_enrichment_calls": {
            "type": "integer",
            "title": "Ai Enrichment Calls"
          },
          "ai_enrichment_calls_period_over_period": {
            "$ref": "#/components/schemas/PeriodOverPeriodDelta"
          },
          "daily_ingestion_volume": {
            "$ref": "#/components/schemas/DailyIngestionVolumePage"
          },
          "daily_retrieval_calls": {
            "$ref": "#/components/schemas/DailyRetrievalVolumePage"
          },
          "daily_persisted_storage": {
            "$ref": "#/components/schemas/DailyPersistedStoragePage"
          }
        },
        "type": "object",
        "required": [
          "date_from_ms",
          "date_to_ms",
          "timezone",
          "data_ingested",
          "data_ingested_period_over_period",
          "data_persisted",
          "data_persisted_period_over_period",
          "retrieval_calls",
          "retrieval_calls_period_over_period",
          "embedding_model_calls",
          "embedding_model_calls_period_over_period",
          "ai_enrichment_calls",
          "ai_enrichment_calls_period_over_period",
          "daily_ingestion_volume",
          "daily_retrieval_calls",
          "daily_persisted_storage"
        ],
        "title": "ConsumptionUsageResponse",
        "description": "The resolved request scope plus every metering dimension's total for it.\n\nEvery dimension has a matching ``<dimension>_period_over_period`` field (see\n``PeriodOverPeriodDelta``), not documented individually below.\n\n:param account: Tenant scope, from the JWT (not caller-supplied).\n:param repository_ids: Optional Repository filter, as supplied.\n:param knowledge_base_ids: Optional Knowledge Base filter, as supplied.\n:param source_ids: Optional Source filter, as supplied. No effect on ``retrieval_calls``,\n    ``data_persisted`` or ``daily_persisted_storage``.\n:param date_from_ms: Range start, UTC epoch ms. Doesn't bound ``data_persisted`` (a gauge as\n    of ``date_to_ms``, not a sum).\n:param date_to_ms: Range end, UTC epoch ms.\n:param timezone: Governs the date-range default and the daily series' day boundaries.\n:param data_ingested: Sum of bytes across successfully-completed ingestion jobs.\n:param data_persisted: Current total storage as of ``date_to_ms`` \u2014 latest snapshot per KB.\n:param retrieval_calls: Count of retrieval calls in range.\n:param embedding_model_calls: Ingestion-time + query-time embedding calls, summed.\n:param ai_enrichment_calls: Always 0 today \u2014 no producer writes usage for this yet.\n:param daily_ingestion_volume: ``data_ingested`` bucketed by local calendar day, paginated.\n:param daily_retrieval_calls: ``retrieval_calls`` bucketed by local calendar day, paginated.\n:param daily_persisted_storage: ``data_persisted`` bucketed by local calendar day, paginated.\n    A *level* series, not increments: each day is that day's last poll per KB, summed, with\n    gaps carried forward per KB and ``None`` before the first-ever snapshot. **Summing these\n    items does not reproduce the ``data_persisted`` scalar** \u2014 unlike\n    ``daily_ingestion_volume``, whose items do sum to ``data_ingested``. The last item of the\n    final page equals the scalar (both are \"latest poll at or before ``date_to_ms``\"), except\n    when no snapshot exists at all, where the scalar is 0 B and every item is ``None``.\n    ``embedding_model_calls`` and ``ai_enrichment_calls`` have no daily series.",
        "example": {
          "account": "boomi-account-1",
          "ai_enrichment_calls": 0,
          "ai_enrichment_calls_period_over_period": {
            "current": 0,
            "previous": 0
          },
          "daily_ingestion_volume": {
            "items": [
              {
                "data_ingested": {
                  "bytes": 1572864,
                  "display": {
                    "unit": "MiB",
                    "value": 1.5
                  }
                },
                "date": "2026-02-01"
              },
              {
                "data_ingested": {
                  "bytes": 1572864,
                  "display": {
                    "unit": "MiB",
                    "value": 1.5
                  }
                },
                "date": "2026-02-02"
              }
            ],
            "limit": 31,
            "offset": 0,
            "total": 7
          },
          "daily_persisted_storage": {
            "items": [
              {
                "data_persisted": {
                  "bytes": 52428800,
                  "display": {
                    "unit": "MiB",
                    "value": 50.0
                  }
                },
                "date": "2026-02-01"
              },
              {
                "data_persisted": {
                  "bytes": 54525952,
                  "display": {
                    "unit": "MiB",
                    "value": 52.0
                  }
                },
                "date": "2026-02-02"
              }
            ],
            "limit": 31,
            "offset": 0,
            "total": 7
          },
          "daily_retrieval_calls": {
            "items": [
              {
                "date": "2026-02-01",
                "retrieval_calls": 60
              },
              {
                "date": "2026-02-02",
                "retrieval_calls": 60
              }
            ],
            "limit": 31,
            "offset": 0,
            "total": 7
          },
          "data_ingested": {
            "bytes": 3145728,
            "display": {
              "unit": "MiB",
              "value": 3.0
            }
          },
          "data_ingested_period_over_period": {
            "current": 3145728,
            "delta_pct": 100.0,
            "previous": 1572864
          },
          "data_persisted": {
            "bytes": 54525952,
            "display": {
              "unit": "MiB",
              "value": 52.0
            }
          },
          "data_persisted_period_over_period": {
            "current": 54525952,
            "delta_pct": 4.0,
            "previous": 52428800
          },
          "date_from_ms": 1769904000000,
          "date_to_ms": 1770508800000,
          "embedding_model_calls": 460,
          "embedding_model_calls_period_over_period": {
            "current": 460,
            "delta_pct": 15.0,
            "previous": 400
          },
          "retrieval_calls": 120,
          "retrieval_calls_period_over_period": {
            "current": 120,
            "delta_pct": 20.0,
            "previous": 100
          },
          "timezone": "UTC"
        }
      },
      "CreateJobRequest": {
        "properties": {
          "schema_mapping_id": {
            "type": "string",
            "format": "uuid",
            "title": "Schema Mapping Id",
            "description": "Schema Mapping ID that defines the Source\u2192KB relationship"
          },
          "storage_type": {
            "$ref": "#/components/schemas/StorageTypeEnum",
            "description": "Storage type: s3, gcs, azure"
          },
          "staged_data_ref": {
            "$ref": "#/components/schemas/StagedDataRefRequest",
            "description": "Staged data location"
          },
          "load_mode": {
            "$ref": "#/components/schemas/LoadModeEnum",
            "description": "Load mode: append, overwrite, or merge"
          },
          "priority": {
            "type": "integer",
            "maximum": 10.0,
            "minimum": 1.0,
            "title": "Priority",
            "description": "Job priority (1=lowest, 10=highest)",
            "default": 5
          },
          "document_filter": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DocumentFilter"
              },
              {
                "type": "null"
              }
            ],
            "description": "Filter criteria for selective document processing"
          },
          "external_run_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "External Run Id",
            "description": "External run ID for tracking"
          },
          "external_provider": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "External Provider",
            "description": "External provider name"
          },
          "options": {
            "additionalProperties": true,
            "type": "object",
            "title": "Options",
            "description": "Additional options"
          }
        },
        "type": "object",
        "required": [
          "schema_mapping_id",
          "storage_type",
          "staged_data_ref",
          "load_mode"
        ],
        "title": "CreateJobRequest",
        "description": "Request schema for creating an ingestion job.",
        "example": {
          "external_provider": "rivery",
          "external_run_id": "rivery-12345",
          "load_mode": "append",
          "priority": 5,
          "schema_mapping_id": "40000000-0000-0000-0000-000000000001",
          "staged_data_ref": {
            "bucket": "kh-staging-bucket",
            "prefix": "hr-policies/2026-02/"
          },
          "storage_type": "s3"
        }
      },
      "CreateJobResponse": {
        "properties": {
          "job_id": {
            "type": "string",
            "format": "uuid",
            "title": "Job Id",
            "description": "KH-generated job ID"
          },
          "source_id": {
            "type": "string",
            "format": "uuid",
            "title": "Source Id",
            "description": "Source ID derived from schema mapping"
          },
          "status": {
            "type": "string",
            "title": "Status",
            "description": "Job status"
          }
        },
        "type": "object",
        "required": [
          "job_id",
          "source_id",
          "status"
        ],
        "title": "CreateJobResponse",
        "description": "Response schema for job creation.",
        "example": {
          "job_id": "01920f4a-0000-7000-8000-000000000001",
          "source_id": "30000000-0000-0000-0000-000000000001",
          "status": "pending"
        }
      },
      "CreateSourcesRequest": {
        "properties": {
          "source_type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Source Type",
            "description": "Type of source (e.g., jira, salesforce)"
          },
          "source_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Source Name",
            "description": "Display name for the source"
          },
          "source_metadata": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Source Metadata",
            "description": "Opaque JSON blob for source-specific metadata"
          },
          "sources": {
            "items": {
              "$ref": "#/components/schemas/SourceItemCreate"
            },
            "type": "array",
            "minItems": 1,
            "title": "Sources",
            "description": "Array of sources to create"
          }
        },
        "type": "object",
        "required": [
          "sources"
        ],
        "title": "CreateSourcesRequest",
        "description": "Request schema for batch creating sources.",
        "example": {
          "source_name": "HR Jira",
          "source_type": "jira",
          "sources": [
            {
              "file_type": "json",
              "name": "HR Jira Issues",
              "source_schema": {
                "fields": [
                  {
                    "embeddable": true,
                    "metadata_eligible": true,
                    "name": "id",
                    "type": "string"
                  },
                  {
                    "embeddable": true,
                    "metadata_eligible": true,
                    "name": "summary",
                    "type": "string"
                  }
                ]
              }
            }
          ]
        }
      },
      "CreateSourcesResponse": {
        "properties": {
          "status": {
            "type": "string",
            "title": "Status",
            "default": "ok"
          },
          "source_ids": {
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "type": "array",
            "title": "Source Ids",
            "description": "IDs of created sources (same order as request)"
          }
        },
        "type": "object",
        "required": [
          "source_ids"
        ],
        "title": "CreateSourcesResponse",
        "description": "Response schema for batch creating sources.",
        "example": {
          "source_ids": [
            "30000000-0000-0000-0000-000000000001"
          ],
          "status": "ok"
        }
      },
      "CreateSourcesWithMappingsResponse": {
        "properties": {
          "status": {
            "type": "string",
            "title": "Status",
            "default": "ok"
          },
          "source_ids": {
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "type": "array",
            "title": "Source Ids",
            "description": "IDs of created sources (same order as request)"
          },
          "schema_mapping_ids": {
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "type": "array",
            "title": "Schema Mapping Ids",
            "description": "IDs of the created schema mappings (same order as request)"
          }
        },
        "type": "object",
        "required": [
          "source_ids",
          "schema_mapping_ids"
        ],
        "title": "CreateSourcesWithMappingsResponse",
        "description": "Response schema for creating sources inside a knowledge base.",
        "example": {
          "schema_mapping_ids": [
            "40000000-0000-0000-0000-000000000001"
          ],
          "source_ids": [
            "30000000-0000-0000-0000-000000000001"
          ],
          "status": "ok"
        }
      },
      "CreatedKbField": {
        "properties": {
          "name": {
            "type": "string",
            "title": "Name"
          },
          "type": {
            "type": "string",
            "enum": [
              "string",
              "integer",
              "float",
              "boolean",
              "datetime"
            ],
            "title": "Type"
          }
        },
        "type": "object",
        "required": [
          "name",
          "type"
        ],
        "title": "CreatedKbField",
        "description": "A KB schema field auto-created during an upsert (ensure_target_fields).",
        "example": {
          "name": "department",
          "type": "string"
        }
      },
      "DailyIngestionVolume": {
        "properties": {
          "date": {
            "type": "string",
            "format": "date",
            "title": "Date"
          },
          "data_ingested": {
            "$ref": "#/components/schemas/ByteSizeInfo"
          }
        },
        "type": "object",
        "required": [
          "date",
          "data_ingested"
        ],
        "title": "DailyIngestionVolume",
        "description": "One calendar day's ingestion total, in the caller's local timezone. Days with zero\ningestion still appear (0 B), so the series is gap-free for charting.\n\n:param date: The local calendar day this entry covers.\n:param data_ingested: Bytes ingested on this day.",
        "example": {
          "data_ingested": {
            "bytes": 1572864,
            "display": {
              "unit": "MiB",
              "value": 1.5
            }
          },
          "date": "2026-02-01"
        }
      },
      "DailyIngestionVolumePage": {
        "properties": {
          "total": {
            "type": "integer",
            "title": "Total",
            "description": "Total number of items matching filters"
          },
          "limit": {
            "type": "integer",
            "title": "Limit",
            "description": "Limit applied"
          },
          "offset": {
            "type": "integer",
            "title": "Offset",
            "description": "Offset applied"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/DailyIngestionVolume"
            },
            "type": "array",
            "title": "Items"
          }
        },
        "type": "object",
        "required": [
          "total",
          "limit",
          "offset",
          "items"
        ],
        "title": "DailyIngestionVolumePage",
        "description": "A page of ``DailyIngestionVolume`` entries. ``total`` is the full day-count of the\nrequested range, independent of ``limit``/``offset``.\n\n:param items: The page's entries.",
        "example": {
          "items": [
            {
              "data_ingested": {
                "bytes": 1572864,
                "display": {
                  "unit": "MiB",
                  "value": 1.5
                }
              },
              "date": "2026-02-01"
            },
            {
              "data_ingested": {
                "bytes": 0,
                "display": {
                  "unit": "B",
                  "value": 0
                }
              },
              "date": "2026-02-02"
            }
          ],
          "limit": 31,
          "offset": 0,
          "total": 7
        }
      },
      "DailyPersistedStorage": {
        "properties": {
          "date": {
            "type": "string",
            "format": "date",
            "title": "Date"
          },
          "data_persisted": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ByteSizeInfo"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "type": "object",
        "required": [
          "date",
          "data_persisted"
        ],
        "title": "DailyPersistedStorage",
        "description": "One calendar day's persisted-storage *level*, in the caller's local timezone: the last\npoll run of that day, per Knowledge Base, summed. A day with no poll carries the previous\nlevel forward per KB (a poller outage is not a drop to zero); ``data_persisted`` is ``None``\nfor a day before the scope's first-ever snapshot, which is not the same as 0 B.\n\nUnlike ``DailyIngestionVolume``, these values are levels, not increments \u2014 summing the\nseries is meaningless (see ``ConsumptionUsageResponse.daily_persisted_storage``).\n\n:param date: The local calendar day this entry covers.\n:param data_persisted: Storage level at the end of this day, or ``None`` if unmeasured.",
        "example": {
          "data_persisted": {
            "bytes": 52428800,
            "display": {
              "unit": "MiB",
              "value": 50.0
            }
          },
          "date": "2026-02-01"
        }
      },
      "DailyPersistedStoragePage": {
        "properties": {
          "total": {
            "type": "integer",
            "title": "Total",
            "description": "Total number of items matching filters"
          },
          "limit": {
            "type": "integer",
            "title": "Limit",
            "description": "Limit applied"
          },
          "offset": {
            "type": "integer",
            "title": "Offset",
            "description": "Offset applied"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/DailyPersistedStorage"
            },
            "type": "array",
            "title": "Items"
          }
        },
        "type": "object",
        "required": [
          "total",
          "limit",
          "offset",
          "items"
        ],
        "title": "DailyPersistedStoragePage",
        "description": "A page of ``DailyPersistedStorage`` entries, sharing ``DailyIngestionVolumePage``'s\nlimit/offset page over the same calendar-day range.\n\n:param items: The page's entries.",
        "example": {
          "items": [
            {
              "data_persisted": {
                "bytes": 52428800,
                "display": {
                  "unit": "MiB",
                  "value": 50.0
                }
              },
              "date": "2026-02-01"
            },
            {
              "data_persisted": {
                "bytes": 54525952,
                "display": {
                  "unit": "MiB",
                  "value": 52.0
                }
              },
              "date": "2026-02-02"
            }
          ],
          "limit": 31,
          "offset": 0,
          "total": 7
        }
      },
      "DailyRetrievalVolume": {
        "properties": {
          "date": {
            "type": "string",
            "format": "date",
            "title": "Date"
          },
          "retrieval_calls": {
            "type": "integer",
            "title": "Retrieval Calls"
          }
        },
        "type": "object",
        "required": [
          "date",
          "retrieval_calls"
        ],
        "title": "DailyRetrievalVolume",
        "description": "One calendar day's retrieval-call count, gap-free like ``DailyIngestionVolume``.\n\n:param date: The local calendar day this entry covers.\n:param retrieval_calls: Retrieval calls made on this day.",
        "example": {
          "date": "2026-02-01",
          "retrieval_calls": 42
        }
      },
      "DailyRetrievalVolumePage": {
        "properties": {
          "total": {
            "type": "integer",
            "title": "Total",
            "description": "Total number of items matching filters"
          },
          "limit": {
            "type": "integer",
            "title": "Limit",
            "description": "Limit applied"
          },
          "offset": {
            "type": "integer",
            "title": "Offset",
            "description": "Offset applied"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/DailyRetrievalVolume"
            },
            "type": "array",
            "title": "Items"
          }
        },
        "type": "object",
        "required": [
          "total",
          "limit",
          "offset",
          "items"
        ],
        "title": "DailyRetrievalVolumePage",
        "description": "A page of ``DailyRetrievalVolume`` entries, sharing ``DailyIngestionVolumePage``'s\nlimit/offset page over the same calendar-day range.\n\n:param items: The page's entries.",
        "example": {
          "items": [
            {
              "date": "2026-02-01",
              "retrieval_calls": 42
            },
            {
              "date": "2026-02-02",
              "retrieval_calls": 0
            }
          ],
          "limit": 31,
          "offset": 0,
          "total": 7
        }
      },
      "DataProviderListResponse": {
        "properties": {
          "total": {
            "type": "integer",
            "title": "Total",
            "description": "Total number of items matching filters"
          },
          "limit": {
            "type": "integer",
            "title": "Limit",
            "description": "Limit applied"
          },
          "offset": {
            "type": "integer",
            "title": "Offset",
            "description": "Offset applied"
          },
          "providers": {
            "items": {
              "$ref": "#/components/schemas/DataProviderResponse"
            },
            "type": "array",
            "title": "Providers"
          }
        },
        "type": "object",
        "required": [
          "total",
          "limit",
          "offset",
          "providers"
        ],
        "title": "DataProviderListResponse",
        "description": "Response schema for listing data providers.",
        "example": {
          "limit": 20,
          "offset": 0,
          "providers": [
            {
              "created_at": "2026-01-15T10:30:00Z",
              "created_by": "seed_data_system",
              "enabled": true,
              "id": "boomi_di",
              "name": "Boomi Data Integration",
              "updated_at": "2026-01-15T10:30:00Z",
              "updated_by": "seed_data_system"
            },
            {
              "created_at": "2026-01-15T10:30:00Z",
              "created_by": "seed_data_system",
              "enabled": true,
              "id": "manual_upload",
              "name": "Manual Upload",
              "updated_at": "2026-01-15T10:30:00Z",
              "updated_by": "seed_data_system"
            }
          ],
          "total": 2
        }
      },
      "DataProviderResponse": {
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 255,
            "title": "Name"
          },
          "enabled": {
            "type": "boolean",
            "title": "Enabled",
            "default": true
          },
          "id": {
            "type": "string",
            "title": "Id"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "title": "Updated At"
          },
          "created_by": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Created By"
          },
          "updated_by": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Updated By"
          }
        },
        "type": "object",
        "required": [
          "name",
          "id",
          "created_at",
          "updated_at"
        ],
        "title": "DataProviderResponse",
        "description": "Schema for data provider response.",
        "example": {
          "created_at": "2026-01-15T10:30:00Z",
          "created_by": "seed_data_system",
          "enabled": true,
          "id": "boomi_di",
          "name": "Boomi Data Integration",
          "updated_at": "2026-01-15T10:30:00Z",
          "updated_by": "seed_data_system"
        }
      },
      "DocumentFilter": {
        "properties": {
          "paths": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Paths",
            "description": "Include patterns (supports *, ?, **)"
          },
          "exclude_paths": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Exclude Paths",
            "description": "Exclude patterns"
          },
          "modified_after": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ],
            "title": "Modified After"
          },
          "modified_before": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ],
            "title": "Modified Before"
          },
          "size_min_bytes": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Size Min Bytes"
          },
          "size_max_bytes": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Size Max Bytes"
          },
          "metadata_filter": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Metadata Filter"
          }
        },
        "type": "object",
        "title": "DocumentFilter",
        "description": "Filter criteria for selective document processing."
      },
      "EmbeddingModelListResponse": {
        "properties": {
          "total": {
            "type": "integer",
            "title": "Total",
            "description": "Total number of items matching filters"
          },
          "limit": {
            "type": "integer",
            "title": "Limit",
            "description": "Limit applied"
          },
          "offset": {
            "type": "integer",
            "title": "Offset",
            "description": "Offset applied"
          },
          "models": {
            "items": {
              "$ref": "#/components/schemas/EmbeddingModelResponse"
            },
            "type": "array",
            "title": "Models"
          }
        },
        "type": "object",
        "required": [
          "total",
          "limit",
          "offset",
          "models"
        ],
        "title": "EmbeddingModelListResponse",
        "description": "Response schema for listing embedding models.",
        "example": {
          "limit": 20,
          "models": [
            {
              "created_at": "2026-01-15T10:30:00Z",
              "created_by": "seed_data_system",
              "description": "Cohere's latest embedding model v4",
              "dimensions": 1024,
              "enabled": true,
              "id": "cohere.embed-v4:0",
              "name": "Cohere Embed v4",
              "provider": "bedrock",
              "updated_at": "2026-01-15T10:30:00Z",
              "updated_by": "seed_data_system"
            }
          ],
          "offset": 0,
          "total": 1
        }
      },
      "EmbeddingModelResponse": {
        "properties": {
          "provider": {
            "type": "string",
            "maxLength": 100,
            "title": "Provider",
            "description": "e.g., 'bedrock', 'cohere', 'sagemaker'"
          },
          "name": {
            "type": "string",
            "maxLength": 255,
            "title": "Name",
            "description": "Display name"
          },
          "dimensions": {
            "type": "integer",
            "title": "Dimensions",
            "description": "Vector dimensions"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Description"
          },
          "enabled": {
            "type": "boolean",
            "title": "Enabled",
            "default": true
          },
          "config": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Config",
            "description": "Provider-specific configuration, e.g. SageMaker endpoint_name/region/output_dimension/max_tokens"
          },
          "id": {
            "type": "string",
            "title": "Id"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "title": "Updated At"
          },
          "created_by": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Created By"
          },
          "updated_by": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Updated By"
          }
        },
        "type": "object",
        "required": [
          "provider",
          "name",
          "dimensions",
          "id",
          "created_at",
          "updated_at"
        ],
        "title": "EmbeddingModelResponse",
        "description": "Schema for embedding model response.",
        "example": {
          "created_at": "2026-01-15T10:30:00Z",
          "created_by": "seed_data_system",
          "description": "Cohere's latest embedding model v4",
          "dimensions": 1024,
          "enabled": true,
          "id": "cohere.embed-v4:0",
          "name": "Cohere Embed v4",
          "provider": "bedrock",
          "updated_at": "2026-01-15T10:30:00Z",
          "updated_by": "seed_data_system"
        }
      },
      "FieldMapping": {
        "properties": {
          "source_field": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Source Field",
            "description": "Field name in data source schema. Use '*' for all unmapped fields."
          },
          "expression": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Expression",
            "description": "Expression that produces the value. Mutually exclusive with source_field."
          },
          "target_field": {
            "type": "string",
            "maxLength": 255,
            "title": "Target Field",
            "description": "Field name in KB schema. Use dot notation for nested fields."
          },
          "query_order": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 1.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Query Order",
            "description": "Position in embedding text (1-based). Null means not included in query."
          },
          "match_order": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 1.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Match Order",
            "description": "Position in upsert merge key (1-based). Null means not part of match key."
          },
          "target_field_type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Target Field Type",
            "description": "KB field type hint for auto-creation via ensure_target_fields. Defaults to 'string' if unset."
          },
          "source_date_format": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Source Date Format",
            "description": "strptime-style format string for parsing this field's source value (datetime-typed mappings only). Unset, or a value that doesn't match the format, both fall back to dateutil's flexible parser in kh-worker's cast_to_type \u2014 a non-matching value is not an error."
          },
          "metadata_field": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Metadata Field",
            "description": "Whether or not this field is a metadata field. Defaults to True.",
            "default": true
          }
        },
        "type": "object",
        "required": [
          "target_field"
        ],
        "title": "FieldMapping",
        "description": "Schema for a single field mapping.\n\nThis schema is used by the SchemaMapping SQLModel as a JSONB column type.\nExactly one of source_field or expression must be provided.\n\nRELEASE ROLLOUT GATE (KH-277): `target_field`'s validation was tightened\n(see below) to reject HTML/script content and cap length at 255 chars.\nBecause this model is read via `PydanticJSONB.process_result_value()` on\n*every* DB read of `SourceSchemaMapping.mappings` (not only on writes),\nany pre-existing stored row whose `target_field` violates the new\nconstraint will raise `pydantic.ValidationError` on its very next read \u2014\na production read-path break, not a deferred write-only concern. A\nproduction data audit for non-conforming `target_field` values MUST be\nrun and cleaned up BEFORE any consuming service (kh-api, kh-worker) bumps\nits kh-commons pin past the release containing this change. See KH-277."
      },
      "FileType": {
        "type": "string",
        "enum": [
          "pdf",
          "json",
          "csv",
          "txt",
          "docx",
          "xlsx",
          "html",
          "md",
          "xml"
        ],
        "title": "FileType",
        "description": "Supported file types for Source ingestion."
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError"
      },
      "HealthResponse": {
        "properties": {
          "status": {
            "type": "string",
            "title": "Status",
            "description": "Service health status"
          }
        },
        "type": "object",
        "required": [
          "status"
        ],
        "title": "HealthResponse",
        "description": "Health status of the API service.",
        "example": {
          "status": "healthy"
        }
      },
      "JobError": {
        "properties": {
          "code": {
            "type": "string",
            "title": "Code",
            "description": "Error code, e.g., PARSE_ERROR, CHUNKING_FAILED, EMBEDDING_FAILED"
          },
          "message": {
            "type": "string",
            "title": "Message",
            "description": "Human-readable error message"
          },
          "document_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Document Id"
          },
          "document_path": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Document Path"
          },
          "timestamp": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ],
            "title": "Timestamp"
          }
        },
        "type": "object",
        "required": [
          "code",
          "message"
        ],
        "title": "JobError",
        "description": "Detailed error information for failed documents."
      },
      "JobProgress": {
        "properties": {
          "total_documents": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Total Documents"
          },
          "processed_documents": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Processed Documents"
          },
          "failed_documents": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Failed Documents"
          },
          "chunks_generated": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Chunks Generated"
          },
          "embeddings_created": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Embeddings Created"
          },
          "percent_complete": {
            "anyOf": [
              {
                "type": "number",
                "maximum": 100.0,
                "minimum": 0.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Percent Complete"
          }
        },
        "type": "object",
        "title": "JobProgress",
        "description": "Detailed progress tracking for jobs."
      },
      "JobResponse": {
        "properties": {
          "job_id": {
            "type": "string",
            "format": "uuid",
            "title": "Job Id",
            "description": "Job ID"
          },
          "schema_mapping_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ],
            "title": "Schema Mapping Id",
            "description": "Schema Mapping ID used for this job; null if that mapping has since been deleted"
          },
          "source_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ],
            "title": "Source Id",
            "description": "Source ID derived from schema mapping"
          },
          "source_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Source Name",
            "description": "Source name for display"
          },
          "knowledge_base_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ],
            "title": "Knowledge Base Id",
            "description": "Knowledge Base ID"
          },
          "knowledge_base_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Knowledge Base Name",
            "description": "Knowledge Base name for display"
          },
          "repository_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ],
            "title": "Repository Id",
            "description": "Repository ID"
          },
          "repository_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Repository Name",
            "description": "Repository name for display"
          },
          "status": {
            "$ref": "#/components/schemas/JobStatusEnum",
            "description": "Job status"
          },
          "priority": {
            "type": "integer",
            "title": "Priority",
            "description": "Job priority (1=lowest, 10=highest)"
          },
          "load_mode": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/LoadModeEnum"
              },
              {
                "type": "null"
              }
            ],
            "description": "Load mode the job was created with: append, overwrite, or merge"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At",
            "description": "Job creation timestamp"
          },
          "started_at": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ],
            "title": "Started At",
            "description": "Job start timestamp"
          },
          "completed_at": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ],
            "title": "Completed At",
            "description": "Job completion timestamp"
          },
          "progress": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/JobProgress"
              },
              {
                "type": "null"
              }
            ],
            "description": "Detailed progress tracking"
          },
          "records_received": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Records Received",
            "description": "Total records received"
          },
          "records_processed": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Records Processed",
            "description": "Records successfully processed"
          },
          "records_failed": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Records Failed",
            "description": "Records that failed processing"
          },
          "chunks_created": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Chunks Created",
            "description": "Number of chunks created"
          },
          "embeddings_generated": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Embeddings Generated",
            "description": "Number of embeddings generated"
          },
          "data_volume_bytes": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Data Volume Bytes",
            "description": "Total bytes of source files loaded, exact and never rounded \u2014 the canonical value for sorting/export. knowledge-hub-frontend's Activity Log reads this field directly; see data_volume.bytes for the same value paired with its human-readable display."
          },
          "data_volume": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ByteSizeInfo"
              },
              {
                "type": "null"
              }
            ],
            "description": "data_volume_bytes paired with its human-readable display"
          },
          "errors": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/JobError"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Errors",
            "description": "Detailed error information"
          },
          "external_run_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "External Run Id",
            "description": "External run ID"
          },
          "external_provider": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "External Provider",
            "description": "External provider name"
          },
          "options": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Options",
            "description": "Additional options"
          },
          "error_message": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Error Message",
            "description": "Overall job error message"
          },
          "created_at_ms": {
            "type": "integer",
            "title": "Created At Ms",
            "description": "created_at expressed as UTC epoch milliseconds",
            "readOnly": true
          },
          "started_at_ms": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Started At Ms",
            "description": "started_at expressed as UTC epoch milliseconds",
            "readOnly": true
          },
          "completed_at_ms": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Completed At Ms",
            "description": "completed_at expressed as UTC epoch milliseconds",
            "readOnly": true
          }
        },
        "type": "object",
        "required": [
          "job_id",
          "status",
          "priority",
          "created_at",
          "created_at_ms",
          "started_at_ms",
          "completed_at_ms"
        ],
        "title": "JobResponse",
        "description": "Response schema for a single job.",
        "example": {
          "chunks_created": 340,
          "completed_at": "2026-02-01T08:45:00Z",
          "completed_at_ms": 1769935500000,
          "created_at": "2026-02-01T08:30:00Z",
          "created_at_ms": 1769934600000,
          "data_volume": {
            "bytes": 1572864,
            "display": {
              "unit": "MiB",
              "value": 1.5
            }
          },
          "data_volume_bytes": 1572864,
          "embeddings_generated": 340,
          "external_provider": "rivery",
          "external_run_id": "rivery-12345",
          "job_id": "01920f4a-0000-7000-8000-000000000001",
          "knowledge_base_id": "10000000-0000-0000-0000-000000000001",
          "knowledge_base_name": "HR Policies KB",
          "load_mode": "append",
          "options": {},
          "priority": 5,
          "progress": {
            "chunks_generated": 340,
            "embeddings_created": 340,
            "failed_documents": 0,
            "percent_complete": 100.0,
            "processed_documents": 120,
            "total_documents": 120
          },
          "records_failed": 0,
          "records_processed": 120,
          "records_received": 120,
          "repository_id": "00000000-0000-0000-0000-000000000001",
          "repository_name": "HR Policies",
          "schema_mapping_id": "40000000-0000-0000-0000-000000000001",
          "source_id": "30000000-0000-0000-0000-000000000001",
          "source_name": "HR Jira Issues",
          "started_at": "2026-02-01T08:31:00Z",
          "started_at_ms": 1769934660000,
          "status": "success"
        }
      },
      "JobStatusEnum": {
        "type": "string",
        "enum": [
          "pending",
          "running",
          "success",
          "failed",
          "cancelled",
          "partial"
        ],
        "title": "JobStatusEnum",
        "description": "Job status values for tracking task completion states."
      },
      "JobsListResponse": {
        "properties": {
          "jobs": {
            "items": {
              "$ref": "#/components/schemas/JobResponse"
            },
            "type": "array",
            "title": "Jobs"
          },
          "total": {
            "type": "integer",
            "title": "Total",
            "description": "Total number of jobs matching filters"
          },
          "limit": {
            "type": "integer",
            "title": "Limit",
            "description": "Limit applied"
          },
          "offset": {
            "type": "integer",
            "title": "Offset",
            "description": "Offset applied"
          }
        },
        "type": "object",
        "required": [
          "jobs",
          "total",
          "limit",
          "offset"
        ],
        "title": "JobsListResponse",
        "description": "Response schema for listing jobs.",
        "example": {
          "jobs": [
            {
              "chunks_created": 340,
              "completed_at": "2026-02-01T08:45:00Z",
              "completed_at_ms": 1769935500000,
              "created_at": "2026-02-01T08:30:00Z",
              "created_at_ms": 1769934600000,
              "data_volume": {
                "bytes": 1572864,
                "display": {
                  "unit": "MiB",
                  "value": 1.5
                }
              },
              "data_volume_bytes": 1572864,
              "embeddings_generated": 340,
              "job_id": "01920f4a-0000-7000-8000-000000000001",
              "knowledge_base_id": "10000000-0000-0000-0000-000000000001",
              "knowledge_base_name": "HR Policies KB",
              "load_mode": "append",
              "options": {},
              "priority": 5,
              "records_failed": 0,
              "records_processed": 120,
              "records_received": 120,
              "repository_id": "00000000-0000-0000-0000-000000000001",
              "repository_name": "HR Policies",
              "schema_mapping_id": "40000000-0000-0000-0000-000000000001",
              "source_id": "30000000-0000-0000-0000-000000000001",
              "source_name": "HR Jira Issues",
              "started_at": "2026-02-01T08:31:00Z",
              "started_at_ms": 1769934660000,
              "status": "success"
            }
          ],
          "limit": 20,
          "offset": 0,
          "total": 1
        }
      },
      "KbSchema": {
        "properties": {
          "fields": {
            "items": {
              "$ref": "#/components/schemas/KbSchemaField"
            },
            "type": "array",
            "title": "Fields",
            "default": []
          }
        },
        "type": "object",
        "title": "KbSchema",
        "description": "Knowledge base metadata schema defining user-facing fields.",
        "example": {
          "fields": [
            {
              "description": "Owning department",
              "id": "e0010000-0000-4000-8000-000000000001",
              "name": "department",
              "type": "string"
            },
            {
              "id": "e0010000-0000-4000-8000-000000000002",
              "name": "effective_date",
              "type": "datetime"
            }
          ]
        }
      },
      "KbSchemaField": {
        "properties": {
          "id": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ],
            "title": "Id",
            "description": "Unique field identifier. Preserve across edits to track field changes."
          },
          "name": {
            "type": "string",
            "maxLength": 255,
            "minLength": 1,
            "title": "Name"
          },
          "type": {
            "type": "string",
            "enum": [
              "string",
              "integer",
              "float",
              "boolean",
              "datetime"
            ],
            "title": "Type"
          },
          "description": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 1000
              },
              {
                "type": "null"
              }
            ],
            "title": "Description"
          }
        },
        "type": "object",
        "required": [
          "name",
          "type"
        ],
        "title": "KbSchemaField",
        "description": "A metadata field definition in the KB schema.\n\nThe ``id`` field is a stable identity tracker used to detect renames vs deletions\nwhen the KB schema is updated. Clients that preserve the ``id`` across edits enable\ncascade logic (rename/delete detection). Clients that omit ``id`` (or send ``None``)\nget plain schema replacement with no cascade \u2014 backward compatible.",
        "example": {
          "description": "Owning department",
          "id": "e0010000-0000-4000-8000-000000000001",
          "name": "department",
          "type": "string"
        }
      },
      "KnowledgeBaseCreate": {
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 255,
            "minLength": 1,
            "title": "Name"
          },
          "description": {
            "type": "string",
            "maxLength": 1000,
            "minLength": 1,
            "title": "Description"
          },
          "embedding_model": {
            "type": "string",
            "title": "Embedding Model",
            "description": "Embedding model ID",
            "default": "cohere.embed-v4:0"
          },
          "retrieval_mode": {
            "$ref": "#/components/schemas/RetrievalMode",
            "default": "hybrid"
          },
          "default_top_k": {
            "type": "integer",
            "title": "Default Top K",
            "default": 10
          },
          "repository_id": {
            "type": "string",
            "format": "uuid",
            "title": "Repository Id"
          },
          "collection_name": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 255,
                "minLength": 1
              },
              {
                "type": "null"
              }
            ],
            "title": "Collection Name",
            "description": "Vector store collection name. Auto-generated from name if not provided"
          },
          "kb_schema": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/KbSchema"
              },
              {
                "type": "null"
              }
            ],
            "description": "Metadata field definitions for this knowledge base. Each field describes a metadata key stored in the vector document. If not provided, an empty schema is created (no metadata fields)."
          },
          "retrieval_config": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Retrieval Config"
          }
        },
        "type": "object",
        "required": [
          "name",
          "description",
          "repository_id"
        ],
        "title": "KnowledgeBaseCreate",
        "description": "Schema for creating a knowledge base.",
        "example": {
          "default_top_k": 10,
          "description": "HR policies for employee self-service",
          "embedding_model": "cohere.embed-v4:0",
          "kb_schema": {
            "fields": [
              {
                "description": "Owning department",
                "id": "e0010000-0000-4000-8000-000000000001",
                "name": "department",
                "type": "string"
              },
              {
                "id": "e0010000-0000-4000-8000-000000000002",
                "name": "effective_date",
                "type": "datetime"
              }
            ]
          },
          "name": "HR Policies KB",
          "repository_id": "00000000-0000-0000-0000-000000000001",
          "retrieval_mode": "hybrid"
        }
      },
      "KnowledgeBaseCreateResponse": {
        "properties": {
          "status": {
            "type": "string",
            "title": "Status",
            "default": "ok"
          },
          "knowledge_base_id": {
            "type": "string",
            "format": "uuid",
            "title": "Knowledge Base Id"
          }
        },
        "type": "object",
        "required": [
          "knowledge_base_id"
        ],
        "title": "KnowledgeBaseCreateResponse",
        "description": "Response schema for creating a knowledge base.",
        "example": {
          "knowledge_base_id": "10000000-0000-0000-0000-000000000001",
          "status": "ok"
        }
      },
      "KnowledgeBaseListResponse": {
        "properties": {
          "total": {
            "type": "integer",
            "title": "Total",
            "description": "Total number of items matching filters"
          },
          "limit": {
            "type": "integer",
            "title": "Limit",
            "description": "Limit applied"
          },
          "offset": {
            "type": "integer",
            "title": "Offset",
            "description": "Offset applied"
          },
          "knowledge_bases": {
            "items": {
              "$ref": "#/components/schemas/KnowledgeBaseResponse"
            },
            "type": "array",
            "title": "Knowledge Bases"
          }
        },
        "type": "object",
        "required": [
          "total",
          "limit",
          "offset",
          "knowledge_bases"
        ],
        "title": "KnowledgeBaseListResponse",
        "description": "Response schema for listing knowledge bases.",
        "example": {
          "knowledge_bases": [
            {
              "collection_name": "hr-policies-kb-1a2b3c4d5e6f",
              "created_at": "2026-01-15T10:30:00Z",
              "default_top_k": 10,
              "description": "HR policies for employee self-service",
              "embedding_model": "cohere.embed-v4:0",
              "field_source_counts": {},
              "id": "10000000-0000-0000-0000-000000000001",
              "kb_schema": {
                "fields": []
              },
              "name": "HR Policies KB",
              "repository_id": "00000000-0000-0000-0000-000000000001",
              "retrieval_mode": "hybrid",
              "source_count": 1,
              "status": "enabled",
              "updated_at": "2026-02-01T09:00:00Z"
            }
          ],
          "limit": 20,
          "offset": 0,
          "total": 1
        }
      },
      "KnowledgeBaseResponse": {
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 255,
            "minLength": 1,
            "title": "Name"
          },
          "description": {
            "type": "string",
            "maxLength": 1000,
            "minLength": 1,
            "title": "Description"
          },
          "embedding_model": {
            "type": "string",
            "title": "Embedding Model",
            "description": "Embedding model ID",
            "default": "cohere.embed-v4:0"
          },
          "retrieval_mode": {
            "$ref": "#/components/schemas/RetrievalMode",
            "default": "hybrid"
          },
          "default_top_k": {
            "type": "integer",
            "title": "Default Top K",
            "default": 10
          },
          "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
          },
          "repository_id": {
            "type": "string",
            "format": "uuid",
            "title": "Repository Id"
          },
          "collection_name": {
            "type": "string",
            "title": "Collection Name"
          },
          "embedding_model_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Embedding Model Name",
            "description": "Display name of the embedding model."
          },
          "embedding_model_provider": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Embedding Model Provider",
            "description": "Provider/routing key for the embedding model."
          },
          "kb_schema": {
            "$ref": "#/components/schemas/KbSchema"
          },
          "retrieval_config": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Retrieval Config"
          },
          "status": {
            "$ref": "#/components/schemas/KnowledgeBaseStatus"
          },
          "source_count": {
            "type": "integer",
            "title": "Source Count",
            "default": 0
          },
          "field_source_counts": {
            "additionalProperties": {
              "type": "integer"
            },
            "type": "object",
            "title": "Field Source Counts"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "title": "Updated At"
          },
          "created_by": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Created By"
          },
          "updated_by": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Updated By"
          }
        },
        "type": "object",
        "required": [
          "name",
          "description",
          "id",
          "repository_id",
          "collection_name",
          "kb_schema",
          "status",
          "created_at",
          "updated_at"
        ],
        "title": "KnowledgeBaseResponse",
        "description": "Schema for knowledge base response.",
        "example": {
          "collection_name": "hr-policies-kb-1a2b3c4d5e6f",
          "created_at": "2026-01-15T10:30:00Z",
          "created_by": "admin@boomi.com",
          "default_top_k": 10,
          "description": "HR policies for employee self-service",
          "embedding_model": "cohere.embed-v4:0",
          "embedding_model_name": "Cohere Embed v4",
          "embedding_model_provider": "bedrock",
          "field_source_counts": {
            "department": 1
          },
          "id": "10000000-0000-0000-0000-000000000001",
          "kb_schema": {
            "fields": [
              {
                "description": "Owning department",
                "id": "e0010000-0000-4000-8000-000000000001",
                "name": "department",
                "type": "string"
              }
            ]
          },
          "name": "HR Policies KB",
          "repository_id": "00000000-0000-0000-0000-000000000001",
          "retrieval_mode": "hybrid",
          "source_count": 1,
          "status": "enabled",
          "updated_at": "2026-02-01T09:00:00Z",
          "updated_by": "admin@boomi.com"
        }
      },
      "KnowledgeBaseSchemaResponse": {
        "properties": {
          "knowledge_base_id": {
            "type": "string",
            "format": "uuid",
            "title": "Knowledge Base Id"
          },
          "kb_schema": {
            "$ref": "#/components/schemas/KbSchema"
          }
        },
        "type": "object",
        "required": [
          "knowledge_base_id",
          "kb_schema"
        ],
        "title": "KnowledgeBaseSchemaResponse",
        "description": "Response schema for GET /knowledge-bases/{id}/schema.\n\nThe KB's metadata schema alone (Retriever surface), no config payload.",
        "example": {
          "kb_schema": {
            "fields": [
              {
                "description": "Owning department",
                "id": "e0010000-0000-4000-8000-000000000001",
                "name": "department",
                "type": "string"
              }
            ]
          },
          "knowledge_base_id": "10000000-0000-0000-0000-000000000001"
        }
      },
      "KnowledgeBaseSourcesListResponse": {
        "properties": {
          "total": {
            "type": "integer",
            "title": "Total",
            "description": "Total number of items matching filters"
          },
          "limit": {
            "type": "integer",
            "title": "Limit",
            "description": "Limit applied"
          },
          "offset": {
            "type": "integer",
            "title": "Offset",
            "description": "Offset applied"
          },
          "sources": {
            "items": {
              "$ref": "#/components/schemas/SourceWithMappingResponse"
            },
            "type": "array",
            "title": "Sources"
          }
        },
        "type": "object",
        "required": [
          "total",
          "limit",
          "offset",
          "sources"
        ],
        "title": "KnowledgeBaseSourcesListResponse",
        "description": "Response for listing sources in a knowledge base.",
        "example": {
          "limit": 20,
          "offset": 0,
          "sources": [
            {
              "created_at": "2026-01-15T10:30:00Z",
              "file_type": "json",
              "id": "30000000-0000-0000-0000-000000000001",
              "name": "HR Jira Issues",
              "schema_mapping_id": "40000000-0000-0000-0000-000000000001",
              "source_name": "HR Jira",
              "source_schema": {
                "fields": [
                  {
                    "embeddable": true,
                    "metadata_eligible": true,
                    "name": "summary",
                    "type": "string"
                  }
                ]
              },
              "source_type": "jira",
              "status": "active",
              "updated_at": "2026-02-01T09:00:00Z"
            }
          ],
          "total": 1
        }
      },
      "KnowledgeBaseStatus": {
        "type": "string",
        "enum": [
          "enabled",
          "archived",
          "draft",
          "disabled"
        ],
        "title": "KnowledgeBaseStatus",
        "description": "Valid statuses for KnowledgeBase."
      },
      "KnowledgeBaseStatusUpdate": {
        "properties": {
          "status": {
            "$ref": "#/components/schemas/KnowledgeBaseStatus",
            "description": "Target status for the knowledge base"
          }
        },
        "type": "object",
        "required": [
          "status"
        ],
        "title": "KnowledgeBaseStatusUpdate",
        "description": "Schema for updating knowledge base status via dedicated endpoint.",
        "example": {
          "status": "enabled"
        }
      },
      "KnowledgeBaseUpdate": {
        "properties": {
          "name": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 255,
                "minLength": 1
              },
              {
                "type": "null"
              }
            ],
            "title": "Name"
          },
          "description": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 1000,
                "minLength": 1
              },
              {
                "type": "null"
              }
            ],
            "title": "Description"
          },
          "retrieval_mode": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/RetrievalMode"
              },
              {
                "type": "null"
              }
            ]
          },
          "default_top_k": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Default Top K"
          },
          "retrieval_config": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Retrieval Config"
          },
          "kb_schema": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/KbSchema"
              },
              {
                "type": "null"
              }
            ],
            "description": "Full replacement of the metadata field definitions. Fields not included will be removed."
          }
        },
        "type": "object",
        "title": "KnowledgeBaseUpdate",
        "description": "Schema for updating a knowledge base.",
        "example": {
          "default_top_k": 10,
          "description": "Updated HR policies knowledge base",
          "name": "HR Policies KB 2026",
          "retrieval_mode": "hybrid"
        }
      },
      "LastIngestion": {
        "properties": {
          "job_id": {
            "type": "string",
            "format": "uuid",
            "title": "Job Id"
          },
          "status": {
            "$ref": "#/components/schemas/JobStatusEnum"
          },
          "completed_at": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ],
            "title": "Completed At"
          },
          "error_message": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Error Message"
          },
          "records_processed": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Records Processed"
          },
          "records_failed": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Records Failed"
          }
        },
        "type": "object",
        "required": [
          "job_id",
          "status"
        ],
        "title": "LastIngestion",
        "description": "Last completed ingestion job data for a source.",
        "example": {
          "completed_at": "2026-02-01T08:45:00Z",
          "job_id": "01920f4a-0000-7000-8000-000000000001",
          "records_failed": 0,
          "records_processed": 120,
          "status": "success"
        }
      },
      "LoadModeEnum": {
        "type": "string",
        "enum": [
          "append",
          "overwrite",
          "merge"
        ],
        "title": "LoadModeEnum",
        "description": "Load mode enumeration for data loading strategies."
      },
      "PeriodOverPeriodDelta": {
        "properties": {
          "current": {
            "type": "integer",
            "title": "Current"
          },
          "previous": {
            "type": "integer",
            "title": "Previous"
          },
          "delta_pct": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Delta Pct"
          }
        },
        "type": "object",
        "required": [
          "current",
          "previous",
          "delta_pct"
        ],
        "title": "PeriodOverPeriodDelta",
        "description": "A dimension's current total against the immediately-preceding period of equal length\n(Figma node 29034-190508 \u2014 the ``+14.9%``/``-3.6%`` pill next to each KPI tile).\n\n:param current: Raw total for the requested range (never the rounded display value).\n:param previous: The same raw total for the preceding period.\n:param delta_pct: ``(current - previous) / previous * 100``, rounded to 1 decimal. ``None``\n    when ``previous`` is 0 \u2014 undefined, not infinite.",
        "example": {
          "current": 3145728,
          "delta_pct": 100.0,
          "previous": 1572864
        }
      },
      "RepositoryCreate": {
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 255,
            "minLength": 1,
            "title": "Name"
          },
          "description": {
            "type": "string",
            "maxLength": 1000,
            "title": "Description"
          },
          "repository_type": {
            "$ref": "#/components/schemas/RepositoryType"
          },
          "vector_store": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/VectorStoreConfig"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "type": "object",
        "required": [
          "name",
          "description",
          "repository_type"
        ],
        "title": "RepositoryCreate",
        "description": "Schema for creating a repository.",
        "example": {
          "description": "HR policy documents for the company wiki",
          "name": "HR Policies",
          "repository_type": "managed"
        }
      },
      "RepositoryCreateResponse": {
        "properties": {
          "status": {
            "type": "string",
            "title": "Status",
            "default": "ok"
          },
          "repository_id": {
            "type": "string",
            "format": "uuid",
            "title": "Repository Id"
          }
        },
        "type": "object",
        "required": [
          "repository_id"
        ],
        "title": "RepositoryCreateResponse",
        "description": "Response schema for creating a repository.\n\nPer OpenAPI spec, returns status and the new repository_id.",
        "example": {
          "repository_id": "00000000-0000-0000-0000-000000000001",
          "status": "ok"
        }
      },
      "RepositoryListResponse": {
        "properties": {
          "total": {
            "type": "integer",
            "title": "Total",
            "description": "Total number of items matching filters"
          },
          "limit": {
            "type": "integer",
            "title": "Limit",
            "description": "Limit applied"
          },
          "offset": {
            "type": "integer",
            "title": "Offset",
            "description": "Offset applied"
          },
          "repositories": {
            "items": {
              "$ref": "#/components/schemas/RepositoryResponse"
            },
            "type": "array",
            "title": "Repositories"
          }
        },
        "type": "object",
        "required": [
          "total",
          "limit",
          "offset",
          "repositories"
        ],
        "title": "RepositoryListResponse",
        "description": "Response schema for listing repositories.",
        "example": {
          "limit": 20,
          "offset": 0,
          "repositories": [
            {
              "created_at": "2026-01-15T10:30:00Z",
              "created_by": "admin@boomi.com",
              "description": "HR policy documents for the company wiki",
              "id": "00000000-0000-0000-0000-000000000001",
              "knowledge_base_count": 2,
              "name": "HR Policies",
              "repository_type": "managed",
              "status": "enabled",
              "updated_at": "2026-02-01T09:00:00Z",
              "updated_by": "admin@boomi.com"
            }
          ],
          "total": 1
        }
      },
      "RepositoryResponse": {
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
          },
          "name": {
            "type": "string",
            "title": "Name"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Description"
          },
          "repository_type": {
            "$ref": "#/components/schemas/RepositoryType"
          },
          "status": {
            "$ref": "#/components/schemas/RepositoryStatus"
          },
          "vector_store": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/VectorStoreConfig"
              },
              {
                "type": "null"
              }
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "title": "Updated At"
          },
          "created_by": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Created By"
          },
          "updated_by": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Updated By"
          },
          "knowledge_base_count": {
            "type": "integer",
            "title": "Knowledge Base Count",
            "default": 0
          }
        },
        "type": "object",
        "required": [
          "id",
          "name",
          "repository_type",
          "status",
          "created_at",
          "updated_at"
        ],
        "title": "RepositoryResponse",
        "description": "Schema for repository response.\n\nFor ``MANAGED`` repositories the ``vector_store`` field is intrinsically\nblanked at validation time \u2014 the platform-owned endpoint is not leaked\nvia the API. This guard lives on the schema (rather than on the route\nhelper) so any current or future endpoint returning this model gets the\nbehaviour for free.",
        "example": {
          "created_at": "2026-01-15T10:30:00Z",
          "created_by": "admin@boomi.com",
          "description": "HR policy documents for the company wiki",
          "id": "00000000-0000-0000-0000-000000000001",
          "knowledge_base_count": 2,
          "name": "HR Policies",
          "repository_type": "managed",
          "status": "enabled",
          "updated_at": "2026-02-01T09:00:00Z",
          "updated_by": "admin@boomi.com"
        }
      },
      "RepositoryStatus": {
        "type": "string",
        "enum": [
          "draft",
          "enabled",
          "archived"
        ],
        "title": "RepositoryStatus",
        "description": "Valid statuses for Repository."
      },
      "RepositoryType": {
        "type": "string",
        "enum": [
          "owned",
          "managed"
        ],
        "title": "RepositoryType",
        "description": "Valid types for Repository."
      },
      "RepositoryUpdate": {
        "properties": {
          "name": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 255,
                "minLength": 1
              },
              {
                "type": "null"
              }
            ],
            "title": "Name"
          },
          "description": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 1000
              },
              {
                "type": "null"
              }
            ],
            "title": "Description"
          }
        },
        "type": "object",
        "title": "RepositoryUpdate",
        "description": "Schema for updating a repository.",
        "example": {
          "description": "Updated title",
          "name": "HR Policies 2026"
        }
      },
      "RetrievalMode": {
        "type": "string",
        "enum": [
          "semantic",
          "lexical",
          "hybrid"
        ],
        "title": "RetrievalMode",
        "description": "Valid retrieval modes for KnowledgeBase."
      },
      "SchemaMappingResponse": {
        "properties": {
          "mappings": {
            "items": {
              "$ref": "#/components/schemas/FieldMapping"
            },
            "type": "array",
            "title": "Mappings",
            "description": "Field mappings from source to KB schema"
          },
          "chunking_config": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ChunkingConfig"
              },
              {
                "type": "null"
              }
            ]
          },
          "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
          },
          "source_id": {
            "type": "string",
            "format": "uuid",
            "title": "Source Id"
          },
          "knowledge_base_id": {
            "type": "string",
            "format": "uuid",
            "title": "Knowledge Base Id"
          },
          "status": {
            "$ref": "#/components/schemas/SchemaMappingStatus"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "title": "Updated At"
          },
          "created_by": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Created By"
          },
          "updated_by": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Updated By"
          },
          "created_kb_fields": {
            "items": {
              "$ref": "#/components/schemas/CreatedKbField"
            },
            "type": "array",
            "title": "Created Kb Fields",
            "description": "KB schema fields auto-created during a PUT upsert when ensure_target_fields created new fields. Present on all schema-mapping responses (GET, PATCH /status, PUT); always empty except on a PUT upsert that created fields."
          }
        },
        "type": "object",
        "required": [
          "mappings",
          "id",
          "source_id",
          "knowledge_base_id",
          "status",
          "created_at",
          "updated_at"
        ],
        "title": "SchemaMappingResponse",
        "description": "Schema for schema mapping response.",
        "example": {
          "chunking_config": {
            "chunk_size": 1000,
            "overlap_percent": 10,
            "strategy": "fixed"
          },
          "created_at": "2026-01-15T10:30:00Z",
          "created_by": "admin@boomi.com",
          "created_kb_fields": [
            {
              "name": "department",
              "type": "string"
            }
          ],
          "id": "40000000-0000-0000-0000-000000000001",
          "knowledge_base_id": "10000000-0000-0000-0000-000000000001",
          "mappings": [
            {
              "query_order": 1,
              "source_field": "summary",
              "target_field": "_content_",
              "target_field_type": "string"
            },
            {
              "match_order": 1,
              "source_field": "id",
              "target_field": "id",
              "target_field_type": "string"
            }
          ],
          "source_id": "30000000-0000-0000-0000-000000000001",
          "status": "active",
          "updated_at": "2026-02-01T09:00:00Z",
          "updated_by": "admin@boomi.com"
        }
      },
      "SchemaMappingStatus": {
        "type": "string",
        "enum": [
          "active",
          "disabled"
        ],
        "title": "SchemaMappingStatus",
        "description": "Valid statuses for SourceSchemaMapping."
      },
      "SchemaMappingStatusUpdate": {
        "properties": {
          "status": {
            "$ref": "#/components/schemas/SchemaMappingStatus",
            "description": "Target status for the schema mapping"
          }
        },
        "type": "object",
        "required": [
          "status"
        ],
        "title": "SchemaMappingStatusUpdate",
        "description": "Schema for updating schema mapping status via dedicated endpoint.",
        "example": {
          "status": "active"
        }
      },
      "SchemaMappingUpdate": {
        "properties": {
          "mappings": {
            "items": {
              "$ref": "#/components/schemas/FieldMapping"
            },
            "type": "array",
            "title": "Mappings",
            "description": "Field mappings from source to KB schema"
          },
          "chunking_config": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ChunkingConfig"
              },
              {
                "type": "null"
              }
            ],
            "description": "Configuration for how source text is split into chunks"
          },
          "ensure_target_fields": {
            "type": "boolean",
            "title": "Ensure Target Fields",
            "description": "When true, auto-create any KB schema fields referenced by mappings that do not yet exist on the KB. Creation-only: never mutates existing field types.",
            "default": false
          }
        },
        "type": "object",
        "required": [
          "mappings"
        ],
        "title": "SchemaMappingUpdate",
        "description": "Schema for creating or updating a schema mapping (PUT endpoint).\n\nmappings is required but may be empty: an empty list creates/keeps a bare source<->KB\nlink. The mapping stays inert until configured (source activation requires query_order).",
        "example": {
          "chunking_config": {
            "chunk_size": 1000,
            "overlap_percent": 10,
            "strategy": "fixed"
          },
          "ensure_target_fields": true,
          "mappings": [
            {
              "query_order": 1,
              "source_field": "summary",
              "target_field": "_content_",
              "target_field_type": "string"
            },
            {
              "match_order": 1,
              "source_field": "id",
              "target_field": "id",
              "target_field_type": "string"
            },
            {
              "source_field": "department",
              "target_field": "department",
              "target_field_type": "string"
            }
          ]
        }
      },
      "SourceField-Input": {
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "title": "Name",
            "description": "Field name in the source system"
          },
          "type": {
            "$ref": "#/components/schemas/SourceFieldType",
            "description": "Field data type"
          }
        },
        "type": "object",
        "required": [
          "name",
          "type"
        ],
        "title": "SourceField",
        "description": "Field definition in a source schema.",
        "example": {
          "embeddable": true,
          "metadata_eligible": true,
          "name": "summary",
          "type": "string"
        }
      },
      "SourceField-Output": {
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "title": "Name",
            "description": "Field name in the source system"
          },
          "type": {
            "$ref": "#/components/schemas/SourceFieldType",
            "description": "Field data type"
          },
          "embeddable": {
            "type": "boolean",
            "title": "Embeddable",
            "description": "True if field can be selected as text_field for embedding (only string types).",
            "readOnly": true
          },
          "metadata_eligible": {
            "type": "boolean",
            "title": "Metadata Eligible",
            "description": "True if field can be selected as metadata.",
            "readOnly": true
          }
        },
        "type": "object",
        "required": [
          "name",
          "type",
          "embeddable",
          "metadata_eligible"
        ],
        "title": "SourceField",
        "description": "Field definition in a source schema.",
        "example": {
          "embeddable": true,
          "metadata_eligible": true,
          "name": "summary",
          "type": "string"
        }
      },
      "SourceFieldType": {
        "type": "string",
        "enum": [
          "string",
          "integer",
          "float",
          "boolean",
          "datetime",
          "array",
          "object"
        ],
        "title": "SourceFieldType",
        "description": "Valid field types for source schema."
      },
      "SourceItemCreate": {
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 255,
            "minLength": 1,
            "title": "Name",
            "description": "Source name"
          },
          "file_type": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FileType"
              },
              {
                "type": "null"
              }
            ],
            "description": "Supported file type for ingestion"
          },
          "is_unstructured": {
            "type": "boolean",
            "title": "Is Unstructured",
            "description": "True when the source has no structured schema; kh-api builds it (KH-433)",
            "default": false
          },
          "source_schema": {
            "$ref": "#/components/schemas/SourceSchema-Input",
            "description": "Source schema fields"
          },
          "custom_metadata": {
            "anyOf": [
              {
                "additionalProperties": {
                  "type": "string"
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Custom Metadata",
            "description": "User-defined key-value pairs"
          }
        },
        "type": "object",
        "required": [
          "name",
          "source_schema"
        ],
        "title": "SourceItemCreate",
        "description": "Individual source item in batch create request.",
        "example": {
          "file_type": "json",
          "name": "HR Jira Issues",
          "source_schema": {
            "fields": [
              {
                "embeddable": true,
                "metadata_eligible": true,
                "name": "id",
                "type": "string"
              },
              {
                "embeddable": true,
                "metadata_eligible": true,
                "name": "summary",
                "type": "string"
              }
            ]
          }
        }
      },
      "SourceListResponse": {
        "properties": {
          "total": {
            "type": "integer",
            "title": "Total",
            "description": "Total number of items matching filters"
          },
          "limit": {
            "type": "integer",
            "title": "Limit",
            "description": "Limit applied"
          },
          "offset": {
            "type": "integer",
            "title": "Offset",
            "description": "Offset applied"
          },
          "sources": {
            "items": {
              "$ref": "#/components/schemas/SourceResponse"
            },
            "type": "array",
            "title": "Sources"
          }
        },
        "type": "object",
        "required": [
          "total",
          "limit",
          "offset",
          "sources"
        ],
        "title": "SourceListResponse",
        "description": "Response schema for listing sources.",
        "example": {
          "limit": 20,
          "offset": 0,
          "sources": [
            {
              "created_at": "2026-01-15T10:30:00Z",
              "file_type": "json",
              "id": "30000000-0000-0000-0000-000000000001",
              "name": "HR Jira Issues",
              "source_name": "HR Jira",
              "source_schema": {
                "fields": [
                  {
                    "embeddable": true,
                    "metadata_eligible": true,
                    "name": "summary",
                    "type": "string"
                  }
                ]
              },
              "source_type": "jira",
              "status": "active",
              "updated_at": "2026-02-01T09:00:00Z"
            }
          ],
          "total": 1
        }
      },
      "SourceResponse": {
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 255,
            "minLength": 1,
            "title": "Name"
          },
          "source_type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Source Type",
            "description": "e.g., 'jira', 'salesforce'"
          },
          "source_name": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 255
              },
              {
                "type": "null"
              }
            ],
            "title": "Source Name",
            "description": "Display name"
          },
          "file_type": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FileType"
              },
              {
                "type": "null"
              }
            ],
            "description": "Supported file type for ingestion"
          },
          "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
          },
          "source_schema": {
            "$ref": "#/components/schemas/SourceSchema-Output"
          },
          "source_metadata": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Source Metadata"
          },
          "is_unstructured": {
            "type": "boolean",
            "title": "Is Unstructured",
            "default": false
          },
          "status": {
            "$ref": "#/components/schemas/SourceStatus"
          },
          "last_ingestion": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/LastIngestion"
              },
              {
                "type": "null"
              }
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "title": "Updated At"
          },
          "created_by": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Created By"
          },
          "updated_by": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Updated By"
          }
        },
        "type": "object",
        "required": [
          "name",
          "id",
          "source_schema",
          "status",
          "created_at",
          "updated_at"
        ],
        "title": "SourceResponse",
        "description": "Schema for source response.",
        "example": {
          "created_at": "2026-01-15T10:30:00Z",
          "created_by": "admin@boomi.com",
          "file_type": "json",
          "id": "30000000-0000-0000-0000-000000000001",
          "last_ingestion": {
            "completed_at": "2026-02-01T08:45:00Z",
            "job_id": "01920f4a-0000-7000-8000-000000000001",
            "records_failed": 0,
            "records_processed": 120,
            "status": "success"
          },
          "name": "HR Jira Issues",
          "source_name": "HR Jira",
          "source_schema": {
            "fields": [
              {
                "embeddable": true,
                "metadata_eligible": true,
                "name": "id",
                "type": "string"
              },
              {
                "embeddable": true,
                "metadata_eligible": true,
                "name": "summary",
                "type": "string"
              }
            ]
          },
          "source_type": "jira",
          "status": "active",
          "updated_at": "2026-02-01T09:00:00Z",
          "updated_by": "admin@boomi.com"
        }
      },
      "SourceSchema-Input": {
        "properties": {
          "fields": {
            "items": {
              "$ref": "#/components/schemas/SourceField-Input"
            },
            "type": "array",
            "minItems": 0,
            "title": "Fields",
            "description": "List of fields available in the source"
          }
        },
        "type": "object",
        "required": [
          "fields"
        ],
        "title": "SourceSchema",
        "description": "Schema describing source data structure.",
        "example": {
          "fields": [
            {
              "embeddable": true,
              "metadata_eligible": true,
              "name": "id",
              "type": "string"
            },
            {
              "embeddable": true,
              "metadata_eligible": true,
              "name": "summary",
              "type": "string"
            },
            {
              "embeddable": false,
              "metadata_eligible": true,
              "name": "created",
              "type": "datetime"
            }
          ]
        }
      },
      "SourceSchema-Output": {
        "properties": {
          "fields": {
            "items": {
              "$ref": "#/components/schemas/SourceField-Output"
            },
            "type": "array",
            "minItems": 0,
            "title": "Fields",
            "description": "List of fields available in the source"
          }
        },
        "type": "object",
        "required": [
          "fields"
        ],
        "title": "SourceSchema",
        "description": "Schema describing source data structure.",
        "example": {
          "fields": [
            {
              "embeddable": true,
              "metadata_eligible": true,
              "name": "id",
              "type": "string"
            },
            {
              "embeddable": true,
              "metadata_eligible": true,
              "name": "summary",
              "type": "string"
            },
            {
              "embeddable": false,
              "metadata_eligible": true,
              "name": "created",
              "type": "datetime"
            }
          ]
        }
      },
      "SourceStatus": {
        "type": "string",
        "enum": [
          "draft",
          "active",
          "disabled",
          "archived"
        ],
        "title": "SourceStatus",
        "description": "Valid statuses for Source."
      },
      "SourceStatusUpdate": {
        "properties": {
          "status": {
            "$ref": "#/components/schemas/SourceStatus",
            "description": "Target status for the source"
          }
        },
        "type": "object",
        "required": [
          "status"
        ],
        "title": "SourceStatusUpdate",
        "description": "Schema for updating source status via dedicated endpoint.",
        "example": {
          "status": "active"
        }
      },
      "SourceUpdate": {
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 255,
            "minLength": 1,
            "title": "Name"
          },
          "source_type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Source Type"
          },
          "source_name": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 255
              },
              {
                "type": "null"
              }
            ],
            "title": "Source Name",
            "description": "Display name"
          },
          "file_type": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FileType"
              },
              {
                "type": "null"
              }
            ]
          },
          "source_metadata": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Source Metadata"
          }
        },
        "type": "object",
        "title": "SourceUpdate",
        "description": "Schema for updating a source.\n\nAll fields can be updated regardless of status (except archived sources \u2192 404).\nStatus changes go through the dedicated PATCH /sources/{id}/status endpoint.",
        "example": {
          "file_type": "json",
          "name": "HR Jira Issues",
          "source_name": "HR Jira"
        }
      },
      "SourceWithMappingResponse": {
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 255,
            "minLength": 1,
            "title": "Name"
          },
          "source_type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Source Type",
            "description": "e.g., 'jira', 'salesforce'"
          },
          "source_name": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 255
              },
              {
                "type": "null"
              }
            ],
            "title": "Source Name",
            "description": "Display name"
          },
          "file_type": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FileType"
              },
              {
                "type": "null"
              }
            ],
            "description": "Supported file type for ingestion"
          },
          "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
          },
          "source_schema": {
            "$ref": "#/components/schemas/SourceSchema-Output"
          },
          "source_metadata": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Source Metadata"
          },
          "is_unstructured": {
            "type": "boolean",
            "title": "Is Unstructured",
            "default": false
          },
          "status": {
            "$ref": "#/components/schemas/SourceStatus"
          },
          "last_ingestion": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/LastIngestion"
              },
              {
                "type": "null"
              }
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "title": "Updated At"
          },
          "created_by": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Created By"
          },
          "updated_by": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Updated By"
          },
          "schema_mapping_id": {
            "type": "string",
            "format": "uuid",
            "title": "Schema Mapping Id",
            "description": "ID of the schema mapping connecting this source to the KB"
          }
        },
        "type": "object",
        "required": [
          "name",
          "id",
          "source_schema",
          "status",
          "created_at",
          "updated_at",
          "schema_mapping_id"
        ],
        "title": "SourceWithMappingResponse",
        "description": "Source with schema mapping context for KB listing.",
        "example": {
          "created_at": "2026-01-15T10:30:00Z",
          "file_type": "json",
          "id": "30000000-0000-0000-0000-000000000001",
          "name": "HR Jira Issues",
          "schema_mapping_id": "40000000-0000-0000-0000-000000000001",
          "source_name": "HR Jira",
          "source_schema": {
            "fields": [
              {
                "embeddable": true,
                "metadata_eligible": true,
                "name": "summary",
                "type": "string"
              }
            ]
          },
          "source_type": "jira",
          "status": "active",
          "updated_at": "2026-02-01T09:00:00Z"
        }
      },
      "StagedDataRefRequest": {
        "properties": {
          "bucket": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Bucket",
            "description": "Bucket/container name (S3, GCS, Azure)"
          },
          "prefix": {
            "type": "string",
            "title": "Prefix",
            "description": "File path/key within storage"
          },
          "credentials": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Credentials",
            "description": "Runtime credentials to access staged data (not stored)"
          }
        },
        "type": "object",
        "required": [
          "prefix"
        ],
        "title": "StagedDataRefRequest",
        "description": "Staged data reference for job creation, including credentials to access it.",
        "example": {
          "bucket": "kh-staging-bucket",
          "prefix": "hr-policies/2026-02/"
        }
      },
      "StagingProviderListResponse": {
        "properties": {
          "total": {
            "type": "integer",
            "title": "Total",
            "description": "Total number of items matching filters"
          },
          "limit": {
            "type": "integer",
            "title": "Limit",
            "description": "Limit applied"
          },
          "offset": {
            "type": "integer",
            "title": "Offset",
            "description": "Offset applied"
          },
          "providers": {
            "items": {
              "$ref": "#/components/schemas/StagingProviderResponse"
            },
            "type": "array",
            "title": "Providers"
          }
        },
        "type": "object",
        "required": [
          "total",
          "limit",
          "offset",
          "providers"
        ],
        "title": "StagingProviderListResponse",
        "description": "Response schema for listing staging providers.",
        "example": {
          "limit": 20,
          "offset": 0,
          "providers": [
            {
              "id": "s3",
              "name": "Amazon S3"
            }
          ],
          "total": 1
        }
      },
      "StagingProviderResponse": {
        "properties": {
          "id": {
            "type": "string",
            "maxLength": 50,
            "minLength": 1,
            "title": "Id",
            "description": "Unique identifier for the staging provider",
            "example": "s3"
          },
          "name": {
            "type": "string",
            "maxLength": 255,
            "minLength": 1,
            "title": "Name",
            "description": "Display name of the staging provider",
            "example": "Amazon S3"
          }
        },
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "title": "StagingProviderResponse",
        "description": "Schema for staging provider response.",
        "example": {
          "id": "s3",
          "name": "Amazon S3"
        }
      },
      "StorageTypeEnum": {
        "type": "string",
        "enum": [
          "s3",
          "gcs",
          "azure"
        ],
        "title": "StorageTypeEnum",
        "description": "Cloud storage backends that job-creation requests may target.\n\nLocal filesystem staging is deliberately not a member: it is a worker-internal,\ndeployment-level opt-in (WORKER_ALLOW_LOCAL_STORAGE) and must never be requestable\nthrough job-creation APIs (KH-577). JobConfig still parses the historical \"local\"\nvalue from already-stored configs."
      },
      "SuccessResponse": {
        "properties": {
          "status": {
            "type": "string",
            "title": "Status",
            "default": "ok"
          }
        },
        "type": "object",
        "title": "SuccessResponse",
        "description": "Generic success response.",
        "example": {
          "status": "ok"
        }
      },
      "SuggestSchemaMappingResponse": {
        "properties": {
          "mappings": {
            "items": {
              "$ref": "#/components/schemas/SuggestedFieldMapping"
            },
            "type": "array",
            "title": "Mappings"
          },
          "would_create_kb_fields": {
            "items": {
              "$ref": "#/components/schemas/WouldCreateKbField"
            },
            "type": "array",
            "title": "Would Create Kb Fields",
            "description": "If non-empty, the subsequent PUT must set ensure_target_fields=true for those fields to actually be created."
          },
          "unmapped": {
            "items": {
              "$ref": "#/components/schemas/UnmappedSourceField"
            },
            "type": "array",
            "title": "Unmapped"
          }
        },
        "type": "object",
        "title": "SuggestSchemaMappingResponse",
        "description": "Response for the suggest-only schema-mapping endpoint. Writes nothing; read-only.\n\nNo separate ``query_fields`` list: it would just duplicate ``mappings[]`` entries that\nhave ``query_order`` set, and could drift if ``target_field``/``source_field`` differ.",
        "example": {
          "mappings": [
            {
              "query_order": 1,
              "source_field": "summary",
              "target_field": "_content_",
              "target_field_type": "string"
            },
            {
              "match_order": 1,
              "source_field": "id",
              "target_field": "id",
              "target_field_type": "string"
            }
          ],
          "unmapped": [
            {
              "reason": "excluded_field",
              "source_field": "creator_id"
            }
          ],
          "would_create_kb_fields": [
            {
              "name": "department",
              "type": "string"
            }
          ]
        }
      },
      "SuggestedFieldMapping": {
        "properties": {
          "source_field": {
            "type": "string",
            "title": "Source Field",
            "description": "Original source field name, verbatim casing"
          },
          "target_field": {
            "type": "string",
            "title": "Target Field",
            "description": "Existing KB attribute, or the proposed new attribute name"
          },
          "target_field_type": {
            "type": "string",
            "enum": [
              "string",
              "integer",
              "float",
              "boolean",
              "datetime"
            ],
            "title": "Target Field Type",
            "description": "Inferred KB field type"
          },
          "query_order": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 1.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Query Order",
            "description": "Set for content/description/title. Null if withheld because 2+ case-variant new fields tied for this slot, rather than picking one arbitrarily."
          },
          "match_order": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 1.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Match Order",
            "description": "Set for a field named 'id' (integer/string). Null if withheld because 2+ case-variant new fields tied for this slot, rather than picking one arbitrarily."
          }
        },
        "type": "object",
        "required": [
          "source_field",
          "target_field",
          "target_field_type"
        ],
        "title": "SuggestedFieldMapping",
        "description": "One entry in a suggest-endpoint response's ``mappings`` list.",
        "example": {
          "query_order": 1,
          "source_field": "summary",
          "target_field": "_content_",
          "target_field_type": "string"
        }
      },
      "UnmappedSourceField": {
        "properties": {
          "source_field": {
            "type": "string",
            "title": "Source Field"
          },
          "reason": {
            "type": "string",
            "enum": [
              "malformed_field",
              "type_collision",
              "ambiguous_name",
              "unresolvable_type",
              "duplicate_target",
              "invalid_target_name",
              "no_pattern_match",
              "excluded_field",
              "suggestion_limit_exceeded",
              "kb_not_editable"
            ],
            "title": "Reason",
            "description": "'excluded_field' covers an id-shaped name: last name segment 'id', as in '*_id', '_id' or 'ids', but not the bare match-key 'id'."
          },
          "detail": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Detail",
            "description": "Human-readable explanation"
          }
        },
        "type": "object",
        "required": [
          "source_field",
          "reason"
        ],
        "title": "UnmappedSourceField",
        "description": "A source field the suggest endpoint could not map, with the reason why.",
        "example": {
          "detail": "Id-shaped name",
          "reason": "excluded_field",
          "source_field": "creator_id"
        }
      },
      "UpdateKnowledgeBaseResponse": {
        "properties": {
          "status": {
            "type": "string",
            "title": "Status",
            "default": "ok"
          },
          "cascade": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/CascadeSummary"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "type": "object",
        "title": "UpdateKnowledgeBaseResponse",
        "description": "Response for PUT /knowledge-bases/{id}.\n\n``cascade`` is ``None`` when no ``kb_schema`` was in the payload or when the\nschema update had no renames/deletions (additions only).",
        "example": {
          "cascade": {
            "disabled_source_names": [],
            "fields_deleted": 0,
            "fields_renamed": 1,
            "mappings_cleaned": 0,
            "mappings_updated": 1,
            "sources_disabled": 0
          },
          "status": "ok"
        }
      },
      "ValidationError": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "VectorStoreConfig": {
        "properties": {
          "provider": {
            "$ref": "#/components/schemas/VectorStoreProvider"
          },
          "endpoint": {
            "type": "string",
            "title": "Endpoint",
            "description": "Vector store endpoint URL"
          },
          "region": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Region",
            "description": "Cloud region (e.g., 'us-east-1')"
          },
          "use_aws_auth": {
            "type": "boolean",
            "title": "Use Aws Auth",
            "description": "Use AWS SigV4 authentication for OpenSearch",
            "default": false
          },
          "credentials_ref": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Credentials Ref",
            "description": "Reference to stored credentials (Phase 2 BYO)"
          }
        },
        "type": "object",
        "required": [
          "provider",
          "endpoint"
        ],
        "title": "VectorStoreConfig",
        "description": "Vector store connection configuration.\n\nThis schema is used by the Repository SQLModel as a JSONB column type."
      },
      "VectorStoreProvider": {
        "type": "string",
        "enum": [
          "opensearch",
          "elasticsearch"
        ],
        "title": "VectorStoreProvider",
        "description": "Supported vector store providers."
      },
      "WouldCreateKbField": {
        "properties": {
          "name": {
            "type": "string",
            "title": "Name"
          },
          "type": {
            "type": "string",
            "enum": [
              "string",
              "integer",
              "float",
              "boolean",
              "datetime"
            ],
            "title": "Type"
          }
        },
        "type": "object",
        "required": [
          "name",
          "type"
        ],
        "title": "WouldCreateKbField",
        "description": "A KB schema field that would be created if this suggestion were applied via PUT.\nPredicted, not actual -- see ``CreatedKbField`` (a sibling) for what a PUT actually created.",
        "example": {
          "name": "department",
          "type": "string"
        }
      }
    },
    "securitySchemes": {
      "HTTPBearer": {
        "type": "http",
        "description": "Boomi platform JWT sent as a Bearer token. The token must carry Knowledge Hub access privileges; its `account` claim identifies the caller's Boomi tenant.",
        "scheme": "bearer"
      }
    }
  },
  "tags": [
    {
      "name": "repositories",
      "description": "Repository management"
    },
    {
      "name": "knowledge-bases",
      "description": "Knowledge Base management"
    },
    {
      "name": "sources",
      "description": "Source configuration and management"
    },
    {
      "name": "schema-mappings",
      "description": "Map source fields to Knowledge Base schema fields"
    },
    {
      "name": "jobs",
      "description": "Create and monitor ingestion jobs"
    },
    {
      "name": "data-providers",
      "description": "Data providers for bringing data into Knowledge Hub (e.g., Boomi DI, Manual Upload)"
    },
    {
      "name": "staging-providers",
      "description": "Cloud storage providers for staging data before ingestion"
    },
    {
      "name": "embedding-models",
      "description": "Available embedding models"
    },
    {
      "name": "consumption",
      "description": "Consumption usage reporting"
    },
    {
      "name": "health",
      "description": "Service health checks"
    }
  ],
  "x-tagGroups": [
    {
      "name": "Configuration",
      "tags": [
        "data-providers",
        "staging-providers",
        "embedding-models",
        "repositories",
        "knowledge-bases",
        "sources",
        "schema-mappings"
      ]
    },
    {
      "name": "Ingestion & Usage",
      "tags": [
        "jobs",
        "consumption"
      ]
    },
    {
      "name": "System",
      "tags": [
        "health"
      ]
    }
  ]
}