Search readable files

Interface Description

Search active source Markdown files with one standalone natural-language question. Omitted mode uses hybrid retrieval. Optional request-scoped reranking refines authorized candidates and safely falls back when unavailable. Every result remains a source-file candidate with read actions; read the Markdown before using its content as evidence.

Endpoint

Field	Value
Method	`GET`
Path	`/openapi/v2/knowledge-bases/{knowledgeBaseId}/files/search`
Operation ID	`searchGeneratedFiles`
Authentication	Bearer OpenAPI key

Parameters

Name	Location	Required	Type	Example	Description
`knowledgeBaseId`	path	Yes	string	knowledge-base-11111111-1111-4111-8111-111111111111	Knowledge-base identifier returned by knowledge-base APIs.
`query`	query	Yes	string	How do I configure and verify the knowledge base deployment?	One standalone natural-language question or search text. After Unicode and whitespace normalization it must contain 2 through 512 grapheme clusters, use at most 2048 UTF-8 bytes, and contain no unsafe control characters. Results are source files that must be read before their content is used as evidence.
`scope`	query	No	all \| path \| metadata	all	Eligible evidence fields. `path` runs exact-path and grounded-title families, `metadata` runs the lexical metadata family, and `all` uses every family enabled by the selected mode.
`fileKind`	query	No	all \| page	page	Readable-file type filter. Search returns active Markdown pages created from uploaded files. `all` removes the explicit type predicate but currently returns the same page set.
`mode`	query	No	file \| graph \| hybrid	hybrid	Search strategy. `file` searches file data and semantic similarity, `graph` follows file relationships and graph-derived semantic signals, and `hybrid` combines both. `scope` narrows the searched fields. Every result remains a readable source file.
`graphDepth`	query	No	0 \| 1 \| 2	1	Relationship context depth returned for graph and hybrid results. `0` returns the seed graph reference without relationships, `1` includes direct relationships, and `2` may include second-level relationships within `graphFanout`. Values above the deployment maximum return 422.
`graphFanout`	query	No	integer	10	Maximum relationship records returned per graph search result across the requested depth. When omitted, the deployment setting is used; values above the deployment maximum return 422.
`okfStatus`	query	No	draft \| stable \| deprecated	draft	Return only files whose normalized OKF document status matches this value. Files with an invalid status are excluded.
`okfTrustTier`	query	No	unverified \| machine-confirmed \| human-reviewed	unverified	Return only files whose normalized OKF verification tier matches this value. Files with invalid verification metadata are excluded.
`okfFreshness`	query	No	fresh \| stale	fresh	Return only files whose valid `stale_after` date is fresh or stale on the request date. Files without a valid stale date are excluded.
`rerank`	query	No	boolean	true	Optionally rerank the authorized fused source-file candidates with the active Admin-configured reranker. The default keeps deterministic fused ranking.
`rerankTopK`	query	No	integer	50	Candidate count sent to the optional reranker. It is valid only with `rerank=true`, must be at least `limit`, and defaults to the greater of 30 and `limit`.
`rerankScoreThreshold`	query	No	number	0	Minimum normalized reranker score for non-exact candidates. It is valid only with `rerank=true` and defaults to 0, so reranking reorders candidates without removing them unless a positive threshold is supplied.
`limit`	query	No	integer	10	Final source-file result count for this search request.
`cursor`	query	No	string	cursor_123	Pagination token returned by the same search query, filters, readable knowledge-base version, and effective ranking settings.

Request Body

This operation has no request body.

Request Example

bash

curl -X GET "https://openapi.example.com/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/search?query=How+do+I+configure+and+verify+the+knowledge+base+deployment%3F&scope=all&fileKind=page&mode=hybrid&graphDepth=1&graphFanout=10&limit=10" \
  -H "Authorization: Bearer <openapi-key>"

Successful Responses

200

Readable files ranked by relevance to the supplied query.

