{ "openapi": "3.1.0", "info": { "title": "Focowiki Developer OpenAPI", "version": "0.7.47", "description": "Authenticated API for creating knowledge bases, uploading Markdown, reading readable files, managing content, and receiving webhooks.", "license": { "name": "Modified Apache License 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0" } }, "servers": [ { "url": "/" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Metadata", "description": "Health, version, and contract discovery." }, { "name": "Knowledge Bases", "description": "Knowledge-base creation, metadata, listing, and deletion." }, { "name": "Upload Sessions", "description": "Resumable Markdown uploads that preserve file and folder paths." }, { "name": "Uploaded Directories", "description": "Directories created from uploaded folder paths." }, { "name": "Uploaded Files", "description": "Uploaded Markdown content, processing status, replacement, movement, retry, and deletion." }, { "name": "File and Directory Changes", "description": "Progress and results for document indexing, file and directory moves, replacements, and deletions." }, { "name": "Files", "description": "Readable file tree, content, search, and file relationships." }, { "name": "Webhooks", "description": "Webhook subscriptions and delivery operations." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Focowiki OpenAPI key" } }, "schemas": { "Error": { "type": "object", "additionalProperties": false, "properties": { "error": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "VALIDATION_ERROR", "RATE_LIMITED", "UNSUPPORTED_ROUTE", "INTERNAL_ERROR", "DATABASE_REPOSITORY_UNAVAILABLE", "SEARCH_TIMEOUT", "SEARCH_UNAVAILABLE", "SEARCH_OVERLOADED" ], "description": "Error or failure code that clients can handle programmatically." }, "message": { "type": "string", "description": "Human-readable error, failure, or availability message." }, "httpStatus": { "type": "integer", "description": "HTTP status returned by the API or webhook endpoint." }, "details": { "type": "object", "additionalProperties": true, "description": "Additional error information. `RATE_LIMITED` responses can include how long to wait and how to retry.", "properties": { "retryHint": { "type": "string", "description": "Recommended way to retry the request." }, "retryAfterSeconds": { "type": "integer", "minimum": 1, "description": "Minimum number of seconds to wait before retrying." }, "retryGuidance": { "type": "string", "description": "Instructions for retrying or checking the request again." } } } }, "required": [ "code", "message", "httpStatus" ], "description": "Structured Developer OpenAPI error." }, "requestId": { "type": "string", "description": "Request identifier used for support correlation." } }, "required": [ "error", "requestId" ] }, "HealthResponse": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "const": "ok", "description": "Current Developer OpenAPI health state." } }, "required": [ "status" ] }, "VersionResponse": { "type": "object", "additionalProperties": false, "properties": { "product": { "type": "string", "const": "focowiki", "description": "Product identifier." }, "version": { "type": "string", "description": "Current product release version." }, "apiVersion": { "type": "string", "const": "v2", "description": "Developer OpenAPI contract version." } }, "required": [ "product", "version", "apiVersion" ] }, "Page": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": {}, "description": "Records returned on this page." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination token returned by this endpoint. Reuse it only with the same endpoint and unchanged filters. If it is rejected, restart without a cursor." } }, "required": [ "items", "nextCursor" ] }, "KnowledgeBase": { "type": "object", "additionalProperties": false, "properties": { "knowledgeBaseId": { "type": "string", "description": "Knowledge-base identifier used by every path that operates on this knowledge base." }, "name": { "type": "string", "description": "Human-readable resource name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional knowledge-base description." }, "activeContentRevision": { "type": "integer", "minimum": 0, "description": "Current readable knowledge-base content revision." }, "resourceRevision": { "type": "integer", "minimum": 1, "description": "Current resource version used with `If-Match` to prevent overwriting a concurrent change." }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the resource was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Time when the resource was last updated." } }, "required": [ "knowledgeBaseId", "name", "description", "activeContentRevision", "resourceRevision", "createdAt", "updatedAt" ] }, "KnowledgeBaseListResponse": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeBase" }, "description": "Records returned on this page." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination token returned by this endpoint. Reuse it only with the same endpoint and unchanged filters. If it is rejected, restart without a cursor." } }, "required": [ "items", "nextCursor" ], "allOf": [ { "$ref": "#/components/schemas/Page" } ] }, "KnowledgeBaseResponse": { "type": "object", "additionalProperties": false, "properties": { "knowledgeBase": { "$ref": "#/components/schemas/KnowledgeBase", "description": "Knowledge base returned by the request." } }, "required": [ "knowledgeBase" ] }, "KnowledgeBaseMutationResponse": { "type": "object", "additionalProperties": false, "properties": { "knowledgeBase": { "$ref": "#/components/schemas/KnowledgeBase", "description": "Knowledge base returned by the request." } }, "required": [ "knowledgeBase" ] }, "CreateKnowledgeBaseRequest": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Human-readable resource name, limited to 255 UTF-8 bytes." }, "description": { "anyOf": [ { "type": "string", "maxLength": 16384 }, { "type": "null" } ], "description": "Optional description, limited to 16384 UTF-8 bytes." } }, "required": [ "name" ] }, "UpdateKnowledgeBaseRequest": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Human-readable resource name, limited to 255 UTF-8 bytes." }, "description": { "anyOf": [ { "type": "string", "maxLength": 16384 }, { "type": "null" } ], "description": "Updated description or null to clear it, limited to 16384 UTF-8 bytes." } }, "minProperties": 1 }, "CreateUploadSessionRequest": { "type": "object", "additionalProperties": false, "properties": { "declaredFileCount": { "type": "integer", "minimum": 0, "example": 2, "description": "Total number of Markdown files declared for the upload session." }, "declaredByteCount": { "type": "integer", "minimum": 0, "example": 4096, "description": "Total number of Markdown file bytes declared for the upload session." } }, "required": [ "declaredFileCount", "declaredByteCount" ] }, "UploadManifestEntryRequest": { "type": "object", "additionalProperties": false, "properties": { "relativePath": { "type": "string", "description": "Markdown path relative to the selected upload root. The server stores the path in Unicode NFC form.", "example": "handbook/onboarding/guide.md" }, "declaredSize": { "type": "integer", "minimum": 0, "example": 2048, "description": "Declared file size in bytes." }, "checksumSha256": { "anyOf": [ { "type": "string", "pattern": "^[a-f0-9]{64}$", "example": "0000000000000000000000000000000000000000000000000000000000000000" }, { "type": "null" } ], "description": "Optional lowercase SHA-256 checksum used to detect unchanged content." } }, "required": [ "relativePath", "declaredSize" ] }, "UploadManifestPageRequest": { "type": "object", "additionalProperties": false, "properties": { "entries": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/UploadManifestEntryRequest" }, "description": "One or more Markdown file records added in this request." } }, "required": [ "entries" ] }, "UploadSessionCounts": { "type": "object", "additionalProperties": false, "properties": { "selected": { "type": "integer", "minimum": 0, "description": "Number of file records accepted into the upload session." }, "uploadRequired": { "type": "integer", "minimum": 0, "description": "Number of registered files whose Markdown content must be uploaded." }, "skippedExisting": { "type": "integer", "minimum": 0, "description": "Number of upload entries already present with matching content." }, "waitingReservation": { "type": "integer", "minimum": 0, "description": "Number of entries waiting for another upload of the same content to finish." }, "rejectedDeleting": { "type": "integer", "minimum": 0, "description": "Number of upload entries rejected because deletion is in progress." }, "uploaded": { "type": "integer", "minimum": 0, "description": "Number of entries whose content upload completed." }, "finalized": { "type": "integer", "minimum": 0, "description": "Number of uploaded files submitted for background processing." } }, "required": [ "selected", "uploadRequired", "skippedExisting", "waitingReservation", "rejectedDeleting", "uploaded", "finalized" ] }, "UploadSession": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Upload session identifier used by every following session action." }, "operationId": { "type": "string", "description": "Operation identifier used to monitor each submitted document after finalizing the upload." }, "knowledgeBaseId": { "type": "string", "description": "Owning knowledge-base identifier." }, "state": { "type": "string", "enum": [ "draft", "manifest_building", "manifest_sealed", "uploading", "finalizing", "completed", "cancelled", "expired" ], "description": "Current upload-session state, from file-list creation through upload completion, cancellation, or expiration." }, "declaredFileCount": { "type": "integer", "minimum": 0, "description": "Total number of Markdown files declared for the upload session." }, "declaredByteCount": { "type": "integer", "minimum": 0, "description": "Total number of Markdown file bytes declared for the upload session." }, "counts": { "$ref": "#/components/schemas/UploadSessionCounts", "description": "Current upload-session counters." }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Final upload-session error code." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Time when an unfinished upload session expires." }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when processing or deletion finished." }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the resource was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Time when the resource was last updated." }, "actions": { "type": "object", "additionalProperties": false, "properties": { "operation": { "type": "string", "description": "File or directory change record returned by the request." } }, "required": [ "operation" ], "description": "Actions currently available for this resource." } }, "required": [ "id", "operationId", "knowledgeBaseId", "state", "declaredFileCount", "declaredByteCount", "counts", "errorCode", "expiresAt", "completedAt", "createdAt", "updatedAt", "actions" ] }, "UploadSessionEntry": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Upload entry identifier used by the Markdown content upload endpoint." }, "relativePath": { "type": "string", "example": "handbook/onboarding/guide.md", "description": "Path within the uploaded folder structure." }, "directoryPath": { "type": "string", "example": "handbook/onboarding", "description": "Parent directory path within the uploaded folder structure." }, "name": { "type": "string", "example": "guide.md", "description": "Human-readable resource name." }, "declaredSize": { "type": "integer", "minimum": 0, "description": "Declared file size in bytes." }, "receivedSize": { "type": [ "integer", "null" ], "minimum": 0, "description": "Number of content bytes received for this upload entry." }, "disposition": { "type": "string", "enum": [ "upload_required", "skipped_existing", "waiting_reservation", "rejected_deleting" ], "description": "Server decision describing whether this entry must upload content." }, "transferState": { "type": "string", "enum": [ "missing", "uploaded", "skipped" ], "description": "Current content transfer state for this upload entry." }, "sourceFileId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identifier of the new or existing uploaded Markdown file." }, "existingResourceRevision": { "type": [ "integer", "null" ], "minimum": 1, "description": "Current file version when an upload is skipped because the same content already exists." } }, "required": [ "id", "relativePath", "directoryPath", "name", "declaredSize", "receivedSize", "disposition", "transferState", "sourceFileId", "existingResourceRevision" ] }, "UploadSessionTransport": { "type": "object", "additionalProperties": false, "properties": { "manifestPageSize": { "type": "integer", "minimum": 1, "description": "Maximum number of file records accepted in one request." }, "contentUploadConcurrency": { "type": "integer", "minimum": 1, "maximum": 16, "description": "Recommended maximum number of concurrent content uploads for this session." } }, "required": [ "manifestPageSize", "contentUploadConcurrency" ] }, "CreateUploadSessionResponse": { "type": "object", "additionalProperties": false, "properties": { "session": { "$ref": "#/components/schemas/UploadSession", "description": "Upload session returned by the request." }, "transport": { "$ref": "#/components/schemas/UploadSessionTransport", "description": "File-list request size and recommended upload concurrency for the new session." } }, "required": [ "session", "transport" ] }, "UploadSessionResponse": { "type": "object", "additionalProperties": false, "properties": { "session": { "$ref": "#/components/schemas/UploadSession", "description": "Upload session returned by the request." } }, "required": [ "session" ] }, "UploadSessionStatusResponse": { "type": "object", "additionalProperties": false, "properties": { "session": { "$ref": "#/components/schemas/UploadSession", "description": "Upload session returned by the request." }, "entries": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/UploadSessionEntry" }, "description": "Records returned on this page." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination token returned by this endpoint. Reuse it only with the same endpoint and unchanged filters. If it is rejected, restart without a cursor." } }, "required": [ "items", "nextCursor" ], "allOf": [ { "$ref": "#/components/schemas/Page" } ], "description": "Requested page of upload file records and the token for reading the next page." } }, "required": [ "session", "entries" ] }, "UploadEntryResponse": { "type": "object", "additionalProperties": false, "properties": { "entry": { "$ref": "#/components/schemas/UploadSessionEntry", "description": "Upload entry returned by the request." } }, "required": [ "entry" ] }, "SourceDirectory": { "type": "object", "additionalProperties": false, "properties": { "directoryId": { "type": "string", "description": "Uploaded-directory identifier." }, "knowledgeBaseId": { "type": "string", "description": "Owning knowledge-base identifier." }, "parentDirectoryId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Parent uploaded-directory identifier." }, "name": { "type": "string", "description": "Human-readable resource name." }, "relativePath": { "type": "string", "description": "Path within the uploaded folder structure." }, "generatedPath": { "type": "string", "description": "Readable knowledge-base path associated with this uploaded file." }, "depth": { "type": "integer", "minimum": 1, "description": "Directory depth or number of relationship levels to explore." }, "resourceRevision": { "type": "integer", "minimum": 1, "description": "Current resource version used with `If-Match` to prevent overwriting a concurrent change." }, "directFileCount": { "type": "integer", "minimum": 0, "description": "Number of uploaded Markdown files directly inside this directory." }, "descendantFileCount": { "type": "integer", "minimum": 0, "description": "Number of uploaded Markdown files below this directory or tree entry." }, "mutable": { "type": "boolean", "description": "Whether this uploaded Markdown file can currently be changed." }, "deletable": { "type": "boolean", "description": "Whether deletion can currently be requested." }, "deleting": { "type": "boolean", "description": "Whether deletion is currently in progress." }, "actions": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] }, "description": "Actions currently available for this resource." }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the resource was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Time when the resource was last updated." } }, "required": [ "directoryId", "knowledgeBaseId", "parentDirectoryId", "name", "relativePath", "generatedPath", "depth", "resourceRevision", "directFileCount", "descendantFileCount", "mutable", "deletable", "deleting", "actions", "createdAt", "updatedAt" ] }, "SourceDirectoryResponse": { "type": "object", "additionalProperties": false, "properties": { "directory": { "$ref": "#/components/schemas/SourceDirectory", "description": "Uploaded directory returned by the request." } }, "required": [ "directory" ] }, "SourceDirectoryListResponse": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SourceDirectory" }, "description": "Records returned on this page." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination token returned by this endpoint. Reuse it only with the same endpoint and unchanged filters. If it is rejected, restart without a cursor." } }, "required": [ "items", "nextCursor" ], "allOf": [ { "$ref": "#/components/schemas/Page" } ] }, "SourceResourceFile": { "type": "object", "additionalProperties": false, "properties": { "sourceFileId": { "type": "string", "description": "Uploaded-file identifier." }, "knowledgeBaseId": { "type": "string", "description": "Owning knowledge-base identifier." }, "directoryId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Parent uploaded-directory identifier." }, "name": { "type": "string", "description": "Human-readable resource name." }, "relativePath": { "type": "string", "description": "Path within the uploaded folder structure." }, "generatedPath": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Readable knowledge-base path when the file is ready to read." }, "contentType": { "type": "string", "description": "Media type of the stored or generated content." }, "sizeBytes": { "type": "integer", "minimum": 0, "description": "Content size in bytes." }, "resourceRevision": { "type": "integer", "minimum": 1, "description": "Current resource version used with `If-Match` to prevent overwriting a concurrent change." }, "contentRevision": { "type": "integer", "minimum": 0, "description": "Readable generated-content revision. Zero means that no generated output is available yet." }, "state": { "type": "string", "enum": [ "waiting", "processing", "available", "error", "deleting" ], "description": "Current document status. `available` is immediately readable. `error` includes safe failure details and backend-authorized recovery actions." }, "workProgress": { "type": "object", "additionalProperties": false, "properties": { "required": { "type": "integer", "minimum": 0 }, "completed": { "type": "integer", "minimum": 0 }, "activeKinds": { "type": "array", "items": { "type": "string", "enum": [ "prepare", "first_layer", "content_projection", "graphrag", "relation_reconcile", "knowledge_projection", "activate", "cleanup" ] } }, "blockingKind": { "type": [ "string", "null" ], "enum": [ "prepare", "first_layer", "content_projection", "graphrag", "relation_reconcile", "knowledge_projection", "activate", "cleanup", null ] }, "retryingKind": { "type": [ "string", "null" ], "enum": [ "prepare", "first_layer", "content_projection", "graphrag", "relation_reconcile", "knowledge_projection", "activate", "cleanup", null ] } }, "required": [ "required", "completed", "activeKinds", "blockingKind", "retryingKind" ], "description": "Progress across the work required for this document. Work can run concurrently; completed counts work that finished successfully." }, "failure": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "workKind": { "type": "string", "enum": [ "prepare", "first_layer", "content_projection", "graphrag", "relation_reconcile", "knowledge_projection", "activate", "cleanup" ], "description": "Processing step where the document stopped." }, "code": { "type": "string", "maxLength": 64, "description": "Error or failure code that clients can handle programmatically." }, "message": { "type": "string", "maxLength": 500, "description": "Human-readable error, failure, or availability message." }, "occurredAt": { "type": "string", "format": "date-time", "description": "Time when file processing stopped with an error." }, "retryKind": { "type": "string", "enum": [ "document_processing", "none" ], "description": "Type of retry that can be requested." }, "correlationId": { "type": "string", "maxLength": 128, "description": "Identifier that support staff can use to trace the failed background request." } }, "required": [ "workKind", "code", "message", "occurredAt", "retryKind", "correlationId" ], "description": "Error details when file processing stopped." }, "generatedOutputStatus": { "type": "string", "enum": [ "unavailable", "previous_available", "current_available" ], "description": "`current_available` is the active current revision. `previous_available` is the prior active revision retained after replacement failure. `unavailable` means no generated content can be read." }, "actions": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "open_generated_file", "view_failure_details", "replace_source_content", "retry_document_processing" ], "description": "Type of file change, retry, or available action." }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT" ], "description": "HTTP method used by this action." }, "href": { "type": "string", "description": "Relative Developer OpenAPI path for this action." }, "scope": { "type": "string", "enum": [ "source_file" ], "description": "File, directory, or knowledge base affected by this action or retry." } }, "required": [ "kind", "method", "href", "scope" ] }, "description": "Actions currently available for this uploaded Markdown file." }, "links": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] }, "description": "Developer OpenAPI links for reading or managing this uploaded file." }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the resource was created." } }, "required": [ "sourceFileId", "knowledgeBaseId", "directoryId", "name", "relativePath", "generatedPath", "contentType", "sizeBytes", "resourceRevision", "contentRevision", "state", "workProgress", "failure", "generatedOutputStatus", "actions", "links", "createdAt" ] }, "SourceResourceFileResponse": { "type": "object", "additionalProperties": false, "properties": { "sourceFile": { "$ref": "#/components/schemas/SourceResourceFile", "description": "Uploaded Markdown file returned by the request." } }, "required": [ "sourceFile" ] }, "SourceFileRetryResponse": { "type": "object", "additionalProperties": false, "properties": { "sourceFile": { "$ref": "#/components/schemas/SourceResourceFile", "description": "Uploaded Markdown file returned by the request." }, "retry": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "description": "Type of file change, retry, or available action." }, "scope": { "type": "string", "description": "File, directory, or knowledge base affected by this action or retry." }, "coalesced": { "type": "boolean", "description": "Whether the retry joined an equivalent retry already in progress." } }, "required": [ "kind", "scope", "coalesced" ], "description": "Retry request accepted by the server." } }, "required": [ "sourceFile", "retry" ] }, "SourceResourceFileListResponse": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SourceResourceFile" }, "description": "Records returned on this page." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination token returned by this endpoint. Reuse it only with the same endpoint and unchanged filters. If it is rejected, restart without a cursor." } }, "required": [ "items", "nextCursor" ], "allOf": [ { "$ref": "#/components/schemas/Page" } ] }, "MoveSourceFileRequest": { "type": "object", "additionalProperties": false, "properties": { "relativePath": { "type": "string", "minLength": 4, "maxLength": 2048, "pattern": "^(?:[^/]{1,1000}/)*[^/]{1,997}\\.md$", "example": "handbook/setup/install.md", "description": "Target Markdown path inside the knowledge base. Its parent directory must already exist, except when moving the file to the root directory." } }, "required": [ "relativePath" ] }, "MoveSourceDirectoryRequest": { "type": "object", "additionalProperties": false, "properties": { "relativePath": { "type": "string", "minLength": 1, "maxLength": 2048, "pattern": "^(?:[^/]{1,1000}/)*[^/]{1,1000}$", "example": "handbook/archive", "description": "Target directory path inside the knowledge base. Its parent directory must already exist, except when moving the directory to the root." } }, "required": [ "relativePath" ] }, "ResourceOperation": { "type": "object", "additionalProperties": false, "properties": { "operationId": { "type": "string", "description": "Identifier used to check the status and result of this file or directory change." }, "knowledgeBaseId": { "type": "string", "description": "Owning knowledge-base identifier." }, "kind": { "type": "string", "enum": [ "upload", "knowledge_base_metadata", "source_file_metadata", "source_file_replace", "source_file_move", "source_directory_move", "source_file_delete", "source_directory_delete", "knowledge_base_delete" ], "description": "Type of file change, retry, or available action." }, "state": { "type": "string", "enum": [ "processing", "completed", "failed", "cancelled", "superseded" ], "description": "Current processing status." }, "expectedResourceRevision": { "type": [ "integer", "null" ], "minimum": 1, "description": "Resource revision required when the operation was accepted." }, "targetKind": { "type": [ "string", "null" ], "enum": [ "source_file", "source_directory", "knowledge_base", null ], "description": "Type of item changed by this request." }, "targetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identifier of the file, directory, or knowledge base changed by this request." }, "candidateRelativePath": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Requested destination path for a move or replacement that is still processing." }, "result": { "type": [ "object", "null" ], "description": "Bounded document progress for `upload` and `source_directory_move`; null for other operation kinds. Available uploaded documents are immediately readable before the aggregate upload completes.", "properties": { "totalCount": { "type": "integer", "minimum": 0 }, "waitingCount": { "type": "integer", "minimum": 0 }, "processingCount": { "type": "integer", "minimum": 0 }, "availableCount": { "type": "integer", "minimum": 0 }, "failedCount": { "type": "integer", "minimum": 0 }, "deletingCount": { "type": "integer", "minimum": 0 }, "cancelledCount": { "type": "integer", "minimum": 0 }, "supersededCount": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Final operation error code." }, "retryGuidance": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Instructions for checking the change again while it is still processing." }, "actions": { "type": "object", "additionalProperties": false, "properties": { "self": { "type": "string", "description": "Developer OpenAPI path for checking this file or directory change." } }, "required": [ "self" ], "description": "Actions currently available for this resource." }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the resource was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Time when the resource was last updated." }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when processing or deletion finished." } }, "required": [ "operationId", "knowledgeBaseId", "kind", "state", "expectedResourceRevision", "targetKind", "targetId", "candidateRelativePath", "result", "errorCode", "retryGuidance", "actions", "createdAt", "updatedAt", "completedAt" ] }, "ResourceOperationResponse": { "type": "object", "additionalProperties": false, "properties": { "operation": { "$ref": "#/components/schemas/ResourceOperation", "description": "File or directory change record returned by the request." } }, "required": [ "operation" ] }, "ResourceOperationListResponse": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceOperation" }, "description": "Records returned on this page." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination token returned by this endpoint. Reuse it only with the same endpoint and unchanged filters. If it is rejected, restart without a cursor." } }, "required": [ "items", "nextCursor" ], "allOf": [ { "$ref": "#/components/schemas/Page" } ] }, "KnowledgeBaseDeletionResponse": { "type": "object", "additionalProperties": false, "properties": { "operation": { "$ref": "#/components/schemas/ResourceOperation", "description": "File or directory change record returned by the request." }, "deletion": { "type": "object", "additionalProperties": false, "properties": { "knowledgeBaseId": { "type": "string", "description": "Deleted knowledge-base identifier." }, "accepted": { "type": "boolean", "description": "Whether the deletion request was accepted." }, "affectedDirectoryCount": { "type": "integer", "minimum": 0, "description": "Number of uploaded directories covered by the deletion request." }, "affectedFileCount": { "type": "integer", "minimum": 0, "description": "Number of uploaded Markdown files covered by the deletion request." } }, "required": [ "knowledgeBaseId", "accepted", "affectedDirectoryCount", "affectedFileCount" ], "description": "Accepted deletion details." } }, "required": [ "operation", "deletion" ] }, "ResourceDeletionResponse": { "type": "object", "additionalProperties": false, "properties": { "operation": { "$ref": "#/components/schemas/ResourceOperation", "description": "File or directory change record returned by the request." }, "deletion": { "type": "object", "additionalProperties": false, "properties": { "sourceFileId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identifier of the deleted uploaded file." }, "directoryId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identifier of the deleted uploaded directory." }, "affectedDirectoryCount": { "type": "integer", "minimum": 0, "description": "Number of uploaded directories covered by the deletion request." }, "affectedFileCount": { "type": "integer", "minimum": 0, "description": "Number of uploaded Markdown files covered by the deletion request." }, "visibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Current visibility of the deleted file or directory." } }, "description": "Accepted deletion details." } }, "required": [ "operation", "deletion" ] }, "GeneratedTreeEntry": { "type": "object", "additionalProperties": false, "properties": { "activeContentRevision": { "type": [ "integer", "null" ], "minimum": 1, "description": "Current readable knowledge-base content revision." }, "id": { "type": "string", "description": "Tree entry identifier." }, "fileId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Readable file identifier when this entry is a file." }, "sourceFileId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Uploaded Markdown file identifier when this readable file was generated from one." }, "directoryId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Uploaded-directory identifier for directory entries." }, "parentPath": { "type": "string", "description": "Parent directory path of this tree entry." }, "name": { "type": "string", "description": "Human-readable resource name." }, "path": { "type": "string", "description": "Readable knowledge-base file path. It is not an S3 or local filesystem path." }, "sortKey": { "type": "string", "description": "Value that keeps tree entries in a consistent order across pages." }, "entryType": { "type": "string", "enum": [ "file", "directory" ], "description": "Tree entry type." }, "fileKind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Readable file type." }, "directEntryCount": { "type": "integer", "minimum": 0, "description": "Direct directory and file entry count. File entries return 0." }, "directDirectoryCount": { "type": "integer", "minimum": 0, "description": "Number of direct child directories." }, "directFileCount": { "type": "integer", "minimum": 0, "description": "Number of uploaded Markdown files directly inside this directory." }, "descendantFileCount": { "type": "integer", "minimum": 0, "description": "Number of uploaded Markdown files below this directory or tree entry." }, "resourceRevision": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Uploaded-file version when available." }, "deletable": { "type": "boolean", "description": "Whether deletion can currently be requested." }, "contentAvailable": { "type": "boolean", "description": "Whether this tree entry can be read through the readable-file content APIs." }, "readActions": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "fileDetailById": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Request path for readable file details when a file ID is available." }, "fileContentById": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Request path for readable file content when a file ID is available." }, "fileContentByPath": { "type": "string", "description": "Request path for readable file content using its URL-encoded knowledge-base path." }, "relatedFilesById": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Request path for related files when a file ID is available." }, "graphExpansionByFileId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Request path for exploring relationships when a file ID is available." }, "sourceFileStatusById": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "File-processing status request path when this result came from an uploaded Markdown file." } }, "required": [ "fileDetailById", "fileContentById", "fileContentByPath", "relatedFilesById", "graphExpansionByFileId", "sourceFileStatusById" ] }, { "type": "null" } ], "description": "Links for reading file entries. Directory entries return null." } }, "required": [ "activeContentRevision", "id", "fileId", "sourceFileId", "directoryId", "parentPath", "name", "path", "sortKey", "entryType", "fileKind", "directEntryCount", "directDirectoryCount", "directFileCount", "descendantFileCount", "resourceRevision", "deletable", "contentAvailable", "readActions" ] }, "TreeResponse": { "type": "object", "additionalProperties": false, "properties": { "activeContentRevision": { "type": [ "integer", "null" ], "minimum": 1, "description": "Current readable knowledge-base content revision." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/GeneratedTreeEntry" }, "description": "Records returned on this page." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination token returned by this endpoint. Reuse it only with the same endpoint and readable knowledge-base version. If it is rejected, restart without a cursor." } }, "required": [ "activeContentRevision", "items", "nextCursor" ] }, "OkfSignals": { "type": "object", "additionalProperties": false, "properties": { "effectiveStatus": { "anyOf": [ { "type": "string", "enum": [ "draft", "stable", "deprecated" ] }, { "type": "null" } ], "description": "Normalized OKF document status. An omitted status is `stable`; an invalid supplied status is null." }, "trustTier": { "anyOf": [ { "type": "string", "enum": [ "unverified", "machine-confirmed", "human-reviewed" ] }, { "type": "null" } ], "description": "Normalized OKF verification tier. Omitted verification is `unverified`; malformed supplied verification is null." }, "isStale": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether `stale_after` is on or before the current request date. It is null without a valid stale date." }, "staleAfter": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Normalized OKF stale date, or null when absent or invalid." }, "generatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Normalized `generated.at`, or the legacy `timestamp` fallback when available." }, "generatedAtSource": { "anyOf": [ { "type": "string", "enum": [ "generated", "legacy_timestamp" ] }, { "type": "null" } ], "description": "Field that supplied `generatedAt`, distinguishing native OKF 0.2 metadata from the legacy fallback." }, "latestVerifiedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Latest valid OKF verification event time, or null when unavailable." }, "sourceCount": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Number of normalized OKF sources. Omitted sources produce zero; malformed supplied sources produce null." } }, "required": [ "effectiveStatus", "trustTier", "isStale", "staleAfter", "generatedAt", "generatedAtSource", "latestVerifiedAt", "sourceCount" ], "examples": [ { "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 }, { "effectiveStatus": "stable", "trustTier": "unverified", "isStale": null, "staleAfter": null, "generatedAt": "2026-06-17T00:00:00.000Z", "generatedAtSource": "legacy_timestamp", "latestVerifiedAt": null, "sourceCount": 0 }, { "effectiveStatus": null, "trustTier": null, "isStale": null, "staleAfter": null, "generatedAt": null, "generatedAtSource": null, "latestVerifiedAt": null, "sourceCount": null } ] }, "GeneratedFile": { "type": "object", "additionalProperties": false, "properties": { "activeContentRevision": { "type": "integer", "minimum": 1, "description": "Current readable knowledge-base content revision." }, "fileId": { "type": "string", "description": "Readable file identifier." }, "knowledgeBaseId": { "type": "string", "description": "Knowledge-base identifier." }, "sourceFileId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Uploaded Markdown file identifier when this readable file was generated from one." }, "path": { "type": "string", "description": "Readable knowledge-base file path accepted by the path-based file read API." }, "fileKind": { "type": "string", "description": "Readable file type." }, "contentType": { "type": "string", "description": "Media type of the stored or generated content." }, "sizeBytes": { "type": "integer", "minimum": 0, "description": "Content size in bytes." }, "okfType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "OKF document type when available." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolved title when available." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolved description when available." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags parsed from the readable Markdown file." }, "frontmatter": { "type": "object", "additionalProperties": true, "examples": [ { "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" }, { "type": "Guide", "title": "Legacy guide", "timestamp": "2026-06-17T00:00:00Z" }, {}, { "type": "Guide", "title": "Minimal guide" }, { "type": "Guide", "status": [ "stable" ], "stale_after": "next quarter" }, { "type": "Guide", "verified": [ { "by": 42, "at": "today" } ] }, { "type": "Guide", "sources": { "resource": "references/source-a.md" } }, { "type": "Guide", "generated": { "by": "publisher:example", "at": "today" } }, { "okf_version": "0.2", "type": "Attested Computation", "title": "Risk score", "runtime": "python", "parameters": [ { "name": "amount", "type": "number", "required": true } ], "computation": { "resource": "references/risk-score.py" }, "executor": { "resource": "executor.md", "receipt": [ "receipt.md" ] }, "attester": { "resource": "attester.md" } }, { "type": "Attested Computation", "title": "Incomplete risk score", "runtime": [ "python" ], "parameters": "unknown", "executor": 42, "attester": false } ], "description": "Metadata parsed from the YAML front matter at the beginning of the Markdown file." }, "okfSignals": { "$ref": "#/components/schemas/OkfSignals" }, "deletable": { "type": "boolean", "description": "Whether deletion can currently be requested." }, "contentAvailable": { "type": "boolean", "description": "Whether the readable file content can currently be read." }, "readActions": { "type": "object", "additionalProperties": false, "properties": { "fileDetailById": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Request path for readable file details when a file ID is available." }, "fileContentById": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Request path for readable file content when a file ID is available." }, "fileContentByPath": { "type": "string", "description": "Request path for readable file content using its URL-encoded knowledge-base path." }, "relatedFilesById": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Request path for related files when a file ID is available." }, "graphExpansionByFileId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Request path for exploring relationships when a file ID is available." }, "sourceFileStatusById": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "File-processing status request path when this result came from an uploaded Markdown file." } }, "required": [ "fileDetailById", "fileContentById", "fileContentByPath", "relatedFilesById", "graphExpansionByFileId", "sourceFileStatusById" ], "description": "Developer OpenAPI links for reading this file or exploring its relationships." } }, "required": [ "activeContentRevision", "fileId", "knowledgeBaseId", "sourceFileId", "path", "fileKind", "contentType", "sizeBytes", "okfType", "title", "description", "tags", "frontmatter", "okfSignals", "deletable", "contentAvailable", "readActions" ] }, "FileSearchResult": { "type": "object", "additionalProperties": false, "properties": { "activeContentRevision": { "type": "integer", "minimum": 1, "description": "Current readable knowledge-base content revision." }, "fileId": { "type": "string", "description": "Readable file identifier accepted by file detail, content, and related-file APIs." }, "knowledgeBaseId": { "type": "string", "description": "Knowledge-base identifier." }, "sourceFileId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Uploaded Markdown file identifier when this readable file was generated from one." }, "path": { "type": "string", "description": "Readable knowledge-base file path accepted by the path-based file read API." }, "fileKind": { "type": "string", "description": "Readable file type." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolved title when available." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolved description when available." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags parsed from the readable Markdown file." }, "frontmatter": { "type": "object", "additionalProperties": true, "examples": [ { "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" }, { "type": "Guide", "title": "Legacy guide", "timestamp": "2026-06-17T00:00:00Z" }, {}, { "type": "Guide", "title": "Minimal guide" }, { "type": "Guide", "status": [ "stable" ], "stale_after": "next quarter" }, { "type": "Guide", "verified": [ { "by": 42, "at": "today" } ] }, { "type": "Guide", "sources": { "resource": "references/source-a.md" } }, { "type": "Guide", "generated": { "by": "publisher:example", "at": "today" } }, { "okf_version": "0.2", "type": "Attested Computation", "title": "Risk score", "runtime": "python", "parameters": [ { "name": "amount", "type": "number", "required": true } ], "computation": { "resource": "references/risk-score.py" }, "executor": { "resource": "executor.md", "receipt": [ "receipt.md" ] }, "attester": { "resource": "attester.md" } }, { "type": "Attested Computation", "title": "Incomplete risk score", "runtime": [ "python" ], "parameters": "unknown", "executor": 42, "attester": false } ], "description": "Metadata parsed from the YAML front matter at the beginning of the Markdown file." }, "okfSignals": { "$ref": "#/components/schemas/OkfSignals" }, "matchedFields": { "type": "array", "items": { "type": "string", "enum": [ "path", "title", "description", "metadata", "content", "graph_node", "file_relationship" ] }, "description": "Fields that caused this search result to match." }, "evidenceTypes": { "type": "array", "items": { "type": "string", "enum": [ "path", "title", "metadata", "content", "graph_node", "file_relationship", "entity", "relationship", "community" ] }, "description": "Safe evidence categories that supported this source-file candidate." }, "sourceExcerpt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Short excerpt from the active source Markdown when source-grounded text evidence is available. Read the source file before using it as answer evidence." }, "score": { "type": "number", "minimum": 0, "description": "Relative relevance score used to order results for this query. Higher values rank first." }, "contentAvailable": { "type": "boolean", "description": "Whether the readable file content can currently be read." }, "readActions": { "type": "object", "additionalProperties": false, "properties": { "fileDetailById": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Request path for readable file details when a file ID is available." }, "fileContentById": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Request path for readable file content when a file ID is available." }, "fileContentByPath": { "type": "string", "description": "Request path for readable file content using its URL-encoded knowledge-base path." }, "relatedFilesById": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Request path for related files when a file ID is available." }, "graphExpansionByFileId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Request path for exploring relationships when a file ID is available." }, "sourceFileStatusById": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "File-processing status request path when this result came from an uploaded Markdown file." } }, "required": [ "fileDetailById", "fileContentById", "fileContentByPath", "relatedFilesById", "graphExpansionByFileId", "sourceFileStatusById" ], "description": "Developer OpenAPI links for reading this file or exploring its relationships." }, "matchType": { "type": "string", "enum": [ "file_direct", "graph_node", "graph_edge", "graph_neighbor", "hybrid" ], "description": "Dominant actual evidence class for this source-file result after duplicate collapse. `hybrid` means both file and relationship evidence supported it." }, "graphContext": { "type": "object", "additionalProperties": false, "properties": { "graphRef": { "type": "string", "description": "Readable relationship-data path under `_graph/by-file/` for this result." }, "depth": { "type": "integer", "enum": [ 0, 1, 2 ], "description": "Directory depth or number of relationship levels to explore." }, "seedSourceFileId": { "type": "string", "description": "Uploaded-file identifier used as the starting point for relationship search." }, "relationships": { "type": "array", "items": { "$ref": "#/components/schemas/RelatedFile" }, "description": "Related readable files found for this search result." }, "graphPaths": { "type": "array", "items": { "type": "string" }, "description": "Readable relationship-data files that can be read with the path-based file content endpoint." } }, "required": [ "graphRef", "depth", "seedSourceFileId", "relationships", "graphPaths" ], "description": "Relationship details and follow-up links for this search result." } }, "required": [ "activeContentRevision", "fileId", "knowledgeBaseId", "sourceFileId", "path", "fileKind", "title", "description", "tags", "frontmatter", "okfSignals", "matchedFields", "evidenceTypes", "sourceExcerpt", "score", "contentAvailable", "matchType", "readActions" ] }, "FileSearchQueryContext": { "type": "object", "additionalProperties": false, "properties": { "query": { "type": "string", "description": "Normalized search text accepted by the endpoint." }, "normalizedQuery": { "type": "string", "description": "Search text after standard character and spacing normalization." }, "scope": { "type": "string", "enum": [ "all", "path", "metadata" ], "description": "Search field scope applied to this response." }, "fileKind": { "type": "string", "description": "Readable file type filter applied to this response. `all` means no type filter." }, "mode": { "type": "string", "enum": [ "file", "graph", "hybrid" ], "description": "Search mode applied to this response." }, "graphDepth": { "type": "integer", "enum": [ 0, 1, 2 ], "description": "Requested relationship context depth. Zero returns no relationship entries; one returns direct entries; two may include second-level entries within fanout." }, "graphFanout": { "type": "integer", "minimum": 0, "description": "Maximum relationship records returned per graph item." }, "okfStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Normalized OKF document-status filter applied to this response." }, "okfTrustTier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Normalized OKF verification-tier filter applied to this response." }, "okfFreshness": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Normalized OKF freshness filter applied to this response." }, "rerank": { "type": "boolean", "description": "Whether optional source-grounded reranking was requested." }, "rerankTopK": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 50 }, { "type": "null" } ], "description": "Non-exact candidate window used only when reranking is enabled." }, "rerankScoreThreshold": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ], "description": "Minimum valid reranker score for non-exact candidates, or null when disabled." }, "limit": { "type": "integer", "minimum": 1, "description": "Maximum number of results applied to this request." }, "cursorProvided": { "type": "boolean", "description": "Whether this request used a pagination token returned by an earlier search with the same query and filters." } }, "required": [ "query", "normalizedQuery", "scope", "fileKind", "mode", "graphDepth", "graphFanout", "okfStatus", "okfTrustTier", "okfFreshness", "rerank", "rerankTopK", "rerankScoreThreshold", "limit", "cursorProvided" ] }, "FileSearchResultSummary": { "type": "object", "additionalProperties": false, "properties": { "resultCount": { "type": "integer", "minimum": 0, "description": "Number of results returned on this page." }, "hasMore": { "type": "boolean", "description": "Whether the same query and filters can continue with `nextCursor`." }, "sort": { "type": "array", "items": { "type": "string" }, "description": "Ordering applied to this result page." }, "meaning": { "type": "string", "description": "Plain-language explanation of what the current result page means." } }, "required": [ "resultCount", "hasMore", "sort", "meaning" ] }, "FileSearchResponse": { "type": "object", "additionalProperties": false, "properties": { "activeContentRevision": { "type": [ "integer", "null" ], "minimum": 1, "description": "Current readable knowledge-base content revision." }, "query": { "$ref": "#/components/schemas/FileSearchQueryContext", "description": "Search text and options used for this result." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/FileSearchResult" }, "description": "Records returned on this page." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "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": { "type": "string", "enum": [ "ok", "no_candidates" ], "description": "`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": { "type": "string", "enum": [ "file", "graph", "hybrid" ], "description": "Search mode applied to this response." }, "semanticStatus": { "type": "object", "additionalProperties": false, "properties": { "state": { "type": "string", "enum": [ "ready", "degraded", "unavailable" ], "description": "Availability of optional semantic search lanes for this response." }, "safeCode": { "anyOf": [ { "type": "string", "enum": [ "SEMANTIC_ADOPTION_REQUIRED", "SEMANTIC_LEXICAL_PROJECTION_UNAVAILABLE", "SEMANTIC_PROVIDER_ADOPTION_REQUIRED", "SEMANTIC_SEARCH_UNAVAILABLE", "SEMANTIC_LANE_PARTIAL_FAILURE" ] }, { "type": "null" } ], "description": "Stable non-sensitive reason code when semantic search is degraded or unavailable." } }, "required": [ "state", "safeCode" ] }, "evidenceStatus": { "type": "object", "additionalProperties": false, "properties": { "completedFamilies": { "type": "array", "items": { "type": "string", "enum": [ "exact_path", "exact_title", "lexical", "jieba", "file_graph", "file_relationship", "content_vector", "entity_vector", "relationship_vector", "community_vector" ] }, "description": "Retrieval evidence families that completed for this response." }, "degradedFamilies": { "type": "array", "items": { "type": "string", "enum": [ "exact_path", "exact_title", "lexical", "jieba", "file_graph", "file_relationship", "content_vector", "entity_vector", "relationship_vector", "community_vector" ] }, "description": "Retrieval evidence families that did not complete." } }, "required": [ "completedFamilies", "degradedFamilies" ], "description": "Retrieval evidence families that completed or degraded for this response." }, "rerankerStatus": { "type": "object", "additionalProperties": false, "properties": { "state": { "type": "string", "enum": [ "not_configured", "skipped", "applied", "degraded" ], "description": "Current processing status." }, "safeCode": { "anyOf": [ { "type": "string", "enum": [ "RERANKER_DISABLED", "RERANKER_RETRIEVAL_UNAVAILABLE", "RERANKER_ABORTED", "RERANKER_AUTHENTICATION_FAILED", "RERANKER_INVALID_REQUEST", "RERANKER_INVALID_RESPONSE", "RERANKER_CONFIGURATION_UNAVAILABLE", "RERANKER_NOT_CONFIGURED", "RERANKER_NOT_ACTIVE", "RERANKER_NO_CANDIDATES", "RERANKER_ALL_BELOW_THRESHOLD", "RERANKER_PAYLOAD_TOO_LARGE", "RERANKER_PROVIDER_UNAVAILABLE", "RERANKER_RATE_LIMITED", "RERANKER_RESPONSE_TOO_LARGE", "RERANKER_TIMEOUT", "RERANKER_UNAVAILABLE" ] }, { "type": "null" } ], "description": "Stable non-sensitive reason code when reranking was not applied." } }, "required": [ "state", "safeCode" ], "description": "Whether optional reranking was applied, skipped, unavailable, or degraded without exposing model scores." }, "graphStatus": { "type": "string", "enum": [ "available", "index_unavailable", "disabled_for_file_mode" ], "description": "Relationship-search availability for this response. `disabled_for_file_mode` is returned for file-only search." }, "graphSummary": { "type": "object", "additionalProperties": false, "properties": { "available": { "type": "boolean", "description": "Whether relationship data is available for this response." }, "indexedDocumentCount": { "type": "integer", "minimum": 0, "description": "Total readable file-graph nodes available to relationship search, not the current result-page count." }, "indexedRelationshipCount": { "type": "integer", "minimum": 0, "description": "Total readable file relationships available to relationship search, not the current result-page count." }, "depth": { "type": "integer", "enum": [ 0, 1, 2 ], "description": "Directory depth or number of relationship levels to explore." }, "fanout": { "type": "integer", "minimum": 0, "description": "Maximum related records returned for each explored item." } }, "required": [ "available", "indexedDocumentCount", "indexedRelationshipCount", "depth", "fanout" ], "description": "File relationship availability and counts for this response." }, "resultSummary": { "$ref": "#/components/schemas/FileSearchResultSummary", "description": "Summary of the current result page." }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Status message when no files matched or search is not available." }, "nextActions": { "type": "array", "items": { "type": "string" }, "description": "Suggested file reads or relationship queries for continuing exploration." } }, "required": [ "activeContentRevision", "query", "items", "nextCursor", "searchStatus", "searchMode", "semanticStatus", "evidenceStatus", "rerankerStatus", "graphStatus", "graphSummary", "resultSummary" ] }, "FileDetailResponse": { "type": "object", "additionalProperties": false, "properties": { "file": { "$ref": "#/components/schemas/GeneratedFile", "description": "Readable file metadata returned by the request." } }, "required": [ "file" ] }, "FileContentResponse": { "type": "object", "additionalProperties": false, "properties": { "file": { "$ref": "#/components/schemas/GeneratedFile", "description": "Readable file metadata returned by the request." }, "content": { "type": "string", "description": "Complete readable file content." } }, "required": [ "file", "content" ] }, "RelatedFile": { "type": "object", "additionalProperties": false, "properties": { "activeContentRevision": { "type": "integer", "minimum": 1, "description": "Current readable knowledge-base content revision." }, "fileId": { "type": "string", "description": "Related readable file identifier accepted by file detail, content, related-file, and relationship-exploration operations." }, "sourceFileId": { "type": "string", "description": "Uploaded-file identifier associated with the related readable file." }, "path": { "type": "string", "description": "Readable knowledge-base path of the related file." }, "title": { "type": "string", "description": "Resolved related-file title." }, "relationType": { "type": "string", "description": "Relationship type." }, "direction": { "type": "string", "enum": [ "outgoing", "incoming", "bidirectional" ], "description": "Relationship direction relative to `fromFileId` for this traversal step." }, "fromFileId": { "type": "string", "description": "Readable source-file identifier from which this traversal step starts." }, "relationshipDepth": { "type": "integer", "minimum": 1, "maximum": 2, "description": "Relationship level of this traversal step from the requested seed file." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable relationship reason when the indexed source evidence supplies one." }, "contentAvailable": { "type": "boolean", "description": "Whether the readable file content can currently be read." }, "readActions": { "type": "object", "additionalProperties": false, "properties": { "fileDetailById": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Request path for readable file details when a file ID is available." }, "fileContentById": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Request path for readable file content when a file ID is available." }, "fileContentByPath": { "type": "string", "description": "Request path for readable file content using its URL-encoded knowledge-base path." }, "relatedFilesById": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Request path for related files when a file ID is available." }, "graphExpansionByFileId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Request path for exploring relationships when a file ID is available." }, "sourceFileStatusById": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "File-processing status request path when this result came from an uploaded Markdown file." } }, "required": [ "fileDetailById", "fileContentById", "fileContentByPath", "relatedFilesById", "graphExpansionByFileId", "sourceFileStatusById" ], "description": "Developer OpenAPI links for reading this file or exploring its relationships." } }, "required": [ "fileId", "activeContentRevision", "sourceFileId", "path", "title", "relationType", "direction", "fromFileId", "relationshipDepth", "reason", "contentAvailable", "readActions" ] }, "RelatedFileListResponse": { "type": "object", "additionalProperties": false, "properties": { "activeContentRevision": { "type": "integer", "minimum": 1, "description": "Current readable knowledge-base content revision." }, "fileId": { "type": "string", "description": "Requested file identifier." }, "sourceFileId": { "type": "string", "description": "Uploaded-file identifier associated with the requested readable file." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/RelatedFile" }, "description": "Records returned on this page." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination token returned by this endpoint for reading the next page with the same file and filters." }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Status and suggested next step when no related files are available." }, "nextActions": { "type": "array", "items": { "type": "string" }, "description": "Suggested follow-up reads for continued file exploration." } }, "required": [ "activeContentRevision", "fileId", "sourceFileId", "items", "nextCursor" ] }, "GraphExpansionResponse": { "type": "object", "additionalProperties": false, "properties": { "activeContentRevision": { "type": "integer", "minimum": 1, "description": "Current readable knowledge-base content revision." }, "seedFile": { "$ref": "#/components/schemas/GeneratedFile", "description": "Current readable starting file resolved from `fileId`." }, "relationships": { "type": "array", "items": { "$ref": "#/components/schemas/RelatedFile" }, "description": "Related files found up to the requested depth and result limits." }, "graphPaths": { "type": "array", "items": { "type": "string" }, "description": "Readable relationship-data files under `_graph/` that can be read with the path-based file content endpoint." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "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": { "type": "object", "additionalProperties": false, "properties": { "relationshipCount": { "type": "integer", "minimum": 0, "description": "Number of relationships returned by graph expansion." }, "hasMore": { "type": "boolean", "description": "Whether another result page is available." }, "depth": { "type": "integer", "enum": [ 0, 1, 2 ], "description": "Directory depth or number of relationship levels to explore." }, "fanout": { "type": "integer", "minimum": 0, "description": "Maximum related records returned for each explored item." }, "meaning": { "type": "string", "description": "Human-readable interpretation of the result." } }, "required": [ "relationshipCount", "hasMore", "depth", "fanout", "meaning" ], "description": "Summary of the current result page." } }, "required": [ "activeContentRevision", "seedFile", "relationships", "graphPaths", "nextCursor", "resultSummary" ] }, "GraphOverviewResponse": { "type": "object", "additionalProperties": false, "properties": { "activeContentRevision": { "type": "integer", "minimum": 1, "description": "Current readable knowledge-base content revision." }, "availability": { "type": "string", "enum": [ "available", "empty", "unavailable" ], "description": "Whether the readable knowledge-base version contains readable relationship data. An empty result does not mean the knowledge base is empty." }, "summary": { "type": "object", "additionalProperties": false, "properties": { "readableFileCount": { "type": "integer", "minimum": 0 }, "relationshipCount": { "type": "integer", "minimum": 0, "description": "Number of relationships returned by graph expansion." } }, "required": [ "readableFileCount", "relationshipCount" ], "description": "File relationship counts." }, "resources": { "type": "object", "additionalProperties": false, "properties": { "graphIndexPath": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Readable relationship index path when available." }, "byDirectoryPath": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Readable relationships grouped by source directory when available." }, "byFilePath": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Readable relationships grouped by source file when available." } }, "required": [ "graphIndexPath", "byDirectoryPath", "byFilePath" ], "description": "Relationship files and API links available for further exploration." }, "readActions": { "type": "object", "additionalProperties": false, "properties": { "graphIndexContent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Read the readable relationship index file when available." }, "listGraphRoot": { "type": "string", "description": "File-tree request for the relationship-data root." }, "listRelationshipsByDirectory": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "List relationship records grouped by source directory when available." }, "listRelationshipsByFile": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "List relationship records grouped by source file when available." } }, "required": [ "graphIndexContent", "listGraphRoot", "listRelationshipsByDirectory", "listRelationshipsByFile" ], "description": "Developer OpenAPI links for reading this file or exploring its relationships." } }, "required": [ "activeContentRevision", "availability", "summary", "resources", "readActions" ] }, "DeleteResponse": { "type": "object", "additionalProperties": false, "properties": { "deleted": { "type": "boolean", "description": "Whether the webhook subscription was deleted." }, "webhookId": { "type": "string", "description": "Deleted webhook identifier." } }, "required": [ "deleted", "webhookId" ] }, "Webhook": { "type": "object", "additionalProperties": false, "properties": { "webhookId": { "type": "string", "description": "Webhook identifier." }, "name": { "type": "string", "description": "Human-readable resource name." }, "endpointHost": { "type": "string", "description": "Public hostname of the webhook endpoint; the full URL is not returned." }, "events": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "document.waiting", "document.processing", "document.available", "document.error", "document.deleting", "file.deleted", "knowledge_base.deleted" ] }, "description": "Webhook event types included in this subscription." }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the resource was created." }, "lastDeliveryAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time of the most recent webhook delivery." } }, "required": [ "webhookId", "name", "endpointHost", "events", "createdAt", "lastDeliveryAt" ] }, "WebhookCreateRequest": { "type": "object", "additionalProperties": false, "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional webhook name." }, "url": { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]://", "description": "Public HTTPS receiver URL. Loopback, private, link-local, reserved, credential-bearing, fragment-bearing, and redirect targets are rejected." }, "events": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "document.waiting", "document.processing", "document.available", "document.error", "document.deleting", "file.deleted", "knowledge_base.deleted" ] }, "description": "Webhook event types included in this subscription." } }, "required": [ "url", "events" ] }, "WebhookCreateResponse": { "type": "object", "additionalProperties": false, "properties": { "webhook": { "$ref": "#/components/schemas/Webhook", "description": "Webhook subscription returned by the request." }, "signingSecret": { "type": "string", "description": "Returned only by this create operation. An identical idempotent replay returns the same value; list operations never return it." } }, "required": [ "webhook", "signingSecret" ] }, "WebhookListResponse": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" }, "description": "Records returned on this page." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination token returned by this endpoint. Reuse it only with the same endpoint and unchanged filters. If it is rejected, restart without a cursor." } }, "required": [ "items", "nextCursor" ], "allOf": [ { "$ref": "#/components/schemas/Page" } ] }, "WebhookDelivery": { "type": "object", "additionalProperties": false, "properties": { "deliveryId": { "type": "string", "description": "Webhook delivery identifier." }, "webhookId": { "type": "string", "description": "Webhook identifier." }, "eventId": { "type": "string", "description": "Webhook event identifier." }, "eventType": { "type": "string", "description": "Webhook event type delivered to the subscription." }, "payload": { "type": "object", "additionalProperties": true, "description": "Original safe public event payload delivered to the webhook endpoint." }, "status": { "type": "string", "enum": [ "pending", "success", "failed" ], "description": "Current health or delivery status." }, "attemptCount": { "type": "integer", "minimum": 0, "description": "Number of delivery attempts made so far." }, "httpStatus": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "HTTP status returned by the API or webhook endpoint." }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Delivery error code when delivery fails." }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the resource was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Time when the resource was last updated." } }, "required": [ "deliveryId", "webhookId", "eventId", "eventType", "payload", "status", "attemptCount", "httpStatus", "errorCode", "createdAt", "updatedAt" ] }, "WebhookDeliveryListResponse": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" }, "description": "Records returned on this page." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination token returned by this endpoint. Reuse it only with the same endpoint and unchanged filters. If it is rejected, restart without a cursor." } }, "required": [ "items", "nextCursor" ], "allOf": [ { "$ref": "#/components/schemas/Page" } ] }, "WebhookRedeliveryResponse": { "type": "object", "additionalProperties": false, "properties": { "delivery": { "$ref": "#/components/schemas/WebhookDelivery", "description": "Webhook delivery created by the redelivery request." } }, "required": [ "delivery" ] } } }, "paths": { "/openapi/v2/health": { "get": { "tags": [ "Metadata" ], "operationId": "getDeveloperOpenApiHealth", "summary": "Get health state", "description": "Check whether the Developer OpenAPI is available. The response only returns the health state.", "security": [ { "bearerAuth": [] } ], "x-request-example": {}, "responses": { "200": { "description": "Current Developer OpenAPI health state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" }, "example": { "status": "ok" } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/version": { "get": { "tags": [ "Metadata" ], "operationId": "getDeveloperOpenApiVersion", "summary": "Get API version", "description": "Read the product version and Developer OpenAPI version for client compatibility checks.", "security": [ { "bearerAuth": [] } ], "x-request-example": {}, "responses": { "200": { "description": "Current product and Developer OpenAPI versions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionResponse" }, "example": { "product": "focowiki", "version": "0.7.47", "apiVersion": "v2" } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/openapi.json": { "get": { "tags": [ "Metadata" ], "operationId": "getDeveloperOpenApiContract", "summary": "Get OpenAPI contract", "description": "Read the machine-readable OpenAPI contract that describes the Developer OpenAPI.", "security": [ { "bearerAuth": [] } ], "x-request-example": {}, "responses": { "200": { "description": "Complete OpenAPI 3.1 contract for the Developer OpenAPI.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "openapi": { "type": "string", "description": "OpenAPI Specification version used by this contract." }, "info": { "type": "object", "additionalProperties": true, "description": "Product, contract version, license, and purpose." }, "servers": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Server base URLs declared by this contract." }, "security": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Default authentication requirements." }, "tags": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Operation groups exposed by this contract." }, "paths": { "type": "object", "additionalProperties": true, "description": "Documented Developer OpenAPI paths and operations." }, "components": { "type": "object", "additionalProperties": true, "description": "Reusable schemas and security definitions." } }, "required": [ "openapi", "info", "servers", "security", "tags", "paths", "components" ] }, "example": { "openapi": "3.1.0", "info": { "title": "Focowiki Developer OpenAPI", "version": "0.7.47" }, "servers": [ { "url": "https://openapi.example.com" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Knowledge Bases" } ], "paths": { "/openapi/v2/knowledge-bases": { "get": { "operationId": "listKnowledgeBases", "summary": "List knowledge bases" }, "post": { "operationId": "createKnowledgeBase", "summary": "Create a knowledge base" } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": {} } } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/knowledge-bases": { "get": { "tags": [ "Knowledge Bases" ], "operationId": "listKnowledgeBases", "summary": "List knowledge bases", "description": "Read a paginated list of knowledge bases available to the current OpenAPI key.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "query": { "limit": 50 } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of records to return. The deployment can enforce a lower limit.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination token returned by the same endpoint for reading the next page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Requested page of knowledge bases and the token for reading the next page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseListResponse" }, "example": { "items": [ { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "name": "Product Docs", "description": "Product documentation", "activeContentRevision": 1, "resourceRevision": 1, "createdAt": "2026-06-17T00:00:00.000Z", "updatedAt": "2026-06-17T00:00:00.000Z" } ], "nextCursor": null } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request failed validation.", "httpStatus": 422 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } }, "post": { "tags": [ "Knowledge Bases" ], "operationId": "createKnowledgeBase", "summary": "Create a knowledge base", "description": "Create a new knowledge base and receive the `knowledgeBaseId` required by its upload, processing-status, readable-file, and deletion APIs.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "body": { "name": "Product Docs", "description": "Product documentation" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKnowledgeBaseRequest" }, "example": { "name": "Product Docs", "description": "Product documentation" } } } }, "responses": { "201": { "description": "Newly created knowledge base.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseResponse" }, "example": { "knowledgeBase": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "name": "Product Docs", "description": "Product documentation", "activeContentRevision": 0, "resourceRevision": 1, "createdAt": "2026-06-17T00:00:00.000Z", "updatedAt": "2026-06-17T00:00:00.000Z" } } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "413": { "description": "The request body exceeds the accepted size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "PAYLOAD_TOO_LARGE", "message": "The request body exceeds the accepted size limit.", "httpStatus": 413 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request failed validation.", "httpStatus": 422 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/knowledge-bases/{knowledgeBaseId}": { "get": { "tags": [ "Knowledge Bases" ], "operationId": "getKnowledgeBase", "summary": "Get a knowledge base", "description": "Read one knowledge base by `knowledgeBaseId`.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111" } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Requested knowledge base.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseResponse" }, "example": { "knowledgeBase": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "name": "Product Docs", "description": "Product documentation", "activeContentRevision": 1, "resourceRevision": 1, "createdAt": "2026-06-17T00:00:00.000Z", "updatedAt": "2026-06-17T00:00:00.000Z" } } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } }, "patch": { "tags": [ "Knowledge Bases" ], "operationId": "updateKnowledgeBase", "summary": "Update knowledge-base metadata", "description": "Update the name or description of one knowledge base. Send its current `resourceRevision` in `If-Match`; the updated record is returned after the change is saved.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111" }, "body": { "name": "Product handbook", "description": "Current product guidance." } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "If-Match", "in": "header", "required": true, "description": "Current `resourceRevision` returned by the API. If the resource changed after it was read, the request returns a conflict instead of overwriting the newer change.", "schema": { "type": "string", "example": "\"1\"" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateKnowledgeBaseRequest" }, "example": { "name": "Product handbook", "description": "Current product guidance." } } } }, "responses": { "200": { "description": "Updated knowledge-base record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseMutationResponse" }, "example": { "knowledgeBase": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "name": "Product Docs", "description": "Product documentation", "activeContentRevision": 1, "resourceRevision": 1, "createdAt": "2026-06-17T00:00:00.000Z", "updatedAt": "2026-06-17T00:00:00.000Z" } } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "409": { "description": "The request conflicts with the current resource state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The request conflicts with the current resource state.", "httpStatus": 409 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "413": { "description": "The request body exceeds the accepted size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "PAYLOAD_TOO_LARGE", "message": "The request body exceeds the accepted size limit.", "httpStatus": 413 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request failed validation.", "httpStatus": 422 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } }, "delete": { "tags": [ "Knowledge Bases" ], "operationId": "deleteKnowledgeBase", "summary": "Delete a knowledge base", "description": "Start deleting one knowledge base. Poll the returned operation URL until it reaches a terminal state. After deletion completes, the operation URL remains readable for a limited retention period while the knowledge-base URL returns 404.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111" } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-generated key for safely retrying the same request. Reuse the same value for retries so duplicate work is not created.", "schema": { "type": "string", "example": "mutation-2026-07-10-001" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Current `resourceRevision` returned by the API. If the resource changed after it was read, the request returns a conflict instead of overwriting the newer change.", "schema": { "type": "string", "example": "\"1\"" } } ], "responses": { "202": { "description": "Accepted knowledge-base deletion, the operation used to check completion, and the number of affected files and directories.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseDeletionResponse" }, "example": { "operation": { "operationId": "deletion-44444444-4444-4444-8444-444444444444", "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "kind": "knowledge_base_delete", "state": "processing", "expectedResourceRevision": 1, "targetKind": "knowledge_base", "targetId": "knowledge-base-11111111-1111-4111-8111-111111111111", "candidateRelativePath": null, "result": null, "errorCode": null, "retryGuidance": "Check this change again after a short delay.", "actions": { "self": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/operations/deletion-44444444-4444-4444-8444-444444444444" }, "createdAt": "2026-06-17T00:00:00.000Z", "updatedAt": "2026-06-17T00:00:00.000Z", "completedAt": null }, "deletion": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "accepted": true, "affectedDirectoryCount": 3, "affectedFileCount": 20 } } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "409": { "description": "The request conflicts with the current resource state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The request conflicts with the current resource state.", "httpStatus": 409 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request failed validation.", "httpStatus": 422 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/knowledge-bases/{knowledgeBaseId}/upload-sessions": { "post": { "tags": [ "Upload Sessions" ], "operationId": "createUploadSession", "summary": "Create a resumable upload session", "description": "Start a resumable upload and receive the session and operation identifiers, the maximum number of files per list request, and the recommended upload concurrency.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111" }, "body": { "declaredFileCount": 1, "declaredByteCount": 37 } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-generated key for safely retrying the same request. Reuse the same value for retries so duplicate work is not created.", "schema": { "type": "string", "example": "mutation-2026-07-10-001" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUploadSessionRequest" }, "example": { "declaredFileCount": 1, "declaredByteCount": 37 } } } }, "responses": { "201": { "description": "New upload session and its file-list and content-upload settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUploadSessionResponse" }, "example": { "session": { "id": "upload-11111111-1111-4111-8111-111111111111", "operationId": "upload-operation-11111111-1111-4111-8111-111111111111", "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "state": "draft", "declaredFileCount": 1, "declaredByteCount": 37, "counts": { "selected": 0, "uploadRequired": 0, "skippedExisting": 0, "waitingReservation": 0, "rejectedDeleting": 0, "uploaded": 0, "finalized": 0 }, "errorCode": null, "expiresAt": "2026-06-18T00:00:00.000Z", "completedAt": null, "createdAt": "2026-06-17T00:00:00.000Z", "updatedAt": "2026-06-17T00:00:00.000Z", "actions": { "operation": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/operations/upload-operation-11111111-1111-4111-8111-111111111111" } }, "transport": { "manifestPageSize": 500, "contentUploadConcurrency": 8 } } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "409": { "description": "The request conflicts with the current resource state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The request conflicts with the current resource state.", "httpStatus": 409 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "413": { "description": "The request body exceeds the accepted size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "PAYLOAD_TOO_LARGE", "message": "The request body exceeds the accepted size limit.", "httpStatus": 413 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request failed validation.", "httpStatus": 422 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/knowledge-bases/{knowledgeBaseId}/upload-sessions/{uploadSessionId}/entries": { "post": { "tags": [ "Upload Sessions" ], "operationId": "addUploadManifestEntries", "summary": "Add files to an upload session", "description": "Add a batch of Markdown files to an upload session by registering each relative path, size, and optional checksum.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "uploadSessionId": "upload-11111111-1111-4111-8111-111111111111" }, "body": { "entries": [ { "relativePath": "handbook/onboarding/guide.md", "declaredSize": 37, "checksumSha256": "67c26271e50e79cadc720ca4eb964ee65fa4be663c87e0314b486b1109a0990c" } ] } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "uploadSessionId", "in": "path", "required": true, "description": "Upload session identifier returned by createUploadSession.", "schema": { "type": "string", "example": "upload-session-123" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadManifestPageRequest" }, "example": { "entries": [ { "relativePath": "handbook/onboarding/guide.md", "declaredSize": 37, "checksumSha256": "67c26271e50e79cadc720ca4eb964ee65fa4be663c87e0314b486b1109a0990c" } ] } } } }, "responses": { "200": { "description": "Upload session after accepting this batch of file records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSessionResponse" }, "example": { "session": { "id": "upload-11111111-1111-4111-8111-111111111111", "operationId": "upload-operation-11111111-1111-4111-8111-111111111111", "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "state": "manifest_building", "declaredFileCount": 1, "declaredByteCount": 37, "counts": { "selected": 1, "uploadRequired": 0, "skippedExisting": 0, "waitingReservation": 0, "rejectedDeleting": 0, "uploaded": 0, "finalized": 0 }, "errorCode": null, "expiresAt": "2026-06-18T00:00:00.000Z", "completedAt": null, "createdAt": "2026-06-17T00:00:00.000Z", "updatedAt": "2026-06-17T00:00:00.000Z", "actions": { "operation": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/operations/upload-operation-11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "409": { "description": "The request conflicts with the current resource state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The request conflicts with the current resource state.", "httpStatus": 409 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "413": { "description": "The request body exceeds the accepted size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "PAYLOAD_TOO_LARGE", "message": "The request body exceeds the accepted size limit.", "httpStatus": 413 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request failed validation.", "httpStatus": 422 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/knowledge-bases/{knowledgeBaseId}/upload-sessions/{uploadSessionId}/seal": { "post": { "tags": [ "Upload Sessions" ], "operationId": "sealUploadManifest", "summary": "Confirm the upload file list", "description": "Confirm that the upload file list is complete, then read the session to find the files whose Markdown content must be uploaded.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "uploadSessionId": "upload-11111111-1111-4111-8111-111111111111" } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "uploadSessionId", "in": "path", "required": true, "description": "Upload session identifier returned by createUploadSession.", "schema": { "type": "string", "example": "upload-session-123" } } ], "responses": { "200": { "description": "Upload session after confirming the complete file list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSessionResponse" }, "example": { "session": { "id": "upload-11111111-1111-4111-8111-111111111111", "operationId": "upload-operation-11111111-1111-4111-8111-111111111111", "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "state": "manifest_sealed", "declaredFileCount": 1, "declaredByteCount": 37, "counts": { "selected": 1, "uploadRequired": 1, "skippedExisting": 0, "waitingReservation": 0, "rejectedDeleting": 0, "uploaded": 0, "finalized": 0 }, "errorCode": null, "expiresAt": "2026-06-18T00:00:00.000Z", "completedAt": null, "createdAt": "2026-06-17T00:00:00.000Z", "updatedAt": "2026-06-17T00:00:00.000Z", "actions": { "operation": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/operations/upload-operation-11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "409": { "description": "The request conflicts with the current resource state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The request conflicts with the current resource state.", "httpStatus": 409 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request failed validation.", "httpStatus": 422 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/knowledge-bases/{knowledgeBaseId}/upload-sessions/{uploadSessionId}/entries/{entryId}/content": { "put": { "tags": [ "Upload Sessions" ], "operationId": "uploadSessionEntryContent", "summary": "Upload one Markdown file body", "description": "Upload the complete Markdown content for one file marked `upload_required`.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "uploadSessionId": "upload-11111111-1111-4111-8111-111111111111", "entryId": "upload-entry-11111111-1111-4111-8111-111111111111" }, "body": "# Guide\n\nCurrent onboarding guidance." }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "uploadSessionId", "in": "path", "required": true, "description": "Upload session identifier returned by createUploadSession.", "schema": { "type": "string", "example": "upload-session-123" } }, { "name": "entryId", "in": "path", "required": true, "description": "Upload entry identifier returned by getUploadSession.", "schema": { "type": "string", "example": "upload-entry-123" } } ], "requestBody": { "required": true, "content": { "text/markdown": { "examples": { "nativeV02": { "summary": "Native OKF 0.2 metadata", "value": "---\nokf_version: '0.2'\ntype: Guide\ntitle: Verified guide\nsources:\n - id: source-a\n resource: references/source-a.md\ngenerated:\n by: publisher:example\n at: '2026-06-17T00:00:00Z'\nverified:\n - by: human:reviewer\n at: '2026-06-17T01:00:00Z'\nstatus: stable\nstale_after: '2026-12-31'\n---\n# Verified guide" }, "legacyFallback": { "summary": "Legacy generated-time fallback", "value": "---\ntype: Guide\ntimestamp: '2026-06-17T00:00:00Z'\n---\n# Legacy guide" }, "noFrontmatter": { "summary": "Markdown without frontmatter", "value": "# Plain Markdown guide\n\nFrontmatter is optional." }, "missingOptionalSignals": { "summary": "Missing optional OKF signals", "value": "---\ntype: Guide\ntitle: Minimal guide\n---\n# Minimal guide" }, "malformedStatus": { "summary": "Safely stored malformed document-status fields", "value": "---\ntype: Guide\nstatus: [stable]\nstale_after: next quarter\n---\n# Document status example" }, "malformedVerification": { "summary": "Safely stored malformed verification fields", "value": "---\ntype: Guide\nverified:\n - by: 42\n at: today\n---\n# Verification example" }, "malformedSources": { "summary": "Safely stored malformed sources", "value": "---\ntype: Guide\nsources:\n resource: references/source-a.md\n---\n# Sources example" }, "malformedGenerated": { "summary": "Safely stored malformed generation event", "value": "---\ntype: Guide\ngenerated:\n by: publisher:example\n at: today\n---\n# Generation example" }, "completeAttestedComputation": { "summary": "Complete Attested Computation file contract", "value": "---\nokf_version: '0.2'\ntype: Attested Computation\ntitle: Risk score\nruntime: python\nparameters:\n - name: amount\n type: number\n required: true\ncomputation:\n resource: references/risk-score.py\nexecutor:\n resource: executor.md\n receipt: [receipt.md]\nattester:\n resource: attester.md\n---\n# Risk score" }, "incompleteAttestedComputation": { "summary": "Safely stored incomplete Attested Computation metadata", "value": "---\ntype: Attested Computation\nruntime: [python]\nparameters: unknown\nexecutor: 42\nattester: false\n---\n# Incomplete risk score" } }, "schema": { "type": "string", "description": "Complete Markdown content for the selected upload entry." } } } }, "responses": { "200": { "description": "Upload entry after receiving its Markdown content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadEntryResponse" }, "example": { "entry": { "id": "upload-entry-11111111-1111-4111-8111-111111111111", "relativePath": "handbook/onboarding/guide.md", "directoryPath": "handbook/onboarding", "name": "guide.md", "declaredSize": 37, "receivedSize": 37, "disposition": "upload_required", "transferState": "uploaded", "sourceFileId": "source-file-11111111-1111-4111-8111-111111111111", "existingResourceRevision": null } } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "409": { "description": "The request conflicts with the current resource state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The request conflicts with the current resource state.", "httpStatus": 409 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "413": { "description": "The request body exceeds the accepted size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "PAYLOAD_TOO_LARGE", "message": "The request body exceeds the accepted size limit.", "httpStatus": 413 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request failed validation.", "httpStatus": 422 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/knowledge-bases/{knowledgeBaseId}/upload-sessions/{uploadSessionId}": { "get": { "tags": [ "Upload Sessions" ], "operationId": "getUploadSession", "summary": "Get upload progress", "description": "Read upload progress and the next page of entries needed to resume a session.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "uploadSessionId": "upload-11111111-1111-4111-8111-111111111111" }, "query": { "limit": 50 } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "uploadSessionId", "in": "path", "required": true, "description": "Upload session identifier returned by createUploadSession.", "schema": { "type": "string", "example": "upload-session-123" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of records to return. The deployment can enforce a lower limit.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination token returned by the same endpoint for reading the next page.", "schema": { "type": "string" } }, { "name": "transferState", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "missing", "uploaded" ] } } ], "responses": { "200": { "description": "Current upload session and the requested page of file records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSessionStatusResponse" }, "example": { "session": { "id": "upload-11111111-1111-4111-8111-111111111111", "operationId": "upload-operation-11111111-1111-4111-8111-111111111111", "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "state": "completed", "declaredFileCount": 1, "declaredByteCount": 37, "counts": { "selected": 1, "uploadRequired": 1, "skippedExisting": 0, "waitingReservation": 0, "rejectedDeleting": 0, "uploaded": 1, "finalized": 1 }, "errorCode": null, "expiresAt": "2026-06-18T00:00:00.000Z", "completedAt": "2026-06-17T00:00:00.000Z", "createdAt": "2026-06-17T00:00:00.000Z", "updatedAt": "2026-06-17T00:00:00.000Z", "actions": { "operation": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/operations/upload-operation-11111111-1111-4111-8111-111111111111" } }, "entries": { "items": [ { "id": "upload-entry-11111111-1111-4111-8111-111111111111", "relativePath": "handbook/onboarding/guide.md", "directoryPath": "handbook/onboarding", "name": "guide.md", "declaredSize": 37, "receivedSize": 37, "disposition": "upload_required", "transferState": "uploaded", "sourceFileId": "source-file-11111111-1111-4111-8111-111111111111", "existingResourceRevision": null } ], "nextCursor": null } } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request failed validation.", "httpStatus": 422 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } }, "delete": { "tags": [ "Upload Sessions" ], "operationId": "cancelUploadSession", "summary": "Cancel an unfinished upload session", "description": "Cancel an upload session that has not completed.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "uploadSessionId": "upload-11111111-1111-4111-8111-111111111111" } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "uploadSessionId", "in": "path", "required": true, "description": "Upload session identifier returned by createUploadSession.", "schema": { "type": "string", "example": "upload-session-123" } } ], "responses": { "200": { "description": "Upload session after cancellation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSessionResponse" }, "example": { "session": { "id": "upload-11111111-1111-4111-8111-111111111111", "operationId": "upload-operation-11111111-1111-4111-8111-111111111111", "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "state": "cancelled", "declaredFileCount": 1, "declaredByteCount": 37, "counts": { "selected": 1, "uploadRequired": 1, "skippedExisting": 0, "waitingReservation": 0, "rejectedDeleting": 0, "uploaded": 0, "finalized": 0 }, "errorCode": null, "expiresAt": "2026-06-18T00:00:00.000Z", "completedAt": "2026-06-17T00:00:00.000Z", "createdAt": "2026-06-17T00:00:00.000Z", "updatedAt": "2026-06-17T00:00:00.000Z", "actions": { "operation": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/operations/upload-operation-11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "409": { "description": "The request conflicts with the current resource state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The request conflicts with the current resource state.", "httpStatus": 409 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/knowledge-bases/{knowledgeBaseId}/upload-sessions/{uploadSessionId}/reconcile": { "post": { "tags": [ "Upload Sessions" ], "operationId": "reconcileUploadSession", "summary": "Refresh blocked upload entries", "description": "Refresh entries that were temporarily blocked by another change to the same path.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "uploadSessionId": "upload-11111111-1111-4111-8111-111111111111" } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "uploadSessionId", "in": "path", "required": true, "description": "Upload session identifier returned by createUploadSession.", "schema": { "type": "string", "example": "upload-session-123" } } ], "responses": { "200": { "description": "Upload session after rechecking blocked entries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSessionResponse" }, "example": { "session": { "id": "upload-11111111-1111-4111-8111-111111111111", "operationId": "upload-operation-11111111-1111-4111-8111-111111111111", "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "state": "manifest_sealed", "declaredFileCount": 1, "declaredByteCount": 37, "counts": { "selected": 1, "uploadRequired": 1, "skippedExisting": 0, "waitingReservation": 0, "rejectedDeleting": 0, "uploaded": 0, "finalized": 0 }, "errorCode": null, "expiresAt": "2026-06-18T00:00:00.000Z", "completedAt": null, "createdAt": "2026-06-17T00:00:00.000Z", "updatedAt": "2026-06-17T00:00:00.000Z", "actions": { "operation": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/operations/upload-operation-11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "409": { "description": "The request conflicts with the current resource state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The request conflicts with the current resource state.", "httpStatus": 409 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request failed validation.", "httpStatus": 422 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/knowledge-bases/{knowledgeBaseId}/upload-sessions/{uploadSessionId}/finalize": { "post": { "tags": [ "Upload Sessions" ], "operationId": "finalizeUploadSession", "summary": "Complete an upload session", "description": "Submit uploaded files for independent background indexing. An active generation model and an active validated Embedding configuration are required before finalization. The returned `finalizing` session confirms transfer acceptance; poll its operation link until every document becomes available or fails.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "uploadSessionId": "upload-11111111-1111-4111-8111-111111111111" } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "uploadSessionId", "in": "path", "required": true, "description": "Upload session identifier returned by createUploadSession.", "schema": { "type": "string", "example": "upload-session-123" } } ], "responses": { "200": { "description": "Accepted transfer session in `finalizing` state with the operation link used to monitor independent document indexing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSessionResponse" }, "example": { "session": { "id": "upload-11111111-1111-4111-8111-111111111111", "operationId": "upload-operation-11111111-1111-4111-8111-111111111111", "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "state": "finalizing", "declaredFileCount": 1, "declaredByteCount": 37, "counts": { "selected": 1, "uploadRequired": 1, "skippedExisting": 0, "waitingReservation": 0, "rejectedDeleting": 0, "uploaded": 1, "finalized": 1 }, "errorCode": null, "expiresAt": "2026-06-18T00:00:00.000Z", "completedAt": null, "createdAt": "2026-06-17T00:00:00.000Z", "updatedAt": "2026-06-17T00:00:00.000Z", "actions": { "operation": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/operations/upload-operation-11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "409": { "description": "The request conflicts with the current resource state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The request conflicts with the current resource state.", "httpStatus": 409 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request failed validation.", "httpStatus": 422 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/knowledge-bases/{knowledgeBaseId}/source-files": { "get": { "tags": [ "Uploaded Files" ], "operationId": "listKnowledgeBaseSourceFiles", "summary": "List uploaded files", "description": "Read a paginated list of uploaded Markdown files and their processing status.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111" }, "query": { "limit": 50, "directoryId": "directory-handbook" } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of records to return. The deployment can enforce a lower limit.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination token returned by the same endpoint for reading the next page.", "schema": { "type": "string" } }, { "name": "directoryId", "in": "query", "required": false, "description": "Parent uploaded-directory identifier. Use `root` for files at the knowledge-base root.", "schema": { "type": "string", "minLength": 1, "maxLength": 200, "example": "source-directory-handbook" } }, { "name": "pathQuery", "in": "query", "required": false, "description": "Case-insensitive partial match against uploaded file paths.", "schema": { "type": "string", "minLength": 1, "maxLength": 160, "example": "handbook/guide" } }, { "name": "sourceFileIdPrefix", "in": "query", "required": false, "description": "Uploaded-file ID prefix used to filter results.", "schema": { "type": "string", "minLength": 8, "maxLength": 160, "example": "source-file-11111111" } }, { "name": "state", "in": "query", "required": false, "description": "Filter by the uploaded file's current processing status.", "schema": { "type": "string", "enum": [ "waiting", "processing", "available", "error", "deleting" ], "example": "available" } }, { "name": "blockingWorkKind", "in": "query", "required": false, "description": "Filter by the processing step currently preventing the document from becoming available.", "schema": { "type": "string", "enum": [ "prepare", "first_layer", "content_projection", "graphrag", "relation_reconcile", "knowledge_projection", "activate", "cleanup" ], "example": "activate" } }, { "name": "generatedOutputStatus", "in": "query", "required": false, "description": "Filter by generated-content availability.", "schema": { "type": "string", "enum": [ "unavailable", "previous_available", "current_available" ], "example": "current_available" } } ], "responses": { "200": { "description": "Requested page of uploaded Markdown files and the token for reading the next page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceResourceFileListResponse" }, "example": { "items": [ { "sourceFileId": "source-file-11111111-1111-4111-8111-111111111111", "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "directoryId": "directory-11111111-1111-4111-8111-111111111111", "name": "guide.md", "relativePath": "handbook/guide.md", "generatedPath": "pages/handbook/guide.md", "contentType": "text/markdown; charset=utf-8", "sizeBytes": 1024, "resourceRevision": 1, "contentRevision": 1, "state": "available", "workProgress": { "required": 8, "completed": 8, "activeKinds": [], "blockingKind": null, "retryingKind": null }, "failure": null, "generatedOutputStatus": "current_available", "actions": [ { "kind": "open_generated_file", "method": "GET", "href": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/content?path=pages%2Fhandbook%2Fguide.md", "scope": "source_file" } ], "links": { "self": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/source-files/source-file-11111111-1111-4111-8111-111111111111", "generatedContent": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/content?path=pages%2Fhandbook%2Fguide.md", "search": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/search?query=guide.md" }, "createdAt": "2026-06-17T00:00:00.000Z" } ], "nextCursor": null } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request failed validation.", "httpStatus": 422 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/knowledge-bases/{knowledgeBaseId}/source-files/{sourceFileId}": { "get": { "tags": [ "Uploaded Files" ], "operationId": "getKnowledgeBaseSourceFile", "summary": "Get uploaded file", "description": "Read the processing status and available actions for one uploaded Markdown file by `sourceFileId`.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "sourceFileId": "source-file-11111111-1111-4111-8111-111111111111" } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "sourceFileId", "in": "path", "required": true, "description": "Uploaded-file identifier returned by upload or uploaded-file list APIs.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Requested uploaded Markdown file and its current processing status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceResourceFileResponse" }, "example": { "sourceFile": { "sourceFileId": "source-file-11111111-1111-4111-8111-111111111111", "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "directoryId": "directory-11111111-1111-4111-8111-111111111111", "name": "guide.md", "relativePath": "handbook/guide.md", "generatedPath": "pages/handbook/guide.md", "contentType": "text/markdown; charset=utf-8", "sizeBytes": 1024, "resourceRevision": 1, "contentRevision": 1, "state": "available", "workProgress": { "required": 8, "completed": 8, "activeKinds": [], "blockingKind": null, "retryingKind": null }, "failure": null, "generatedOutputStatus": "current_available", "actions": [ { "kind": "open_generated_file", "method": "GET", "href": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/content?path=pages%2Fhandbook%2Fguide.md", "scope": "source_file" } ], "links": { "self": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/source-files/source-file-11111111-1111-4111-8111-111111111111", "generatedContent": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/content?path=pages%2Fhandbook%2Fguide.md", "search": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/search?query=guide.md" }, "createdAt": "2026-06-17T00:00:00.000Z" } } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } }, "patch": { "tags": [ "Uploaded Files" ], "operationId": "moveSourceFile", "summary": "Rename or move an uploaded file", "description": "Rename an uploaded Markdown file or move it to an existing uploaded directory.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "sourceFileId": "source-file-11111111-1111-4111-8111-111111111111" }, "body": { "relativePath": "handbook/setup/install.md" } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "sourceFileId", "in": "path", "required": true, "description": "Uploaded-file identifier returned by upload or uploaded-file list APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-generated key for safely retrying the same request. Reuse the same value for retries so duplicate work is not created.", "schema": { "type": "string", "example": "mutation-2026-07-10-001" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Current `resourceRevision` returned by the API. If the resource changed after it was read, the request returns a conflict instead of overwriting the newer change.", "schema": { "type": "string", "example": "\"1\"" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveSourceFileRequest" }, "example": { "relativePath": "handbook/setup/install.md" } } } }, "responses": { "202": { "description": "File move or rename request accepted for background processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceOperationResponse" }, "example": { "operation": { "operationId": "source-move-11111111-1111-4111-8111-111111111111", "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "kind": "source_file_move", "state": "processing", "expectedResourceRevision": 1, "targetKind": "source_file", "targetId": "source-file-11111111-1111-4111-8111-111111111111", "candidateRelativePath": "handbook/setup/install.md", "result": null, "errorCode": null, "retryGuidance": "Check this change again after a short delay.", "actions": { "self": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/operations/source-move-11111111-1111-4111-8111-111111111111" }, "createdAt": "2026-06-17T00:00:00.000Z", "updatedAt": "2026-06-17T00:00:00.000Z", "completedAt": null } } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "409": { "description": "The request conflicts with the current resource state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The request conflicts with the current resource state.", "httpStatus": 409 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "413": { "description": "The request body exceeds the accepted size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "PAYLOAD_TOO_LARGE", "message": "The request body exceeds the accepted size limit.", "httpStatus": 413 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request failed validation.", "httpStatus": 422 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } }, "delete": { "tags": [ "Uploaded Files" ], "operationId": "deleteSourceFile", "summary": "Delete an uploaded file", "description": "Delete one uploaded Markdown file and remove its readable page from the readable knowledge base.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "sourceFileId": "source-file-11111111-1111-4111-8111-111111111111" } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "sourceFileId", "in": "path", "required": true, "description": "Uploaded-file identifier returned by upload or uploaded-file list APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-generated key for safely retrying the same request. Reuse the same value for retries so duplicate work is not created.", "schema": { "type": "string", "example": "mutation-2026-07-10-001" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Current `resourceRevision` returned by the API. If the resource changed after it was read, the request returns a conflict instead of overwriting the newer change.", "schema": { "type": "string", "example": "\"1\"" } } ], "responses": { "202": { "description": "File deletion accepted for background processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceDeletionResponse" }, "example": { "operation": { "operationId": "deletion-33333333-3333-4333-8333-333333333333", "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "kind": "source_file_delete", "state": "processing", "expectedResourceRevision": 1, "targetKind": "source_file", "targetId": "source-file-11111111-1111-4111-8111-111111111111", "candidateRelativePath": "handbook/guide.md", "result": null, "errorCode": null, "retryGuidance": "Check this change again after a short delay.", "actions": { "self": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/operations/deletion-33333333-3333-4333-8333-333333333333" }, "createdAt": "2026-06-17T00:00:00.000Z", "updatedAt": "2026-06-17T00:00:00.000Z", "completedAt": null }, "deletion": { "sourceFileId": "source-file-11111111-1111-4111-8111-111111111111" } } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "409": { "description": "The request conflicts with the current resource state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The request conflicts with the current resource state.", "httpStatus": 409 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request failed validation.", "httpStatus": 422 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/knowledge-bases/{knowledgeBaseId}/source-files/{sourceFileId}/content": { "get": { "tags": [ "Uploaded Files" ], "operationId": "getSourceFileContent", "summary": "Read uploaded Markdown content", "description": "Read the complete Markdown content currently stored for one uploaded file.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "sourceFileId": "source-file-11111111-1111-4111-8111-111111111111" } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "sourceFileId", "in": "path", "required": true, "description": "Uploaded-file identifier returned by upload or uploaded-file list APIs.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Complete content of the uploaded Markdown file.", "headers": { "ETag": { "description": "Current version number of the uploaded file.", "schema": { "type": "string" } }, "X-Content-Revision": { "description": "Current version number of the Markdown content.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "text/markdown": { "schema": { "type": "string" }, "example": "---\ntype: guide\ntitle: Guide\n---\n# Guide" } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } }, "put": { "tags": [ "Uploaded Files" ], "operationId": "replaceSourceFileContent", "summary": "Replace complete Markdown content and optionally move the uploaded file", "description": "Replace the complete Markdown content of one uploaded file and optionally move it.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "sourceFileId": "source-file-11111111-1111-4111-8111-111111111111" }, "body": "# Installation\n\nCurrent installation guidance." }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "sourceFileId", "in": "path", "required": true, "description": "Uploaded-file identifier returned by upload or uploaded-file list APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-generated key for safely retrying the same request. Reuse the same value for retries so duplicate work is not created.", "schema": { "type": "string", "example": "mutation-2026-07-10-001" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Current `resourceRevision` returned by the API. If the resource changed after it was read, the request returns a conflict instead of overwriting the newer change.", "schema": { "type": "string", "example": "\"1\"" } }, { "name": "X-Source-Relative-Path", "in": "header", "required": false, "description": "Optional new path when replacing and moving the file in one request. The destination directory must already exist.", "schema": { "type": "string", "example": "handbook/setup/install.md" } } ], "requestBody": { "required": true, "content": { "text/markdown": { "schema": { "type": "string", "description": "Complete Markdown content that will replace the current file." }, "examples": { "nativeV02": { "summary": "Native OKF 0.2 metadata", "value": "---\nokf_version: '0.2'\ntype: Guide\ntitle: Verified guide\nsources:\n - id: source-a\n resource: references/source-a.md\ngenerated:\n by: publisher:example\n at: '2026-06-17T00:00:00Z'\nverified:\n - by: human:reviewer\n at: '2026-06-17T01:00:00Z'\nstatus: stable\nstale_after: '2026-12-31'\n---\n# Verified guide" }, "legacyFallback": { "summary": "Legacy generated-time fallback", "value": "---\ntype: Guide\ntimestamp: '2026-06-17T00:00:00Z'\n---\n# Legacy guide" }, "noFrontmatter": { "summary": "Markdown without frontmatter", "value": "# Plain Markdown guide\n\nFrontmatter is optional." }, "missingOptionalSignals": { "summary": "Missing optional OKF signals", "value": "---\ntype: Guide\ntitle: Minimal guide\n---\n# Minimal guide" }, "malformedStatus": { "summary": "Safely stored malformed document-status fields", "value": "---\ntype: Guide\nstatus: [stable]\nstale_after: next quarter\n---\n# Document status example" }, "malformedVerification": { "summary": "Safely stored malformed verification fields", "value": "---\ntype: Guide\nverified:\n - by: 42\n at: today\n---\n# Verification example" }, "malformedSources": { "summary": "Safely stored malformed sources", "value": "---\ntype: Guide\nsources:\n resource: references/source-a.md\n---\n# Sources example" }, "malformedGenerated": { "summary": "Safely stored malformed generation event", "value": "---\ntype: Guide\ngenerated:\n by: publisher:example\n at: today\n---\n# Generation example" }, "completeAttestedComputation": { "summary": "Complete Attested Computation file contract", "value": "---\nokf_version: '0.2'\ntype: Attested Computation\ntitle: Risk score\nruntime: python\nparameters:\n - name: amount\n type: number\n required: true\ncomputation:\n resource: references/risk-score.py\nexecutor:\n resource: executor.md\n receipt: [receipt.md]\nattester:\n resource: attester.md\n---\n# Risk score" }, "incompleteAttestedComputation": { "summary": "Safely stored incomplete Attested Computation metadata", "value": "---\ntype: Attested Computation\nruntime: [python]\nparameters: unknown\nexecutor: 42\nattester: false\n---\n# Incomplete risk score" } } } } }, "responses": { "202": { "description": "File content replacement accepted for background processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceOperationResponse" }, "example": { "operation": { "operationId": "source-replace-44444444-4444-4444-8444-444444444444", "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "kind": "source_file_replace", "state": "processing", "expectedResourceRevision": 1, "targetKind": "source_file", "targetId": "source-file-11111111-1111-4111-8111-111111111111", "candidateRelativePath": "handbook/setup/install.md", "result": null, "errorCode": null, "retryGuidance": "Check this change again after a short delay.", "actions": { "self": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/operations/source-replace-44444444-4444-4444-8444-444444444444" }, "createdAt": "2026-06-17T00:00:00.000Z", "updatedAt": "2026-06-17T00:00:00.000Z", "completedAt": null } } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "409": { "description": "The request conflicts with the current resource state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The request conflicts with the current resource state.", "httpStatus": 409 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "413": { "description": "The request body exceeds the accepted size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "PAYLOAD_TOO_LARGE", "message": "The request body exceeds the accepted size limit.", "httpStatus": 413 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request failed validation.", "httpStatus": 422 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/knowledge-bases/{knowledgeBaseId}/source-directories": { "get": { "tags": [ "Uploaded Directories" ], "operationId": "listSourceDirectories", "summary": "List uploaded directories", "description": "Read the direct child directories under an uploaded directory.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111" }, "query": { "parentDirectoryId": "directory-handbook", "limit": 50 } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "parentDirectoryId", "in": "query", "required": false, "description": "Parent uploaded-directory ID. Omit it or use `root` to list top-level directories.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of records to return. The deployment can enforce a lower limit.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination token returned by the same endpoint for reading the next page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Requested page of direct child directories from the uploaded folder structure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceDirectoryListResponse" }, "example": { "items": [ { "directoryId": "directory-11111111-1111-4111-8111-111111111111", "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "parentDirectoryId": "directory-handbook", "name": "onboarding", "relativePath": "handbook/onboarding", "generatedPath": "pages/handbook/onboarding", "depth": 2, "resourceRevision": 1, "directFileCount": 1, "descendantFileCount": 1, "mutable": true, "deletable": true, "deleting": false, "actions": { "self": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/source-directories/directory-11111111-1111-4111-8111-111111111111", "children": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/source-directories?parentDirectoryId=directory-11111111-1111-4111-8111-111111111111", "sourceFiles": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/source-files?directoryId=directory-11111111-1111-4111-8111-111111111111", "generatedTree": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/tree?parentPath=pages%2Fhandbook%2Fonboarding" }, "createdAt": "2026-06-17T00:00:00.000Z", "updatedAt": "2026-06-17T00:00:00.000Z" } ], "nextCursor": null } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request failed validation.", "httpStatus": 422 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/knowledge-bases/{knowledgeBaseId}/source-directories/{directoryId}": { "get": { "tags": [ "Uploaded Directories" ], "operationId": "getSourceDirectory", "summary": "Get an uploaded directory", "description": "Read one uploaded directory and its file counts.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "directoryId": "directory-11111111-1111-4111-8111-111111111111" } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "directoryId", "in": "path", "required": true, "description": "Uploaded-directory identifier returned by directory or tree APIs.", "schema": { "type": "string", "example": "source-directory-123" } } ], "responses": { "200": { "description": "Requested directory from the uploaded folder structure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceDirectoryResponse" }, "example": { "directory": { "directoryId": "directory-11111111-1111-4111-8111-111111111111", "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "parentDirectoryId": "directory-handbook", "name": "onboarding", "relativePath": "handbook/onboarding", "generatedPath": "pages/handbook/onboarding", "depth": 2, "resourceRevision": 1, "directFileCount": 1, "descendantFileCount": 1, "mutable": true, "deletable": true, "deleting": false, "actions": { "self": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/source-directories/directory-11111111-1111-4111-8111-111111111111", "children": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/source-directories?parentDirectoryId=directory-11111111-1111-4111-8111-111111111111", "sourceFiles": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/source-files?directoryId=directory-11111111-1111-4111-8111-111111111111", "generatedTree": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/tree?parentPath=pages%2Fhandbook%2Fonboarding" }, "createdAt": "2026-06-17T00:00:00.000Z", "updatedAt": "2026-06-17T00:00:00.000Z" } } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } }, "patch": { "tags": [ "Uploaded Directories" ], "operationId": "moveSourceDirectory", "summary": "Rename or move an uploaded directory", "description": "Rename or move one uploaded directory with all files and subdirectories below it.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "directoryId": "directory-11111111-1111-4111-8111-111111111111" }, "body": { "relativePath": "handbook/archive" } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "directoryId", "in": "path", "required": true, "description": "Uploaded-directory identifier returned by directory or tree APIs.", "schema": { "type": "string", "example": "source-directory-123" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-generated key for safely retrying the same request. Reuse the same value for retries so duplicate work is not created.", "schema": { "type": "string", "example": "mutation-2026-07-10-001" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Current `resourceRevision` returned by the API. If the resource changed after it was read, the request returns a conflict instead of overwriting the newer change.", "schema": { "type": "string", "example": "\"1\"" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveSourceDirectoryRequest" }, "example": { "relativePath": "handbook/archive" } } } }, "responses": { "202": { "description": "Directory move or rename request accepted for background processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceOperationResponse" }, "example": { "operation": { "operationId": "directory-move-22222222-2222-4222-8222-222222222222", "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "kind": "source_directory_move", "state": "processing", "expectedResourceRevision": 1, "targetKind": "source_directory", "targetId": "directory-11111111-1111-4111-8111-111111111111", "candidateRelativePath": "handbook/archive", "result": null, "errorCode": null, "retryGuidance": "Check this change again after a short delay.", "actions": { "self": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/operations/directory-move-22222222-2222-4222-8222-222222222222" }, "createdAt": "2026-06-17T00:00:00.000Z", "updatedAt": "2026-06-17T00:00:00.000Z", "completedAt": null } } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "409": { "description": "The request conflicts with the current resource state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The request conflicts with the current resource state.", "httpStatus": 409 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "413": { "description": "The request body exceeds the accepted size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "PAYLOAD_TOO_LARGE", "message": "The request body exceeds the accepted size limit.", "httpStatus": 413 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request failed validation.", "httpStatus": 422 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } }, "delete": { "tags": [ "Uploaded Directories" ], "operationId": "deleteSourceDirectory", "summary": "Delete an uploaded directory and its contents", "description": "Delete one uploaded directory and all files and subdirectories below it.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "directoryId": "directory-11111111-1111-4111-8111-111111111111" } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "directoryId", "in": "path", "required": true, "description": "Uploaded-directory identifier returned by directory or tree APIs.", "schema": { "type": "string", "example": "source-directory-123" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-generated key for safely retrying the same request. Reuse the same value for retries so duplicate work is not created.", "schema": { "type": "string", "example": "mutation-2026-07-10-001" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Current `resourceRevision` returned by the API. If the resource changed after it was read, the request returns a conflict instead of overwriting the newer change.", "schema": { "type": "string", "example": "\"1\"" } } ], "responses": { "202": { "description": "Directory deletion accepted for background processing, with the number of affected files and directories.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceDeletionResponse" }, "example": { "operation": { "operationId": "deletion-55555555-5555-4555-8555-555555555555", "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "kind": "source_directory_delete", "state": "processing", "expectedResourceRevision": 1, "targetKind": "source_directory", "targetId": "directory-11111111-1111-4111-8111-111111111111", "candidateRelativePath": "handbook/onboarding", "result": null, "errorCode": null, "retryGuidance": "Check this change again after a short delay.", "actions": { "self": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/operations/deletion-55555555-5555-4555-8555-555555555555" }, "createdAt": "2026-06-17T00:00:00.000Z", "updatedAt": "2026-06-17T00:00:00.000Z", "completedAt": null }, "deletion": { "directoryId": "directory-11111111-1111-4111-8111-111111111111", "affectedDirectoryCount": 1, "affectedFileCount": 1, "visibility": "pending_processing" } } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "409": { "description": "The request conflicts with the current resource state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The request conflicts with the current resource state.", "httpStatus": 409 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request failed validation.", "httpStatus": 422 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/knowledge-bases/{knowledgeBaseId}/operations": { "get": { "tags": [ "File and Directory Changes" ], "operationId": "listResourceOperations", "summary": "List file and directory changes", "description": "List upload indexing and file or directory changes for a knowledge base. Results can be filtered by processing status.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111" }, "query": { "limit": 50 } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "processing", "completed", "failed", "cancelled", "superseded" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of records to return. The deployment can enforce a lower limit.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination token returned by the same endpoint for reading the next page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Requested page of upload indexing and resource changes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceOperationListResponse" }, "example": { "items": [ { "operationId": "source-move-11111111-1111-4111-8111-111111111111", "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "kind": "source_file_move", "state": "processing", "expectedResourceRevision": 1, "targetKind": "source_file", "targetId": "source-file-11111111-1111-4111-8111-111111111111", "candidateRelativePath": "handbook/setup/install.md", "result": null, "errorCode": null, "retryGuidance": "Check this change again after a short delay.", "actions": { "self": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/operations/source-move-11111111-1111-4111-8111-111111111111" }, "createdAt": "2026-06-17T00:00:00.000Z", "updatedAt": "2026-06-17T00:00:00.000Z", "completedAt": null } ], "nextCursor": null } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request failed validation.", "httpStatus": 422 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/knowledge-bases/{knowledgeBaseId}/operations/{operationId}": { "get": { "tags": [ "File and Directory Changes" ], "operationId": "getResourceOperation", "summary": "Get a file or directory change", "description": "Use the `operationId` returned by an upload or resource change to read its processing state, progressive document counts, final result, and error details.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "operationId": "source-move-11111111-1111-4111-8111-111111111111" } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "operationId", "in": "path", "required": true, "description": "Change identifier returned by file and directory move, replace, or delete requests.", "schema": { "type": "string", "example": "source-move-123" } } ], "responses": { "200": { "description": "Requested upload indexing or resource change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceOperationResponse" }, "example": { "operation": { "operationId": "source-move-11111111-1111-4111-8111-111111111111", "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "kind": "source_file_move", "state": "processing", "expectedResourceRevision": 1, "targetKind": "source_file", "targetId": "source-file-11111111-1111-4111-8111-111111111111", "candidateRelativePath": "handbook/setup/install.md", "result": null, "errorCode": null, "retryGuidance": "Check this change again after a short delay.", "actions": { "self": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/operations/source-move-11111111-1111-4111-8111-111111111111" }, "createdAt": "2026-06-17T00:00:00.000Z", "updatedAt": "2026-06-17T00:00:00.000Z", "completedAt": null } } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/knowledge-bases/{knowledgeBaseId}/source-files/{sourceFileId}/retry": { "post": { "tags": [ "Uploaded Files" ], "operationId": "retryKnowledgeBaseSourceFile", "summary": "Retry an uploaded file", "description": "Manually retry one uploaded Markdown file that failed processing.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "sourceFileId": "source-file-11111111-1111-4111-8111-111111111111" } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "sourceFileId", "in": "path", "required": true, "description": "Uploaded-file identifier returned by upload or uploaded-file list APIs.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "202": { "description": "Uploaded file and accepted retry details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceFileRetryResponse" }, "example": { "sourceFile": { "sourceFileId": "source-file-11111111-1111-4111-8111-111111111111", "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "directoryId": "directory-11111111-1111-4111-8111-111111111111", "name": "guide.md", "relativePath": "handbook/guide.md", "generatedPath": "pages/handbook/guide.md", "contentType": "text/markdown; charset=utf-8", "sizeBytes": 1024, "resourceRevision": 1, "contentRevision": 1, "state": "waiting", "workProgress": { "required": 8, "completed": 0, "activeKinds": [], "blockingKind": "prepare", "retryingKind": null }, "failure": null, "generatedOutputStatus": "unavailable", "actions": [], "links": { "self": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/source-files/source-file-11111111-1111-4111-8111-111111111111", "generatedContent": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/content?path=pages%2Fhandbook%2Fguide.md", "search": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/search?query=guide.md" }, "createdAt": "2026-06-17T00:00:00.000Z" }, "retry": { "kind": "document_processing", "scope": "source_file", "coalesced": false } } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "409": { "description": "The request conflicts with the current resource state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The request conflicts with the current resource state.", "httpStatus": 409 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/knowledge-bases/{knowledgeBaseId}/tree": { "get": { "tags": [ "Files" ], "operationId": "listKnowledgeBaseTree", "summary": "List readable file tree entries", "description": "Browse the currently readable knowledge-base files and directories.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111" }, "query": { "parentPath": "pages", "entryType": "file", "limit": 50 } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "parentPath", "in": "query", "required": false, "description": "Directory path to browse, or `root` for the bundle root. Parent traversal, file paths, and storage paths are rejected.", "schema": { "type": "string", "default": "root" } }, { "name": "entryType", "in": "query", "required": false, "description": "Optional tree node type filter.", "schema": { "type": "string", "enum": [ "file", "directory" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of records to return. The deployment can enforce a lower limit.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination token returned by the same endpoint for reading the next page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Requested page of direct readable files and directories under the selected parent path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreeResponse" }, "example": { "activeContentRevision": 1, "items": [ { "activeContentRevision": 1, "id": "tree-file-11111111111111111111111111111111", "fileId": "source-file-11111111-1111-4111-8111-111111111111", "sourceFileId": "source-file-11111111-1111-4111-8111-111111111111", "directoryId": null, "parentPath": "pages", "name": "guide.md", "path": "pages/guide.md", "sortKey": "1:guide.md", "entryType": "file", "fileKind": "page", "directEntryCount": 0, "directDirectoryCount": 0, "directFileCount": 0, "descendantFileCount": 0, "resourceRevision": 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" } } ], "nextCursor": null } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request failed validation.", "httpStatus": 422 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/knowledge-bases/{knowledgeBaseId}/files/content": { "get": { "tags": [ "Files" ], "operationId": "getFileContentByPath", "summary": "Read a readable file by path", "description": "Read a readable knowledge-base file by its `path`, such as `index.md` or `pages/example.md`.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111" }, "query": { "path": "pages/guide.md" } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "path", "in": "query", "required": true, "description": "Readable knowledge-base file path returned by tree, search, or file APIs. Parent traversal, backslashes, and storage paths are rejected.", "schema": { "type": "string", "pattern": "\\.(?:md|json)$", "example": "index.md" } } ], "responses": { "200": { "description": "Complete content of the readable file at the requested path. A file under `pages/` that comes from uploaded Markdown preserves the current uploaded text; generated resources return their generated content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileContentResponse" }, "example": { "file": { "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" } }, "content": "---\ntype: page\ntitle: Guide\n---\n# Guide\n\nContent." } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "413": { "description": "The readable file exceeds the configured content read limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "PAYLOAD_TOO_LARGE", "message": "The readable file exceeds the configured content read limit.", "httpStatus": 413 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request failed validation.", "httpStatus": 422 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/knowledge-bases/{knowledgeBaseId}/files/search": { "get": { "tags": [ "Files" ], "operationId": "searchGeneratedFiles", "summary": "Search knowledge-base files", "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.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111" }, "query": { "query": "How do I configure and verify the knowledge base deployment?", "scope": "all", "fileKind": "page", "mode": "hybrid", "graphDepth": 1, "graphFanout": 10, "limit": 10 } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "query", "in": "query", "required": true, "description": "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.", "schema": { "type": "string", "minLength": 2, "maxLength": 512 } }, { "name": "scope", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "all", "path", "metadata" ], "default": "all" } }, { "name": "fileKind", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "all", "page" ], "default": "page" } }, { "name": "mode", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "file", "graph", "hybrid" ], "default": "hybrid" } }, { "name": "graphDepth", "in": "query", "required": false, "description": "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.", "schema": { "type": "integer", "enum": [ 0, 1, 2 ] } }, { "name": "graphFanout", "in": "query", "required": false, "description": "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.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "okfStatus", "in": "query", "required": false, "description": "Return only files whose normalized OKF document status matches this value. Files with an invalid status are excluded.", "schema": { "type": "string", "enum": [ "draft", "stable", "deprecated" ] } }, { "name": "okfTrustTier", "in": "query", "required": false, "description": "Return only files whose normalized OKF verification tier matches this value. Files with invalid verification metadata are excluded.", "schema": { "type": "string", "enum": [ "unverified", "machine-confirmed", "human-reviewed" ] } }, { "name": "okfFreshness", "in": "query", "required": false, "description": "Return only files whose valid `stale_after` date is fresh or stale on the request date. Files without a valid stale date are excluded.", "schema": { "type": "string", "enum": [ "fresh", "stale" ] } }, { "name": "rerank", "in": "query", "required": false, "description": "Optionally rerank the authorized fused source-file candidates with the active Admin-configured reranker. The default keeps deterministic fused ranking.", "schema": { "type": "boolean", "default": false } }, { "name": "rerankTopK", "in": "query", "required": false, "description": "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`.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "rerankScoreThreshold", "in": "query", "required": false, "description": "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.", "schema": { "type": "number", "minimum": 0, "maximum": 1, "default": 0, "example": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Final source-file result count for this search request.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination token returned by the same search query, filters, readable knowledge-base version, and effective ranking settings.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Readable files ranked by relevance to the supplied query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileSearchResponse" }, "example": { "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." } } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request failed validation.", "httpStatus": 422 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The required data or search service is temporarily unavailable or overloaded. Retry after the service recovers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SEARCH_UNAVAILABLE", "message": "The required data or search service is temporarily unavailable or overloaded. Retry after the service recovers.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } }, "x-error-codes": [ "DATABASE_REPOSITORY_UNAVAILABLE", "SEARCH_UNAVAILABLE", "SEARCH_OVERLOADED" ] }, "504": { "description": "Search exceeded the configured response deadline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SEARCH_TIMEOUT", "message": "Search exceeded the configured response deadline.", "httpStatus": 504 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } }, "x-validation-detail-codes": [ "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" ] } }, "/openapi/v2/knowledge-bases/{knowledgeBaseId}/graph/expand": { "get": { "tags": [ "Files" ], "operationId": "expandGraph", "summary": "Explore related files", "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.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111" }, "query": { "fileId": "source-file-11111111-1111-4111-8111-111111111111", "depth": 1, "fanout": 10, "limit": 10 } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "fileId", "in": "query", "required": true, "description": "Readable file ID returned by tree, search, file, or related-file operations.", "schema": { "type": "string", "minLength": 1 } }, { "name": "depth", "in": "query", "required": false, "description": "Number of relationship levels to explore.", "schema": { "type": "integer", "enum": [ 0, 1, 2 ] } }, { "name": "fanout", "in": "query", "required": false, "description": "Maximum related files returned for each explored file. When omitted, the deployment setting is used.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of records to return. The deployment can enforce a lower limit.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination token returned by the same endpoint for reading the next page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Related files and relationship details for the selected starting point.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphExpansionResponse" }, "example": { "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." } } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request failed validation.", "httpStatus": 422 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } }, "x-validation-detail-codes": [ "GRAPH_EXPANSION_FILE_ID_REQUIRED", "INVALID_GRAPH_EXPANSION_DEPTH", "INVALID_GRAPH_EXPANSION_FANOUT" ] } }, "/openapi/v2/knowledge-bases/{knowledgeBaseId}/graph/overview": { "get": { "tags": [ "Files" ], "operationId": "getGraphOverview", "summary": "Get file relationship overview", "description": "Read a compact overview of available file relationships.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111" } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Relationship counts and links for exploring the currently readable knowledge-base version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphOverviewResponse" }, "example": { "activeContentRevision": 1, "availability": "available", "summary": { "readableFileCount": 24, "relationshipCount": 18 }, "resources": { "graphIndexPath": "_graph/index.md", "byDirectoryPath": "_graph/by-directory", "byFilePath": "_graph/by-file" }, "readActions": { "graphIndexContent": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/content?path=_graph%2Findex.md", "listGraphRoot": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/tree?parentPath=_graph", "listRelationshipsByDirectory": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/tree?parentPath=_graph%2Fby-directory", "listRelationshipsByFile": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/tree?parentPath=_graph%2Fby-file" } } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/knowledge-bases/{knowledgeBaseId}/files/{fileId}": { "get": { "tags": [ "Files" ], "operationId": "getFileById", "summary": "Get readable file metadata", "description": "Read the metadata and available read links for one readable file by `fileId`.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "fileId": "source-file-11111111-1111-4111-8111-111111111111" } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "fileId", "in": "path", "required": true, "description": "Readable file identifier returned by tree, search, related-file, or file APIs.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Requested readable file metadata and links for reading or exploring it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileDetailResponse" }, "example": { "file": { "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" } } } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/knowledge-bases/{knowledgeBaseId}/files/{fileId}/content": { "get": { "tags": [ "Files" ], "operationId": "getFileContentById", "summary": "Read a readable file by ID", "description": "Read a readable knowledge-base file by `fileId`.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "fileId": "source-file-11111111-1111-4111-8111-111111111111" } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "fileId", "in": "path", "required": true, "description": "Readable file identifier returned by tree, search, related-file, or file APIs.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Complete content of the readable file with the requested identifier. A file under `pages/` that comes from uploaded Markdown preserves the current uploaded text; generated resources return their generated content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileContentResponse" }, "example": { "file": { "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" } }, "content": "---\ntype: page\ntitle: Guide\n---\n# Guide\n\nContent." } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "413": { "description": "The readable file exceeds the configured content read limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "PAYLOAD_TOO_LARGE", "message": "The readable file exceeds the configured content read limit.", "httpStatus": 413 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/knowledge-bases/{knowledgeBaseId}/files/{fileId}/related": { "get": { "tags": [ "Files" ], "operationId": "listRelatedFiles", "summary": "List related files", "description": "Read a paginated list of files related to the selected file, with paths for opening their content.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "fileId": "source-file-11111111-1111-4111-8111-111111111111" }, "query": { "limit": 50 } }, "parameters": [ { "name": "knowledgeBaseId", "in": "path", "required": true, "description": "Knowledge-base identifier returned by knowledge-base APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "fileId", "in": "path", "required": true, "description": "Readable file identifier returned by tree, search, related-file, or file APIs.", "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of records to return. The deployment can enforce a lower limit.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination token returned by the same endpoint for reading the next page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Requested page of files related to the selected readable file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelatedFileListResponse" }, "example": { "activeContentRevision": 1, "fileId": "source-file-11111111-1111-4111-8111-111111111111", "sourceFileId": "source-file-11111111-1111-4111-8111-111111111111", "items": [ { "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" } } ], "nextCursor": null } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "409": { "description": "The request conflicts with the current resource state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The request conflicts with the current resource state.", "httpStatus": 409 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request failed validation.", "httpStatus": 422 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/webhooks": { "post": { "tags": [ "Webhooks" ], "operationId": "createWebhook", "summary": "Create a webhook subscription", "description": "Create a webhook subscription and receive the signing secret once.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "body": { "name": "Source file updates", "url": "https://hooks.example.com/focowiki", "events": [ "document.available", "document.error", "document.deleting" ] } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-generated key for safely retrying the same request. Reuse the same value for retries so duplicate work is not created.", "schema": { "type": "string", "example": "mutation-2026-07-10-001" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreateRequest" }, "example": { "name": "Source file updates", "url": "https://hooks.example.com/focowiki", "events": [ "document.available", "document.error", "document.deleting" ] } } } }, "responses": { "201": { "description": "New webhook subscription and its signing secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreateResponse" }, "example": { "webhook": { "webhookId": "webhook-11111111-1111-4111-8111-111111111111", "name": "Source file updates", "endpointHost": "hooks.example.com", "events": [ "document.available", "document.error", "document.deleting" ], "createdAt": "2026-06-17T00:00:00.000Z", "lastDeliveryAt": null }, "signingSecret": "" } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "413": { "description": "The request body exceeds the accepted size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "PAYLOAD_TOO_LARGE", "message": "The request body exceeds the accepted size limit.", "httpStatus": 413 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request failed validation.", "httpStatus": 422 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } }, "get": { "tags": [ "Webhooks" ], "operationId": "listWebhooks", "summary": "List webhook subscriptions", "description": "Read a paginated list of webhook subscriptions.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "query": { "limit": 50 } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of records to return. The deployment can enforce a lower limit.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination token returned by the same endpoint for reading the next page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Requested page of webhook subscriptions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookListResponse" }, "example": { "items": [ { "webhookId": "webhook-11111111-1111-4111-8111-111111111111", "name": "Source file updates", "endpointHost": "hooks.example.com", "events": [ "document.available", "document.error", "document.deleting" ], "createdAt": "2026-06-17T00:00:00.000Z", "lastDeliveryAt": null } ], "nextCursor": null } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request failed validation.", "httpStatus": 422 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/webhooks/{webhookId}": { "delete": { "tags": [ "Webhooks" ], "operationId": "deleteWebhook", "summary": "Delete a webhook subscription", "description": "Delete one webhook subscription by `webhookId`.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "webhookId": "webhook-11111111-1111-4111-8111-111111111111" } }, "parameters": [ { "name": "webhookId", "in": "path", "required": true, "description": "Webhook identifier returned by webhook APIs.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Confirmation that the webhook subscription was deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResponse" }, "example": { "deleted": true, "webhookId": "webhook-11111111-1111-4111-8111-111111111111" } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/webhook-deliveries": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhookDeliveries", "summary": "List webhook deliveries", "description": "Read a paginated list of webhook delivery records.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "query": { "webhookId": "webhook-11111111-1111-4111-8111-111111111111", "limit": 50 } }, "parameters": [ { "name": "webhookId", "in": "query", "required": false, "description": "Webhook identifier returned by create or list operations.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of records to return. The deployment can enforce a lower limit.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination token returned by the same endpoint for reading the next page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Requested page of webhook delivery attempts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryListResponse" }, "example": { "items": [ { "deliveryId": "delivery-11111111-1111-4111-8111-111111111111", "webhookId": "webhook-11111111-1111-4111-8111-111111111111", "eventId": "event-11111111-1111-4111-8111-111111111111", "eventType": "document.available", "payload": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "operationId": "document-operation-11111111-1111-4111-8111-111111111111", "sourceFileId": "source-file-11111111-1111-4111-8111-111111111111", "state": "available", "errorCode": null, "occurredAt": "2026-06-17T00:00:00.000Z" }, "status": "success", "attemptCount": 1, "httpStatus": 200, "errorCode": null, "createdAt": "2026-06-17T00:00:00.000Z", "updatedAt": "2026-06-17T00:00:00.000Z" } ], "nextCursor": null } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request failed validation.", "httpStatus": 422 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } }, "/openapi/v2/webhook-deliveries/{deliveryId}/redeliver": { "post": { "tags": [ "Webhooks" ], "operationId": "redeliverWebhook", "summary": "Redeliver a webhook delivery", "description": "Request redelivery for one webhook delivery record by `deliveryId`.", "security": [ { "bearerAuth": [] } ], "x-request-example": { "path": { "deliveryId": "delivery-11111111-1111-4111-8111-111111111111" } }, "parameters": [ { "name": "deliveryId", "in": "path", "required": true, "description": "Webhook delivery identifier returned by delivery listing APIs.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "202": { "description": "New delivery attempt created from the selected webhook delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRedeliveryResponse" }, "example": { "delivery": { "deliveryId": "delivery-22222222-2222-4222-8222-222222222222", "webhookId": "webhook-11111111-1111-4111-8111-111111111111", "eventId": "event-11111111-1111-4111-8111-111111111111", "eventType": "document.available", "payload": { "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111", "operationId": "document-operation-11111111-1111-4111-8111-111111111111", "sourceFileId": "source-file-11111111-1111-4111-8111-111111111111", "state": "available", "errorCode": null, "occurredAt": "2026-06-17T00:00:00.000Z" }, "status": "pending", "attemptCount": 0, "httpStatus": null, "errorCode": null, "createdAt": "2026-06-17T00:00:00.000Z", "updatedAt": "2026-06-17T00:00:00.000Z" } } } } }, "401": { "description": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Bearer API key is missing, malformed, unknown, revoked, or deleted.", "httpStatus": 401 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "httpStatus": 404 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "409": { "description": "The request conflicts with the current resource state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The request conflicts with the current resource state.", "httpStatus": 409 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "429": { "description": "The request exceeded configured rate limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait briefly and retry.", "httpStatus": 429, "details": { "retryHint": "retry_after_short_delay", "retryAfterSeconds": 60, "retryGuidance": "Wait briefly before sending the next Developer OpenAPI request." } }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "500": { "description": "The API encountered an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The API encountered an internal error.", "httpStatus": 500 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } }, "503": { "description": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DATABASE_REPOSITORY_UNAVAILABLE", "message": "The data required by this operation is temporarily unavailable. Retry later and keep the request ID if support assistance is needed.", "httpStatus": 503 }, "requestId": "req-11111111-1111-4111-8111-111111111111" } } } } } } } } }