Explore related files
Interface Description
Start from a readable file ID returned by tree, search, file, or related-file operations. The response returns related files up to the requested depth and result limits, with paths for reading the complete files.
Endpoint
| Field | Value |
|---|---|
| Method | GET |
| Path | /openapi/v2/knowledge-bases/{knowledgeBaseId}/graph/expand |
| Operation ID | expandGraph |
| 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. |
fileId | query | Yes | string | source-file-11111111-1111-4111-8111-111111111111 | Readable file ID returned by tree, search, file, or related-file operations. |
depth | query | No | 0 | 1 | 2 | 1 | Number of relationship levels to explore. |
fanout | query | No | integer | 10 | Maximum related files returned for each explored file. When omitted, the deployment setting is used. |
limit | query | No | integer | 10 | Maximum number of records to return. The deployment can enforce a lower limit. |
cursor | query | No | string | cursor_123 | Pagination token returned by the same endpoint for reading the next page. |
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/graph/expand?fileId=source-file-11111111-1111-4111-8111-111111111111&depth=1&fanout=10&limit=10" \
-H "Authorization: Bearer <openapi-key>"Successful Responses
200
Related files and relationship details for the selected starting point.
| Field | Required | Type | Description |
|---|---|---|---|
activeContentRevision | Yes | integer | Current readable knowledge-base content revision. |
seedFile | Yes | object | Current readable starting file resolved from fileId. |
relationships | Yes | array<RelatedFile> | Related files found up to the requested depth and result limits. |
graphPaths | Yes | array<string> | Readable relationship-data files under _graph/ that can be read with the path-based file content endpoint. |
nextCursor | Yes | string | null | Pagination token returned by this endpoint. Reuse it only with the same starting point and readable knowledge-base version. If it is rejected, restart without a cursor. |
resultSummary | Yes | object | Summary of the current result page. |
Success Response Example
json
{
"activeContentRevision": 1,
"seedFile": {
"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",
"contentType": "text/markdown; charset=utf-8",
"sizeBytes": 2048,
"okfType": "Guide",
"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
},
"deletable": true,
"contentAvailable": true,
"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"
}
},
"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,
"resultSummary": {
"relationshipCount": 1,
"hasMore": false,
"depth": 1,
"fanout": 10,
"meaning": "Related files were found. Read the returned 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. |
Validation Detail Codes
For a 422 VALIDATION_ERROR, inspect error.details.code. This operation can return:
GRAPH_EXPANSION_FILE_ID_REQUIREDINVALID_GRAPH_EXPANSION_DEPTHINVALID_GRAPH_EXPANSION_FANOUT