Field	Required	Type	Description
`activeContentRevision`	Yes	object	Current readable knowledge-base content revision.
`query`	Yes	object	Search text and options used for this result.
`items`	Yes	array<FileSearchResult>	Records returned on this page.
`nextCursor`	Yes	string \| null	Pagination token returned by this endpoint. Reuse it only with the same query, filters, and readable knowledge-base version. If it is rejected, restart without a cursor.
`searchStatus`	Yes	ok \| no_candidates	`ok` means results are returned. `no_candidates` means the current query matched no files. Dependency failures use the documented 503 or 504 error envelope.
`searchMode`	Yes	file \| graph \| hybrid	Search mode applied to this response.
`semanticStatus`	Yes	object	Availability and safe reason code for optional semantic search lanes in this response.
`evidenceStatus`	Yes	object	Retrieval evidence families that completed or degraded for this response.
`rerankerStatus`	Yes	object	Whether optional reranking was applied, skipped, unavailable, or degraded without exposing model scores.
`graphStatus`	Yes	available \| index_unavailable \| disabled_for_file_mode	Relationship-search availability for this response. `disabled_for_file_mode` is returned for file-only search.
`graphSummary`	Yes	object	File relationship availability and counts for this response.
`resultSummary`	Yes	object	Summary of the current result page.
`message`	No	string \| null	Status message when no files matched or search is not available.
`nextActions`	No	array<string>	Suggested file reads or relationship queries for continuing exploration.

Success Response Example

json

{
  "activeContentRevision": 1,
  "query": {
    "query": "How do I configure and verify the knowledge base deployment?",
    "normalizedQuery": "How do I configure and verify the knowledge base deployment?",
    "scope": "all",
    "fileKind": "page",
    "mode": "hybrid",
    "graphDepth": 1,
    "graphFanout": 10,
    "okfStatus": null,
    "okfTrustTier": null,
    "okfFreshness": null,
    "rerank": false,
    "rerankTopK": null,
    "rerankScoreThreshold": null,
    "limit": 10,
    "cursorProvided": false
  },
  "items": [
    {
      "activeContentRevision": 1,
      "fileId": "source-file-11111111-1111-4111-8111-111111111111",
      "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111",
      "sourceFileId": "source-file-11111111-1111-4111-8111-111111111111",
      "path": "pages/guide.md",
      "fileKind": "page",
      "title": "Verified guide",
      "description": null,
      "tags": [
        "guide",
        "policy"
      ],
      "frontmatter": {
        "okf_version": "0.2",
        "type": "Guide",
        "title": "Verified guide",
        "tags": [
          "guide",
          "policy"
        ],
        "sources": [
          {
            "id": "source-a",
            "resource": "references/source-a.md"
          }
        ],
        "generated": {
          "by": "publisher:example",
          "at": "2026-06-17T00:00:00Z"
        },
        "verified": [
          {
            "by": "human:reviewer",
            "at": "2026-06-17T01:00:00Z"
          }
        ],
        "status": "stable",
        "stale_after": "2026-12-31"
      },
      "okfSignals": {
        "effectiveStatus": "stable",
        "trustTier": "human-reviewed",
        "isStale": false,
        "staleAfter": "2026-12-31",
        "generatedAt": "2026-06-17T00:00:00.000Z",
        "generatedAtSource": "generated",
        "latestVerifiedAt": "2026-06-17T01:00:00.000Z",
        "sourceCount": 1
      },
      "matchedFields": [
        "content"
      ],
      "evidenceTypes": [
        "content"
      ],
      "sourceExcerpt": "Configure the deployment, then verify service health and search readiness.",
      "score": 9,
      "contentAvailable": true,
      "matchType": "file_direct",
      "readActions": {
        "fileDetailById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/source-file-11111111-1111-4111-8111-111111111111",
        "fileContentById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/source-file-11111111-1111-4111-8111-111111111111/content",
        "fileContentByPath": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/content?path=pages%2Fguide.md",
        "relatedFilesById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/source-file-11111111-1111-4111-8111-111111111111/related",
        "graphExpansionByFileId": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/graph/expand?fileId=source-file-11111111-1111-4111-8111-111111111111",
        "sourceFileStatusById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/source-files/source-file-11111111-1111-4111-8111-111111111111"
      },
      "graphContext": {
        "graphRef": "_graph/by-file/handbook/guide.json",
        "depth": 1,
        "seedSourceFileId": "source-file-11111111-1111-4111-8111-111111111111",
        "relationships": [
          {
            "activeContentRevision": 1,
            "fileId": "source-file-22222222-2222-4222-8222-222222222222",
            "sourceFileId": "source-file-22222222-2222-4222-8222-222222222222",
            "path": "pages/reference.md",
            "title": "Reference",
            "relationType": "same_specific_subject",
            "direction": "outgoing",
            "fromFileId": "source-file-11111111-1111-4111-8111-111111111111",
            "relationshipDepth": 1,
            "reason": "Both files share body-derived subjects.",
            "contentAvailable": true,
            "readActions": {
              "fileDetailById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/source-file-22222222-2222-4222-8222-222222222222",
              "fileContentById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/source-file-22222222-2222-4222-8222-222222222222/content",
              "fileContentByPath": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/content?path=pages%2Freference.md",
              "relatedFilesById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/source-file-22222222-2222-4222-8222-222222222222/related",
              "graphExpansionByFileId": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/graph/expand?fileId=source-file-22222222-2222-4222-8222-222222222222",
              "sourceFileStatusById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/source-files/source-file-22222222-2222-4222-8222-222222222222"
            }
          }
        ],
        "graphPaths": [
          "_graph/by-file/handbook/guide.json",
          "_graph/by-file/reference.json"
        ]
      }
    }
  ],
  "nextCursor": null,
  "searchStatus": "ok",
  "searchMode": "hybrid",
  "semanticStatus": {
    "state": "ready",
    "safeCode": null
  },
  "evidenceStatus": {
    "completedFamilies": [
      "exact_path",
      "exact_title",
      "lexical",
      "jieba",
      "content_vector",
      "entity_vector",
      "relationship_vector",
      "community_vector",
      "file_graph",
      "file_relationship"
    ],
    "degradedFamilies": []
  },
  "rerankerStatus": {
    "state": "skipped",
    "safeCode": "RERANKER_DISABLED"
  },
  "graphStatus": "available",
  "graphSummary": {
    "available": true,
    "indexedDocumentCount": 24,
    "indexedRelationshipCount": 86,
    "depth": 1,
    "fanout": 10
  },
  "resultSummary": {
    "resultCount": 1,
    "hasMore": false,
    "sort": [
      "relevance_desc",
      "logical_path_asc",
      "source_file_id_asc"
    ],
    "meaning": "The query matched readable files. Read the returned files and related files before using their content."
  }
}

