{
  "openapi": "3.1.0",
  "info": {
    "title": "Knowledge Retrieve API",
    "description": "REST API service for querying Knowledge Bases and retrieving relevant knowledge chunks for AI agents",
    "contact": {
      "name": "Knowledge Hub Team"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://retrieve-api.prod.kh.boomi.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": [
          "health"
        ],
        "summary": "Health check",
        "description": "Health check endpoint.\n\nReturns the health status of the API service with version and uptime.",
        "operationId": "health_check_health_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/health/live": {
      "get": {
        "tags": [
          "health"
        ],
        "summary": "Liveness check",
        "description": "Liveness probe endpoint.\n\nSimple check that returns 200 if the process is running.\nUsed by Kubernetes liveness probes.",
        "operationId": "liveness_check_health_live_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProbeResponse"
                }
              }
            }
          }
        }
      }
    },
    "/health/ready": {
      "get": {
        "tags": [
          "health"
        ],
        "summary": "Readiness check",
        "description": "Readiness probe endpoint.\n\nReturns 200 when the service is ready to accept traffic.\nUsed by Kubernetes readiness probes.",
        "operationId": "readiness_check_health_ready_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProbeResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/knowledge-bases/{knowledge_base_id}/retrieve": {
      "post": {
        "tags": [
          "retrieval"
        ],
        "summary": "Retrieve chunks",
        "description": "Retrieve knowledge chunks matching the query.\n\nSearches the Knowledge Base's indexed chunks and returns the top matches with\nrelevance scores. The ``retrieval_mode`` selects semantic (vector), lexical\n(BM25 keyword), or hybrid search; ``filters`` narrows results by indexed\nmetadata fields; ``retrieval_config_override`` tweaks scoring per request.\n\nRequires a valid Boomi platform JWT (Bearer token) holding the\n``KNOWLEDGE_HUB_KB_RETRIEVE`` privilege; a token without it gets a 403. The\ntoken's ``account`` claim identifies the caller's Boomi tenant and scopes\nthe search to that tenant's Knowledge Bases; a Knowledge Base outside it is\na 404.\n\nRequired privileges: `KNOWLEDGE_HUB_KB_RETRIEVE`.",
        "operationId": "retrieve_chunks_api_v1_knowledge_bases__knowledge_base_id__retrieve_post",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "knowledge_base_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUID of the Knowledge Base to search",
              "title": "Knowledge Base Id"
            },
            "description": "UUID of the Knowledge Base to search"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RetrievalRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RetrievalResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid Authorization token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Knowledge Base inactive or insufficient privileges",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Knowledge Base not found or not available for search",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Knowledge Base exists but has no indexed data yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Embedding model invalid or provider rejected the request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BM25Config": {
        "properties": {
          "k1": {
            "anyOf": [
              {
                "type": "number",
                "maximum": 3.0,
                "minimum": 0.0
              },
              {
                "type": "null"
              }
            ],
            "title": "K1"
          },
          "b": {
            "anyOf": [
              {
                "type": "number",
                "maximum": 1.0,
                "minimum": 0.0
              },
              {
                "type": "null"
              }
            ],
            "title": "B"
          }
        },
        "type": "object",
        "title": "BM25Config",
        "description": "Configuration for BM25 search.",
        "example": {
          "b": 0.75,
          "k1": 1.2
        }
      },
      "Chunk": {
        "properties": {
          "chunk_id": {
            "type": "string",
            "title": "Chunk Id"
          },
          "content": {
            "type": "string",
            "title": "Content"
          },
          "score": {
            "type": "number",
            "minimum": 0.0,
            "title": "Score"
          },
          "metadata": {
            "$ref": "#/components/schemas/ChunkMetadata"
          },
          "source_reference": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/SourceReference"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "type": "object",
        "required": [
          "chunk_id",
          "content",
          "score",
          "metadata"
        ],
        "title": "Chunk",
        "description": "A retrieved knowledge chunk.",
        "example": {
          "chunk_id": "c3d9a1f0-1a2b-4c3d-8e5f-6a7b8c9d0e1f",
          "content": "Employees are eligible for parental leave after six months of employment.",
          "metadata": {
            "chunk_index": 0,
            "ds_id": "b7a1e0f2-...",
            "record_id": "doc-42",
            "total_chunks": 3
          },
          "score": 0.91,
          "source_reference": {
            "type": "file",
            "uri": "s3://kh-ingest/hr-policies/leave.pdf"
          }
        }
      },
      "ChunkMetadata": {
        "properties": {
          "ds_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Ds Id"
          },
          "record_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Record Id"
          },
          "chunk_index": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Chunk Index"
          },
          "total_chunks": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Total Chunks"
          }
        },
        "additionalProperties": true,
        "type": "object",
        "title": "ChunkMetadata",
        "description": "Metadata for a retrieved chunk.",
        "example": {
          "chunk_index": 0,
          "ds_id": "b7a1e0f2-...",
          "record_id": "doc-42",
          "total_chunks": 3
        }
      },
      "ErrorResponse": {
        "properties": {
          "error": {
            "type": "string",
            "title": "Error"
          },
          "message": {
            "type": "string",
            "title": "Message"
          },
          "details": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Details"
          }
        },
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "title": "ErrorResponse",
        "description": "Standard error response.",
        "example": {
          "error": "not_found",
          "message": "Knowledge Base not found or not available for search"
        }
      },
      "FieldConfig": {
        "properties": {
          "boost": {
            "type": "number",
            "minimum": 0.1,
            "title": "Boost",
            "description": "Score multiplier applied to matches in this field",
            "default": 1.0
          },
          "searchable": {
            "type": "boolean",
            "title": "Searchable",
            "default": true
          }
        },
        "type": "object",
        "title": "FieldConfig",
        "description": "Configuration for a searchable field.",
        "example": {
          "boost": 2.0,
          "searchable": true
        }
      },
      "HealthResponse": {
        "properties": {
          "status": {
            "type": "string",
            "title": "Status",
            "description": "Service health status"
          },
          "version": {
            "type": "string",
            "title": "Version",
            "description": "Service version"
          },
          "uptime_seconds": {
            "type": "integer",
            "title": "Uptime Seconds",
            "description": "Seconds since service start"
          }
        },
        "type": "object",
        "required": [
          "status",
          "version",
          "uptime_seconds"
        ],
        "title": "HealthResponse",
        "description": "Health status of the API service.",
        "example": {
          "status": "healthy",
          "uptime_seconds": 3600,
          "version": "1.0.0"
        }
      },
      "HybridFusionConfig": {
        "properties": {
          "algorithm": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "rrf",
                  "weighted_sum"
                ]
              },
              {
                "type": "null"
              }
            ],
            "title": "Algorithm"
          },
          "semantic_weight": {
            "anyOf": [
              {
                "type": "number",
                "maximum": 1.0,
                "minimum": 0.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Semantic Weight"
          },
          "lexical_weight": {
            "anyOf": [
              {
                "type": "number",
                "maximum": 1.0,
                "minimum": 0.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Lexical Weight"
          },
          "rrf_rank_constant": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 1.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Rrf Rank Constant"
          }
        },
        "type": "object",
        "title": "HybridFusionConfig",
        "description": "Configuration for hybrid fusion search.",
        "example": {
          "algorithm": "rrf",
          "rrf_rank_constant": 60
        }
      },
      "MatchOptionsConfig": {
        "properties": {
          "type": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "best_fields",
                  "cross_fields",
                  "phrase",
                  "most_fields"
                ]
              },
              {
                "type": "null"
              }
            ],
            "title": "Type"
          },
          "minimum_should_match": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Minimum Should Match"
          },
          "fuzziness": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "AUTO",
                  "0",
                  "1",
                  "2"
                ]
              },
              {
                "type": "null"
              }
            ],
            "title": "Fuzziness"
          }
        },
        "type": "object",
        "title": "MatchOptionsConfig",
        "description": "Configuration for match options.",
        "example": {
          "minimum_should_match": "75%",
          "type": "best_fields"
        }
      },
      "ProbeResponse": {
        "properties": {
          "status": {
            "type": "string",
            "title": "Status",
            "description": "Probe status"
          }
        },
        "type": "object",
        "required": [
          "status"
        ],
        "title": "ProbeResponse",
        "description": "Kubernetes probe status.",
        "example": {
          "status": "ok"
        }
      },
      "RetrievalConfig": {
        "properties": {
          "fields": {
            "additionalProperties": {
              "$ref": "#/components/schemas/FieldConfig"
            },
            "type": "object",
            "title": "Fields"
          },
          "hybrid_fusion": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/HybridFusionConfig"
              },
              {
                "type": "null"
              }
            ]
          },
          "bm25": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/BM25Config"
              },
              {
                "type": "null"
              }
            ]
          },
          "match_options": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/MatchOptionsConfig"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "type": "object",
        "title": "RetrievalConfig",
        "description": "Full effective retrieval config used in response.",
        "example": {
          "fields": {
            "content": {
              "boost": 1.5
            }
          }
        }
      },
      "RetrievalConfigOverride": {
        "properties": {
          "fields": {
            "anyOf": [
              {
                "additionalProperties": {
                  "$ref": "#/components/schemas/FieldConfig"
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Fields"
          },
          "hybrid_fusion": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/HybridFusionConfig"
              },
              {
                "type": "null"
              }
            ]
          },
          "bm25": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/BM25Config"
              },
              {
                "type": "null"
              }
            ]
          },
          "match_options": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/MatchOptionsConfig"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "type": "object",
        "title": "RetrievalConfigOverride",
        "description": "Request-level retrieval config override (deep merged with KB defaults).",
        "example": {
          "fields": {
            "content": {
              "boost": 2.0
            }
          },
          "hybrid_fusion": {
            "algorithm": "rrf",
            "rrf_rank_constant": 60
          }
        }
      },
      "RetrievalMode": {
        "type": "string",
        "enum": [
          "semantic",
          "lexical",
          "hybrid"
        ],
        "title": "RetrievalMode",
        "description": "Valid retrieval modes for KnowledgeBase."
      },
      "RetrievalRequest": {
        "properties": {
          "query": {
            "type": "string",
            "maxLength": 10000,
            "minLength": 1,
            "title": "Query"
          },
          "top_k": {
            "anyOf": [
              {
                "type": "integer",
                "maximum": 100.0,
                "minimum": 1.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Top K"
          },
          "retrieval_mode": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/RetrievalMode"
              },
              {
                "type": "null"
              }
            ]
          },
          "filters": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Filters"
          },
          "retrieval_config_override": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/RetrievalConfigOverride"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "type": "object",
        "required": [
          "query"
        ],
        "title": "RetrievalRequest",
        "description": "Request body for the retrieve endpoint.",
        "example": {
          "filters": {
            "department": "HR"
          },
          "query": "What is the parental leave policy?",
          "retrieval_mode": "hybrid",
          "top_k": 5
        }
      },
      "RetrievalResponse": {
        "properties": {
          "chunks": {
            "items": {
              "$ref": "#/components/schemas/Chunk"
            },
            "type": "array",
            "title": "Chunks"
          },
          "settings_used": {
            "$ref": "#/components/schemas/SettingsUsed"
          },
          "activity_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Activity Id"
          }
        },
        "type": "object",
        "required": [
          "chunks",
          "settings_used"
        ],
        "title": "RetrievalResponse",
        "description": "Response for the retrieve endpoint.",
        "example": {
          "activity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "chunks": [
            {
              "chunk_id": "c3d9a1f0-1a2b-4c3d-8e5f-6a7b8c9d0e1f",
              "content": "Employees are eligible for parental leave after six months of employment.",
              "metadata": {
                "chunk_index": 0,
                "ds_id": "b7a1e0f2-...",
                "record_id": "doc-42",
                "total_chunks": 3
              },
              "score": 0.91,
              "source_reference": {
                "type": "file",
                "uri": "s3://kh-ingest/hr-policies/leave.pdf"
              }
            }
          ],
          "settings_used": {
            "embedding_model": "cohere.embed-v4:0",
            "retrieval_config": {
              "fields": {
                "content": {
                  "boost": 1.5
                }
              }
            },
            "retrieval_mode": "hybrid",
            "top_k": 5
          }
        }
      },
      "SettingsUsed": {
        "properties": {
          "retrieval_mode": {
            "$ref": "#/components/schemas/RetrievalMode"
          },
          "top_k": {
            "type": "integer",
            "title": "Top K"
          },
          "embedding_model": {
            "type": "string",
            "title": "Embedding Model"
          },
          "retrieval_config": {
            "$ref": "#/components/schemas/RetrievalConfig"
          }
        },
        "type": "object",
        "required": [
          "retrieval_mode",
          "top_k",
          "embedding_model",
          "retrieval_config"
        ],
        "title": "SettingsUsed",
        "description": "Effective settings used for the retrieval operation.",
        "example": {
          "embedding_model": "cohere.embed-v4:0",
          "retrieval_config": {
            "fields": {
              "content": {
                "boost": 1.5
              }
            }
          },
          "retrieval_mode": "hybrid",
          "top_k": 5
        }
      },
      "SourceReference": {
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "application",
              "file"
            ],
            "title": "Type"
          },
          "uri": {
            "type": "string",
            "title": "Uri"
          }
        },
        "type": "object",
        "required": [
          "type",
          "uri"
        ],
        "title": "SourceReference",
        "description": "Source reference for a chunk.",
        "example": {
          "type": "file",
          "uri": "s3://kh-ingest/hr-policies/leave.pdf"
        }
      }
    },
    "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": "retrieval",
      "description": "Search Knowledge Bases and retrieve knowledge chunks"
    },
    {
      "name": "health",
      "description": "Service health checks"
    }
  ]
}