Error Codes

The table below lists every error response documented for this operation.

HTTP Status	Error Code	Explanation
401	`UNAUTHORIZED`	The Bearer API key is missing, malformed, unknown, revoked, or deleted.
404	`NOT_FOUND`	The requested resource was not found.
422	`VALIDATION_ERROR`	The request failed validation.
429	`RATE_LIMITED`	The request exceeded the configured rate limits.
500	`INTERNAL_ERROR`	The API encountered an internal error.
503	`DATABASE_REPOSITORY_UNAVAILABLE`	The data required by this operation is temporarily unavailable.
503	`SEARCH_UNAVAILABLE`	The search service is temporarily unavailable.
503	`SEARCH_OVERLOADED`	The search service is temporarily overloaded.
504	`SEARCH_TIMEOUT`	Search exceeded the configured response deadline.

Validation Detail Codes

For a 422 VALIDATION_ERROR, inspect error.details.code. This operation can return:

FILE_SEARCH_QUERY_REQUIRED
FILE_SEARCH_QUERY_TOO_SHORT
FILE_SEARCH_QUERY_TOO_LONG
INVALID_FILE_SEARCH_QUERY
INVALID_FILE_SEARCH_SCOPE
INVALID_FILE_SEARCH_KIND
INVALID_FILE_SEARCH_MODE
INVALID_FILE_SEARCH_GRAPH_DEPTH
INVALID_FILE_SEARCH_GRAPH_FANOUT
INVALID_FILE_SEARCH_OKF_STATUS
INVALID_FILE_SEARCH_OKF_TRUST_TIER
INVALID_FILE_SEARCH_OKF_FRESHNESS
INVALID_FILE_SEARCH_LIMIT
INVALID_FILE_SEARCH_RERANK_CONTROLS

Search readable files ​

Interface Description ​

Endpoint ​

Parameters ​

Request Body ​

Request Example ​

Successful Responses ​

200 ​

Success Response Example ​

Error Codes ​

Validation Detail Codes ​

Next Steps ​