mtfyun/dify
1
0 Fork 0
mirror of https://github.com/langgenius/dify.git synced 2026-11-11 22:02:23 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
feat/dify-builder
dify/api/knowledge-fs-contract/knowledge-fs.openapi.json
T
Stephen ZhouJyonghjlarryClaude Opus 5.5autofix-ci[bot]zhaohao1004yyhFFXN
 fd2db63184 feat: KnowledgeFS and New Knowledge (#44165) 
Co-authored-by: Jyong <76649700+JohnJyong@users.noreply.github.com>
Co-authored-by: hjlarry <hjlarry@163.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: zhaohao1004 <zhaohao1004@gmail.com>
Co-authored-by: yyh <yuanyouhuilyz@gmail.com>
Co-authored-by: FFXN <lizy@dify.ai>
2026-10-23 03:34:59 +00:00

52707 lines
1.6 MiB
Plaintext
Raw Permalink Blame History

{
"openapi": "3.1.0",
"info": {
"title": "Knowledge Platform API",
"version": "0.1.0"
},
"security": [
{
"bearerAuth": []
}
],
"components": {
"securitySchemes": {
"bearerAuth": {
"bearerFormat": "JWT or API token",
"scheme": "bearer",
"type": "http"
}
},
"schemas": {
"KnowledgeFsPublicFailure": {
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"configure_model",
"configure_parser",
"configure_source",
"contact_admin",
"reupload",
"retry"
]
},
"category": {
"type": "string",
"enum": [
"authorization",
"canceled",
"configuration",
"conflict",
"dependency",
"internal",
"not_found",
"rate_limit",
"timeout",
"validation"
]
},
"code": {
"type": "string",
"enum": [
"VECTOR_SPACE_QUOTA_EXCEEDED",
"VECTOR_SPACE_QUOTA_UNAVAILABLE",
"DOCUMENT_COUNT_QUOTA_EXCEEDED",
"DOCUMENT_COUNT_QUOTA_UNAVAILABLE",
"LOGICAL_DOCUMENT_CAS_CONFLICT",
"DURABLE_DELETION_IDEMPOTENCY_CONFLICT",
"SOURCE_VERSION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_COMPILATION_IN_PROGRESS",
"KNOWLEDGE_SPACE_SETTINGS_REVISION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_MIGRATION_REQUIRED",
"DOCUMENT_COMPILATION_PROFILE_CHANGED",
"DOCUMENT_COMPILATION_FAILED",
"DOCUMENT_COMPILATION_RETRYABLE",
"DOCUMENT_COMPILATION_LEASE_LOST",
"DOCUMENT_DISABLED",
"DOCUMENT_PARSER_INPUT_INVALID",
"DOCUMENT_PARSER_NOT_CONFIGURED",
"DOCUMENT_PARSER_RATE_LIMITED",
"DOCUMENT_PARSER_RESPONSE_INVALID",
"DOCUMENT_PARSER_TIMEOUT",
"DOCUMENT_PARSER_UNAVAILABLE",
"DOCUMENT_PARSER_UNSUPPORTED_TYPE",
"DOCUMENT_PDF_RENDER_FAILED",
"EMBEDDING_DIMENSION_INVALID",
"EMBEDDING_DIMENSION_UNSUPPORTED",
"EXECUTION_ATTEMPTS_EXHAUSTED",
"KNOWLEDGE_FS_ACCESS_DENIED",
"KNOWLEDGE_FS_CONFLICT",
"KNOWLEDGE_FS_INTERNAL_ERROR",
"KNOWLEDGE_FS_INVALID_REQUEST",
"KNOWLEDGE_FS_NOT_FOUND",
"KNOWLEDGE_FS_RATE_LIMITED",
"KNOWLEDGE_FS_TIMEOUT",
"KNOWLEDGE_FS_UNAVAILABLE",
"KNOWLEDGE_SPACE_MANIFEST_NOT_FOUND",
"KNOWLEDGE_SPACE_MODEL_CONFIGURATION_REQUIRED",
"MODEL_CAPABILITY_MISMATCH",
"MODEL_CONFIGURATION_STALE",
"MODEL_CREDENTIAL_INVALID",
"MODEL_CREDENTIAL_VALIDATION_UNAVAILABLE",
"MODEL_IDENTITY_MISMATCH",
"MODEL_PREFLIGHT_CANCELED",
"MODEL_PREFLIGHT_FAILED",
"MODEL_PREFLIGHT_TIMEOUT",
"MODEL_PREFLIGHT_UNAVAILABLE",
"MODEL_PROFILE_ACTIVATION_INCOMPLETE",
"MODEL_PROFILE_ACTIVATION_PERMISSION_REQUIRED",
"MODEL_RUNTIME_FAILED",
"MODEL_RUNTIME_RESPONSE_INVALID",
"MODEL_RUNTIME_OUTPUT_LIMIT",
"MODEL_RUNTIME_CONTEXT_LIMIT",
"MODEL_RUNTIME_TIMEOUT",
"MODEL_RUNTIME_UNAVAILABLE",
"MODEL_SELECTION_NOT_FOUND",
"RESEARCH_TASK_CAPABILITY_REVOKED",
"RESEARCH_TASK_DISPATCH_DEAD",
"RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED",
"RESEARCH_TASK_FAILED",
"RESEARCH_TASK_PERMISSION_SNAPSHOT_INVALID",
"RESEARCH_TASK_RUNTIME_SNAPSHOT_INVALID",
"RETRIEVAL_DELETION_IN_PROGRESS",
"RETRIEVAL_EXECUTION_LEASE_LOST",
"SOURCE_BULK_ACTION_FAILED",
"SOURCE_CONNECTION_UNAVAILABLE",
"SOURCE_CRAWL_PAGE_NOT_FOUND",
"SOURCE_CRAWL_PROVIDER_UNAVAILABLE",
"SOURCE_CRAWL_RESULT_LIMIT_EXCEEDED",
"SOURCE_CREDENTIAL_CONFIG_INVALID",
"SOURCE_CREDENTIAL_MUTATION_FAILED",
"SOURCE_CREDENTIAL_TEST_FAILED",
"SOURCE_CREDENTIAL_UNAVAILABLE",
"SOURCE_DOCUMENT_COMPILATION_FAILED",
"SOURCE_DOCUMENT_MATERIALIZATION_FAILED",
"SOURCE_DOCUMENT_REPLACEMENT_SAGA_REQUIRED",
"SOURCE_IMPORT_PARTIAL_FAILURE",
"SOURCE_ONLINE_DOCUMENT_CONFIG_INVALID",
"SOURCE_ONLINE_DOCUMENT_IMPORT_FAILED",
"SOURCE_ONLINE_DOCUMENT_PAGE_FETCH_FAILED",
"SOURCE_ONLINE_DOCUMENT_REQUEST_FAILED",
"SOURCE_ONLINE_DOCUMENT_UNAVAILABLE",
"SOURCE_ONLINE_DRIVE_CONFIG_INVALID",
"SOURCE_ONLINE_DRIVE_FILE_DOWNLOAD_FAILED",
"SOURCE_ONLINE_DRIVE_IMPORT_FAILED",
"SOURCE_ONLINE_DRIVE_REQUEST_FAILED",
"SOURCE_ONLINE_DRIVE_UNAVAILABLE",
"SOURCE_OPERATION_FAILED",
"SOURCE_PROVIDER_REJECTED",
"SOURCE_PROVIDER_TIMEOUT",
"SOURCE_PROVIDER_UNAVAILABLE",
"SOURCE_SYNC_SELECTION_MISMATCH",
"SOURCE_SECRET_INTEGRITY_FAILED",
"SOURCE_SECRET_REF_CONFLICT",
"SOURCE_SYNC_FAILED",
"SOURCE_WEBSITE_CRAWL_CONFIG_INVALID",
"SOURCE_WEBSITE_CRAWL_FAILED",
"SOURCE_WORKFLOW_FAILED",
"SOURCE_WORKFLOW_CONTENT_MISSING",
"SOURCE_WORKFLOW_CONTENT_TOO_LARGE",
"SOURCE_WORKFLOW_EXTERNAL_TIMEOUT",
"UPLOAD_INITIALIZATION_FAILED",
"UPLOAD_INTEGRITY_MISMATCH"
]
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"parameters": {
"type": "object",
"properties": {
"attempt": {
"anyOf": [
{
"type": "string",
"maxLength": 256
},
{
"type": "number"
},
{
"type": "boolean"
}
]
},
"currentRowVersion": {
"anyOf": [
{
"type": "string",
"maxLength": 256
},
{
"type": "number"
},
{
"type": "boolean"
}
]
},
"expectedRowVersion": {
"anyOf": [
{
"type": "string",
"maxLength": 256
},
{
"type": "number"
},
{
"type": "boolean"
}
]
},
"documentCount": {
"anyOf": [
{
"type": "string",
"maxLength": 256
},
{
"type": "number"
},
{
"type": "boolean"
}
]
},
"fileSizeBytes": {
"anyOf": [
{
"type": "string",
"maxLength": 256
},
{
"type": "number"
},
{
"type": "boolean"
}
]
},
"limit": {
"anyOf": [
{
"type": "string",
"maxLength": 256
},
{
"type": "number"
},
{
"type": "boolean"
}
]
},
"maxFileSizeBytes": {
"anyOf": [
{
"type": "string",
"maxLength": 256
},
{
"type": "number"
},
{
"type": "boolean"
}
]
},
"maxItems": {
"anyOf": [
{
"type": "string",
"maxLength": 256
},
{
"type": "number"
},
{
"type": "boolean"
}
]
},
"modelType": {
"anyOf": [
{
"type": "string",
"maxLength": 256
},
{
"type": "number"
},
{
"type": "boolean"
}
]
},
"providerKind": {
"anyOf": [
{
"type": "string",
"maxLength": 256
},
{
"type": "number"
},
{
"type": "boolean"
}
]
},
"retryAfterSeconds": {
"anyOf": [
{
"type": "string",
"maxLength": 256
},
{
"type": "number"
},
{
"type": "boolean"
}
]
},
"status": {
"anyOf": [
{
"type": "string",
"maxLength": 256
},
{
"type": "number"
},
{
"type": "boolean"
}
]
}
}
},
"retryPolicy": {
"type": "string",
"enum": [
"automatic",
"manual",
"after_configuration",
"never"
]
},
"stage": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[a-z][a-z0-9_.-]{0,127}$"
},
"traceId": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]{1,128}$"
}
},
"required": [
"category",
"code",
"message",
"retryPolicy"
],
"additionalProperties": false
},
"ErrorResponse": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"error": {
"type": "string"
},
"failure": {
"$ref": "#/components/schemas/KnowledgeFsPublicFailure"
},
"violations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"pattern": "^[a-z_]{1,64}$"
},
"path": {
"type": "array",
"items": {
"type": "string",
"maxLength": 128
},
"maxItems": 8
}
},
"required": [
"code",
"path"
],
"additionalProperties": false
},
"maxItems": 20
}
},
"required": [
"error"
]
},
"KnowledgeSpaceCreationResponse": {
"type": "object",
"properties": {
"createdAt": {
"type": "string",
"format": "date-time"
},
"description": {
"type": "string",
"maxLength": 2000
},
"iconRef": {
"type": "string",
"maxLength": 72,
"pattern": "^(?:builtin:)?[+a-z0-9_-]{1,64}$"
},
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 160
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
},
"slug": {
"type": "string",
"maxLength": 160,
"pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
},
"tenantId": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"configurationStatus": {
"type": "string",
"enum": [
"pending-validation",
"ready",
"setup-required",
"validation-failed"
]
}
},
"required": [
"createdAt",
"id",
"name",
"revision",
"slug",
"tenantId",
"updatedAt",
"configurationStatus"
]
},
"KnowledgeSpace": {
"type": "object",
"properties": {
"createdAt": {
"type": "string",
"format": "date-time"
},
"description": {
"type": "string",
"maxLength": 2000
},
"iconRef": {
"type": "string",
"maxLength": 72,
"pattern": "^(?:builtin:)?[+a-z0-9_-]{1,64}$"
},
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 160
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
},
"slug": {
"type": "string",
"maxLength": 160,
"pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
},
"tenantId": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"createdAt",
"id",
"name",
"revision",
"slug",
"tenantId",
"updatedAt"
]
},
"KnowledgeSpaceList": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/KnowledgeSpace"
}
},
"nextCursor": {
"type": "string"
}
},
"required": [
"items"
]
},
"KnowledgeSpaceManifest": {
"type": "object",
"properties": {
"consistencyPolicy": {
"type": "object",
"properties": {
"cacheTtlSeconds": {
"type": "integer",
"exclusiveMinimum": 0
},
"defaultClass": {
"type": "string",
"enum": [
"path-consistent",
"snapshot-consistent",
"cache-consistent",
"eventual-preview"
]
},
"snapshotTtlSeconds": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"defaultClass",
"snapshotTtlSeconds"
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"embeddingProfile": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"dimension": {
"type": "integer",
"exclusiveMinimum": 0
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
},
"vectorSpaceId": {
"type": "string",
"pattern": "^embedding-space-sha256:[a-f0-9]{64}$"
}
},
"required": [
"model",
"pluginId",
"provider",
"revision",
"vectorSpaceId"
],
"additionalProperties": false
},
"embeddingProfileFrozenAt": {
"type": "string",
"format": "date-time"
},
"encryptionPolicy": {
"type": "object",
"properties": {
"keyRef": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"strategy": {
"type": "string",
"enum": [
"provider-managed",
"customer-managed",
"none"
]
}
},
"required": [
"strategy"
]
},
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"knowledgeSpaceId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"manifestVersion": {
"type": "integer",
"exclusiveMinimum": 0
},
"metadata": {
"type": "object",
"additionalProperties": {},
"default": {}
},
"metadataDialect": {
"type": "string",
"enum": [
"portable",
"postgres",
"tidb"
]
},
"minClientVersion": {
"type": "string",
"pattern": "^\\d+\\.\\d+\\.\\d+(?:[-+][0-9A-Za-z.-]+)?$"
},
"nodeSchemaVersion": {
"type": "integer",
"exclusiveMinimum": 0
},
"objectKeyPrefix": {
"type": "string",
"minLength": 1,
"maxLength": 512,
"pattern": "^[A-Za-z0-9._=-]+(?:\\/[A-Za-z0-9._=-]+)*$"
},
"parserPolicyVersion": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"pendingModelConfiguration": {
"type": "object",
"properties": {
"digest": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"embeddingSelection": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
},
"failure": {
"type": "object",
"properties": {
"code": {
"type": "string",
"pattern": "^[A-Za-z0-9._:-]{1,64}$"
},
"failedAt": {
"type": "string",
"format": "date-time"
},
"field": {
"type": "string",
"enum": [
"embedding",
"reasoning",
"rerank"
]
},
"retryable": {
"type": "boolean"
}
},
"required": [
"code",
"failedAt",
"retryable"
],
"additionalProperties": false
},
"retrievalProfile": {
"type": "object",
"properties": {
"defaultMode": {
"type": "string",
"enum": [
"fast",
"research",
"deep"
]
},
"reasoningModel": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
},
"rerank": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"model": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
}
},
"required": [
"enabled"
],
"additionalProperties": false
},
"scoreThreshold": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"stage": {
"type": "string",
"enum": [
"mode-final",
"rerank"
]
},
"value": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"enabled",
"stage"
],
"additionalProperties": false
},
"topK": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"required": [
"defaultMode",
"reasoningModel",
"rerank",
"scoreThreshold",
"topK"
],
"additionalProperties": false
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
},
"state": {
"type": "string",
"enum": [
"pending-validation",
"validation-failed"
]
}
},
"required": [
"digest",
"revision",
"state"
],
"additionalProperties": false
},
"projectionSetVersion": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"quotaPolicy": {
"type": "object",
"properties": {
"maxActiveJobCount": {
"type": [
"integer",
"null"
],
"exclusiveMinimum": 0,
"default": null
},
"maxActiveSessionCount": {
"type": [
"integer",
"null"
],
"exclusiveMinimum": 0,
"default": null
},
"maxArtifactBytes": {
"type": [
"integer",
"null"
],
"exclusiveMinimum": 0,
"default": null
},
"maxGraphEntityCount": {
"type": [
"integer",
"null"
],
"exclusiveMinimum": 0,
"default": null
},
"maxGraphRelationCount": {
"type": [
"integer",
"null"
],
"exclusiveMinimum": 0,
"default": null
},
"maxNodeCount": {
"type": [
"integer",
"null"
],
"exclusiveMinimum": 0,
"default": null
},
"maxProjectionCount": {
"type": [
"integer",
"null"
],
"exclusiveMinimum": 0,
"default": null
},
"maxRawDocumentBytes": {
"type": [
"integer",
"null"
],
"exclusiveMinimum": 0,
"default": null
},
"maxSegmentCount": {
"type": [
"integer",
"null"
],
"exclusiveMinimum": 0,
"default": null
},
"maxTraceBytes": {
"type": [
"integer",
"null"
],
"exclusiveMinimum": 0,
"default": null
},
"providerBudgets": {
"type": "object",
"properties": {
"maxEmbeddingTokensPerDay": {
"type": [
"integer",
"null"
],
"exclusiveMinimum": 0,
"default": null
},
"maxLlmTokensPerDay": {
"type": [
"integer",
"null"
],
"exclusiveMinimum": 0,
"default": null
},
"maxParserPagesPerDay": {
"type": [
"integer",
"null"
],
"exclusiveMinimum": 0,
"default": null
},
"maxRerankRequestsPerDay": {
"type": [
"integer",
"null"
],
"exclusiveMinimum": 0,
"default": null
}
},
"default": {}
}
}
},
"retentionPolicy": {
"type": "object",
"properties": {
"artifactVersionsToKeep": {
"type": "integer",
"exclusiveMinimum": 0
},
"failedCommitRetentionDays": {
"type": "integer",
"exclusiveMinimum": 0
},
"traceRetentionDays": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"artifactVersionsToKeep",
"failedCommitRetentionDays",
"traceRetentionDays"
]
},
"retrievalProfile": {
"type": "object",
"properties": {
"defaultMode": {
"type": "string",
"enum": [
"fast",
"research",
"deep"
]
},
"reasoningModel": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
},
"rerank": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"model": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
}
},
"required": [
"enabled"
],
"additionalProperties": false
},
"scoreThreshold": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"stage": {
"type": "string",
"enum": [
"mode-final",
"rerank"
]
},
"value": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"enabled",
"stage"
],
"additionalProperties": false
},
"topK": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"defaultMode",
"reasoningModel",
"rerank",
"scoreThreshold",
"topK",
"revision"
],
"additionalProperties": false
},
"storageProvider": {
"type": "string",
"enum": [
"dify",
"memory-dev",
"r2",
"s3-compatible"
]
},
"tenantId": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"consistencyPolicy",
"createdAt",
"encryptionPolicy",
"id",
"knowledgeSpaceId",
"manifestVersion",
"metadataDialect",
"minClientVersion",
"nodeSchemaVersion",
"objectKeyPrefix",
"parserPolicyVersion",
"projectionSetVersion",
"quotaPolicy",
"retentionPolicy",
"storageProvider",
"tenantId",
"updatedAt"
]
},
"KnowledgeSpaceProductSettings": {
"type": "object",
"properties": {
"activeProfileAvailable": {
"type": "boolean"
},
"activeProfileRevisions": {
"type": "object",
"properties": {
"embedding": {
"type": "integer",
"exclusiveMinimum": 0
},
"retrieval": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"capabilities": {
"type": "object",
"properties": {
"deep": {
"type": "boolean"
},
"index": {
"type": "boolean"
},
"ingest": {
"type": "boolean"
},
"query": {
"type": "boolean"
},
"research": {
"type": "boolean"
},
"sourceSync": {
"type": "boolean"
}
},
"required": [
"deep",
"index",
"ingest",
"query",
"research",
"sourceSync"
],
"additionalProperties": false
},
"configurationState": {
"type": "string",
"enum": [
"active",
"pending-validation",
"setup-required",
"validation-failed"
]
},
"embedding": {
"anyOf": [
{
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"dimension": {
"type": "integer",
"exclusiveMinimum": 0
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
},
"vectorSpaceId": {
"type": "string",
"pattern": "^embedding-space-sha256:[a-f0-9]{64}$"
}
},
"required": [
"model",
"pluginId",
"provider",
"revision",
"vectorSpaceId"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"retrieval": {
"anyOf": [
{
"type": "object",
"properties": {
"defaultMode": {
"type": "string",
"enum": [
"fast",
"research",
"deep"
]
},
"reasoningModel": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
},
"rerank": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"model": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
}
},
"required": [
"enabled"
],
"additionalProperties": false
},
"scoreThreshold": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"stage": {
"type": "string",
"enum": [
"mode-final",
"rerank"
]
},
"value": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"enabled",
"stage"
],
"additionalProperties": false
},
"topK": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"required": [
"defaultMode",
"reasoningModel",
"rerank",
"scoreThreshold",
"topK"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"defaultMode": {
"type": "string",
"enum": [
"fast",
"research",
"deep"
]
},
"reasoningModel": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
},
"rerank": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"model": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
}
},
"required": [
"enabled"
],
"additionalProperties": false
},
"scoreThreshold": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"stage": {
"type": "string",
"enum": [
"mode-final",
"rerank"
]
},
"value": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"enabled",
"stage"
],
"additionalProperties": false
},
"topK": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"defaultMode",
"reasoningModel",
"rerank",
"scoreThreshold",
"topK",
"revision"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"binding_missing",
"incompatible",
"missing",
"unavailable",
"validation_failed"
]
},
"field": {
"type": "string",
"enum": [
"embedding",
"publication",
"reasoning",
"rerank"
]
},
"retryable": {
"type": "boolean"
}
},
"required": [
"code",
"field",
"retryable"
],
"additionalProperties": false
}
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"activeProfileAvailable",
"activeProfileRevisions",
"capabilities",
"configurationState",
"embedding",
"retrieval",
"issues",
"revision"
],
"additionalProperties": false
},
"UpdateKnowledgeSpaceProductSettings": {
"type": "object",
"properties": {
"embedding": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
},
"expectedRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"retrieval": {
"type": "object",
"properties": {
"defaultMode": {
"type": "string",
"enum": [
"fast",
"research",
"deep"
]
},
"reasoningModel": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
},
"rerank": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"model": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
}
},
"required": [
"enabled"
],
"additionalProperties": false
},
"scoreThreshold": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"stage": {
"type": "string",
"enum": [
"mode-final",
"rerank"
]
},
"value": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"enabled",
"stage"
],
"additionalProperties": false
},
"topK": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"required": [
"defaultMode",
"reasoningModel",
"rerank",
"scoreThreshold",
"topK"
],
"additionalProperties": false
}
},
"required": [
"expectedRevision"
],
"additionalProperties": false
},
"KnowledgeSpaceEmbeddingProfile": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"dimension": {
"type": "integer",
"exclusiveMinimum": 0
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
},
"vectorSpaceId": {
"type": "string",
"pattern": "^embedding-space-sha256:[a-f0-9]{64}$"
}
},
"required": [
"model",
"pluginId",
"provider",
"revision",
"vectorSpaceId"
],
"additionalProperties": false
},
"KnowledgeSpacePendingModelConfiguration": {
"type": "object",
"properties": {
"configurationStatus": {
"type": "string",
"enum": [
"pending-validation",
"setup-required"
]
},
"digest": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"operation": {
"type": "string",
"enum": [
"initial-validation-pending"
]
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"configurationStatus",
"digest",
"operation",
"revision"
],
"additionalProperties": false
},
"KnowledgeSpaceProfileMigration": {
"type": "object",
"properties": {
"candidatePublicationFingerprint": {
"type": "string",
"minLength": 1,
"maxLength": 86
},
"changedKind": {
"type": "string",
"enum": [
"embedding",
"retrieval"
]
},
"checkpoint": {
"type": "string",
"enum": [
"queued",
"candidate-built",
"evaluated",
"activated"
]
},
"completedAt": {
"type": "string",
"format": "date-time"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"errorCode": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"evaluationSummary": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
}
]
}
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"rebuildScope": {
"type": "string",
"enum": [
"clone-publication",
"full-page-index-summary-outline",
"full-vector-space"
]
},
"runState": {
"type": "string",
"enum": [
"queued",
"running",
"succeeded",
"failed",
"canceled"
]
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"changedKind",
"checkpoint",
"createdAt",
"id",
"knowledgeSpaceId",
"rebuildScope",
"runState",
"updatedAt"
],
"additionalProperties": false
},
"KnowledgeSpaceRetrievalProfile": {
"type": "object",
"properties": {
"defaultMode": {
"type": "string",
"enum": [
"fast",
"research",
"deep"
]
},
"reasoningModel": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
},
"rerank": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"model": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
}
},
"required": [
"enabled"
],
"additionalProperties": false
},
"scoreThreshold": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"stage": {
"type": "string",
"enum": [
"mode-final",
"rerank"
]
},
"value": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"enabled",
"stage"
],
"additionalProperties": false
},
"topK": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"defaultMode",
"reasoningModel",
"rerank",
"scoreThreshold",
"topK",
"revision"
],
"additionalProperties": false
},
"KnowledgeSpaceStatus": {
"type": "object",
"properties": {
"activeLeases": {
"type": "object",
"properties": {
"count": {
"type": "integer",
"minimum": 0
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"expiresAt": {
"type": "string",
"format": "date-time"
},
"id": {
"type": "string",
"format": "uuid"
},
"leaseType": {
"type": "string",
"enum": [
"read",
"publish",
"delete",
"reindex"
]
},
"targetType": {
"type": "string",
"enum": [
"knowledge-space",
"document-asset",
"parse-artifact",
"knowledge-path",
"projection",
"staged-commit"
]
},
"virtualPath": {
"type": "string"
}
},
"required": [
"expiresAt",
"id",
"leaseType",
"targetType",
"virtualPath"
]
}
},
"truncated": {
"type": "boolean"
}
},
"required": [
"count",
"items",
"truncated"
]
},
"activeSessions": {
"type": "object",
"properties": {
"count": {
"type": "integer",
"minimum": 0
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"clientKind": {
"type": "string",
"enum": [
"api",
"mcp",
"worker",
"admin"
]
},
"consistencyClass": {
"type": "string",
"enum": [
"path-consistent",
"snapshot-consistent",
"cache-consistent",
"eventual-preview"
]
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"heartbeatAt": {
"type": "string",
"format": "date-time"
},
"id": {
"type": "string",
"format": "uuid"
},
"subjectId": {
"type": "string"
}
},
"required": [
"clientKind",
"consistencyClass",
"expiresAt",
"heartbeatAt",
"id",
"subjectId"
]
}
},
"truncated": {
"type": "boolean"
}
},
"required": [
"count",
"items",
"truncated"
]
},
"configuration": {
"type": "object",
"properties": {
"activeProfiles": {
"type": "object",
"properties": {
"embeddingRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"retrievalRevision": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"availableModes": {
"type": "array",
"items": {
"type": "string",
"enum": [
"fast",
"research",
"deep"
]
}
},
"pendingModelConfiguration": {
"oneOf": [
{
"type": "object",
"properties": {
"digest": {
"type": "string",
"pattern": "^(?:sha256:)?[a-f0-9]{64}$"
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
},
"state": {
"type": "string",
"enum": [
"pending-validation"
]
}
},
"required": [
"digest",
"revision",
"state"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"digest": {
"type": "string",
"pattern": "^(?:sha256:)?[a-f0-9]{64}$"
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
},
"failure": {
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"failedAt": {
"type": "string",
"format": "date-time"
},
"retryable": {
"type": "boolean"
}
},
"required": [
"code",
"failedAt",
"retryable"
],
"additionalProperties": false
},
"state": {
"type": "string",
"enum": [
"validation-failed"
]
}
},
"required": [
"digest",
"revision",
"failure",
"state"
],
"additionalProperties": false
}
]
},
"status": {
"type": "string",
"enum": [
"setup-required",
"pending-validation",
"validation-failed",
"ready"
]
}
},
"required": [
"activeProfiles",
"availableModes",
"status"
],
"additionalProperties": false
},
"failedCommits": {
"type": "object",
"properties": {
"count": {
"type": "integer",
"minimum": 0
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"errorCode": {
"type": "string",
"enum": [
"VECTOR_SPACE_QUOTA_EXCEEDED",
"VECTOR_SPACE_QUOTA_UNAVAILABLE",
"DOCUMENT_COUNT_QUOTA_EXCEEDED",
"DOCUMENT_COUNT_QUOTA_UNAVAILABLE",
"LOGICAL_DOCUMENT_CAS_CONFLICT",
"DURABLE_DELETION_IDEMPOTENCY_CONFLICT",
"SOURCE_VERSION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_COMPILATION_IN_PROGRESS",
"KNOWLEDGE_SPACE_SETTINGS_REVISION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_MIGRATION_REQUIRED",
"DOCUMENT_COMPILATION_PROFILE_CHANGED",
"DOCUMENT_COMPILATION_FAILED",
"DOCUMENT_COMPILATION_RETRYABLE",
"DOCUMENT_COMPILATION_LEASE_LOST",
"DOCUMENT_DISABLED",
"DOCUMENT_PARSER_INPUT_INVALID",
"DOCUMENT_PARSER_NOT_CONFIGURED",
"DOCUMENT_PARSER_RATE_LIMITED",
"DOCUMENT_PARSER_RESPONSE_INVALID",
"DOCUMENT_PARSER_TIMEOUT",
"DOCUMENT_PARSER_UNAVAILABLE",
"DOCUMENT_PARSER_UNSUPPORTED_TYPE",
"DOCUMENT_PDF_RENDER_FAILED",
"EMBEDDING_DIMENSION_INVALID",
"EMBEDDING_DIMENSION_UNSUPPORTED",
"EXECUTION_ATTEMPTS_EXHAUSTED",
"KNOWLEDGE_FS_ACCESS_DENIED",
"KNOWLEDGE_FS_CONFLICT",
"KNOWLEDGE_FS_INTERNAL_ERROR",
"KNOWLEDGE_FS_INVALID_REQUEST",
"KNOWLEDGE_FS_NOT_FOUND",
"KNOWLEDGE_FS_RATE_LIMITED",
"KNOWLEDGE_FS_TIMEOUT",
"KNOWLEDGE_FS_UNAVAILABLE",
"KNOWLEDGE_SPACE_MANIFEST_NOT_FOUND",
"KNOWLEDGE_SPACE_MODEL_CONFIGURATION_REQUIRED",
"MODEL_CAPABILITY_MISMATCH",
"MODEL_CONFIGURATION_STALE",
"MODEL_CREDENTIAL_INVALID",
"MODEL_CREDENTIAL_VALIDATION_UNAVAILABLE",
"MODEL_IDENTITY_MISMATCH",
"MODEL_PREFLIGHT_CANCELED",
"MODEL_PREFLIGHT_FAILED",
"MODEL_PREFLIGHT_TIMEOUT",
"MODEL_PREFLIGHT_UNAVAILABLE",
"MODEL_PROFILE_ACTIVATION_INCOMPLETE",
"MODEL_PROFILE_ACTIVATION_PERMISSION_REQUIRED",
"MODEL_RUNTIME_FAILED",
"MODEL_RUNTIME_RESPONSE_INVALID",
"MODEL_RUNTIME_OUTPUT_LIMIT",
"MODEL_RUNTIME_CONTEXT_LIMIT",
"MODEL_RUNTIME_TIMEOUT",
"MODEL_RUNTIME_UNAVAILABLE",
"MODEL_SELECTION_NOT_FOUND",
"RESEARCH_TASK_CAPABILITY_REVOKED",
"RESEARCH_TASK_DISPATCH_DEAD",
"RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED",
"RESEARCH_TASK_FAILED",
"RESEARCH_TASK_PERMISSION_SNAPSHOT_INVALID",
"RESEARCH_TASK_RUNTIME_SNAPSHOT_INVALID",
"RETRIEVAL_DELETION_IN_PROGRESS",
"RETRIEVAL_EXECUTION_LEASE_LOST",
"SOURCE_BULK_ACTION_FAILED",
"SOURCE_CONNECTION_UNAVAILABLE",
"SOURCE_CRAWL_PAGE_NOT_FOUND",
"SOURCE_CRAWL_PROVIDER_UNAVAILABLE",
"SOURCE_CRAWL_RESULT_LIMIT_EXCEEDED",
"SOURCE_CREDENTIAL_CONFIG_INVALID",
"SOURCE_CREDENTIAL_MUTATION_FAILED",
"SOURCE_CREDENTIAL_TEST_FAILED",
"SOURCE_CREDENTIAL_UNAVAILABLE",
"SOURCE_DOCUMENT_COMPILATION_FAILED",
"SOURCE_DOCUMENT_MATERIALIZATION_FAILED",
"SOURCE_DOCUMENT_REPLACEMENT_SAGA_REQUIRED",
"SOURCE_IMPORT_PARTIAL_FAILURE",
"SOURCE_ONLINE_DOCUMENT_CONFIG_INVALID",
"SOURCE_ONLINE_DOCUMENT_IMPORT_FAILED",
"SOURCE_ONLINE_DOCUMENT_PAGE_FETCH_FAILED",
"SOURCE_ONLINE_DOCUMENT_REQUEST_FAILED",
"SOURCE_ONLINE_DOCUMENT_UNAVAILABLE",
"SOURCE_ONLINE_DRIVE_CONFIG_INVALID",
"SOURCE_ONLINE_DRIVE_FILE_DOWNLOAD_FAILED",
"SOURCE_ONLINE_DRIVE_IMPORT_FAILED",
"SOURCE_ONLINE_DRIVE_REQUEST_FAILED",
"SOURCE_ONLINE_DRIVE_UNAVAILABLE",
"SOURCE_OPERATION_FAILED",
"SOURCE_PROVIDER_REJECTED",
"SOURCE_PROVIDER_TIMEOUT",
"SOURCE_PROVIDER_UNAVAILABLE",
"SOURCE_SYNC_SELECTION_MISMATCH",
"SOURCE_SECRET_INTEGRITY_FAILED",
"SOURCE_SECRET_REF_CONFLICT",
"SOURCE_SYNC_FAILED",
"SOURCE_WEBSITE_CRAWL_CONFIG_INVALID",
"SOURCE_WEBSITE_CRAWL_FAILED",
"SOURCE_WORKFLOW_FAILED",
"SOURCE_WORKFLOW_CONTENT_MISSING",
"SOURCE_WORKFLOW_CONTENT_TOO_LARGE",
"SOURCE_WORKFLOW_EXTERNAL_TIMEOUT",
"UPLOAD_INITIALIZATION_FAILED",
"UPLOAD_INTEGRITY_MISMATCH"
]
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"failure": {
"$ref": "#/components/schemas/KnowledgeFsPublicFailure"
},
"id": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string",
"enum": [
"failed-retryable",
"failed-terminal"
]
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"status",
"updatedAt"
]
}
},
"truncated": {
"type": "boolean"
}
},
"required": [
"count",
"items",
"truncated"
]
},
"generatedAt": {
"type": "string",
"format": "date-time"
},
"index": {
"type": "object",
"properties": {
"nodeSchemaVersion": {
"type": "integer",
"exclusiveMinimum": 0
},
"projectionSetVersion": {
"type": "string"
},
"projectionVersion": {
"type": "integer",
"exclusiveMinimum": 0
},
"summaries": {
"type": "object",
"properties": {
"denseVector": {
"type": "object",
"properties": {
"building": {
"type": "integer",
"minimum": 0
},
"failed": {
"type": "integer",
"minimum": 0
},
"ready": {
"type": "integer",
"minimum": 0
},
"stale": {
"type": "integer",
"minimum": 0
},
"total": {
"type": "integer",
"minimum": 0
}
},
"required": [
"building",
"failed",
"ready",
"stale",
"total"
]
},
"fts": {
"type": "object",
"properties": {
"building": {
"type": "integer",
"minimum": 0
},
"failed": {
"type": "integer",
"minimum": 0
},
"ready": {
"type": "integer",
"minimum": 0
},
"stale": {
"type": "integer",
"minimum": 0
},
"total": {
"type": "integer",
"minimum": 0
}
},
"required": [
"building",
"failed",
"ready",
"stale",
"total"
]
},
"graph": {
"type": "object",
"properties": {
"building": {
"type": "integer",
"minimum": 0
},
"failed": {
"type": "integer",
"minimum": 0
},
"ready": {
"type": "integer",
"minimum": 0
},
"stale": {
"type": "integer",
"minimum": 0
},
"total": {
"type": "integer",
"minimum": 0
}
},
"required": [
"building",
"failed",
"ready",
"stale",
"total"
]
},
"metadata": {
"type": "object",
"properties": {
"building": {
"type": "integer",
"minimum": 0
},
"failed": {
"type": "integer",
"minimum": 0
},
"ready": {
"type": "integer",
"minimum": 0
},
"stale": {
"type": "integer",
"minimum": 0
},
"total": {
"type": "integer",
"minimum": 0
}
},
"required": [
"building",
"failed",
"ready",
"stale",
"total"
]
}
},
"required": [
"denseVector",
"fts",
"graph",
"metadata"
]
}
},
"required": [
"nodeSchemaVersion",
"projectionSetVersion",
"projectionVersion",
"summaries"
]
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"manifest": {
"type": "object",
"properties": {
"consistencyClass": {
"type": "string",
"enum": [
"path-consistent",
"snapshot-consistent",
"cache-consistent",
"eventual-preview"
]
},
"manifestVersion": {
"type": "integer",
"exclusiveMinimum": 0
},
"metadataDialect": {
"type": "string",
"enum": [
"portable",
"postgres",
"tidb"
]
},
"objectKeyPrefix": {
"type": "string"
},
"storageProvider": {
"type": "string",
"enum": [
"dify",
"memory-dev",
"r2",
"s3-compatible"
]
}
},
"required": [
"consistencyClass",
"manifestVersion",
"metadataDialect",
"objectKeyPrefix",
"storageProvider"
]
},
"parser": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"native-html",
"native-markdown",
"native-structured",
"unstructured"
]
},
"policyVersion": {
"type": "string"
}
},
"required": [
"kind",
"policyVersion"
]
},
"storage": {
"type": "object",
"properties": {
"healthy": {
"type": "boolean"
},
"objectStorageKind": {
"type": "string",
"enum": [
"dify",
"local",
"memory"
]
},
"provider": {
"type": "string",
"enum": [
"dify",
"memory-dev",
"r2",
"s3-compatible"
]
}
},
"required": [
"healthy",
"objectStorageKind",
"provider"
]
},
"tenantId": {
"type": "string"
}
},
"required": [
"activeLeases",
"activeSessions",
"configuration",
"failedCommits",
"generatedAt",
"index",
"knowledgeSpaceId",
"manifest",
"parser",
"storage",
"tenantId"
]
},
"KnowledgeSpaceStats": {
"type": "object",
"properties": {
"cache": {
"type": "object",
"properties": {
"available": {
"type": "boolean"
},
"entries": {
"type": "integer",
"minimum": 0
},
"totalBytes": {
"type": "integer",
"minimum": 0
}
},
"required": [
"available",
"entries",
"totalBytes"
]
},
"commits": {
"type": "object",
"properties": {
"failedRetryable": {
"type": "integer",
"minimum": 0
},
"failedTerminal": {
"type": "integer",
"minimum": 0
},
"sampled": {
"type": "integer",
"minimum": 0
},
"truncated": {
"type": "boolean"
}
},
"required": [
"failedRetryable",
"failedTerminal",
"sampled",
"truncated"
]
},
"generatedAt": {
"type": "string",
"format": "date-time"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"metrics": {
"type": "object",
"properties": {
"available": {
"type": "boolean"
},
"reason": {
"type": "string"
}
},
"required": [
"available"
]
},
"projections": {
"type": "object",
"properties": {
"denseVector": {
"type": "object",
"properties": {
"building": {
"type": "integer",
"minimum": 0
},
"failed": {
"type": "integer",
"minimum": 0
},
"ready": {
"type": "integer",
"minimum": 0
},
"stale": {
"type": "integer",
"minimum": 0
},
"total": {
"type": "integer",
"minimum": 0
}
},
"required": [
"building",
"failed",
"ready",
"stale",
"total"
]
},
"fts": {
"type": "object",
"properties": {
"building": {
"type": "integer",
"minimum": 0
},
"failed": {
"type": "integer",
"minimum": 0
},
"ready": {
"type": "integer",
"minimum": 0
},
"stale": {
"type": "integer",
"minimum": 0
},
"total": {
"type": "integer",
"minimum": 0
}
},
"required": [
"building",
"failed",
"ready",
"stale",
"total"
]
},
"graph": {
"type": "object",
"properties": {
"building": {
"type": "integer",
"minimum": 0
},
"failed": {
"type": "integer",
"minimum": 0
},
"ready": {
"type": "integer",
"minimum": 0
},
"stale": {
"type": "integer",
"minimum": 0
},
"total": {
"type": "integer",
"minimum": 0
}
},
"required": [
"building",
"failed",
"ready",
"stale",
"total"
]
},
"metadata": {
"type": "object",
"properties": {
"building": {
"type": "integer",
"minimum": 0
},
"failed": {
"type": "integer",
"minimum": 0
},
"ready": {
"type": "integer",
"minimum": 0
},
"stale": {
"type": "integer",
"minimum": 0
},
"total": {
"type": "integer",
"minimum": 0
}
},
"required": [
"building",
"failed",
"ready",
"stale",
"total"
]
},
"projectionVersion": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"denseVector",
"fts",
"graph",
"metadata",
"projectionVersion"
]
},
"runtime": {
"type": "object",
"properties": {
"activeLeaseSampleCount": {
"type": "integer",
"minimum": 0
},
"activeSessionSampleCount": {
"type": "integer",
"minimum": 0
},
"truncated": {
"type": "boolean"
}
},
"required": [
"activeLeaseSampleCount",
"activeSessionSampleCount",
"truncated"
]
},
"storage": {
"type": "object",
"properties": {
"documentCount": {
"type": "integer",
"minimum": 0
},
"rawDocumentBytes": {
"type": "integer",
"minimum": 0
}
},
"required": [
"documentCount",
"rawDocumentBytes"
]
},
"tenantId": {
"type": "string"
},
"window": {
"type": "object",
"properties": {
"end": {
"type": "string",
"format": "date-time"
},
"minutes": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 1440
},
"start": {
"type": "string",
"format": "date-time"
}
},
"required": [
"end",
"minutes",
"start"
]
}
},
"required": [
"cache",
"commits",
"generatedAt",
"knowledgeSpaceId",
"metrics",
"projections",
"runtime",
"storage",
"tenantId",
"window"
]
},
"KnowledgeFsckReport": {
"type": "object",
"properties": {
"cursor": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"repairability": {
"type": "string",
"enum": [
"auto-repairable",
"manual",
"not-repairable"
]
},
"severity": {
"type": "string",
"enum": [
"info",
"warning",
"error",
"critical"
]
},
"target": {
"type": "object",
"properties": {
"documentAssetId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"objectKey": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"parseArtifactId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"type": {
"type": "string",
"enum": [
"raw-object",
"artifact-object",
"artifact-segment",
"knowledge-path",
"knowledge-node",
"index-projection",
"staged-commit"
]
},
"virtualPath": {
"type": "string",
"maxLength": 384,
"pattern": "^\\/(?:sources|knowledge|evidence|workspaces)(?:\\/[^/\\s]+)*$"
}
},
"required": [
"type"
]
},
"type": {
"type": "string",
"enum": [
"missing-raw-object",
"checksum-mismatch",
"size-mismatch",
"missing-artifact-object",
"segment-hash-mismatch",
"broken-path-target",
"missing-node-target",
"stale-projection",
"orphaned-staged-object",
"failed-commit-expired"
]
}
},
"required": [
"code",
"message",
"repairability",
"severity",
"target",
"type"
]
},
"maxItems": 1000
},
"knowledgeSpaceId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"scannedAt": {
"type": "string",
"format": "date-time"
},
"summary": {
"type": "object",
"properties": {
"critical": {
"type": "integer",
"minimum": 0
},
"error": {
"type": "integer",
"minimum": 0
},
"info": {
"type": "integer",
"minimum": 0
},
"repairable": {
"type": "integer",
"minimum": 0
},
"scanned": {
"type": "integer",
"minimum": 0
},
"warning": {
"type": "integer",
"minimum": 0
}
},
"required": [
"critical",
"error",
"info",
"repairable",
"scanned",
"warning"
]
},
"tenantId": {
"type": "string",
"minLength": 1,
"maxLength": 255
}
},
"required": [
"issues",
"knowledgeSpaceId",
"scannedAt",
"summary",
"tenantId"
]
},
"KnowledgeFsGcDryRunReport": {
"type": "object",
"properties": {
"candidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"candidateType": {
"type": "string",
"enum": [
"staged-object",
"failed-commit",
"artifact-segment",
"parse-artifact",
"index-projection",
"answer-trace"
]
},
"count": {
"type": "integer",
"exclusiveMinimum": 0
},
"estimatedBytes": {
"type": "integer",
"minimum": 0
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"target": {
"type": "object",
"properties": {
"documentAssetId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"objectKey": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"parseArtifactId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"type": {
"type": "string",
"enum": [
"raw-object",
"artifact-object",
"artifact-segment",
"knowledge-path",
"knowledge-node",
"index-projection",
"staged-commit"
]
},
"virtualPath": {
"type": "string",
"maxLength": 384,
"pattern": "^\\/(?:sources|knowledge|evidence|workspaces)(?:\\/[^/\\s]+)*$"
}
},
"required": [
"type"
]
}
},
"required": [
"candidateType",
"count",
"estimatedBytes",
"idempotencyKey",
"reason",
"target"
]
},
"maxItems": 1000
},
"cursor": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"dryRunId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"generatedAt": {
"type": "string",
"format": "date-time"
},
"knowledgeSpaceId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"summary": {
"type": "object",
"properties": {
"candidateCount": {
"type": "integer",
"minimum": 0
},
"estimatedBytes": {
"type": "integer",
"minimum": 0
},
"failedCommitCount": {
"type": "integer",
"minimum": 0
},
"stagedObjectCount": {
"type": "integer",
"minimum": 0
}
},
"required": [
"candidateCount",
"estimatedBytes",
"failedCommitCount",
"stagedObjectCount"
]
},
"tenantId": {
"type": "string",
"minLength": 1,
"maxLength": 255
}
},
"required": [
"candidates",
"dryRunId",
"generatedAt",
"knowledgeSpaceId",
"summary",
"tenantId"
]
},
"KnowledgeFsStagedObjectGcExecuteResult": {
"type": "object",
"properties": {
"deleted": {
"type": "integer",
"minimum": 0
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"idempotencyKey": {
"type": "string"
},
"objectKey": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"deleted",
"skipped-active-lease"
]
}
},
"required": [
"idempotencyKey",
"objectKey",
"status"
]
}
},
"skipped": {
"type": "integer",
"minimum": 0
},
"tenantId": {
"type": "string"
}
},
"required": [
"deleted",
"items",
"skipped",
"tenantId"
]
},
"KnowledgeFsLease": {
"type": "object",
"properties": {
"acquiredAt": {
"type": "string",
"format": "date-time"
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"heartbeatAt": {
"type": "string",
"format": "date-time"
},
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"knowledgeSpaceId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"leaseType": {
"type": "string",
"enum": [
"read",
"publish",
"delete",
"reindex"
]
},
"metadata": {
"type": "object",
"additionalProperties": {},
"default": {}
},
"sessionId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"status": {
"type": "string",
"enum": [
"active",
"released",
"expired",
"failed"
]
},
"targetId": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"targetType": {
"type": "string",
"enum": [
"knowledge-space",
"document-asset",
"parse-artifact",
"knowledge-path",
"projection",
"staged-commit"
]
},
"targetVersion": {
"type": "integer",
"exclusiveMinimum": 0
},
"tenantId": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"virtualPath": {
"type": "string",
"maxLength": 384,
"pattern": "^\\/(?:sources|knowledge|evidence|workspaces)(?:\\/[^/\\s]+)*$"
}
},
"required": [
"acquiredAt",
"expiresAt",
"heartbeatAt",
"id",
"knowledgeSpaceId",
"leaseType",
"sessionId",
"status",
"targetId",
"targetType",
"tenantId",
"updatedAt",
"virtualPath"
]
},
"KnowledgeSpaceStagedCommit": {
"type": "object",
"properties": {
"checksum": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"documentAssetId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"knowledgeSpaceId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"operationType": {
"type": "string",
"enum": [
"document-upload",
"artifact-segment-write",
"bulk-reindex",
"projection-publish"
]
},
"parseArtifactId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"projectionFingerprint": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"publishedObjectKey": {
"type": "string",
"minLength": 1,
"maxLength": 1024,
"pattern": "^[A-Za-z0-9._=-]+(?:\\/[A-Za-z0-9._=-]+)*$"
},
"rawObjectKey": {
"type": "string",
"minLength": 1,
"maxLength": 1024,
"pattern": "^[A-Za-z0-9._=-]+(?:\\/[A-Za-z0-9._=-]+)*$"
},
"sizeBytes": {
"type": "integer",
"minimum": 0
},
"status": {
"type": "string",
"enum": [
"received",
"object-staged",
"object-verified",
"metadata-prepared",
"artifacts-built",
"nodes-built",
"projections-built",
"published",
"failed-retryable",
"failed-terminal",
"canceled",
"gc-pending",
"gc-complete"
]
},
"tenantId": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"errorCode": {
"type": "string",
"enum": [
"VECTOR_SPACE_QUOTA_EXCEEDED",
"VECTOR_SPACE_QUOTA_UNAVAILABLE",
"DOCUMENT_COUNT_QUOTA_EXCEEDED",
"DOCUMENT_COUNT_QUOTA_UNAVAILABLE",
"LOGICAL_DOCUMENT_CAS_CONFLICT",
"DURABLE_DELETION_IDEMPOTENCY_CONFLICT",
"SOURCE_VERSION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_COMPILATION_IN_PROGRESS",
"KNOWLEDGE_SPACE_SETTINGS_REVISION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_MIGRATION_REQUIRED",
"DOCUMENT_COMPILATION_PROFILE_CHANGED",
"DOCUMENT_COMPILATION_FAILED",
"DOCUMENT_COMPILATION_RETRYABLE",
"DOCUMENT_COMPILATION_LEASE_LOST",
"DOCUMENT_DISABLED",
"DOCUMENT_PARSER_INPUT_INVALID",
"DOCUMENT_PARSER_NOT_CONFIGURED",
"DOCUMENT_PARSER_RATE_LIMITED",
"DOCUMENT_PARSER_RESPONSE_INVALID",
"DOCUMENT_PARSER_TIMEOUT",
"DOCUMENT_PARSER_UNAVAILABLE",
"DOCUMENT_PARSER_UNSUPPORTED_TYPE",
"DOCUMENT_PDF_RENDER_FAILED",
"EMBEDDING_DIMENSION_INVALID",
"EMBEDDING_DIMENSION_UNSUPPORTED",
"EXECUTION_ATTEMPTS_EXHAUSTED",
"KNOWLEDGE_FS_ACCESS_DENIED",
"KNOWLEDGE_FS_CONFLICT",
"KNOWLEDGE_FS_INTERNAL_ERROR",
"KNOWLEDGE_FS_INVALID_REQUEST",
"KNOWLEDGE_FS_NOT_FOUND",
"KNOWLEDGE_FS_RATE_LIMITED",
"KNOWLEDGE_FS_TIMEOUT",
"KNOWLEDGE_FS_UNAVAILABLE",
"KNOWLEDGE_SPACE_MANIFEST_NOT_FOUND",
"KNOWLEDGE_SPACE_MODEL_CONFIGURATION_REQUIRED",
"MODEL_CAPABILITY_MISMATCH",
"MODEL_CONFIGURATION_STALE",
"MODEL_CREDENTIAL_INVALID",
"MODEL_CREDENTIAL_VALIDATION_UNAVAILABLE",
"MODEL_IDENTITY_MISMATCH",
"MODEL_PREFLIGHT_CANCELED",
"MODEL_PREFLIGHT_FAILED",
"MODEL_PREFLIGHT_TIMEOUT",
"MODEL_PREFLIGHT_UNAVAILABLE",
"MODEL_PROFILE_ACTIVATION_INCOMPLETE",
"MODEL_PROFILE_ACTIVATION_PERMISSION_REQUIRED",
"MODEL_RUNTIME_FAILED",
"MODEL_RUNTIME_RESPONSE_INVALID",
"MODEL_RUNTIME_OUTPUT_LIMIT",
"MODEL_RUNTIME_CONTEXT_LIMIT",
"MODEL_RUNTIME_TIMEOUT",
"MODEL_RUNTIME_UNAVAILABLE",
"MODEL_SELECTION_NOT_FOUND",
"RESEARCH_TASK_CAPABILITY_REVOKED",
"RESEARCH_TASK_DISPATCH_DEAD",
"RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED",
"RESEARCH_TASK_FAILED",
"RESEARCH_TASK_PERMISSION_SNAPSHOT_INVALID",
"RESEARCH_TASK_RUNTIME_SNAPSHOT_INVALID",
"RETRIEVAL_DELETION_IN_PROGRESS",
"RETRIEVAL_EXECUTION_LEASE_LOST",
"SOURCE_BULK_ACTION_FAILED",
"SOURCE_CONNECTION_UNAVAILABLE",
"SOURCE_CRAWL_PAGE_NOT_FOUND",
"SOURCE_CRAWL_PROVIDER_UNAVAILABLE",
"SOURCE_CRAWL_RESULT_LIMIT_EXCEEDED",
"SOURCE_CREDENTIAL_CONFIG_INVALID",
"SOURCE_CREDENTIAL_MUTATION_FAILED",
"SOURCE_CREDENTIAL_TEST_FAILED",
"SOURCE_CREDENTIAL_UNAVAILABLE",
"SOURCE_DOCUMENT_COMPILATION_FAILED",
"SOURCE_DOCUMENT_MATERIALIZATION_FAILED",
"SOURCE_DOCUMENT_REPLACEMENT_SAGA_REQUIRED",
"SOURCE_IMPORT_PARTIAL_FAILURE",
"SOURCE_ONLINE_DOCUMENT_CONFIG_INVALID",
"SOURCE_ONLINE_DOCUMENT_IMPORT_FAILED",
"SOURCE_ONLINE_DOCUMENT_PAGE_FETCH_FAILED",
"SOURCE_ONLINE_DOCUMENT_REQUEST_FAILED",
"SOURCE_ONLINE_DOCUMENT_UNAVAILABLE",
"SOURCE_ONLINE_DRIVE_CONFIG_INVALID",
"SOURCE_ONLINE_DRIVE_FILE_DOWNLOAD_FAILED",
"SOURCE_ONLINE_DRIVE_IMPORT_FAILED",
"SOURCE_ONLINE_DRIVE_REQUEST_FAILED",
"SOURCE_ONLINE_DRIVE_UNAVAILABLE",
"SOURCE_OPERATION_FAILED",
"SOURCE_PROVIDER_REJECTED",
"SOURCE_PROVIDER_TIMEOUT",
"SOURCE_PROVIDER_UNAVAILABLE",
"SOURCE_SYNC_SELECTION_MISMATCH",
"SOURCE_SECRET_INTEGRITY_FAILED",
"SOURCE_SECRET_REF_CONFLICT",
"SOURCE_SYNC_FAILED",
"SOURCE_WEBSITE_CRAWL_CONFIG_INVALID",
"SOURCE_WEBSITE_CRAWL_FAILED",
"SOURCE_WORKFLOW_FAILED",
"SOURCE_WORKFLOW_CONTENT_MISSING",
"SOURCE_WORKFLOW_CONTENT_TOO_LARGE",
"SOURCE_WORKFLOW_EXTERNAL_TIMEOUT",
"UPLOAD_INITIALIZATION_FAILED",
"UPLOAD_INTEGRITY_MISMATCH"
]
},
"errorMessage": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"failure": {
"$ref": "#/components/schemas/KnowledgeFsPublicFailure"
}
},
"required": [
"createdAt",
"id",
"idempotencyKey",
"knowledgeSpaceId",
"operationType",
"status",
"tenantId",
"updatedAt"
]
},
"KnowledgeSpaceProductModelProfile": {
"type": [
"object",
"null"
],
"properties": {
"embeddingProfile": {
"type": [
"object",
"null"
],
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"dimension": {
"type": "integer",
"exclusiveMinimum": 0
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
},
"vectorSpaceId": {
"type": "string",
"pattern": "^embedding-space-sha256:[a-f0-9]{64}$"
}
},
"required": [
"model",
"pluginId",
"provider",
"revision",
"vectorSpaceId"
],
"additionalProperties": false
},
"pendingModelConfiguration": {
"type": [
"object",
"null"
],
"properties": {
"digest": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"embeddingSelection": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
},
"failure": {
"type": "object",
"properties": {
"code": {
"type": "string",
"pattern": "^[A-Za-z0-9._:-]{1,64}$"
},
"failedAt": {
"type": "string",
"format": "date-time"
},
"field": {
"type": "string",
"enum": [
"embedding",
"reasoning",
"rerank"
]
},
"retryable": {
"type": "boolean"
}
},
"required": [
"code",
"failedAt",
"retryable"
],
"additionalProperties": false
},
"retrievalProfile": {
"type": "object",
"properties": {
"defaultMode": {
"type": "string",
"enum": [
"fast",
"research",
"deep"
]
},
"reasoningModel": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
},
"rerank": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"model": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
}
},
"required": [
"enabled"
],
"additionalProperties": false
},
"scoreThreshold": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"stage": {
"type": "string",
"enum": [
"mode-final",
"rerank"
]
},
"value": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"enabled",
"stage"
],
"additionalProperties": false
},
"topK": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"required": [
"defaultMode",
"reasoningModel",
"rerank",
"scoreThreshold",
"topK"
],
"additionalProperties": false
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
},
"state": {
"type": "string",
"enum": [
"pending-validation",
"validation-failed"
]
}
},
"required": [
"digest",
"revision",
"state"
],
"additionalProperties": false
},
"retrievalProfile": {
"type": [
"object",
"null"
],
"properties": {
"defaultMode": {
"type": "string",
"enum": [
"fast",
"research",
"deep"
]
},
"reasoningModel": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
},
"rerank": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"model": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
}
},
"required": [
"enabled"
],
"additionalProperties": false
},
"scoreThreshold": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"stage": {
"type": "string",
"enum": [
"mode-final",
"rerank"
]
},
"value": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"enabled",
"stage"
],
"additionalProperties": false
},
"topK": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"defaultMode",
"reasoningModel",
"rerank",
"scoreThreshold",
"topK",
"revision"
],
"additionalProperties": false
}
},
"required": [
"embeddingProfile",
"pendingModelConfiguration",
"retrievalProfile"
],
"additionalProperties": false
},
"KnowledgeSpaceProductSummary": {
"type": "object",
"properties": {
"description": {
"type": [
"string",
"null"
],
"maxLength": 2000
},
"documentCount": {
"type": "integer",
"minimum": 0
},
"icon": {
"type": [
"string",
"null"
],
"maxLength": 72
},
"indexState": {
"type": [
"string",
"null"
],
"maxLength": 64
},
"knowledgeSpaceId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"lastJobState": {
"type": [
"string",
"null"
],
"maxLength": 64
},
"modelProfile": {
"$ref": "#/components/schemas/KnowledgeSpaceProductModelProfile"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 160
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
},
"slug": {
"type": "string",
"minLength": 1,
"maxLength": 160
}
},
"required": [
"description",
"documentCount",
"icon",
"indexState",
"knowledgeSpaceId",
"lastJobState",
"modelProfile",
"name",
"revision",
"slug"
],
"additionalProperties": false
},
"BatchKnowledgeSpaceProductSummariesResponse": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/KnowledgeSpaceProductSummary"
},
"maxItems": 100
}
},
"required": [
"items"
],
"additionalProperties": false
},
"BatchKnowledgeSpaceProductSummariesRequest": {
"type": "object",
"properties": {
"knowledgeSpaceIds": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"minItems": 1,
"maxItems": 100
}
},
"required": [
"knowledgeSpaceIds"
],
"additionalProperties": false
},
"DurableDeletionJob": {
"type": "object",
"properties": {
"checkpoint": {
"type": "string",
"enum": [
"requested",
"quiescing",
"deleting_objects",
"deleting_derived_data",
"deleting_primary_data",
"completed"
]
},
"completedAt": {
"type": "string",
"format": "date-time"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"pattern": "^[A-Z][A-Z0-9_]{0,63}$"
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"retryable": {
"type": "boolean"
}
},
"required": [
"code",
"message",
"retryable"
],
"additionalProperties": false
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"mode": {
"type": "string",
"enum": [
"cascade",
"keep"
]
},
"progress": {
"type": "object",
"properties": {
"completedItems": {
"type": "integer",
"minimum": 0
},
"currentItemKind": {
"type": "string",
"minLength": 1
},
"totalItems": {
"type": "integer",
"minimum": 0
}
},
"required": [
"completedItems"
],
"additionalProperties": false
},
"retryAt": {
"type": "string",
"format": "date-time"
},
"runState": {
"type": "string",
"enum": [
"dispatch_pending",
"queued",
"running",
"retry_wait",
"completed",
"failed",
"canceled"
]
},
"targetId": {
"type": "string",
"format": "uuid"
},
"targetType": {
"type": "string",
"enum": [
"knowledge_space",
"source",
"document",
"logical_document"
]
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"checkpoint",
"createdAt",
"id",
"knowledgeSpaceId",
"runState",
"targetId",
"targetType",
"updatedAt"
],
"additionalProperties": false
},
"DurableDeletionAccepted": {
"type": "object",
"properties": {
"documentTitle": {
"type": "string",
"minLength": 1
},
"job": {
"$ref": "#/components/schemas/DurableDeletionJob"
},
"statusUrl": {
"type": "string",
"minLength": 1
}
},
"required": [
"job",
"statusUrl"
],
"additionalProperties": false
},
"DurableBulkDeletionAccepted": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"documentId": {
"type": "string",
"format": "uuid"
},
"documentTitle": {
"type": "string",
"minLength": 1
},
"job": {
"$ref": "#/components/schemas/DurableDeletionJob"
},
"statusUrl": {
"type": "string",
"minLength": 1
}
},
"required": [
"documentId",
"job",
"statusUrl"
],
"additionalProperties": false
}
},
"total": {
"type": "integer",
"exclusiveMinimum": 0
},
"batchId": {
"type": "string",
"format": "uuid"
},
"statusUrl": {
"type": "string",
"minLength": 1
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"documentId": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string",
"enum": [
"pending",
"accepted",
"rejected"
]
},
"job": {
"$ref": "#/components/schemas/DurableDeletionJob"
},
"statusUrl": {
"type": "string",
"minLength": 1
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"pattern": "^[A-Z][A-Z0-9_]{0,63}$"
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"retryable": {
"type": "boolean"
}
},
"required": [
"code",
"message",
"retryable"
],
"additionalProperties": false
}
},
"required": [
"documentId",
"status"
],
"additionalProperties": false
}
}
},
"required": [
"items",
"total"
],
"additionalProperties": false
},
"KnowledgeSpaceProfileAuditRevision": {
"type": "object",
"properties": {
"activatedAt": {
"type": "string",
"format": "date-time"
},
"capabilitySnapshotDigest": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"createdBySubjectId": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"dimension": {
"type": "integer",
"exclusiveMinimum": 0
},
"failedAt": {
"type": "string",
"format": "date-time"
},
"failureCode": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"kind": {
"type": "string",
"enum": [
"embedding",
"retrieval"
]
},
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
},
"snapshotDigest": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"state": {
"type": "string",
"enum": [
"candidate",
"active",
"superseded",
"failed"
]
},
"supersededAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"vectorSpaceId": {
"type": "string",
"pattern": "^embedding-space-sha256:[a-f0-9]{64}$"
}
},
"required": [
"capabilitySnapshotDigest",
"createdAt",
"createdBySubjectId",
"kind",
"model",
"pluginId",
"provider",
"revision",
"snapshotDigest",
"state",
"updatedAt"
],
"additionalProperties": false
},
"KnowledgeSpaceProfileAuditRevisionList": {
"type": "object",
"properties": {
"activeRevision": {
"type": [
"integer",
"null"
],
"exclusiveMinimum": 0
},
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/KnowledgeSpaceProfileAuditRevision"
},
"maxItems": 100
},
"nextRevision": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"activeRevision",
"items"
],
"additionalProperties": false
},
"GoldenQuestion": {
"type": "object",
"properties": {
"createdAt": {
"type": "string",
"format": "date-time"
},
"expectedEvidenceIds": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"default": []
},
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"knowledgeSpaceId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"metadata": {
"type": "object",
"additionalProperties": {},
"default": {}
},
"question": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"tags": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"default": []
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"createdAt",
"id",
"knowledgeSpaceId",
"question",
"updatedAt"
]
},
"QualityAnswerTraceSummary": {
"type": "object",
"properties": {
"completed": {
"type": "boolean"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"durationMs": {
"type": "integer",
"minimum": 0
},
"evidenceBundleId": {
"type": "string",
"format": "uuid"
},
"evidenceState": {
"type": "string"
},
"finalScore": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"id": {
"type": "string",
"format": "uuid"
},
"mode": {
"type": "string",
"enum": [
"auto",
"deep",
"fast",
"research"
]
},
"openBadCaseId": {
"type": "string",
"format": "uuid"
},
"profile": {
"type": "object",
"properties": {
"embeddingModel": {
"type": "string"
},
"embeddingVectorSpaceId": {
"type": "string"
},
"projectionPublicationId": {
"type": "string",
"format": "uuid"
},
"projectionVersion": {
"type": "integer",
"exclusiveMinimum": 0
},
"reasoningModel": {
"type": "string"
},
"rerankModel": {
"type": "string"
},
"retrievalProfileRevision": {
"type": "integer",
"exclusiveMinimum": 0
}
}
},
"query": {
"type": "string"
},
"queryImages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"byteSize": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 10485760
},
"mimeType": {
"type": "string",
"enum": [
"image/gif",
"image/jpeg",
"image/png",
"image/webp"
]
},
"sha256": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"uploadFileId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
}
},
"required": [
"byteSize",
"mimeType",
"sha256",
"uploadFileId"
]
},
"maxItems": 4
},
"resultCount": {
"type": "integer",
"minimum": 0
},
"scores": {
"type": "object",
"properties": {
"final": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"rerank": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"retrieval": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
},
"source": {
"type": "string",
"enum": [
"retrieval_test",
"workflow",
"service_api",
"agent",
"mcp"
]
},
"stages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"candidateCount": {
"type": "integer",
"minimum": 0
},
"name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"error",
"ok",
"skipped"
]
}
},
"required": [
"name",
"status"
]
}
}
},
"required": [
"completed",
"createdAt",
"id",
"mode",
"profile",
"query",
"resultCount",
"scores",
"source",
"stages"
]
},
"MissingEvidenceReview": {
"type": "object",
"properties": {
"actorSubjectId": {
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"id": {
"type": "string",
"format": "uuid"
},
"itemKey": {
"type": "string"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"reason": {
"type": "string"
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
},
"status": {
"type": "string",
"enum": [
"active",
"dismissed"
]
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"actorSubjectId",
"createdAt",
"id",
"itemKey",
"knowledgeSpaceId",
"revision",
"status",
"updatedAt"
]
},
"ProductionBadCase": {
"type": "object",
"properties": {
"actorSubjectId": {
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"query": {
"type": "string"
},
"reason": {
"type": "string"
},
"replayRunId": {
"type": "string",
"format": "uuid"
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
},
"status": {
"type": "string",
"enum": [
"open",
"replaying",
"fixed",
"dismissed"
]
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"actorSubjectId",
"createdAt",
"id",
"knowledgeSpaceId",
"reason",
"revision",
"status",
"tags",
"updatedAt"
]
},
"QualityReplayRun": {
"type": "object",
"properties": {
"attempt": {
"type": "integer",
"minimum": 0
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"error": {
"type": "string"
},
"id": {
"type": "string",
"format": "uuid"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"goldenQuestionId": {
"type": "string",
"format": "uuid"
},
"id": {
"type": "string",
"format": "uuid"
},
"matchPolicy": {
"type": "string",
"enum": [
"all",
"any"
]
},
"ordinal": {
"type": "integer",
"exclusiveMinimum": 0
},
"question": {
"type": "string"
},
"result": {
"type": "object",
"properties": {
"evidenceDiff": {
"type": "object",
"properties": {
"evidenceItems": {
"type": "array",
"items": {
"type": "object",
"properties": {
"available": {
"type": "boolean"
},
"documentName": {
"type": "string"
},
"matched": {
"type": "boolean"
},
"ordinal": {
"type": "integer",
"exclusiveMinimum": 0
},
"pageNumber": {
"type": "integer",
"exclusiveMinimum": 0
},
"sectionPath": {
"type": "array",
"items": {
"type": "string"
}
},
"text": {
"type": "string"
}
},
"required": [
"available",
"matched",
"ordinal",
"sectionPath"
]
}
},
"expectedCount": {
"type": "integer",
"minimum": 0
},
"matchedCount": {
"type": "integer",
"minimum": 0
},
"missingCount": {
"type": "integer",
"minimum": 0
},
"retrievedCount": {
"type": "integer",
"minimum": 0
}
},
"required": [
"expectedCount",
"matchedCount",
"missingCount",
"retrievedCount"
]
},
"metrics": {
"type": "object",
"properties": {
"denseCandidates": {
"type": "integer",
"minimum": 0
},
"ftsCandidates": {
"type": "integer",
"minimum": 0
},
"fusedCandidates": {
"type": "integer",
"minimum": 0
},
"graphExpansionCandidates": {
"type": "integer",
"minimum": 0
},
"pageIndexMatchedNodes": {
"type": "integer",
"minimum": 0
},
"permissionFilteredCandidates": {
"type": "integer",
"minimum": 0
},
"rerankCandidates": {
"type": "integer",
"minimum": 0
},
"scoreThresholdFilteredCandidates": {
"type": "integer",
"minimum": 0
},
"summaryCandidates": {
"type": "integer",
"minimum": 0
},
"totalMs": {
"type": "number",
"minimum": 0
}
}
},
"passed": {
"type": "boolean"
}
},
"required": [
"evidenceDiff",
"metrics",
"passed"
]
},
"state": {
"type": "string",
"enum": [
"queued",
"running",
"passed",
"failed",
"canceled"
]
}
},
"required": [
"goldenQuestionId",
"id",
"matchPolicy",
"ordinal",
"question",
"state"
]
}
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"mode": {
"type": "string",
"enum": [
"deep",
"fast",
"research"
]
},
"provenance": {
"type": "object",
"properties": {
"embedding": {
"type": "object",
"properties": {
"dimension": {
"type": "integer",
"exclusiveMinimum": 0
},
"model": {
"type": "string"
},
"vectorSpaceId": {
"type": "string"
}
},
"required": [
"dimension",
"model",
"vectorSpaceId"
]
},
"projection": {
"type": "object",
"properties": {
"projectionVersion": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"projectionVersion"
]
},
"retrieval": {
"type": "object",
"properties": {
"profileRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"reasoningModel": {
"type": "string"
},
"rerankModel": {
"type": "string"
}
},
"required": [
"profileRevision",
"reasoningModel"
]
}
},
"required": [
"projection",
"retrieval"
]
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
},
"state": {
"type": "string",
"enum": [
"queued",
"running",
"passed",
"failed",
"canceled"
]
},
"summary": {
"type": "object",
"properties": {
"completed": {
"type": "integer",
"minimum": 0
},
"failed": {
"type": "integer",
"minimum": 0
},
"hitRate": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"passed": {
"type": "integer",
"minimum": 0
},
"total": {
"type": "integer",
"minimum": 0
}
},
"required": [
"completed",
"failed",
"hitRate",
"passed",
"total"
]
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"attempt",
"createdAt",
"id",
"items",
"knowledgeSpaceId",
"mode",
"provenance",
"revision",
"state",
"summary",
"updatedAt"
]
},
"QualityTrendReport": {
"type": "object",
"properties": {
"baseline": {
"type": "object",
"properties": {
"failedQueries": {
"type": "number"
},
"passRate": {
"type": "number"
},
"totalReplays": {
"type": "number"
}
},
"required": [
"failedQueries",
"passRate",
"totalReplays"
]
},
"current": {
"type": "object",
"properties": {
"badCases": {
"type": "object",
"properties": {
"dismissed": {
"type": "number"
},
"fixed": {
"type": "number"
},
"open": {
"type": "number"
},
"replaying": {
"type": "number"
}
},
"required": [
"dismissed",
"fixed",
"open",
"replaying"
]
},
"failedQueries": {
"type": "number"
},
"passRate": {
"type": "number"
},
"totalReplays": {
"type": "number"
}
},
"required": [
"badCases",
"failedQueries",
"passRate",
"totalReplays"
]
},
"from": {
"type": "string",
"format": "date-time"
},
"slices": {
"type": "array",
"items": {
"type": "object",
"properties": {
"failedQueries": {
"type": "number"
},
"mode": {
"type": "string"
},
"model": {
"type": "string"
},
"passRate": {
"type": "number"
},
"profileRevision": {
"type": "number"
},
"replayRuns": {
"type": "number"
}
},
"required": [
"failedQueries",
"mode",
"model",
"passRate",
"profileRevision",
"replayRuns"
]
}
},
"to": {
"type": "string",
"format": "date-time"
},
"topUnanswered": {
"type": "array",
"items": {
"type": "object",
"properties": {
"count": {
"type": "number"
},
"query": {
"type": "string"
}
},
"required": [
"count",
"query"
]
}
}
},
"required": [
"baseline",
"current",
"from",
"slices",
"to",
"topUnanswered"
]
},
"DocumentAsset": {
"type": "object",
"properties": {
"createdAt": {
"type": "string",
"format": "date-time"
},
"filename": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"knowledgeSpaceId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"metadata": {
"type": "object",
"additionalProperties": {},
"default": {}
},
"mimeType": {
"type": "string",
"minLength": 1
},
"objectKey": {
"type": "string",
"minLength": 1
},
"parserStatus": {
"type": "string",
"enum": [
"pending",
"parsed",
"failed"
]
},
"sha256": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"sizeBytes": {
"type": "integer",
"minimum": 0
},
"sourceId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"version": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"createdAt",
"filename",
"id",
"knowledgeSpaceId",
"mimeType",
"objectKey",
"parserStatus",
"sha256",
"sizeBytes",
"version"
]
},
"DocumentAssetList": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DocumentAsset"
}
},
"nextCursor": {
"type": "string",
"format": "uuid"
}
},
"required": [
"items"
]
},
"ParseArtifact": {
"type": "object",
"properties": {
"artifactHash": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"contentType": {
"type": "string",
"enum": [
"text",
"structured",
"mixed"
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"documentAssetId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"elements": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"metadata": {
"type": "object",
"additionalProperties": {},
"default": {}
},
"pageNumber": {
"type": "integer",
"exclusiveMinimum": 0
},
"sectionPath": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"default": []
},
"text": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"title",
"heading",
"paragraph",
"table",
"list",
"image",
"code",
"page-break"
]
}
},
"required": [
"id",
"type"
]
}
},
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"metadata": {
"type": "object",
"additionalProperties": {},
"default": {}
},
"parser": {
"type": "string",
"enum": [
"native-markdown",
"native-html",
"native-structured",
"unstructured"
]
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"version": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"artifactHash",
"contentType",
"createdAt",
"documentAssetId",
"elements",
"id",
"parser",
"version"
]
},
"DocumentOutlineNode": {
"type": "object",
"properties": {
"childNodeIds": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"children": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
},
"default": []
},
"endOffset": {
"type": "integer",
"minimum": 0
},
"endPage": {
"type": "integer",
"exclusiveMinimum": 0
},
"id": {
"type": "string"
},
"level": {
"type": "integer",
"exclusiveMinimum": 0
},
"metadata": {
"type": "object",
"additionalProperties": {}
},
"sectionPath": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"sourceElementIds": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"sourceNodeIds": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"startOffset": {
"type": "integer",
"minimum": 0
},
"startPage": {
"type": "integer",
"exclusiveMinimum": 0
},
"summary": {
"type": "string"
},
"title": {
"type": "string"
},
"titleLocation": {
"type": "object",
"additionalProperties": {}
},
"tocSource": {
"type": "string"
}
},
"required": [
"id",
"level",
"metadata",
"title",
"tocSource"
]
},
"DocumentOutline": {
"type": "object",
"properties": {
"artifactHash": {
"type": "string"
},
"createdAt": {
"type": "string"
},
"documentAssetId": {
"type": "string",
"format": "uuid"
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"metadata": {
"type": "object",
"additionalProperties": {}
},
"nodes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DocumentOutlineNode"
}
},
"outlineVersion": {
"type": "string"
},
"parseArtifactId": {
"type": "string",
"format": "uuid"
},
"updatedAt": {
"type": "string"
},
"version": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"artifactHash",
"createdAt",
"documentAssetId",
"id",
"knowledgeSpaceId",
"metadata",
"nodes",
"outlineVersion",
"parseArtifactId",
"version"
]
},
"DocumentMultimodalManifest": {
"type": "object",
"properties": {
"artifactHash": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"documentAssetId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"assetRef": {
"type": "object",
"properties": {
"analysisUnavailable": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"enum": [
"asset-count-budget",
"materialized-byte-budget",
"variant-pixel-budget",
"variant-deadline",
"variant-input-rejected",
"variant-unavailable"
]
}
},
"required": [
"reason"
],
"additionalProperties": false
},
"contentType": {
"type": "string",
"minLength": 1
},
"objectKey": {
"type": "string",
"minLength": 1,
"maxLength": 1024,
"pattern": "^[A-Za-z0-9._=-]+(?:\\/[A-Za-z0-9._=-]+)*$"
},
"sha256": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"uri": {
"type": "string",
"minLength": 1,
"maxLength": 2048
},
"variants": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"contentType": {
"type": "string",
"minLength": 1
},
"height": {
"type": "number",
"minimum": 0
},
"objectKey": {
"type": "string",
"minLength": 1,
"maxLength": 1024,
"pattern": "^[A-Za-z0-9._=-]+(?:\\/[A-Za-z0-9._=-]+)*$"
},
"sha256": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"uri": {
"type": "string",
"minLength": 1,
"maxLength": 2048
},
"width": {
"type": "number",
"minimum": 0
}
}
}
}
}
},
"boundingBox": {
"type": "object",
"properties": {
"height": {
"type": "number",
"minimum": 0
},
"width": {
"type": "number",
"minimum": 0
},
"x": {
"type": "number",
"minimum": 0
},
"y": {
"type": "number",
"minimum": 0
}
},
"required": [
"height",
"width",
"x",
"y"
]
},
"caption": {
"type": "string",
"minLength": 1,
"maxLength": 16000
},
"endOffset": {
"type": "integer",
"minimum": 0
},
"enrichment": {
"type": "object",
"properties": {
"asset": {
"type": "string",
"enum": [
"missing",
"pending",
"provided",
"unsupported"
]
},
"caption": {
"type": "string",
"enum": [
"missing",
"pending",
"provided",
"unsupported"
]
},
"ocr": {
"type": "string",
"enum": [
"missing",
"pending",
"provided",
"unsupported"
]
},
"tableStructure": {
"type": "string",
"enum": [
"missing",
"pending",
"provided",
"unsupported"
]
},
"visualEmbedding": {
"type": "string",
"enum": [
"missing",
"pending",
"provided",
"unsupported"
]
}
},
"required": [
"asset",
"caption",
"ocr",
"tableStructure",
"visualEmbedding"
]
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"modality": {
"type": "string",
"enum": [
"code",
"image",
"page",
"table"
]
},
"ocrText": {
"type": "string",
"minLength": 1,
"maxLength": 64000
},
"pageNumber": {
"type": "integer",
"exclusiveMinimum": 0
},
"parseElementId": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"sectionPath": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"default": []
},
"sourceMetadata": {
"type": "object",
"additionalProperties": {},
"default": {}
},
"startOffset": {
"type": "integer",
"minimum": 0
},
"textPreview": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 2000
}
},
"required": [
"enrichment",
"id",
"modality",
"parseElementId"
]
}
},
"knowledgeSpaceId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"manifestVersion": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"metadata": {
"type": "object",
"additionalProperties": {},
"default": {}
},
"parseArtifactId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"publicationGenerationId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"version": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"artifactHash",
"createdAt",
"documentAssetId",
"id",
"items",
"knowledgeSpaceId",
"manifestVersion",
"parseArtifactId",
"version"
]
},
"KnowledgeSpaceMetadataField": {
"type": "object",
"properties": {
"count": {
"type": "integer",
"minimum": 0
},
"createdAt": {
"type": "string"
},
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"rowVersion": {
"type": "integer",
"minimum": 0
},
"type": {
"type": "string",
"enum": [
"string",
"number",
"time"
]
},
"updatedAt": {
"type": "string"
}
},
"required": [
"count",
"createdAt",
"id",
"name",
"rowVersion",
"type",
"updatedAt"
],
"additionalProperties": false
},
"KnowledgeSpaceMetadataFieldList": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/KnowledgeSpaceMetadataField"
}
},
"nextCursor": {
"type": "string"
}
},
"required": [
"items"
],
"additionalProperties": false
},
"LogicalDocumentRevision": {
"type": [
"object",
"null"
],
"properties": {
"activatedAt": {
"type": "string"
},
"contentHash": {
"type": "string",
"minLength": 64,
"maxLength": 64
},
"createdAt": {
"type": "string"
},
"documentAssetId": {
"type": "string",
"format": "uuid"
},
"documentAssetVersion": {
"type": "integer",
"exclusiveMinimum": 0
},
"documentId": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"mimeType": {
"type": "string"
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
},
"sizeBytes": {
"type": "integer",
"minimum": 0
},
"state": {
"type": "string",
"enum": [
"candidate",
"active",
"superseded",
"failed"
]
}
},
"required": [
"contentHash",
"createdAt",
"documentAssetId",
"documentAssetVersion",
"documentId",
"knowledgeSpaceId",
"mimeType",
"revision",
"sizeBytes",
"state"
],
"additionalProperties": false
},
"LogicalDocument": {
"type": "object",
"properties": {
"latestTask": {
"type": [
"object",
"null"
],
"properties": {
"activeOperations": {
"type": "array",
"items": {
"type": "string",
"enum": [
"parse",
"outline_summary",
"chunk",
"fts_index",
"embedding",
"graph_admission",
"publication"
]
}
},
"canCancel": {
"type": "boolean"
},
"canRetry": {
"type": "boolean"
},
"completedAt": {
"type": "string"
},
"createdAt": {
"type": "string"
},
"documentId": {
"type": "string",
"format": "uuid"
},
"documentTitle": {
"type": "string",
"minLength": 1
},
"documentRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"errorCode": {
"type": "string",
"enum": [
"VECTOR_SPACE_QUOTA_EXCEEDED",
"VECTOR_SPACE_QUOTA_UNAVAILABLE",
"DOCUMENT_COUNT_QUOTA_EXCEEDED",
"DOCUMENT_COUNT_QUOTA_UNAVAILABLE",
"LOGICAL_DOCUMENT_CAS_CONFLICT",
"DURABLE_DELETION_IDEMPOTENCY_CONFLICT",
"SOURCE_VERSION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_COMPILATION_IN_PROGRESS",
"KNOWLEDGE_SPACE_SETTINGS_REVISION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_MIGRATION_REQUIRED",
"DOCUMENT_COMPILATION_PROFILE_CHANGED",
"DOCUMENT_COMPILATION_FAILED",
"DOCUMENT_COMPILATION_RETRYABLE",
"DOCUMENT_COMPILATION_LEASE_LOST",
"DOCUMENT_DISABLED",
"DOCUMENT_PARSER_INPUT_INVALID",
"DOCUMENT_PARSER_NOT_CONFIGURED",
"DOCUMENT_PARSER_RATE_LIMITED",
"DOCUMENT_PARSER_RESPONSE_INVALID",
"DOCUMENT_PARSER_TIMEOUT",
"DOCUMENT_PARSER_UNAVAILABLE",
"DOCUMENT_PARSER_UNSUPPORTED_TYPE",
"DOCUMENT_PDF_RENDER_FAILED",
"EMBEDDING_DIMENSION_INVALID",
"EMBEDDING_DIMENSION_UNSUPPORTED",
"EXECUTION_ATTEMPTS_EXHAUSTED",
"KNOWLEDGE_FS_ACCESS_DENIED",
"KNOWLEDGE_FS_CONFLICT",
"KNOWLEDGE_FS_INTERNAL_ERROR",
"KNOWLEDGE_FS_INVALID_REQUEST",
"KNOWLEDGE_FS_NOT_FOUND",
"KNOWLEDGE_FS_RATE_LIMITED",
"KNOWLEDGE_FS_TIMEOUT",
"KNOWLEDGE_FS_UNAVAILABLE",
"KNOWLEDGE_SPACE_MANIFEST_NOT_FOUND",
"KNOWLEDGE_SPACE_MODEL_CONFIGURATION_REQUIRED",
"MODEL_CAPABILITY_MISMATCH",
"MODEL_CONFIGURATION_STALE",
"MODEL_CREDENTIAL_INVALID",
"MODEL_CREDENTIAL_VALIDATION_UNAVAILABLE",
"MODEL_IDENTITY_MISMATCH",
"MODEL_PREFLIGHT_CANCELED",
"MODEL_PREFLIGHT_FAILED",
"MODEL_PREFLIGHT_TIMEOUT",
"MODEL_PREFLIGHT_UNAVAILABLE",
"MODEL_PROFILE_ACTIVATION_INCOMPLETE",
"MODEL_PROFILE_ACTIVATION_PERMISSION_REQUIRED",
"MODEL_RUNTIME_FAILED",
"MODEL_RUNTIME_RESPONSE_INVALID",
"MODEL_RUNTIME_OUTPUT_LIMIT",
"MODEL_RUNTIME_CONTEXT_LIMIT",
"MODEL_RUNTIME_TIMEOUT",
"MODEL_RUNTIME_UNAVAILABLE",
"MODEL_SELECTION_NOT_FOUND",
"RESEARCH_TASK_CAPABILITY_REVOKED",
"RESEARCH_TASK_DISPATCH_DEAD",
"RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED",
"RESEARCH_TASK_FAILED",
"RESEARCH_TASK_PERMISSION_SNAPSHOT_INVALID",
"RESEARCH_TASK_RUNTIME_SNAPSHOT_INVALID",
"RETRIEVAL_DELETION_IN_PROGRESS",
"RETRIEVAL_EXECUTION_LEASE_LOST",
"SOURCE_BULK_ACTION_FAILED",
"SOURCE_CONNECTION_UNAVAILABLE",
"SOURCE_CRAWL_PAGE_NOT_FOUND",
"SOURCE_CRAWL_PROVIDER_UNAVAILABLE",
"SOURCE_CRAWL_RESULT_LIMIT_EXCEEDED",
"SOURCE_CREDENTIAL_CONFIG_INVALID",
"SOURCE_CREDENTIAL_MUTATION_FAILED",
"SOURCE_CREDENTIAL_TEST_FAILED",
"SOURCE_CREDENTIAL_UNAVAILABLE",
"SOURCE_DOCUMENT_COMPILATION_FAILED",
"SOURCE_DOCUMENT_MATERIALIZATION_FAILED",
"SOURCE_DOCUMENT_REPLACEMENT_SAGA_REQUIRED",
"SOURCE_IMPORT_PARTIAL_FAILURE",
"SOURCE_ONLINE_DOCUMENT_CONFIG_INVALID",
"SOURCE_ONLINE_DOCUMENT_IMPORT_FAILED",
"SOURCE_ONLINE_DOCUMENT_PAGE_FETCH_FAILED",
"SOURCE_ONLINE_DOCUMENT_REQUEST_FAILED",
"SOURCE_ONLINE_DOCUMENT_UNAVAILABLE",
"SOURCE_ONLINE_DRIVE_CONFIG_INVALID",
"SOURCE_ONLINE_DRIVE_FILE_DOWNLOAD_FAILED",
"SOURCE_ONLINE_DRIVE_IMPORT_FAILED",
"SOURCE_ONLINE_DRIVE_REQUEST_FAILED",
"SOURCE_ONLINE_DRIVE_UNAVAILABLE",
"SOURCE_OPERATION_FAILED",
"SOURCE_PROVIDER_REJECTED",
"SOURCE_PROVIDER_TIMEOUT",
"SOURCE_PROVIDER_UNAVAILABLE",
"SOURCE_SYNC_SELECTION_MISMATCH",
"SOURCE_SECRET_INTEGRITY_FAILED",
"SOURCE_SECRET_REF_CONFLICT",
"SOURCE_SYNC_FAILED",
"SOURCE_WEBSITE_CRAWL_CONFIG_INVALID",
"SOURCE_WEBSITE_CRAWL_FAILED",
"SOURCE_WORKFLOW_FAILED",
"SOURCE_WORKFLOW_CONTENT_MISSING",
"SOURCE_WORKFLOW_CONTENT_TOO_LARGE",
"SOURCE_WORKFLOW_EXTERNAL_TIMEOUT",
"UPLOAD_INITIALIZATION_FAILED",
"UPLOAD_INTEGRITY_MISMATCH"
]
},
"errorMessage": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"failure": {
"$ref": "#/components/schemas/KnowledgeFsPublicFailure"
},
"failures": {
"type": "array",
"items": {
"type": "object",
"properties": {
"documentId": {
"type": "string",
"format": "uuid"
},
"documentTitle": {
"type": "string"
},
"errorCode": {
"type": "string",
"enum": [
"VECTOR_SPACE_QUOTA_EXCEEDED",
"VECTOR_SPACE_QUOTA_UNAVAILABLE",
"DOCUMENT_COUNT_QUOTA_EXCEEDED",
"DOCUMENT_COUNT_QUOTA_UNAVAILABLE",
"LOGICAL_DOCUMENT_CAS_CONFLICT",
"DURABLE_DELETION_IDEMPOTENCY_CONFLICT",
"SOURCE_VERSION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_COMPILATION_IN_PROGRESS",
"KNOWLEDGE_SPACE_SETTINGS_REVISION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_MIGRATION_REQUIRED",
"DOCUMENT_COMPILATION_PROFILE_CHANGED",
"DOCUMENT_COMPILATION_FAILED",
"DOCUMENT_COMPILATION_RETRYABLE",
"DOCUMENT_COMPILATION_LEASE_LOST",
"DOCUMENT_DISABLED",
"DOCUMENT_PARSER_INPUT_INVALID",
"DOCUMENT_PARSER_NOT_CONFIGURED",
"DOCUMENT_PARSER_RATE_LIMITED",
"DOCUMENT_PARSER_RESPONSE_INVALID",
"DOCUMENT_PARSER_TIMEOUT",
"DOCUMENT_PARSER_UNAVAILABLE",
"DOCUMENT_PARSER_UNSUPPORTED_TYPE",
"DOCUMENT_PDF_RENDER_FAILED",
"EMBEDDING_DIMENSION_INVALID",
"EMBEDDING_DIMENSION_UNSUPPORTED",
"EXECUTION_ATTEMPTS_EXHAUSTED",
"KNOWLEDGE_FS_ACCESS_DENIED",
"KNOWLEDGE_FS_CONFLICT",
"KNOWLEDGE_FS_INTERNAL_ERROR",
"KNOWLEDGE_FS_INVALID_REQUEST",
"KNOWLEDGE_FS_NOT_FOUND",
"KNOWLEDGE_FS_RATE_LIMITED",
"KNOWLEDGE_FS_TIMEOUT",
"KNOWLEDGE_FS_UNAVAILABLE",
"KNOWLEDGE_SPACE_MANIFEST_NOT_FOUND",
"KNOWLEDGE_SPACE_MODEL_CONFIGURATION_REQUIRED",
"MODEL_CAPABILITY_MISMATCH",
"MODEL_CONFIGURATION_STALE",
"MODEL_CREDENTIAL_INVALID",
"MODEL_CREDENTIAL_VALIDATION_UNAVAILABLE",
"MODEL_IDENTITY_MISMATCH",
"MODEL_PREFLIGHT_CANCELED",
"MODEL_PREFLIGHT_FAILED",
"MODEL_PREFLIGHT_TIMEOUT",
"MODEL_PREFLIGHT_UNAVAILABLE",
"MODEL_PROFILE_ACTIVATION_INCOMPLETE",
"MODEL_PROFILE_ACTIVATION_PERMISSION_REQUIRED",
"MODEL_RUNTIME_FAILED",
"MODEL_RUNTIME_RESPONSE_INVALID",
"MODEL_RUNTIME_OUTPUT_LIMIT",
"MODEL_RUNTIME_CONTEXT_LIMIT",
"MODEL_RUNTIME_TIMEOUT",
"MODEL_RUNTIME_UNAVAILABLE",
"MODEL_SELECTION_NOT_FOUND",
"RESEARCH_TASK_CAPABILITY_REVOKED",
"RESEARCH_TASK_DISPATCH_DEAD",
"RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED",
"RESEARCH_TASK_FAILED",
"RESEARCH_TASK_PERMISSION_SNAPSHOT_INVALID",
"RESEARCH_TASK_RUNTIME_SNAPSHOT_INVALID",
"RETRIEVAL_DELETION_IN_PROGRESS",
"RETRIEVAL_EXECUTION_LEASE_LOST",
"SOURCE_BULK_ACTION_FAILED",
"SOURCE_CONNECTION_UNAVAILABLE",
"SOURCE_CRAWL_PAGE_NOT_FOUND",
"SOURCE_CRAWL_PROVIDER_UNAVAILABLE",
"SOURCE_CRAWL_RESULT_LIMIT_EXCEEDED",
"SOURCE_CREDENTIAL_CONFIG_INVALID",
"SOURCE_CREDENTIAL_MUTATION_FAILED",
"SOURCE_CREDENTIAL_TEST_FAILED",
"SOURCE_CREDENTIAL_UNAVAILABLE",
"SOURCE_DOCUMENT_COMPILATION_FAILED",
"SOURCE_DOCUMENT_MATERIALIZATION_FAILED",
"SOURCE_DOCUMENT_REPLACEMENT_SAGA_REQUIRED",
"SOURCE_IMPORT_PARTIAL_FAILURE",
"SOURCE_ONLINE_DOCUMENT_CONFIG_INVALID",
"SOURCE_ONLINE_DOCUMENT_IMPORT_FAILED",
"SOURCE_ONLINE_DOCUMENT_PAGE_FETCH_FAILED",
"SOURCE_ONLINE_DOCUMENT_REQUEST_FAILED",
"SOURCE_ONLINE_DOCUMENT_UNAVAILABLE",
"SOURCE_ONLINE_DRIVE_CONFIG_INVALID",
"SOURCE_ONLINE_DRIVE_FILE_DOWNLOAD_FAILED",
"SOURCE_ONLINE_DRIVE_IMPORT_FAILED",
"SOURCE_ONLINE_DRIVE_REQUEST_FAILED",
"SOURCE_ONLINE_DRIVE_UNAVAILABLE",
"SOURCE_OPERATION_FAILED",
"SOURCE_PROVIDER_REJECTED",
"SOURCE_PROVIDER_TIMEOUT",
"SOURCE_PROVIDER_UNAVAILABLE",
"SOURCE_SYNC_SELECTION_MISMATCH",
"SOURCE_SECRET_INTEGRITY_FAILED",
"SOURCE_SECRET_REF_CONFLICT",
"SOURCE_SYNC_FAILED",
"SOURCE_WEBSITE_CRAWL_CONFIG_INVALID",
"SOURCE_WEBSITE_CRAWL_FAILED",
"SOURCE_WORKFLOW_FAILED",
"SOURCE_WORKFLOW_CONTENT_MISSING",
"SOURCE_WORKFLOW_CONTENT_TOO_LARGE",
"SOURCE_WORKFLOW_EXTERNAL_TIMEOUT",
"UPLOAD_INITIALIZATION_FAILED",
"UPLOAD_INTEGRITY_MISMATCH"
]
},
"errorMessage": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"failure": {
"$ref": "#/components/schemas/KnowledgeFsPublicFailure"
},
"jobId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"documentId",
"errorCode",
"errorMessage",
"failure"
],
"additionalProperties": false
}
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"operation": {
"type": "string",
"enum": [
"document_processing",
"document_upload",
"document_delete",
"document_reindex",
"source_crawl_preview",
"source_crawl_import",
"source_online_document_import",
"source_online_drive_import",
"source_sync",
"source_bulk"
]
},
"phase": {
"type": "string",
"enum": [
"queued",
"parsing",
"outline_summary",
"chunking_indexing",
"graph_admission",
"publication",
"complete"
]
},
"progressCompleted": {
"type": "integer",
"minimum": 0
},
"progressFailed": {
"type": "integer",
"minimum": 0
},
"progressPercent": {
"type": "integer",
"minimum": 0,
"maximum": 100
},
"progressTotal": {
"type": "integer",
"minimum": 0
},
"sourceId": {
"type": "string",
"format": "uuid"
},
"sourceTitle": {
"type": "string",
"minLength": 1
},
"state": {
"type": "string",
"enum": [
"queued",
"running",
"completed",
"failed",
"canceled"
]
},
"semanticEnrichment": {
"type": "object",
"properties": {
"errorCode": {
"type": "string",
"enum": [
"VECTOR_SPACE_QUOTA_EXCEEDED",
"VECTOR_SPACE_QUOTA_UNAVAILABLE",
"DOCUMENT_COUNT_QUOTA_EXCEEDED",
"DOCUMENT_COUNT_QUOTA_UNAVAILABLE",
"LOGICAL_DOCUMENT_CAS_CONFLICT",
"DURABLE_DELETION_IDEMPOTENCY_CONFLICT",
"SOURCE_VERSION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_COMPILATION_IN_PROGRESS",
"KNOWLEDGE_SPACE_SETTINGS_REVISION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_MIGRATION_REQUIRED",
"DOCUMENT_COMPILATION_PROFILE_CHANGED",
"DOCUMENT_COMPILATION_FAILED",
"DOCUMENT_COMPILATION_RETRYABLE",
"DOCUMENT_COMPILATION_LEASE_LOST",
"DOCUMENT_DISABLED",
"DOCUMENT_PARSER_INPUT_INVALID",
"DOCUMENT_PARSER_NOT_CONFIGURED",
"DOCUMENT_PARSER_RATE_LIMITED",
"DOCUMENT_PARSER_RESPONSE_INVALID",
"DOCUMENT_PARSER_TIMEOUT",
"DOCUMENT_PARSER_UNAVAILABLE",
"DOCUMENT_PARSER_UNSUPPORTED_TYPE",
"DOCUMENT_PDF_RENDER_FAILED",
"EMBEDDING_DIMENSION_INVALID",
"EMBEDDING_DIMENSION_UNSUPPORTED",
"EXECUTION_ATTEMPTS_EXHAUSTED",
"KNOWLEDGE_FS_ACCESS_DENIED",
"KNOWLEDGE_FS_CONFLICT",
"KNOWLEDGE_FS_INTERNAL_ERROR",
"KNOWLEDGE_FS_INVALID_REQUEST",
"KNOWLEDGE_FS_NOT_FOUND",
"KNOWLEDGE_FS_RATE_LIMITED",
"KNOWLEDGE_FS_TIMEOUT",
"KNOWLEDGE_FS_UNAVAILABLE",
"KNOWLEDGE_SPACE_MANIFEST_NOT_FOUND",
"KNOWLEDGE_SPACE_MODEL_CONFIGURATION_REQUIRED",
"MODEL_CAPABILITY_MISMATCH",
"MODEL_CONFIGURATION_STALE",
"MODEL_CREDENTIAL_INVALID",
"MODEL_CREDENTIAL_VALIDATION_UNAVAILABLE",
"MODEL_IDENTITY_MISMATCH",
"MODEL_PREFLIGHT_CANCELED",
"MODEL_PREFLIGHT_FAILED",
"MODEL_PREFLIGHT_TIMEOUT",
"MODEL_PREFLIGHT_UNAVAILABLE",
"MODEL_PROFILE_ACTIVATION_INCOMPLETE",
"MODEL_PROFILE_ACTIVATION_PERMISSION_REQUIRED",
"MODEL_RUNTIME_FAILED",
"MODEL_RUNTIME_RESPONSE_INVALID",
"MODEL_RUNTIME_OUTPUT_LIMIT",
"MODEL_RUNTIME_CONTEXT_LIMIT",
"MODEL_RUNTIME_TIMEOUT",
"MODEL_RUNTIME_UNAVAILABLE",
"MODEL_SELECTION_NOT_FOUND",
"RESEARCH_TASK_CAPABILITY_REVOKED",
"RESEARCH_TASK_DISPATCH_DEAD",
"RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED",
"RESEARCH_TASK_FAILED",
"RESEARCH_TASK_PERMISSION_SNAPSHOT_INVALID",
"RESEARCH_TASK_RUNTIME_SNAPSHOT_INVALID",
"RETRIEVAL_DELETION_IN_PROGRESS",
"RETRIEVAL_EXECUTION_LEASE_LOST",
"SOURCE_BULK_ACTION_FAILED",
"SOURCE_CONNECTION_UNAVAILABLE",
"SOURCE_CRAWL_PAGE_NOT_FOUND",
"SOURCE_CRAWL_PROVIDER_UNAVAILABLE",
"SOURCE_CRAWL_RESULT_LIMIT_EXCEEDED",
"SOURCE_CREDENTIAL_CONFIG_INVALID",
"SOURCE_CREDENTIAL_MUTATION_FAILED",
"SOURCE_CREDENTIAL_TEST_FAILED",
"SOURCE_CREDENTIAL_UNAVAILABLE",
"SOURCE_DOCUMENT_COMPILATION_FAILED",
"SOURCE_DOCUMENT_MATERIALIZATION_FAILED",
"SOURCE_DOCUMENT_REPLACEMENT_SAGA_REQUIRED",
"SOURCE_IMPORT_PARTIAL_FAILURE",
"SOURCE_ONLINE_DOCUMENT_CONFIG_INVALID",
"SOURCE_ONLINE_DOCUMENT_IMPORT_FAILED",
"SOURCE_ONLINE_DOCUMENT_PAGE_FETCH_FAILED",
"SOURCE_ONLINE_DOCUMENT_REQUEST_FAILED",
"SOURCE_ONLINE_DOCUMENT_UNAVAILABLE",
"SOURCE_ONLINE_DRIVE_CONFIG_INVALID",
"SOURCE_ONLINE_DRIVE_FILE_DOWNLOAD_FAILED",
"SOURCE_ONLINE_DRIVE_IMPORT_FAILED",
"SOURCE_ONLINE_DRIVE_REQUEST_FAILED",
"SOURCE_ONLINE_DRIVE_UNAVAILABLE",
"SOURCE_OPERATION_FAILED",
"SOURCE_PROVIDER_REJECTED",
"SOURCE_PROVIDER_TIMEOUT",
"SOURCE_PROVIDER_UNAVAILABLE",
"SOURCE_SYNC_SELECTION_MISMATCH",
"SOURCE_SECRET_INTEGRITY_FAILED",
"SOURCE_SECRET_REF_CONFLICT",
"SOURCE_SYNC_FAILED",
"SOURCE_WEBSITE_CRAWL_CONFIG_INVALID",
"SOURCE_WEBSITE_CRAWL_FAILED",
"SOURCE_WORKFLOW_FAILED",
"SOURCE_WORKFLOW_CONTENT_MISSING",
"SOURCE_WORKFLOW_CONTENT_TOO_LARGE",
"SOURCE_WORKFLOW_EXTERNAL_TIMEOUT",
"UPLOAD_INITIALIZATION_FAILED",
"UPLOAD_INTEGRITY_MISMATCH"
]
},
"errorMessage": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"failure": {
"$ref": "#/components/schemas/KnowledgeFsPublicFailure"
},
"nodesCompleted": {
"type": "integer",
"minimum": 0
},
"nodesTotal": {
"type": "integer",
"minimum": 0
},
"providerCalls": {
"type": "integer",
"minimum": 0
},
"providerCallsMaximum": {
"type": "integer",
"minimum": 0
},
"state": {
"type": "string",
"enum": [
"not_scheduled",
"pending",
"running",
"ready",
"failed",
"disabled"
]
},
"updatedAt": {
"type": "string"
}
},
"required": [
"nodesCompleted",
"state"
],
"additionalProperties": false
},
"taskKind": {
"type": "string",
"enum": [
"document",
"document_bulk",
"source"
]
},
"updatedAt": {
"type": "string"
}
},
"required": [
"canCancel",
"canRetry",
"createdAt",
"id",
"knowledgeSpaceId",
"operation",
"progressCompleted",
"progressFailed",
"progressPercent",
"progressTotal",
"state",
"taskKind",
"updatedAt"
]
},
"active": {
"$ref": "#/components/schemas/LogicalDocumentRevision"
},
"activeRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"createdAt": {
"type": "string"
},
"disabledAt": {
"type": "string"
},
"disabledBySubjectId": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"providerItemId": {
"type": "string"
},
"rowVersion": {
"type": "integer",
"minimum": 0
},
"sourceId": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string",
"enum": [
"pending",
"ready",
"failed",
"deleting"
]
},
"title": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"userMetadata": {
"type": "object",
"additionalProperties": {}
}
},
"required": [
"active",
"createdAt",
"enabled",
"id",
"knowledgeSpaceId",
"rowVersion",
"status",
"title",
"updatedAt",
"userMetadata"
],
"additionalProperties": false
},
"LogicalDocumentList": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LogicalDocument"
}
},
"nextCursor": {
"type": "string"
}
},
"required": [
"items"
],
"additionalProperties": false
},
"ResolvedDocumentReference": {
"type": "object",
"properties": {
"documentId": {
"type": "string",
"format": "uuid"
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"documentId",
"revision"
],
"additionalProperties": false
},
"DocumentRevisionList": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/LogicalDocumentRevision"
},
{
"type": "object"
}
]
}
},
"nextCursor": {
"type": "string"
}
},
"required": [
"items"
],
"additionalProperties": false
},
"DocumentProcessingTask": {
"type": "object",
"properties": {
"activeOperations": {
"type": "array",
"items": {
"type": "string",
"enum": [
"parse",
"outline_summary",
"chunk",
"fts_index",
"embedding",
"graph_admission",
"publication"
]
}
},
"completedAt": {
"type": "string"
},
"createdAt": {
"type": "string"
},
"documentId": {
"type": "string",
"format": "uuid"
},
"documentRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"errorCode": {
"type": "string",
"enum": [
"VECTOR_SPACE_QUOTA_EXCEEDED",
"VECTOR_SPACE_QUOTA_UNAVAILABLE",
"DOCUMENT_COUNT_QUOTA_EXCEEDED",
"DOCUMENT_COUNT_QUOTA_UNAVAILABLE",
"LOGICAL_DOCUMENT_CAS_CONFLICT",
"DURABLE_DELETION_IDEMPOTENCY_CONFLICT",
"SOURCE_VERSION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_COMPILATION_IN_PROGRESS",
"KNOWLEDGE_SPACE_SETTINGS_REVISION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_MIGRATION_REQUIRED",
"DOCUMENT_COMPILATION_PROFILE_CHANGED",
"DOCUMENT_COMPILATION_FAILED",
"DOCUMENT_COMPILATION_RETRYABLE",
"DOCUMENT_COMPILATION_LEASE_LOST",
"DOCUMENT_DISABLED",
"DOCUMENT_PARSER_INPUT_INVALID",
"DOCUMENT_PARSER_NOT_CONFIGURED",
"DOCUMENT_PARSER_RATE_LIMITED",
"DOCUMENT_PARSER_RESPONSE_INVALID",
"DOCUMENT_PARSER_TIMEOUT",
"DOCUMENT_PARSER_UNAVAILABLE",
"DOCUMENT_PARSER_UNSUPPORTED_TYPE",
"DOCUMENT_PDF_RENDER_FAILED",
"EMBEDDING_DIMENSION_INVALID",
"EMBEDDING_DIMENSION_UNSUPPORTED",
"EXECUTION_ATTEMPTS_EXHAUSTED",
"KNOWLEDGE_FS_ACCESS_DENIED",
"KNOWLEDGE_FS_CONFLICT",
"KNOWLEDGE_FS_INTERNAL_ERROR",
"KNOWLEDGE_FS_INVALID_REQUEST",
"KNOWLEDGE_FS_NOT_FOUND",
"KNOWLEDGE_FS_RATE_LIMITED",
"KNOWLEDGE_FS_TIMEOUT",
"KNOWLEDGE_FS_UNAVAILABLE",
"KNOWLEDGE_SPACE_MANIFEST_NOT_FOUND",
"KNOWLEDGE_SPACE_MODEL_CONFIGURATION_REQUIRED",
"MODEL_CAPABILITY_MISMATCH",
"MODEL_CONFIGURATION_STALE",
"MODEL_CREDENTIAL_INVALID",
"MODEL_CREDENTIAL_VALIDATION_UNAVAILABLE",
"MODEL_IDENTITY_MISMATCH",
"MODEL_PREFLIGHT_CANCELED",
"MODEL_PREFLIGHT_FAILED",
"MODEL_PREFLIGHT_TIMEOUT",
"MODEL_PREFLIGHT_UNAVAILABLE",
"MODEL_PROFILE_ACTIVATION_INCOMPLETE",
"MODEL_PROFILE_ACTIVATION_PERMISSION_REQUIRED",
"MODEL_RUNTIME_FAILED",
"MODEL_RUNTIME_RESPONSE_INVALID",
"MODEL_RUNTIME_OUTPUT_LIMIT",
"MODEL_RUNTIME_CONTEXT_LIMIT",
"MODEL_RUNTIME_TIMEOUT",
"MODEL_RUNTIME_UNAVAILABLE",
"MODEL_SELECTION_NOT_FOUND",
"RESEARCH_TASK_CAPABILITY_REVOKED",
"RESEARCH_TASK_DISPATCH_DEAD",
"RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED",
"RESEARCH_TASK_FAILED",
"RESEARCH_TASK_PERMISSION_SNAPSHOT_INVALID",
"RESEARCH_TASK_RUNTIME_SNAPSHOT_INVALID",
"RETRIEVAL_DELETION_IN_PROGRESS",
"RETRIEVAL_EXECUTION_LEASE_LOST",
"SOURCE_BULK_ACTION_FAILED",
"SOURCE_CONNECTION_UNAVAILABLE",
"SOURCE_CRAWL_PAGE_NOT_FOUND",
"SOURCE_CRAWL_PROVIDER_UNAVAILABLE",
"SOURCE_CRAWL_RESULT_LIMIT_EXCEEDED",
"SOURCE_CREDENTIAL_CONFIG_INVALID",
"SOURCE_CREDENTIAL_MUTATION_FAILED",
"SOURCE_CREDENTIAL_TEST_FAILED",
"SOURCE_CREDENTIAL_UNAVAILABLE",
"SOURCE_DOCUMENT_COMPILATION_FAILED",
"SOURCE_DOCUMENT_MATERIALIZATION_FAILED",
"SOURCE_DOCUMENT_REPLACEMENT_SAGA_REQUIRED",
"SOURCE_IMPORT_PARTIAL_FAILURE",
"SOURCE_ONLINE_DOCUMENT_CONFIG_INVALID",
"SOURCE_ONLINE_DOCUMENT_IMPORT_FAILED",
"SOURCE_ONLINE_DOCUMENT_PAGE_FETCH_FAILED",
"SOURCE_ONLINE_DOCUMENT_REQUEST_FAILED",
"SOURCE_ONLINE_DOCUMENT_UNAVAILABLE",
"SOURCE_ONLINE_DRIVE_CONFIG_INVALID",
"SOURCE_ONLINE_DRIVE_FILE_DOWNLOAD_FAILED",
"SOURCE_ONLINE_DRIVE_IMPORT_FAILED",
"SOURCE_ONLINE_DRIVE_REQUEST_FAILED",
"SOURCE_ONLINE_DRIVE_UNAVAILABLE",
"SOURCE_OPERATION_FAILED",
"SOURCE_PROVIDER_REJECTED",
"SOURCE_PROVIDER_TIMEOUT",
"SOURCE_PROVIDER_UNAVAILABLE",
"SOURCE_SYNC_SELECTION_MISMATCH",
"SOURCE_SECRET_INTEGRITY_FAILED",
"SOURCE_SECRET_REF_CONFLICT",
"SOURCE_SYNC_FAILED",
"SOURCE_WEBSITE_CRAWL_CONFIG_INVALID",
"SOURCE_WEBSITE_CRAWL_FAILED",
"SOURCE_WORKFLOW_FAILED",
"SOURCE_WORKFLOW_CONTENT_MISSING",
"SOURCE_WORKFLOW_CONTENT_TOO_LARGE",
"SOURCE_WORKFLOW_EXTERNAL_TIMEOUT",
"UPLOAD_INITIALIZATION_FAILED",
"UPLOAD_INTEGRITY_MISMATCH"
]
},
"errorMessage": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"failure": {
"$ref": "#/components/schemas/KnowledgeFsPublicFailure"
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"phase": {
"type": "string",
"enum": [
"queued",
"parsing",
"outline_summary",
"chunking_indexing",
"graph_admission",
"publication",
"complete"
]
},
"progressPercent": {
"type": "integer",
"minimum": 0,
"maximum": 100
},
"retryAt": {
"type": "string"
},
"stage": {
"type": "string",
"enum": [
"queued",
"parsed",
"outline_built",
"nodes_generated",
"projection_built",
"smoke_eval_passed",
"published"
]
},
"state": {
"type": "string",
"enum": [
"dispatch_pending",
"queued",
"running",
"retry_wait",
"succeeded",
"failed",
"canceled",
"superseded"
]
},
"semanticEnrichment": {
"type": "object",
"properties": {
"errorCode": {
"type": "string",
"enum": [
"VECTOR_SPACE_QUOTA_EXCEEDED",
"VECTOR_SPACE_QUOTA_UNAVAILABLE",
"DOCUMENT_COUNT_QUOTA_EXCEEDED",
"DOCUMENT_COUNT_QUOTA_UNAVAILABLE",
"LOGICAL_DOCUMENT_CAS_CONFLICT",
"DURABLE_DELETION_IDEMPOTENCY_CONFLICT",
"SOURCE_VERSION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_COMPILATION_IN_PROGRESS",
"KNOWLEDGE_SPACE_SETTINGS_REVISION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_MIGRATION_REQUIRED",
"DOCUMENT_COMPILATION_PROFILE_CHANGED",
"DOCUMENT_COMPILATION_FAILED",
"DOCUMENT_COMPILATION_RETRYABLE",
"DOCUMENT_COMPILATION_LEASE_LOST",
"DOCUMENT_DISABLED",
"DOCUMENT_PARSER_INPUT_INVALID",
"DOCUMENT_PARSER_NOT_CONFIGURED",
"DOCUMENT_PARSER_RATE_LIMITED",
"DOCUMENT_PARSER_RESPONSE_INVALID",
"DOCUMENT_PARSER_TIMEOUT",
"DOCUMENT_PARSER_UNAVAILABLE",
"DOCUMENT_PARSER_UNSUPPORTED_TYPE",
"DOCUMENT_PDF_RENDER_FAILED",
"EMBEDDING_DIMENSION_INVALID",
"EMBEDDING_DIMENSION_UNSUPPORTED",
"EXECUTION_ATTEMPTS_EXHAUSTED",
"KNOWLEDGE_FS_ACCESS_DENIED",
"KNOWLEDGE_FS_CONFLICT",
"KNOWLEDGE_FS_INTERNAL_ERROR",
"KNOWLEDGE_FS_INVALID_REQUEST",
"KNOWLEDGE_FS_NOT_FOUND",
"KNOWLEDGE_FS_RATE_LIMITED",
"KNOWLEDGE_FS_TIMEOUT",
"KNOWLEDGE_FS_UNAVAILABLE",
"KNOWLEDGE_SPACE_MANIFEST_NOT_FOUND",
"KNOWLEDGE_SPACE_MODEL_CONFIGURATION_REQUIRED",
"MODEL_CAPABILITY_MISMATCH",
"MODEL_CONFIGURATION_STALE",
"MODEL_CREDENTIAL_INVALID",
"MODEL_CREDENTIAL_VALIDATION_UNAVAILABLE",
"MODEL_IDENTITY_MISMATCH",
"MODEL_PREFLIGHT_CANCELED",
"MODEL_PREFLIGHT_FAILED",
"MODEL_PREFLIGHT_TIMEOUT",
"MODEL_PREFLIGHT_UNAVAILABLE",
"MODEL_PROFILE_ACTIVATION_INCOMPLETE",
"MODEL_PROFILE_ACTIVATION_PERMISSION_REQUIRED",
"MODEL_RUNTIME_FAILED",
"MODEL_RUNTIME_RESPONSE_INVALID",
"MODEL_RUNTIME_OUTPUT_LIMIT",
"MODEL_RUNTIME_CONTEXT_LIMIT",
"MODEL_RUNTIME_TIMEOUT",
"MODEL_RUNTIME_UNAVAILABLE",
"MODEL_SELECTION_NOT_FOUND",
"RESEARCH_TASK_CAPABILITY_REVOKED",
"RESEARCH_TASK_DISPATCH_DEAD",
"RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED",
"RESEARCH_TASK_FAILED",
"RESEARCH_TASK_PERMISSION_SNAPSHOT_INVALID",
"RESEARCH_TASK_RUNTIME_SNAPSHOT_INVALID",
"RETRIEVAL_DELETION_IN_PROGRESS",
"RETRIEVAL_EXECUTION_LEASE_LOST",
"SOURCE_BULK_ACTION_FAILED",
"SOURCE_CONNECTION_UNAVAILABLE",
"SOURCE_CRAWL_PAGE_NOT_FOUND",
"SOURCE_CRAWL_PROVIDER_UNAVAILABLE",
"SOURCE_CRAWL_RESULT_LIMIT_EXCEEDED",
"SOURCE_CREDENTIAL_CONFIG_INVALID",
"SOURCE_CREDENTIAL_MUTATION_FAILED",
"SOURCE_CREDENTIAL_TEST_FAILED",
"SOURCE_CREDENTIAL_UNAVAILABLE",
"SOURCE_DOCUMENT_COMPILATION_FAILED",
"SOURCE_DOCUMENT_MATERIALIZATION_FAILED",
"SOURCE_DOCUMENT_REPLACEMENT_SAGA_REQUIRED",
"SOURCE_IMPORT_PARTIAL_FAILURE",
"SOURCE_ONLINE_DOCUMENT_CONFIG_INVALID",
"SOURCE_ONLINE_DOCUMENT_IMPORT_FAILED",
"SOURCE_ONLINE_DOCUMENT_PAGE_FETCH_FAILED",
"SOURCE_ONLINE_DOCUMENT_REQUEST_FAILED",
"SOURCE_ONLINE_DOCUMENT_UNAVAILABLE",
"SOURCE_ONLINE_DRIVE_CONFIG_INVALID",
"SOURCE_ONLINE_DRIVE_FILE_DOWNLOAD_FAILED",
"SOURCE_ONLINE_DRIVE_IMPORT_FAILED",
"SOURCE_ONLINE_DRIVE_REQUEST_FAILED",
"SOURCE_ONLINE_DRIVE_UNAVAILABLE",
"SOURCE_OPERATION_FAILED",
"SOURCE_PROVIDER_REJECTED",
"SOURCE_PROVIDER_TIMEOUT",
"SOURCE_PROVIDER_UNAVAILABLE",
"SOURCE_SYNC_SELECTION_MISMATCH",
"SOURCE_SECRET_INTEGRITY_FAILED",
"SOURCE_SECRET_REF_CONFLICT",
"SOURCE_SYNC_FAILED",
"SOURCE_WEBSITE_CRAWL_CONFIG_INVALID",
"SOURCE_WEBSITE_CRAWL_FAILED",
"SOURCE_WORKFLOW_FAILED",
"SOURCE_WORKFLOW_CONTENT_MISSING",
"SOURCE_WORKFLOW_CONTENT_TOO_LARGE",
"SOURCE_WORKFLOW_EXTERNAL_TIMEOUT",
"UPLOAD_INITIALIZATION_FAILED",
"UPLOAD_INTEGRITY_MISMATCH"
]
},
"errorMessage": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"failure": {
"$ref": "#/components/schemas/KnowledgeFsPublicFailure"
},
"nodesCompleted": {
"type": "integer",
"minimum": 0
},
"nodesTotal": {
"type": "integer",
"minimum": 0
},
"providerCalls": {
"type": "integer",
"minimum": 0
},
"providerCallsMaximum": {
"type": "integer",
"minimum": 0
},
"state": {
"type": "string",
"enum": [
"not_scheduled",
"pending",
"running",
"ready",
"failed",
"disabled"
]
},
"updatedAt": {
"type": "string"
}
},
"required": [
"nodesCompleted",
"state"
],
"additionalProperties": false
},
"updatedAt": {
"type": "string"
}
},
"required": [
"createdAt",
"documentId",
"documentRevision",
"id",
"knowledgeSpaceId",
"progressPercent",
"stage",
"state",
"updatedAt"
],
"additionalProperties": false
},
"DocumentRevisionChunk": {
"type": "object",
"properties": {
"createdAt": {
"type": "string"
},
"documentId": {
"type": "string",
"format": "uuid"
},
"documentRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"endOffset": {
"type": "integer",
"minimum": 0
},
"enabled": {
"type": "boolean"
},
"id": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"chunk",
"section",
"table",
"image",
"summary"
]
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"ordinal": {
"type": "integer",
"minimum": 0
},
"parentChunkId": {
"type": "string",
"format": "uuid"
},
"parseElementIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"maxItems": 20000
},
"sectionPath": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"startOffset": {
"type": "integer",
"minimum": 0
},
"text": {
"type": "string"
},
"tokenCount": {
"type": "integer",
"minimum": 0
},
"userMetadata": {
"type": "object",
"additionalProperties": {}
}
},
"required": [
"createdAt",
"documentId",
"documentRevision",
"enabled",
"id",
"kind",
"knowledgeSpaceId",
"ordinal",
"parseElementIds",
"sectionPath",
"text",
"tokenCount",
"userMetadata"
],
"additionalProperties": false
},
"DocumentChunkList": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DocumentRevisionChunk"
}
},
"nextCursor": {
"type": "string"
}
},
"required": [
"items"
],
"additionalProperties": false
},
"DocumentChunkStateChangeAccepted": {
"type": "object",
"properties": {
"candidateFingerprint": {
"type": "string"
},
"candidatePublicationId": {
"type": "string",
"format": "uuid"
},
"chunkId": {
"type": "string",
"format": "uuid"
},
"compilationAttemptId": {
"type": "string",
"format": "uuid"
},
"createdAt": {
"type": "string"
},
"documentId": {
"type": "string",
"format": "uuid"
},
"documentRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"enabled": {
"type": "boolean"
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"state": {
"type": "string",
"enum": [
"candidate"
]
},
"statusUrl": {
"type": "string",
"minLength": 1
}
},
"required": [
"chunkId",
"compilationAttemptId",
"createdAt",
"documentId",
"documentRevision",
"enabled",
"id",
"knowledgeSpaceId",
"state",
"statusUrl"
],
"additionalProperties": false
},
"DocumentProcessingTaskList": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DocumentProcessingTask"
}
},
"nextCursor": {
"type": "string"
}
},
"required": [
"items"
],
"additionalProperties": false
},
"DocumentSettingsHead": {
"type": "object",
"properties": {
"activeRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"profile": {
"type": "object",
"properties": {
"activatedAt": {
"type": "string"
},
"createdAt": {
"type": "string"
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
},
"settings": {
"type": "object",
"properties": {
"chunkOverlap": {
"type": "integer",
"minimum": 0,
"maximum": 8191
},
"chunkSize": {
"type": "integer",
"minimum": 128,
"maximum": 8192
},
"enableGraph": {
"type": "boolean"
},
"enablePageIndex": {
"type": "boolean"
},
"language": {
"type": "string",
"minLength": 2,
"maxLength": 64
}
},
"required": [
"chunkOverlap",
"chunkSize",
"enableGraph",
"enablePageIndex"
],
"additionalProperties": false
},
"state": {
"type": "string",
"enum": [
"active"
]
}
},
"required": [
"createdAt",
"revision",
"settings",
"state"
]
},
"rowVersion": {
"type": "integer",
"minimum": 0
},
"updatedAt": {
"type": "string"
}
},
"required": [
"activeRevision",
"profile",
"rowVersion",
"updatedAt"
],
"additionalProperties": false
},
"DocumentReindexAccepted": {
"type": "object",
"properties": {
"attemptId": {
"type": "string",
"format": "uuid"
},
"compilationAttemptId": {
"type": "string",
"format": "uuid"
},
"settingsRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"state": {
"type": "string",
"enum": [
"running"
]
},
"statusUrl": {
"type": "string"
}
},
"required": [
"attemptId",
"compilationAttemptId",
"settingsRevision",
"state",
"statusUrl"
],
"additionalProperties": false
},
"DocumentCompilationJob": {
"type": "object",
"properties": {
"baseHeadRevision": {
"type": "integer",
"minimum": 0
},
"candidateFingerprint": {
"type": "string",
"minLength": 1
},
"candidatePublicationId": {
"type": "string",
"format": "uuid"
},
"completedAt": {
"type": "number"
},
"createdAt": {
"type": "number"
},
"documentAssetId": {
"type": "string",
"minLength": 1
},
"error": {
"type": "string"
},
"failure": {
"$ref": "#/components/schemas/KnowledgeFsPublicFailure"
},
"executionAttempts": {
"type": "integer",
"minimum": 0
},
"id": {
"type": "string",
"minLength": 1
},
"knowledgeSpaceId": {
"type": "string",
"minLength": 1
},
"leaseExpiresAt": {
"type": "number"
},
"maxExecutionAttempts": {
"type": "integer",
"exclusiveMinimum": 0
},
"publicationGenerationId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"queueJobId": {
"type": "string",
"minLength": 1
},
"retryAt": {
"type": "number"
},
"runState": {
"type": "string",
"enum": [
"dispatch_pending",
"queued",
"running",
"retry_wait",
"succeeded",
"failed",
"canceled",
"superseded"
]
},
"stage": {
"type": "string",
"enum": [
"queued",
"parsed",
"outline_built",
"nodes_generated",
"projection_built",
"smoke_eval_passed",
"published",
"failed",
"canceled"
]
},
"tenantId": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"updatedAt": {
"type": "number"
},
"version": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"createdAt",
"documentAssetId",
"id",
"knowledgeSpaceId",
"stage",
"tenantId",
"updatedAt",
"version"
]
},
"AnswerTrace": {
"type": "object",
"properties": {
"createdAt": {
"type": "string",
"format": "date-time"
},
"evidenceBundleId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"knowledgeSpaceId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"mode": {
"type": "string",
"enum": [
"fast",
"deep",
"research",
"auto"
]
},
"query": {
"type": "string"
},
"queryImages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"byteSize": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 10485760
},
"mimeType": {
"type": "string",
"enum": [
"image/gif",
"image/jpeg",
"image/png",
"image/webp"
]
},
"sha256": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"uploadFileId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
}
},
"required": [
"byteSize",
"mimeType",
"sha256",
"uploadFileId"
]
},
"maxItems": 4
},
"source": {
"type": "string",
"enum": [
"retrieval_test",
"workflow",
"service_api",
"agent",
"mcp"
]
},
"steps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"endedAt": {
"type": "string",
"format": "date-time"
},
"metadata": {
"type": "object",
"additionalProperties": {},
"default": {}
},
"name": {
"type": "string",
"minLength": 1
},
"startedAt": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string",
"enum": [
"ok",
"error",
"skipped"
]
}
},
"required": [
"name",
"startedAt",
"status"
]
}
}
},
"required": [
"createdAt",
"id",
"knowledgeSpaceId",
"mode",
"query",
"steps"
]
},
"BulkOperationProgress": {
"type": "object",
"properties": {
"canceledItems": {
"type": "integer",
"minimum": 0
},
"completedItems": {
"type": "integer",
"minimum": 0
},
"createdAt": {
"type": "string"
},
"failedItemIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"failedItems": {
"type": "integer",
"minimum": 0
},
"id": {
"type": "string",
"minLength": 1
},
"knowledgeSpaceId": {
"type": "string",
"minLength": 1
},
"status": {
"type": "string",
"enum": [
"running",
"completed",
"failed",
"canceled"
]
},
"totalItems": {
"type": "integer",
"minimum": 0
},
"type": {
"type": "string",
"enum": [
"document_upload",
"document_delete",
"document_reindex"
]
},
"updatedAt": {
"type": "string"
}
},
"required": [
"canceledItems",
"completedItems",
"createdAt",
"failedItemIds",
"failedItems",
"id",
"knowledgeSpaceId",
"status",
"totalItems",
"type",
"updatedAt"
]
},
"RetentionPolicy": {
"type": "object",
"properties": {
"answerTraceRetentionDays": {
"type": "integer",
"exclusiveMinimum": 0
},
"createdAt": {
"type": "string"
},
"evidenceCacheRetentionDays": {
"type": "integer",
"exclusiveMinimum": 0
},
"id": {
"type": "string",
"minLength": 1
},
"inactiveProjectionRetentionDays": {
"type": "integer",
"exclusiveMinimum": 0
},
"knowledgeSpaceId": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"parseArtifactVersions": {
"type": "integer",
"exclusiveMinimum": 0
},
"rawDocumentRetentionDays": {
"type": [
"integer",
"null"
],
"exclusiveMinimum": 0
},
"scope": {
"type": "string",
"enum": [
"tenant",
"knowledge_space"
]
},
"sessionInactivityMinutes": {
"type": "integer",
"exclusiveMinimum": 0
},
"tenantId": {
"type": "string",
"minLength": 1
},
"updatedAt": {
"type": "string"
}
},
"required": [
"answerTraceRetentionDays",
"createdAt",
"evidenceCacheRetentionDays",
"id",
"inactiveProjectionRetentionDays",
"knowledgeSpaceId",
"parseArtifactVersions",
"rawDocumentRetentionDays",
"scope",
"sessionInactivityMinutes",
"tenantId",
"updatedAt"
]
},
"FailedQuery": {
"type": "object",
"properties": {
"createdAt": {
"type": "string",
"format": "date-time"
},
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"knowledgeSpaceId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"metadata": {
"type": "object",
"additionalProperties": {},
"default": {}
},
"mode": {
"type": "string",
"enum": [
"fast",
"deep",
"research",
"auto"
]
},
"query": {
"type": "string",
"minLength": 1
},
"status": {
"type": "string",
"enum": [
"pending-triage",
"triaged",
"pending-annotation",
"annotated",
"dismissed",
"promoted"
]
},
"trigger": {
"type": "string",
"enum": [
"no-retrieval-evidence",
"low-confidence",
"abstained"
]
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"createdAt",
"id",
"knowledgeSpaceId",
"mode",
"query",
"status",
"trigger",
"updatedAt"
]
},
"FailedQueryMetrics": {
"type": "object",
"properties": {
"byStatus": {
"type": "object",
"properties": {
"annotated": {
"type": "number"
},
"dismissed": {
"type": "number"
},
"pending-annotation": {
"type": "number"
},
"pending-triage": {
"type": "number"
},
"promoted": {
"type": "number"
},
"triaged": {
"type": "number"
}
},
"required": [
"annotated",
"dismissed",
"pending-annotation",
"pending-triage",
"promoted",
"triaged"
]
},
"promotionRate": {
"type": "number"
},
"total": {
"type": "number"
}
},
"required": [
"byStatus",
"promotionRate",
"total"
]
},
"FailedQueryTriageResult": {
"type": "object",
"properties": {
"triaged": {
"type": "number"
},
"verdicts": {
"type": "object",
"properties": {
"coverage-gap": {
"type": "number"
},
"irrelevant": {
"type": "number"
},
"retrieval-miss": {
"type": "number"
},
"uncertain": {
"type": "number"
}
},
"required": [
"coverage-gap",
"irrelevant",
"retrieval-miss",
"uncertain"
]
}
},
"required": [
"triaged",
"verdicts"
]
},
"FailedQueryClusters": {
"type": "object",
"properties": {
"clusters": {
"type": "array",
"items": {
"type": "object",
"properties": {
"clusterKey": {
"type": "string"
},
"count": {
"type": "number"
},
"failedQueryIds": {
"type": "array",
"items": {
"type": "string"
}
},
"representative": {
"$ref": "#/components/schemas/FailedQuery"
}
},
"required": [
"clusterKey",
"count",
"failedQueryIds",
"representative"
]
}
}
},
"required": [
"clusters"
]
},
"AgentWorkspaceSnapshot": {
"type": "object",
"properties": {
"commandLog": {
"type": "array",
"items": {
"type": "object",
"properties": {
"command": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"completedAt": {
"type": "string",
"format": "date-time"
},
"cost": {
"type": "object",
"additionalProperties": {}
},
"input": {
"type": "object",
"additionalProperties": {},
"default": {}
},
"outputSummary": {
"type": "string",
"maxLength": 4000
},
"startedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"command",
"startedAt"
],
"additionalProperties": false
}
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"evidenceBundles": {
"type": "array",
"items": {
"type": "object",
"properties": {
"createdAt": {
"type": "string",
"format": "date-time"
},
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"citations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"artifactHash": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"documentAssetId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"documentVersion": {
"type": "integer",
"exclusiveMinimum": 0
},
"endOffset": {
"type": "integer",
"minimum": 0
},
"pageNumber": {
"type": "integer",
"exclusiveMinimum": 0
},
"sectionPath": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"default": []
},
"startOffset": {
"type": "integer",
"minimum": 0
}
},
"required": [
"documentAssetId",
"documentVersion"
]
},
"minItems": 1
},
"conflicts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"severity": {
"type": "string",
"enum": [
"info",
"warning",
"blocking"
]
},
"withNodeId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
}
},
"required": [
"reason",
"severity"
]
},
"default": []
},
"freshness": {
"type": "object",
"properties": {
"observedAt": {
"type": "string",
"format": "date-time"
},
"sourceUpdatedAt": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string",
"enum": [
"fresh",
"stale",
"unknown"
]
}
},
"required": [
"status"
]
},
"metadata": {
"type": "object",
"additionalProperties": {},
"default": {}
},
"nodeId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"score": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"scores": {
"type": "object",
"properties": {
"final": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"freshness": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"rerank": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"retrieval": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"final",
"retrieval"
]
},
"text": {
"type": "string",
"minLength": 1
}
},
"required": [
"citations",
"freshness",
"nodeId",
"score",
"scores",
"text"
]
}
},
"missingEvidence": {
"type": "array",
"items": {
"type": "object",
"properties": {
"expectedEvidenceId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"metadata": {
"type": "object",
"additionalProperties": {},
"default": {}
},
"reason": {
"type": "string",
"enum": [
"not-retrieved",
"permission-filtered",
"stale",
"conflict",
"unknown"
]
},
"text": {
"type": "string",
"minLength": 1,
"maxLength": 4000
}
},
"required": [
"reason",
"text"
]
},
"default": []
},
"query": {
"type": "string"
},
"queryImages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"byteSize": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 10485760
},
"mimeType": {
"type": "string",
"enum": [
"image/gif",
"image/jpeg",
"image/png",
"image/webp"
]
},
"sha256": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"uploadFileId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
}
},
"required": [
"byteSize",
"mimeType",
"sha256",
"uploadFileId"
]
},
"maxItems": 4
},
"retrievalQuery": {
"type": "string",
"minLength": 1
},
"state": {
"type": "string",
"enum": [
"answerable",
"partial",
"not-enough-evidence",
"conflict",
"permission-limited"
]
},
"traceId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
}
},
"required": [
"createdAt",
"id",
"items",
"query",
"state"
]
}
},
"fingerprint": {
"type": "string",
"pattern": "^snapshot-sha256:[a-f0-9]{64}$"
},
"id": {
"type": "string",
"minLength": 1
},
"indexProjection": {
"type": "object",
"properties": {
"fingerprint": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"projectionIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 240
},
"default": []
}
},
"required": [
"fingerprint"
],
"additionalProperties": false
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"manifestVersion": {
"type": "integer",
"exclusiveMinimum": 0
},
"metadata": {
"type": "object",
"additionalProperties": {}
},
"mounts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"cachePolicy": {
"type": "object",
"properties": {
"maxBytes": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 1073741824
},
"strategy": {
"type": "string",
"enum": [
"none",
"memory",
"object-storage"
]
},
"ttlSeconds": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 86400
}
},
"default": {
"strategy": "none"
},
"required": [
"strategy"
]
},
"capabilities": {
"type": "array",
"items": {
"type": "string",
"enum": [
"ls",
"tree",
"cat",
"grep",
"find",
"stat",
"diff",
"sync",
"watch"
]
},
"default": []
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"freshnessPolicy": {
"type": "object",
"properties": {
"staleAfterSeconds": {
"type": "integer",
"exclusiveMinimum": 0
},
"strategy": {
"type": "string",
"enum": [
"realtime",
"ttl",
"manual",
"async"
]
}
},
"required": [
"strategy"
]
},
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"knowledgeSpaceId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"lastSyncedAt": {
"type": "string",
"format": "date-time"
},
"metadata": {
"type": "object",
"additionalProperties": {},
"default": {}
},
"mode": {
"type": "string",
"enum": [
"read",
"write",
"exec"
]
},
"mountPath": {
"type": "string",
"maxLength": 384,
"pattern": "^\\/(?:sources|knowledge|evidence|workspaces)(?:\\/[^/\\s]+)*$"
},
"permissionScope": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"default": []
},
"permissionSnapshotVersion": {
"type": "integer",
"exclusiveMinimum": 0
},
"provider": {
"type": "string",
"enum": [
"upload",
"object-storage",
"connector",
"web",
"database",
"github",
"slack",
"internal"
]
},
"resourceType": {
"type": "string",
"enum": [
"source",
"document",
"node",
"artifact",
"evidence",
"workspace"
]
},
"sourcePointer": {
"type": "string",
"minLength": 1
},
"tenantId": {
"type": "string",
"minLength": 1,
"maxLength": 255
}
},
"required": [
"createdAt",
"freshnessPolicy",
"id",
"knowledgeSpaceId",
"mode",
"mountPath",
"permissionSnapshotVersion",
"provider",
"resourceType",
"sourcePointer",
"tenantId"
]
}
},
"pathVersions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"virtualPath": {
"type": "string",
"minLength": 1,
"maxLength": 1000
}
},
"required": [
"version",
"virtualPath"
],
"additionalProperties": false
}
},
"researchTaskJobId": {
"type": "string"
},
"sourceVersions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"providerResourceKey": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"version": {
"type": "string",
"minLength": 1,
"maxLength": 512
}
},
"required": [
"provider",
"providerResourceKey",
"version"
],
"additionalProperties": false
}
},
"traceIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"commandLog",
"createdAt",
"evidenceBundles",
"fingerprint",
"id",
"indexProjection",
"knowledgeSpaceId",
"manifestVersion",
"metadata",
"mounts",
"pathVersions",
"sourceVersions",
"traceIds"
]
},
"AgentWorkspaceReplay": {
"type": "object",
"properties": {
"commands": {
"type": "array",
"items": {
"type": "object",
"properties": {
"command": {
"type": "string"
},
"commandIndex": {
"type": "integer",
"minimum": 0
},
"completedAt": {
"type": "string",
"format": "date-time"
},
"error": {
"type": "string"
},
"input": {
"type": "object",
"additionalProperties": {}
},
"originalOutputSummary": {
"type": "string"
},
"replayedOutputSummary": {
"type": "string"
},
"startedAt": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string",
"enum": [
"changed",
"failed",
"matched"
]
}
},
"required": [
"command",
"commandIndex",
"completedAt",
"input",
"startedAt",
"status"
],
"additionalProperties": false
}
},
"completedAt": {
"type": "string",
"format": "date-time"
},
"id": {
"type": "string",
"minLength": 1
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"snapshotId": {
"type": "string",
"minLength": 1
},
"startedAt": {
"type": "string",
"format": "date-time"
},
"summary": {
"type": "object",
"properties": {
"changed": {
"type": "integer",
"minimum": 0
},
"failed": {
"type": "integer",
"minimum": 0
},
"matched": {
"type": "integer",
"minimum": 0
},
"total": {
"type": "integer",
"minimum": 0
}
},
"required": [
"changed",
"failed",
"matched",
"total"
],
"additionalProperties": false
},
"traceId": {
"type": "string"
}
},
"required": [
"commands",
"completedAt",
"id",
"knowledgeSpaceId",
"snapshotId",
"startedAt",
"summary"
]
},
"ResearchTaskJob": {
"type": "object",
"properties": {
"budgetUsd": {
"type": "number",
"minimum": 0
},
"completedAt": {
"type": "number"
},
"cost": {
"type": "object",
"properties": {
"budgetExceeded": {
"type": "boolean"
},
"budgetUsd": {
"type": "number",
"minimum": 0
},
"entries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"costUsd": {
"type": "number",
"minimum": 0
},
"provider": {
"type": "string",
"minLength": 1
},
"recordedAt": {
"type": "number"
},
"step": {
"type": "string",
"minLength": 1
},
"usage": {
"type": "object",
"additionalProperties": {}
}
},
"required": [
"costUsd",
"provider",
"recordedAt",
"step",
"usage"
]
}
},
"totalUsd": {
"type": "number",
"minimum": 0
}
},
"required": [
"entries",
"totalUsd"
]
},
"createdAt": {
"type": "number"
},
"error": {
"type": "string"
},
"failure": {
"$ref": "#/components/schemas/KnowledgeFsPublicFailure"
},
"id": {
"type": "string",
"minLength": 1
},
"knowledgeSpaceId": {
"type": "string",
"minLength": 1
},
"limits": {
"type": "object",
"properties": {
"maxRetrievalSteps": {
"type": "integer",
"exclusiveMinimum": 0
},
"maxScannedResources": {
"type": "integer",
"exclusiveMinimum": 0
},
"maxToolCalls": {
"type": "integer",
"exclusiveMinimum": 0
},
"timeoutMs": {
"type": "integer",
"exclusiveMinimum": 0
}
}
},
"metadata": {
"type": "object",
"additionalProperties": {}
},
"mode": {
"type": "string",
"enum": [
"auto",
"deep",
"fast",
"research"
]
},
"query": {
"type": "string",
"minLength": 1
},
"stage": {
"type": "string",
"enum": [
"queued",
"planning",
"retrieving",
"analyzing",
"generating",
"paused",
"completed",
"failed",
"canceled"
]
},
"topK": {
"type": "integer",
"exclusiveMinimum": 0
},
"updatedAt": {
"type": "number"
}
},
"required": [
"cost",
"createdAt",
"id",
"knowledgeSpaceId",
"metadata",
"query",
"stage",
"updatedAt"
]
},
"ResearchTaskJobList": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResearchTaskJob"
}
},
"nextCursor": {
"type": "string"
}
},
"required": [
"items"
],
"additionalProperties": false
},
"ResearchTaskDryRunPlan": {
"type": "object",
"properties": {
"budget": {
"type": "object",
"properties": {
"budgetUsd": {
"type": "number",
"minimum": 0
},
"exceedsBudget": {
"type": "boolean"
},
"remainingBudgetUsd": {
"type": "number"
}
},
"required": [
"exceedsBudget"
]
},
"estimates": {
"type": "object",
"properties": {
"cacheHitProbability": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"costUsd": {
"type": "object",
"properties": {
"currency": {
"type": "string",
"enum": [
"USD"
]
},
"estimated": {
"type": "number",
"minimum": 0
},
"max": {
"type": "number",
"minimum": 0
},
"min": {
"type": "number",
"minimum": 0
}
},
"required": [
"currency",
"estimated",
"max",
"min"
]
},
"inputTokens": {
"type": "integer",
"minimum": 0
},
"latencyMs": {
"type": "object",
"properties": {
"p50": {
"type": "integer",
"minimum": 0
},
"p95": {
"type": "integer",
"minimum": 0
}
},
"required": [
"p50",
"p95"
]
},
"outputTokens": {
"type": "integer",
"minimum": 0
},
"retrievalSteps": {
"type": "integer",
"minimum": 0
},
"scannedResources": {
"type": "integer",
"minimum": 0
},
"toolCalls": {
"type": "integer",
"minimum": 0
},
"totalTokens": {
"type": "integer",
"minimum": 0
},
"workBounds": {
"type": "object",
"properties": {
"modelCalls": {
"type": "object",
"properties": {
"estimated": {
"type": "integer",
"minimum": 0
},
"max": {
"type": "integer",
"minimum": 0
},
"min": {
"type": "integer",
"minimum": 0
}
},
"required": [
"estimated",
"max",
"min"
]
},
"openedResources": {
"type": "object",
"properties": {
"estimated": {
"type": "integer",
"minimum": 0
},
"max": {
"type": "integer",
"minimum": 0
},
"min": {
"type": "integer",
"minimum": 0
}
},
"required": [
"estimated",
"max",
"min"
]
},
"retrievalSteps": {
"type": "object",
"properties": {
"estimated": {
"type": "integer",
"minimum": 0
},
"max": {
"type": "integer",
"minimum": 0
},
"min": {
"type": "integer",
"minimum": 0
}
},
"required": [
"estimated",
"max",
"min"
]
}
},
"required": [
"modelCalls",
"openedResources",
"retrievalSteps"
]
}
},
"required": [
"cacheHitProbability",
"costUsd",
"inputTokens",
"latencyMs",
"outputTokens",
"retrievalSteps",
"scannedResources",
"toolCalls",
"totalTokens"
]
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"query": {
"type": "string",
"minLength": 1
},
"retrievalPlan": {
"type": "object",
"properties": {
"denseTopK": {
"type": "integer",
"minimum": 0
},
"ftsTopK": {
"type": "integer",
"minimum": 0
},
"fusionLimit": {
"type": "integer",
"minimum": 0
},
"queryLanguage": {
"type": "string",
"enum": [
"cjk",
"latin",
"mixed-cjk-latin",
"other"
]
},
"requestedMode": {
"type": "string",
"enum": [
"auto",
"deep",
"fast",
"research"
]
},
"rerankCandidateLimit": {
"type": "integer",
"minimum": 0
},
"resolvedMode": {
"type": "string",
"enum": [
"deep",
"fast",
"research"
]
},
"strategyVersion": {
"type": "string",
"minLength": 1
},
"topK": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"denseTopK",
"ftsTopK",
"fusionLimit",
"queryLanguage",
"requestedMode",
"rerankCandidateLimit",
"resolvedMode",
"strategyVersion",
"topK"
]
},
"steps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"estimatedCostUsd": {
"type": "number",
"minimum": 0
},
"estimatedInputTokens": {
"type": "integer",
"minimum": 0
},
"estimatedLatencyMs": {
"type": "integer",
"minimum": 0
},
"estimatedOutputTokens": {
"type": "integer",
"minimum": 0
},
"estimatedToolCalls": {
"type": "integer",
"minimum": 0
},
"name": {
"type": "string",
"enum": [
"analyze",
"generate",
"inspect",
"plan",
"retrieve"
]
}
},
"required": [
"estimatedCostUsd",
"estimatedInputTokens",
"estimatedLatencyMs",
"estimatedOutputTokens",
"estimatedToolCalls",
"name"
]
}
},
"strategyVersion": {
"type": "string",
"enum": [
"research-dry-run-planner-v1"
]
}
},
"required": [
"budget",
"estimates",
"knowledgeSpaceId",
"query",
"retrievalPlan",
"steps",
"strategyVersion"
]
},
"ResearchTaskPartialResult": {
"type": "object",
"properties": {
"answer": {
"type": "string",
"minLength": 1,
"maxLength": 20000
},
"evidenceBundle": {
"type": "object",
"properties": {
"createdAt": {
"type": "string",
"format": "date-time"
},
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"citations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"artifactHash": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"documentAssetId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"documentVersion": {
"type": "integer",
"exclusiveMinimum": 0
},
"endOffset": {
"type": "integer",
"minimum": 0
},
"pageNumber": {
"type": "integer",
"exclusiveMinimum": 0
},
"sectionPath": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"default": []
},
"startOffset": {
"type": "integer",
"minimum": 0
}
},
"required": [
"documentAssetId",
"documentVersion"
]
},
"minItems": 1
},
"conflicts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"severity": {
"type": "string",
"enum": [
"info",
"warning",
"blocking"
]
},
"withNodeId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
}
},
"required": [
"reason",
"severity"
]
},
"default": []
},
"freshness": {
"type": "object",
"properties": {
"observedAt": {
"type": "string",
"format": "date-time"
},
"sourceUpdatedAt": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string",
"enum": [
"fresh",
"stale",
"unknown"
]
}
},
"required": [
"status"
]
},
"metadata": {
"type": "object",
"additionalProperties": {},
"default": {}
},
"nodeId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"score": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"scores": {
"type": "object",
"properties": {
"final": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"freshness": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"rerank": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"retrieval": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"final",
"retrieval"
]
},
"text": {
"type": "string",
"minLength": 1
}
},
"required": [
"citations",
"freshness",
"nodeId",
"score",
"scores",
"text"
]
}
},
"missingEvidence": {
"type": "array",
"items": {
"type": "object",
"properties": {
"expectedEvidenceId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"metadata": {
"type": "object",
"additionalProperties": {},
"default": {}
},
"reason": {
"type": "string",
"enum": [
"not-retrieved",
"permission-filtered",
"stale",
"conflict",
"unknown"
]
},
"text": {
"type": "string",
"minLength": 1,
"maxLength": 4000
}
},
"required": [
"reason",
"text"
]
},
"default": []
},
"query": {
"type": "string"
},
"queryImages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"byteSize": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 10485760
},
"mimeType": {
"type": "string",
"enum": [
"image/gif",
"image/jpeg",
"image/png",
"image/webp"
]
},
"sha256": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"uploadFileId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
}
},
"required": [
"byteSize",
"mimeType",
"sha256",
"uploadFileId"
]
},
"maxItems": 4
},
"retrievalQuery": {
"type": "string",
"minLength": 1
},
"state": {
"type": "string",
"enum": [
"answerable",
"partial",
"not-enough-evidence",
"conflict",
"permission-limited"
]
},
"traceId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
}
},
"required": [
"createdAt",
"id",
"items",
"query",
"state"
]
},
"knowledgeSpaceId": {
"type": "string",
"minLength": 1
},
"researchTaskJobId": {
"type": "string",
"minLength": 1
},
"sequence": {
"type": "integer",
"exclusiveMinimum": 0
},
"tenantId": {
"type": "string",
"minLength": 1
}
},
"required": [
"evidenceBundle",
"knowledgeSpaceId",
"researchTaskJobId",
"sequence",
"tenantId"
]
},
"ResearchTaskPartialResultList": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResearchTaskPartialResult"
}
},
"nextCursor": {
"type": "string"
}
},
"required": [
"items"
]
},
"TopicViewMaterializationResult": {
"type": "object",
"properties": {
"documentCount": {
"type": "integer",
"minimum": 0
},
"generatedVersion": {
"type": "string",
"minLength": 1
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"pathCount": {
"type": "integer",
"minimum": 0
},
"topicName": {
"type": "string",
"minLength": 1
},
"topicSlug": {
"type": "string",
"minLength": 1
}
},
"required": [
"documentCount",
"generatedVersion",
"knowledgeSpaceId",
"pathCount",
"topicName",
"topicSlug"
]
},
"SemanticEntityExtractionResult": {
"type": "object",
"properties": {
"entitiesExtracted": {
"type": "integer",
"minimum": 0
},
"extractionMode": {
"type": "string",
"enum": [
"provider"
]
},
"graphEntitiesIndexed": {
"type": "integer",
"minimum": 0
},
"graphRelationsIndexed": {
"type": "integer",
"minimum": 0
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"nodesScanned": {
"type": "integer",
"minimum": 0
},
"nodesUpdated": {
"type": "integer",
"minimum": 0
}
},
"required": [
"entitiesExtracted",
"extractionMode",
"graphEntitiesIndexed",
"graphRelationsIndexed",
"knowledgeSpaceId",
"nodesScanned",
"nodesUpdated"
]
},
"SemanticCommunityMaterializationResult": {
"type": "object",
"properties": {
"communityCount": {
"type": "integer",
"minimum": 0
},
"documentCount": {
"type": "integer",
"minimum": 0
},
"entityCount": {
"type": "integer",
"minimum": 0
},
"generatedVersion": {
"type": "string",
"minLength": 1
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"pathCount": {
"type": "integer",
"minimum": 0
}
},
"required": [
"communityCount",
"documentCount",
"entityCount",
"generatedVersion",
"knowledgeSpaceId",
"pathCount"
]
},
"BulkDocumentReindexResult": {
"type": "object",
"properties": {
"bulkJobId": {
"type": "string",
"minLength": 1
},
"items": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"asset": {
"$ref": "#/components/schemas/DocumentAsset"
},
"compilationJob": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"stage": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"stage"
]
},
"status": {
"type": "string",
"enum": [
"queued"
]
},
"statusUrl": {
"type": "string",
"minLength": 1
}
},
"required": [
"asset",
"compilationJob",
"status",
"statusUrl"
]
},
{
"type": "object",
"properties": {
"documentId": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string",
"enum": [
"pending"
]
}
},
"required": [
"documentId",
"status"
]
},
{
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 1
},
"documentId": {
"type": "string",
"format": "uuid"
},
"error": {
"type": "string",
"minLength": 1
},
"status": {
"type": "string",
"enum": [
"failed"
]
}
},
"required": [
"code",
"documentId",
"error",
"status"
]
},
{
"type": "object",
"properties": {
"documentId": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string",
"enum": [
"disabled",
"not_found"
]
}
},
"required": [
"documentId",
"status"
]
}
]
}
},
"total": {
"type": "integer",
"minimum": 0
}
},
"required": [
"bulkJobId",
"items",
"total"
]
},
"DocumentUploadAccepted": {
"type": "object",
"properties": {
"asset": {
"$ref": "#/components/schemas/DocumentAsset"
},
"assetStatusUrl": {
"type": "string",
"minLength": 1
},
"compilationJob": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"stage": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"stage"
]
},
"logicalDocument": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"id",
"revision"
]
},
"logicalDocumentId": {
"type": "string",
"format": "uuid"
},
"documentRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"statusUrl": {
"type": "string",
"minLength": 1
},
"status": {
"type": "string",
"enum": [
"accepted"
]
}
},
"required": [
"asset",
"compilationJob",
"logicalDocument",
"logicalDocumentId",
"documentRevision",
"statusUrl"
]
},
"BulkDocumentUploadAccepted": {
"type": "object",
"properties": {
"accepted": {
"type": "integer",
"minimum": 0
},
"bulkJobId": {
"type": "string",
"minLength": 1
},
"excluded": {
"type": "integer",
"minimum": 0
},
"items": {
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/DocumentUploadAccepted"
},
{
"type": "object",
"properties": {
"filename": {
"type": "string"
},
"index": {
"type": "integer",
"minimum": 0
},
"mimeType": {
"type": "string"
},
"reason": {
"type": "string",
"enum": [
"batch_byte_limit_exceeded",
"document_not_found",
"file_count_limit_exceeded",
"file_too_large",
"invalid_file",
"invalid_target",
"processing_failed",
"quota_exceeded",
"revision_conflict",
"unsupported_mime_type"
]
},
"sizeBytes": {
"type": "integer",
"minimum": 0
},
"status": {
"type": "string",
"enum": [
"excluded"
]
}
},
"required": [
"filename",
"index",
"mimeType",
"reason",
"sizeBytes",
"status"
]
}
]
}
},
"total": {
"type": "integer",
"minimum": 0
}
},
"required": [
"accepted",
"bulkJobId",
"excluded",
"items",
"total"
]
},
"SourceSyncPolicy": {
"type": "object",
"properties": {
"createdAt": {
"type": "string"
},
"customIntervalSeconds": {
"type": "integer"
},
"enabled": {
"type": "boolean"
},
"expectedSourceVersion": {
"type": "integer",
"minimum": 1
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"mode": {
"type": "string",
"enum": [
"manual",
"interval",
"custom"
]
},
"nextRunAt": {
"type": "string"
},
"revision": {
"type": "integer",
"minimum": 1
},
"sourceId": {
"type": "string",
"format": "uuid"
},
"updatedAt": {
"type": "string"
}
},
"required": [
"createdAt",
"enabled",
"expectedSourceVersion",
"id",
"knowledgeSpaceId",
"mode",
"revision",
"sourceId",
"updatedAt"
]
},
"Source": {
"type": "object",
"properties": {
"connectionId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"knowledgeSpaceId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"metadata": {
"type": "object",
"additionalProperties": {},
"description": "Source metadata with credentials and other secret-bearing fields removed"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"permissionScope": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"default": []
},
"status": {
"type": "string",
"enum": [
"active",
"syncing",
"error",
"disabled"
]
},
"type": {
"type": "string",
"enum": [
"upload",
"object-storage",
"connector",
"web"
]
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"uri": {
"type": "string",
"minLength": 1
},
"version": {
"type": "integer",
"minimum": 1,
"default": 1
},
"credentialConfigured": {
"type": "boolean",
"description": "True when credentials exist; the opaque SecretStore reference is never exposed"
},
"lastSyncedAt": {
"type": "string"
},
"syncPolicy": {
"$ref": "#/components/schemas/SourceSyncPolicy"
}
},
"required": [
"createdAt",
"id",
"knowledgeSpaceId",
"metadata",
"name",
"status",
"type",
"updatedAt",
"uri"
]
},
"SourceWorkflowRun": {
"type": "object",
"properties": {
"canceledAt": {
"type": "string"
},
"checkpoint": {
"type": "string"
},
"completedAt": {
"type": "string"
},
"createdAt": {
"type": "string"
},
"cursor": {
"type": "string"
},
"executionAttempts": {
"type": "integer"
},
"failure": {
"$ref": "#/components/schemas/KnowledgeFsPublicFailure"
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string"
},
"lastErrorCode": {
"type": "string",
"enum": [
"VECTOR_SPACE_QUOTA_EXCEEDED",
"VECTOR_SPACE_QUOTA_UNAVAILABLE",
"DOCUMENT_COUNT_QUOTA_EXCEEDED",
"DOCUMENT_COUNT_QUOTA_UNAVAILABLE",
"LOGICAL_DOCUMENT_CAS_CONFLICT",
"DURABLE_DELETION_IDEMPOTENCY_CONFLICT",
"SOURCE_VERSION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_COMPILATION_IN_PROGRESS",
"KNOWLEDGE_SPACE_SETTINGS_REVISION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_MIGRATION_REQUIRED",
"DOCUMENT_COMPILATION_PROFILE_CHANGED",
"DOCUMENT_COMPILATION_FAILED",
"DOCUMENT_COMPILATION_RETRYABLE",
"DOCUMENT_COMPILATION_LEASE_LOST",
"DOCUMENT_DISABLED",
"DOCUMENT_PARSER_INPUT_INVALID",
"DOCUMENT_PARSER_NOT_CONFIGURED",
"DOCUMENT_PARSER_RATE_LIMITED",
"DOCUMENT_PARSER_RESPONSE_INVALID",
"DOCUMENT_PARSER_TIMEOUT",
"DOCUMENT_PARSER_UNAVAILABLE",
"DOCUMENT_PARSER_UNSUPPORTED_TYPE",
"DOCUMENT_PDF_RENDER_FAILED",
"EMBEDDING_DIMENSION_INVALID",
"EMBEDDING_DIMENSION_UNSUPPORTED",
"EXECUTION_ATTEMPTS_EXHAUSTED",
"KNOWLEDGE_FS_ACCESS_DENIED",
"KNOWLEDGE_FS_CONFLICT",
"KNOWLEDGE_FS_INTERNAL_ERROR",
"KNOWLEDGE_FS_INVALID_REQUEST",
"KNOWLEDGE_FS_NOT_FOUND",
"KNOWLEDGE_FS_RATE_LIMITED",
"KNOWLEDGE_FS_TIMEOUT",
"KNOWLEDGE_FS_UNAVAILABLE",
"KNOWLEDGE_SPACE_MANIFEST_NOT_FOUND",
"KNOWLEDGE_SPACE_MODEL_CONFIGURATION_REQUIRED",
"MODEL_CAPABILITY_MISMATCH",
"MODEL_CONFIGURATION_STALE",
"MODEL_CREDENTIAL_INVALID",
"MODEL_CREDENTIAL_VALIDATION_UNAVAILABLE",
"MODEL_IDENTITY_MISMATCH",
"MODEL_PREFLIGHT_CANCELED",
"MODEL_PREFLIGHT_FAILED",
"MODEL_PREFLIGHT_TIMEOUT",
"MODEL_PREFLIGHT_UNAVAILABLE",
"MODEL_PROFILE_ACTIVATION_INCOMPLETE",
"MODEL_PROFILE_ACTIVATION_PERMISSION_REQUIRED",
"MODEL_RUNTIME_FAILED",
"MODEL_RUNTIME_RESPONSE_INVALID",
"MODEL_RUNTIME_OUTPUT_LIMIT",
"MODEL_RUNTIME_CONTEXT_LIMIT",
"MODEL_RUNTIME_TIMEOUT",
"MODEL_RUNTIME_UNAVAILABLE",
"MODEL_SELECTION_NOT_FOUND",
"RESEARCH_TASK_CAPABILITY_REVOKED",
"RESEARCH_TASK_DISPATCH_DEAD",
"RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED",
"RESEARCH_TASK_FAILED",
"RESEARCH_TASK_PERMISSION_SNAPSHOT_INVALID",
"RESEARCH_TASK_RUNTIME_SNAPSHOT_INVALID",
"RETRIEVAL_DELETION_IN_PROGRESS",
"RETRIEVAL_EXECUTION_LEASE_LOST",
"SOURCE_BULK_ACTION_FAILED",
"SOURCE_CONNECTION_UNAVAILABLE",
"SOURCE_CRAWL_PAGE_NOT_FOUND",
"SOURCE_CRAWL_PROVIDER_UNAVAILABLE",
"SOURCE_CRAWL_RESULT_LIMIT_EXCEEDED",
"SOURCE_CREDENTIAL_CONFIG_INVALID",
"SOURCE_CREDENTIAL_MUTATION_FAILED",
"SOURCE_CREDENTIAL_TEST_FAILED",
"SOURCE_CREDENTIAL_UNAVAILABLE",
"SOURCE_DOCUMENT_COMPILATION_FAILED",
"SOURCE_DOCUMENT_MATERIALIZATION_FAILED",
"SOURCE_DOCUMENT_REPLACEMENT_SAGA_REQUIRED",
"SOURCE_IMPORT_PARTIAL_FAILURE",
"SOURCE_ONLINE_DOCUMENT_CONFIG_INVALID",
"SOURCE_ONLINE_DOCUMENT_IMPORT_FAILED",
"SOURCE_ONLINE_DOCUMENT_PAGE_FETCH_FAILED",
"SOURCE_ONLINE_DOCUMENT_REQUEST_FAILED",
"SOURCE_ONLINE_DOCUMENT_UNAVAILABLE",
"SOURCE_ONLINE_DRIVE_CONFIG_INVALID",
"SOURCE_ONLINE_DRIVE_FILE_DOWNLOAD_FAILED",
"SOURCE_ONLINE_DRIVE_IMPORT_FAILED",
"SOURCE_ONLINE_DRIVE_REQUEST_FAILED",
"SOURCE_ONLINE_DRIVE_UNAVAILABLE",
"SOURCE_OPERATION_FAILED",
"SOURCE_PROVIDER_REJECTED",
"SOURCE_PROVIDER_TIMEOUT",
"SOURCE_PROVIDER_UNAVAILABLE",
"SOURCE_SYNC_SELECTION_MISMATCH",
"SOURCE_SECRET_INTEGRITY_FAILED",
"SOURCE_SECRET_REF_CONFLICT",
"SOURCE_SYNC_FAILED",
"SOURCE_WEBSITE_CRAWL_CONFIG_INVALID",
"SOURCE_WEBSITE_CRAWL_FAILED",
"SOURCE_WORKFLOW_FAILED",
"SOURCE_WORKFLOW_CONTENT_MISSING",
"SOURCE_WORKFLOW_CONTENT_TOO_LARGE",
"SOURCE_WORKFLOW_EXTERNAL_TIMEOUT",
"UPLOAD_INITIALIZATION_FAILED",
"UPLOAD_INTEGRITY_MISMATCH"
]
},
"maxExecutionAttempts": {
"type": "integer"
},
"progressCompleted": {
"type": "integer"
},
"progressFailed": {
"type": "integer"
},
"progressSkipped": {
"type": "integer"
},
"progressTotal": {
"type": "integer"
},
"sourceId": {
"type": "string",
"format": "uuid"
},
"state": {
"type": "string"
},
"updatedAt": {
"type": "string"
}
},
"required": [
"checkpoint",
"createdAt",
"executionAttempts",
"id",
"knowledgeSpaceId",
"kind",
"maxExecutionAttempts",
"progressCompleted",
"progressFailed",
"progressSkipped",
"state",
"updatedAt"
]
},
"WebsiteCrawlResult": {
"type": "object",
"properties": {
"completed": {
"type": "number"
},
"failed": {
"type": "number"
},
"imported": {
"type": "number"
},
"pages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"content": {
"type": "string"
},
"description": {
"type": "string"
},
"sourceUrl": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"content",
"sourceUrl"
]
}
},
"replaced": {
"type": "number"
},
"skipped": {
"type": "number"
},
"status": {
"type": "string"
},
"total": {
"type": "number"
}
},
"required": [
"pages"
]
},
"OnlineDocumentPages": {
"type": "object",
"properties": {
"nextCursor": {
"type": "string"
},
"workspaces": {
"type": "array",
"items": {
"type": "object",
"properties": {
"pages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"lastEditedTime": {
"type": "string"
},
"pageId": {
"type": "string"
},
"pageName": {
"type": "string"
},
"parentId": {
"type": "string"
},
"type": {
"type": "string"
}
},
"required": [
"pageId",
"pageName",
"type"
]
}
},
"total": {
"type": "number"
},
"workspaceId": {
"type": "string"
},
"workspaceName": {
"type": "string"
}
},
"required": [
"pages"
]
}
}
},
"required": [
"workspaces"
]
},
"SourceImportResult": {
"type": "object",
"properties": {
"documents": {
"type": "array",
"items": {
"type": "object",
"properties": {
"documentAssetId": {
"type": "string"
},
"filename": {
"type": "string"
}
},
"required": [
"documentAssetId",
"filename"
]
}
},
"failed": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"VECTOR_SPACE_QUOTA_EXCEEDED",
"VECTOR_SPACE_QUOTA_UNAVAILABLE",
"DOCUMENT_COUNT_QUOTA_EXCEEDED",
"DOCUMENT_COUNT_QUOTA_UNAVAILABLE",
"LOGICAL_DOCUMENT_CAS_CONFLICT",
"DURABLE_DELETION_IDEMPOTENCY_CONFLICT",
"SOURCE_VERSION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_COMPILATION_IN_PROGRESS",
"KNOWLEDGE_SPACE_SETTINGS_REVISION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_MIGRATION_REQUIRED",
"DOCUMENT_COMPILATION_PROFILE_CHANGED",
"DOCUMENT_COMPILATION_FAILED",
"DOCUMENT_COMPILATION_RETRYABLE",
"DOCUMENT_COMPILATION_LEASE_LOST",
"DOCUMENT_DISABLED",
"DOCUMENT_PARSER_INPUT_INVALID",
"DOCUMENT_PARSER_NOT_CONFIGURED",
"DOCUMENT_PARSER_RATE_LIMITED",
"DOCUMENT_PARSER_RESPONSE_INVALID",
"DOCUMENT_PARSER_TIMEOUT",
"DOCUMENT_PARSER_UNAVAILABLE",
"DOCUMENT_PARSER_UNSUPPORTED_TYPE",
"DOCUMENT_PDF_RENDER_FAILED",
"EMBEDDING_DIMENSION_INVALID",
"EMBEDDING_DIMENSION_UNSUPPORTED",
"EXECUTION_ATTEMPTS_EXHAUSTED",
"KNOWLEDGE_FS_ACCESS_DENIED",
"KNOWLEDGE_FS_CONFLICT",
"KNOWLEDGE_FS_INTERNAL_ERROR",
"KNOWLEDGE_FS_INVALID_REQUEST",
"KNOWLEDGE_FS_NOT_FOUND",
"KNOWLEDGE_FS_RATE_LIMITED",
"KNOWLEDGE_FS_TIMEOUT",
"KNOWLEDGE_FS_UNAVAILABLE",
"KNOWLEDGE_SPACE_MANIFEST_NOT_FOUND",
"KNOWLEDGE_SPACE_MODEL_CONFIGURATION_REQUIRED",
"MODEL_CAPABILITY_MISMATCH",
"MODEL_CONFIGURATION_STALE",
"MODEL_CREDENTIAL_INVALID",
"MODEL_CREDENTIAL_VALIDATION_UNAVAILABLE",
"MODEL_IDENTITY_MISMATCH",
"MODEL_PREFLIGHT_CANCELED",
"MODEL_PREFLIGHT_FAILED",
"MODEL_PREFLIGHT_TIMEOUT",
"MODEL_PREFLIGHT_UNAVAILABLE",
"MODEL_PROFILE_ACTIVATION_INCOMPLETE",
"MODEL_PROFILE_ACTIVATION_PERMISSION_REQUIRED",
"MODEL_RUNTIME_FAILED",
"MODEL_RUNTIME_RESPONSE_INVALID",
"MODEL_RUNTIME_OUTPUT_LIMIT",
"MODEL_RUNTIME_CONTEXT_LIMIT",
"MODEL_RUNTIME_TIMEOUT",
"MODEL_RUNTIME_UNAVAILABLE",
"MODEL_SELECTION_NOT_FOUND",
"RESEARCH_TASK_CAPABILITY_REVOKED",
"RESEARCH_TASK_DISPATCH_DEAD",
"RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED",
"RESEARCH_TASK_FAILED",
"RESEARCH_TASK_PERMISSION_SNAPSHOT_INVALID",
"RESEARCH_TASK_RUNTIME_SNAPSHOT_INVALID",
"RETRIEVAL_DELETION_IN_PROGRESS",
"RETRIEVAL_EXECUTION_LEASE_LOST",
"SOURCE_BULK_ACTION_FAILED",
"SOURCE_CONNECTION_UNAVAILABLE",
"SOURCE_CRAWL_PAGE_NOT_FOUND",
"SOURCE_CRAWL_PROVIDER_UNAVAILABLE",
"SOURCE_CRAWL_RESULT_LIMIT_EXCEEDED",
"SOURCE_CREDENTIAL_CONFIG_INVALID",
"SOURCE_CREDENTIAL_MUTATION_FAILED",
"SOURCE_CREDENTIAL_TEST_FAILED",
"SOURCE_CREDENTIAL_UNAVAILABLE",
"SOURCE_DOCUMENT_COMPILATION_FAILED",
"SOURCE_DOCUMENT_MATERIALIZATION_FAILED",
"SOURCE_DOCUMENT_REPLACEMENT_SAGA_REQUIRED",
"SOURCE_IMPORT_PARTIAL_FAILURE",
"SOURCE_ONLINE_DOCUMENT_CONFIG_INVALID",
"SOURCE_ONLINE_DOCUMENT_IMPORT_FAILED",
"SOURCE_ONLINE_DOCUMENT_PAGE_FETCH_FAILED",
"SOURCE_ONLINE_DOCUMENT_REQUEST_FAILED",
"SOURCE_ONLINE_DOCUMENT_UNAVAILABLE",
"SOURCE_ONLINE_DRIVE_CONFIG_INVALID",
"SOURCE_ONLINE_DRIVE_FILE_DOWNLOAD_FAILED",
"SOURCE_ONLINE_DRIVE_IMPORT_FAILED",
"SOURCE_ONLINE_DRIVE_REQUEST_FAILED",
"SOURCE_ONLINE_DRIVE_UNAVAILABLE",
"SOURCE_OPERATION_FAILED",
"SOURCE_PROVIDER_REJECTED",
"SOURCE_PROVIDER_TIMEOUT",
"SOURCE_PROVIDER_UNAVAILABLE",
"SOURCE_SYNC_SELECTION_MISMATCH",
"SOURCE_SECRET_INTEGRITY_FAILED",
"SOURCE_SECRET_REF_CONFLICT",
"SOURCE_SYNC_FAILED",
"SOURCE_WEBSITE_CRAWL_CONFIG_INVALID",
"SOURCE_WEBSITE_CRAWL_FAILED",
"SOURCE_WORKFLOW_FAILED",
"SOURCE_WORKFLOW_CONTENT_MISSING",
"SOURCE_WORKFLOW_CONTENT_TOO_LARGE",
"SOURCE_WORKFLOW_EXTERNAL_TIMEOUT",
"UPLOAD_INITIALIZATION_FAILED",
"UPLOAD_INTEGRITY_MISMATCH"
]
},
"error": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"failure": {
"$ref": "#/components/schemas/KnowledgeFsPublicFailure"
},
"filename": {
"type": "string"
}
},
"required": [
"code",
"error",
"failure",
"filename"
]
}
},
"skipped": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"documents",
"failed",
"skipped"
]
},
"SourceCredentialTest": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"VECTOR_SPACE_QUOTA_EXCEEDED",
"VECTOR_SPACE_QUOTA_UNAVAILABLE",
"DOCUMENT_COUNT_QUOTA_EXCEEDED",
"DOCUMENT_COUNT_QUOTA_UNAVAILABLE",
"LOGICAL_DOCUMENT_CAS_CONFLICT",
"DURABLE_DELETION_IDEMPOTENCY_CONFLICT",
"SOURCE_VERSION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_COMPILATION_IN_PROGRESS",
"KNOWLEDGE_SPACE_SETTINGS_REVISION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_MIGRATION_REQUIRED",
"DOCUMENT_COMPILATION_PROFILE_CHANGED",
"DOCUMENT_COMPILATION_FAILED",
"DOCUMENT_COMPILATION_RETRYABLE",
"DOCUMENT_COMPILATION_LEASE_LOST",
"DOCUMENT_DISABLED",
"DOCUMENT_PARSER_INPUT_INVALID",
"DOCUMENT_PARSER_NOT_CONFIGURED",
"DOCUMENT_PARSER_RATE_LIMITED",
"DOCUMENT_PARSER_RESPONSE_INVALID",
"DOCUMENT_PARSER_TIMEOUT",
"DOCUMENT_PARSER_UNAVAILABLE",
"DOCUMENT_PARSER_UNSUPPORTED_TYPE",
"DOCUMENT_PDF_RENDER_FAILED",
"EMBEDDING_DIMENSION_INVALID",
"EMBEDDING_DIMENSION_UNSUPPORTED",
"EXECUTION_ATTEMPTS_EXHAUSTED",
"KNOWLEDGE_FS_ACCESS_DENIED",
"KNOWLEDGE_FS_CONFLICT",
"KNOWLEDGE_FS_INTERNAL_ERROR",
"KNOWLEDGE_FS_INVALID_REQUEST",
"KNOWLEDGE_FS_NOT_FOUND",
"KNOWLEDGE_FS_RATE_LIMITED",
"KNOWLEDGE_FS_TIMEOUT",
"KNOWLEDGE_FS_UNAVAILABLE",
"KNOWLEDGE_SPACE_MANIFEST_NOT_FOUND",
"KNOWLEDGE_SPACE_MODEL_CONFIGURATION_REQUIRED",
"MODEL_CAPABILITY_MISMATCH",
"MODEL_CONFIGURATION_STALE",
"MODEL_CREDENTIAL_INVALID",
"MODEL_CREDENTIAL_VALIDATION_UNAVAILABLE",
"MODEL_IDENTITY_MISMATCH",
"MODEL_PREFLIGHT_CANCELED",
"MODEL_PREFLIGHT_FAILED",
"MODEL_PREFLIGHT_TIMEOUT",
"MODEL_PREFLIGHT_UNAVAILABLE",
"MODEL_PROFILE_ACTIVATION_INCOMPLETE",
"MODEL_PROFILE_ACTIVATION_PERMISSION_REQUIRED",
"MODEL_RUNTIME_FAILED",
"MODEL_RUNTIME_RESPONSE_INVALID",
"MODEL_RUNTIME_OUTPUT_LIMIT",
"MODEL_RUNTIME_CONTEXT_LIMIT",
"MODEL_RUNTIME_TIMEOUT",
"MODEL_RUNTIME_UNAVAILABLE",
"MODEL_SELECTION_NOT_FOUND",
"RESEARCH_TASK_CAPABILITY_REVOKED",
"RESEARCH_TASK_DISPATCH_DEAD",
"RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED",
"RESEARCH_TASK_FAILED",
"RESEARCH_TASK_PERMISSION_SNAPSHOT_INVALID",
"RESEARCH_TASK_RUNTIME_SNAPSHOT_INVALID",
"RETRIEVAL_DELETION_IN_PROGRESS",
"RETRIEVAL_EXECUTION_LEASE_LOST",
"SOURCE_BULK_ACTION_FAILED",
"SOURCE_CONNECTION_UNAVAILABLE",
"SOURCE_CRAWL_PAGE_NOT_FOUND",
"SOURCE_CRAWL_PROVIDER_UNAVAILABLE",
"SOURCE_CRAWL_RESULT_LIMIT_EXCEEDED",
"SOURCE_CREDENTIAL_CONFIG_INVALID",
"SOURCE_CREDENTIAL_MUTATION_FAILED",
"SOURCE_CREDENTIAL_TEST_FAILED",
"SOURCE_CREDENTIAL_UNAVAILABLE",
"SOURCE_DOCUMENT_COMPILATION_FAILED",
"SOURCE_DOCUMENT_MATERIALIZATION_FAILED",
"SOURCE_DOCUMENT_REPLACEMENT_SAGA_REQUIRED",
"SOURCE_IMPORT_PARTIAL_FAILURE",
"SOURCE_ONLINE_DOCUMENT_CONFIG_INVALID",
"SOURCE_ONLINE_DOCUMENT_IMPORT_FAILED",
"SOURCE_ONLINE_DOCUMENT_PAGE_FETCH_FAILED",
"SOURCE_ONLINE_DOCUMENT_REQUEST_FAILED",
"SOURCE_ONLINE_DOCUMENT_UNAVAILABLE",
"SOURCE_ONLINE_DRIVE_CONFIG_INVALID",
"SOURCE_ONLINE_DRIVE_FILE_DOWNLOAD_FAILED",
"SOURCE_ONLINE_DRIVE_IMPORT_FAILED",
"SOURCE_ONLINE_DRIVE_REQUEST_FAILED",
"SOURCE_ONLINE_DRIVE_UNAVAILABLE",
"SOURCE_OPERATION_FAILED",
"SOURCE_PROVIDER_REJECTED",
"SOURCE_PROVIDER_TIMEOUT",
"SOURCE_PROVIDER_UNAVAILABLE",
"SOURCE_SYNC_SELECTION_MISMATCH",
"SOURCE_SECRET_INTEGRITY_FAILED",
"SOURCE_SECRET_REF_CONFLICT",
"SOURCE_SYNC_FAILED",
"SOURCE_WEBSITE_CRAWL_CONFIG_INVALID",
"SOURCE_WEBSITE_CRAWL_FAILED",
"SOURCE_WORKFLOW_FAILED",
"SOURCE_WORKFLOW_CONTENT_MISSING",
"SOURCE_WORKFLOW_CONTENT_TOO_LARGE",
"SOURCE_WORKFLOW_EXTERNAL_TIMEOUT",
"UPLOAD_INITIALIZATION_FAILED",
"UPLOAD_INTEGRITY_MISMATCH"
]
},
"error": {
"type": "string"
},
"failure": {
"$ref": "#/components/schemas/KnowledgeFsPublicFailure"
},
"valid": {
"type": "boolean"
}
},
"required": [
"valid"
]
},
"OnlineDriveFiles": {
"type": "object",
"properties": {
"buckets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"bucket": {
"type": "string"
},
"continuationToken": {
"type": "string"
},
"files": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"size": {
"type": "number"
},
"type": {
"type": "string"
}
},
"required": [
"id",
"name",
"type"
]
}
},
"isTruncated": {
"type": "boolean"
}
},
"required": [
"files"
]
}
}
},
"required": [
"buckets"
]
}
},
"parameters": {}
},
"paths": {
"/health": {
"get": {
"operationId": "getHealth",
"security": [],
"responses": {
"200": {
"description": "Platform component health",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"runtime": {
"type": "string",
"enum": [
"cloudflare-workers",
"node-docker"
]
},
"components": {
"type": "object",
"additionalProperties": {
"type": "boolean"
}
}
},
"required": [
"ok",
"runtime",
"components"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"parameters": [
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"x-knowledge-fs-max-response-bytes": 1048576
}
},
"/ready": {
"get": {
"operationId": "getReadiness",
"security": [],
"responses": {
"200": {
"description": "Deployment is ready to receive traffic",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"runtime": {
"type": "string",
"enum": [
"cloudflare-workers",
"node-docker"
]
},
"components": {
"type": "object",
"additionalProperties": {
"type": "boolean"
}
}
},
"required": [
"ok",
"runtime",
"components"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Deployment is not ready to receive traffic",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"runtime": {
"type": "string",
"enum": [
"cloudflare-workers",
"node-docker"
]
},
"components": {
"type": "object",
"additionalProperties": {
"type": "boolean"
}
}
},
"required": [
"ok",
"runtime",
"components"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"parameters": [
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"x-knowledge-fs-max-response-bytes": 1048576
}
},
"/internal/dify-integration/freeze": {
"post": {
"operationId": "freezeDifyWorkspaceIntegration",
"tags": [
"Internal Dify Integration"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"freezeId": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$"
},
"freezeRevision": {
"type": "integer",
"exclusiveMinimum": 0,
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"sourceRevisionDigest": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$"
},
"sourceTaskWatermark": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"freezeId",
"freezeRevision",
"sourceRevisionDigest",
"sourceTaskWatermark"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Persisted or replayed Dify Workspace maintenance freeze",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"freezeId": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$"
},
"freezeRevision": {
"type": "integer",
"exclusiveMinimum": 0,
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"sourceRevisionDigest": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$"
},
"sourceTaskWatermark": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"applied": {
"type": "boolean"
},
"frozen": {
"type": "boolean",
"enum": [
true
]
},
"frozenAt": {
"type": "string",
"format": "date-time"
},
"namespaceId": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"replayed": {
"type": "boolean"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"freezeId",
"freezeRevision",
"sourceRevisionDigest",
"sourceTaskWatermark",
"applied",
"frozen",
"frozenAt",
"namespaceId",
"replayed",
"updatedAt"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "The Capability is not the exact internal freeze grant",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "The freeze revision or evidence conflicts with durable state",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"parameters": [
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/internal/dify-integration/activate": {
"post": {
"operationId": "activateDifyWorkspaceIntegration",
"tags": [
"Internal Dify Integration"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"activationId": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$"
},
"activationRevision": {
"type": "integer",
"exclusiveMinimum": 0,
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"sourceRevisionDigest": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$"
}
},
"required": [
"activationId",
"activationRevision",
"sourceRevisionDigest"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Persisted or replayed monotonic Dify Workspace integration activation",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"activationId": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$"
},
"activationRevision": {
"type": "integer",
"exclusiveMinimum": 0,
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"sourceRevisionDigest": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$"
},
"activatedAt": {
"type": "string",
"format": "date-time"
},
"active": {
"type": "boolean",
"enum": [
true
]
},
"applied": {
"type": "boolean"
},
"namespaceId": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"replayed": {
"type": "boolean"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"activationId",
"activationRevision",
"sourceRevisionDigest",
"activatedAt",
"active",
"applied",
"namespaceId",
"replayed",
"updatedAt"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "The Capability is not the exact internal activation grant",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "The activation revision or evidence conflicts with durable state",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"parameters": [
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/internal/capability-grants/{grantId}/revoke": {
"post": {
"operationId": "revokeCapabilityGrant",
"tags": [
"Internal Capability Revocation"
],
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "grantId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"eventId": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"reasonCode": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-z0-9_.:-]+$"
},
"revokeSequence": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"eventId",
"knowledgeSpaceId",
"reasonCode",
"revokeSequence"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Applied or idempotently observed a monotonic grant revoke",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"applied": {
"type": "boolean"
},
"highestRevokeSequence": {
"type": "integer",
"minimum": 0
},
"state": {
"type": "string",
"enum": [
"active",
"revoked"
]
}
},
"required": [
"applied",
"highestRevokeSequence",
"state"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "The event conflicts with prior monotonic authorization state",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/internal/knowledge-spaces/{id}/capability-fence": {
"post": {
"operationId": "fenceCapabilityKnowledgeSpace",
"tags": [
"Internal Capability Revocation"
],
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"eventId": {
"type": "string",
"format": "uuid"
},
"reasonCode": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-z0-9_.:-]+$"
},
"revokeSequence": {
"type": "integer",
"exclusiveMinimum": 0
},
"tombstoned": {
"type": "boolean"
}
},
"required": [
"eventId",
"reasonCode",
"revokeSequence",
"tombstoned"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Applied or idempotently observed a monotonic Space publication fence",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"applied": {
"type": "boolean"
},
"highestRevokeSequence": {
"type": "integer",
"minimum": 0
},
"tombstoned": {
"type": "boolean"
}
},
"required": [
"applied",
"highestRevokeSequence",
"tombstoned"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "The event conflicts with prior monotonic authorization state",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/upload-sessions": {
"post": {
"operationId": "createUploadSession",
"tags": [
"Upload Sessions"
],
"parameters": [
{
"schema": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"checksumSha256Base64": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"contentType": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"expectedSizeBytes": {
"type": "integer",
"exclusiveMinimum": 0
},
"fileName": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"maxLength": 255
}
},
"required": [
"checksumSha256Base64",
"contentType",
"expectedSizeBytes",
"fileName",
"idempotencyKey"
],
"additionalProperties": false
}
}
}
},
"responses": {
"201": {
"description": "Created or replayed a quota-reserved upload session",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"session": {
"type": "object",
"properties": {
"compilationJobId": {
"type": "string"
},
"completedAt": {
"type": "integer",
"minimum": 0
},
"documentAssetId": {
"type": "string"
},
"expectedSizeBytes": {
"type": "integer",
"exclusiveMinimum": 0
},
"expiresAt": {
"type": "integer",
"minimum": 0
},
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"mode": {
"type": "string",
"enum": [
"single",
"multipart",
"small_fallback"
]
},
"multipartPartCount": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"multipartPartSizeBytes": {
"type": "integer",
"exclusiveMinimum": 0
},
"status": {
"type": "string",
"enum": [
"creating",
"ready",
"completing",
"completed",
"aborting",
"aborted",
"expired",
"failed"
]
}
},
"required": [
"expectedSizeBytes",
"expiresAt",
"id",
"mode",
"status"
],
"additionalProperties": false
},
"upload": {
"type": "object",
"properties": {
"expiresAt": {
"type": "integer",
"minimum": 0
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"method": {
"type": "string",
"enum": [
"PUT"
]
},
"url": {
"type": "string",
"format": "uri"
}
},
"required": [
"expiresAt",
"headers",
"method",
"url"
],
"additionalProperties": false
}
},
"required": [
"session"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Upload session not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Upload session state or idempotency conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"413": {
"description": "Upload exceeds the configured bound or quota",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"422": {
"description": "Uploaded object failed integrity verification",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Direct object upload is unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/upload-sessions/{id}/parts/{partNumber}/presign": {
"post": {
"operationId": "presignUploadSessionPart",
"tags": [
"Upload Sessions"
],
"parameters": [
{
"schema": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"required": true,
"name": "partNumber",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"knowledgeSpaceId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"checksumSha256Base64": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"contentLength": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"knowledgeSpaceId",
"checksumSha256Base64",
"contentLength"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Short-lived URL for one deterministic multipart part",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"expiresAt": {
"type": "integer",
"minimum": 0
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"method": {
"type": "string",
"enum": [
"PUT"
]
},
"url": {
"type": "string",
"format": "uri"
}
},
"required": [
"expiresAt",
"headers",
"method",
"url"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Upload session not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Upload session state or idempotency conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"413": {
"description": "Upload exceeds the configured bound or quota",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"422": {
"description": "Uploaded object failed integrity verification",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Direct object upload is unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/upload-sessions/{id}/small-file": {
"post": {
"operationId": "uploadSmallFile",
"tags": [
"Upload Sessions"
],
"parameters": [
{
"schema": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"required": true,
"name": "knowledgeSpaceId",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"responses": {
"200": {
"description": "Uploaded and completed a strictly bounded small-file fallback",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"session": {
"type": "object",
"properties": {
"compilationJobId": {
"type": "string"
},
"completedAt": {
"type": "integer",
"minimum": 0
},
"documentAssetId": {
"type": "string"
},
"expectedSizeBytes": {
"type": "integer",
"exclusiveMinimum": 0
},
"expiresAt": {
"type": "integer",
"minimum": 0
},
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"mode": {
"type": "string",
"enum": [
"single",
"multipart",
"small_fallback"
]
},
"multipartPartCount": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"multipartPartSizeBytes": {
"type": "integer",
"exclusiveMinimum": 0
},
"status": {
"type": "string",
"enum": [
"creating",
"ready",
"completing",
"completed",
"aborting",
"aborted",
"expired",
"failed"
]
}
},
"required": [
"expectedSizeBytes",
"expiresAt",
"id",
"mode",
"status"
],
"additionalProperties": false
}
},
"required": [
"session"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Upload session not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"408": {
"description": "Small-file request body timed out",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Upload session state or idempotency conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"413": {
"description": "Upload exceeds the configured bound or quota",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"422": {
"description": "Uploaded object failed integrity verification",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Direct object upload is unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/upload-sessions/{id}/complete": {
"post": {
"operationId": "completeUploadSession",
"tags": [
"Upload Sessions"
],
"parameters": [
{
"schema": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"knowledgeSpaceId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"parts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"checksumSha256Base64": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"etag": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"partNumber": {
"type": "integer",
"minimum": 1,
"maximum": 10000
}
},
"required": [
"etag",
"partNumber"
],
"additionalProperties": false
},
"maxItems": 10000
}
},
"required": [
"knowledgeSpaceId"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Verified upload and idempotent document compilation publication",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"session": {
"type": "object",
"properties": {
"compilationJobId": {
"type": "string"
},
"completedAt": {
"type": "integer",
"minimum": 0
},
"documentAssetId": {
"type": "string"
},
"expectedSizeBytes": {
"type": "integer",
"exclusiveMinimum": 0
},
"expiresAt": {
"type": "integer",
"minimum": 0
},
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"mode": {
"type": "string",
"enum": [
"single",
"multipart",
"small_fallback"
]
},
"multipartPartCount": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"multipartPartSizeBytes": {
"type": "integer",
"exclusiveMinimum": 0
},
"status": {
"type": "string",
"enum": [
"creating",
"ready",
"completing",
"completed",
"aborting",
"aborted",
"expired",
"failed"
]
}
},
"required": [
"expectedSizeBytes",
"expiresAt",
"id",
"mode",
"status"
],
"additionalProperties": false
}
},
"required": [
"session"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Upload session not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Upload session state or idempotency conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"413": {
"description": "Upload exceeds the configured bound or quota",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"422": {
"description": "Uploaded object failed integrity verification",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Direct object upload is unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/upload-sessions/{id}/abort": {
"post": {
"operationId": "abortUploadSession",
"tags": [
"Upload Sessions"
],
"parameters": [
{
"schema": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"knowledgeSpaceId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
}
},
"required": [
"knowledgeSpaceId"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Aborted or replayed an upload-session abort",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"session": {
"type": "object",
"properties": {
"compilationJobId": {
"type": "string"
},
"completedAt": {
"type": "integer",
"minimum": 0
},
"documentAssetId": {
"type": "string"
},
"expectedSizeBytes": {
"type": "integer",
"exclusiveMinimum": 0
},
"expiresAt": {
"type": "integer",
"minimum": 0
},
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"mode": {
"type": "string",
"enum": [
"single",
"multipart",
"small_fallback"
]
},
"multipartPartCount": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"multipartPartSizeBytes": {
"type": "integer",
"exclusiveMinimum": 0
},
"status": {
"type": "string",
"enum": [
"creating",
"ready",
"completing",
"completed",
"aborting",
"aborted",
"expired",
"failed"
]
}
},
"required": [
"expectedSizeBytes",
"expiresAt",
"id",
"mode",
"status"
],
"additionalProperties": false
}
},
"required": [
"session"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Upload session not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Upload session state or idempotency conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"413": {
"description": "Upload exceeds the configured bound or quota",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"422": {
"description": "Uploaded object failed integrity verification",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Direct object upload is unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces": {
"post": {
"operationId": "createKnowledgeSpace",
"tags": [
"Knowledge Spaces"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"description": {
"type": "string",
"maxLength": 2000
},
"embeddingProfile": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
},
"iconRef": {
"type": "string",
"maxLength": 72,
"pattern": "^(?:builtin:)?[+a-z0-9_-]{1,64}$"
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"retrievalProfile": {
"type": "object",
"properties": {
"defaultMode": {
"type": "string",
"enum": [
"fast",
"research",
"deep"
]
},
"reasoningModel": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
},
"rerank": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"model": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
}
},
"required": [
"enabled"
],
"additionalProperties": false
},
"scoreThreshold": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"stage": {
"type": "string",
"enum": [
"mode-final",
"rerank"
]
},
"value": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"enabled",
"stage"
],
"additionalProperties": false
},
"topK": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"required": [
"defaultMode",
"reasoningModel",
"rerank",
"scoreThreshold",
"topK"
],
"additionalProperties": false
},
"slug": {
"type": "string",
"maxLength": 160,
"pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
}
},
"required": [
"name"
],
"additionalProperties": false
}
}
}
},
"responses": {
"201": {
"description": "Created knowledge space",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeSpaceCreationResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid knowledge space configuration",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"RETRIEVAL_PROFILE_SCORE_THRESHOLD_REQUIRES_RERANK"
]
},
"error": {
"type": "string",
"enum": [
"Fast/Deep mode-final score threshold requires the knowledge-space reranker to be enabled"
]
},
"mode": {
"type": "string",
"enum": [
"fast",
"research",
"deep"
]
}
},
"required": [
"code",
"error",
"mode"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Tenant slug conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"422": {
"description": "A selected model failed capability validation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Knowledge space capacity exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Model capability preflight or atomic provisioning is unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"parameters": [
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
},
"get": {
"operationId": "listKnowledgeSpaces",
"tags": [
"Knowledge Spaces"
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"name": "limit",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Tenant knowledge spaces",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeSpaceList"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid list request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}": {
"get": {
"operationId": "getKnowledgeSpace",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Knowledge space",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeSpace"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
},
"patch": {
"operationId": "updateKnowledgeSpace",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"description": {
"type": "string",
"maxLength": 2000
},
"expectedRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"iconRef": {
"type": [
"string",
"null"
],
"maxLength": 72,
"pattern": "^(?:builtin:)?[+a-z0-9_-]{1,64}$"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"slug": {
"type": "string",
"maxLength": 160,
"pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
}
},
"required": [
"expectedRevision"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Updated knowledge space",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeSpace"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Tenant slug or knowledge-space revision conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
},
"delete": {
"operationId": "requestKnowledgeSpaceDeletion",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 255
},
"required": true,
"name": "idempotency-key",
"in": "header"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"challenge": {
"type": "string",
"minLength": 1,
"maxLength": 160
},
"expectedRevision": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"challenge",
"expectedRevision"
],
"additionalProperties": false
}
}
}
},
"responses": {
"202": {
"description": "Durable deletion accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DurableDeletionAccepted"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid deletion request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Deletion target or job not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Challenge, revision, idempotency, or job-state conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Durable deletion service unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/manifest": {
"get": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "KnowledgeSpace control-plane manifest",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeSpaceManifest"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getKnowledgeSpacesByIdManifest",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/product-settings": {
"get": {
"operationId": "getKnowledgeSpaceProductSettings",
"tags": [
"Knowledge Spaces"
],
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Effective product model settings for the knowledge space",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeSpaceProductSettings"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
},
"patch": {
"operationId": "updateKnowledgeSpaceProductSettings",
"tags": [
"Knowledge Spaces"
],
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateKnowledgeSpaceProductSettings"
}
}
}
},
"responses": {
"200": {
"description": "Pending model settings accepted for first-document asynchronous validation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeSpaceProductSettings"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Retrieval profile is incompatible with its default mode",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"RETRIEVAL_PROFILE_SCORE_THRESHOLD_REQUIRES_RERANK"
]
},
"error": {
"type": "string",
"enum": [
"Fast/Deep mode-final score threshold requires the knowledge-space reranker to be enabled"
]
},
"mode": {
"type": "string",
"enum": [
"fast",
"research",
"deep"
]
}
},
"required": [
"code",
"error",
"mode"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Settings revision conflict or an active profile requires the migration workflow",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/embedding-profile": {
"put": {
"operationId": "updateKnowledgeSpaceEmbeddingProfile",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Active embedding profile for the knowledge space",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeSpaceEmbeddingProfile"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Initial validation or a published-space embedding migration was accepted",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/KnowledgeSpacePendingModelConfiguration"
},
{
"$ref": "#/components/schemas/KnowledgeSpaceProfileMigration"
}
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Embedding ingestion was admitted; profile change requires a reindex workflow",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"422": {
"description": "The embedding model failed capability validation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Embedding model preflight is temporarily unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/retrieval-profile": {
"put": {
"operationId": "updateKnowledgeSpaceRetrievalProfile",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"expectedRevision": {
"type": "integer",
"minimum": 0
},
"profile": {
"type": "object",
"properties": {
"defaultMode": {
"type": "string",
"enum": [
"fast",
"research",
"deep"
]
},
"reasoningModel": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
},
"rerank": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"model": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
}
},
"required": [
"enabled"
],
"additionalProperties": false
},
"scoreThreshold": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"stage": {
"type": "string",
"enum": [
"mode-final",
"rerank"
]
},
"value": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"enabled",
"stage"
],
"additionalProperties": false
},
"topK": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"required": [
"defaultMode",
"reasoningModel",
"rerank",
"scoreThreshold",
"topK"
],
"additionalProperties": false
}
},
"required": [
"expectedRevision",
"profile"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Versioned retrieval profile for the knowledge space",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeSpaceRetrievalProfile"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Initial validation or a published-space retrieval migration was accepted",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/KnowledgeSpacePendingModelConfiguration"
},
{
"$ref": "#/components/schemas/KnowledgeSpaceProfileMigration"
}
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Retrieval profile is incompatible with its default mode",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"RETRIEVAL_PROFILE_SCORE_THRESHOLD_REQUIRES_RERANK"
]
},
"error": {
"type": "string",
"enum": [
"Fast/Deep mode-final score threshold requires the knowledge-space reranker to be enabled"
]
},
"mode": {
"type": "string",
"enum": [
"fast",
"research",
"deep"
]
}
},
"required": [
"code",
"error",
"mode"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Retrieval profile revision conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"422": {
"description": "A retrieval model failed capability validation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Retrieval model preflight is temporarily unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/status": {
"get": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Bounded KnowledgeSpace control-plane status, including safe model-configuration validation state",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeSpaceStatus"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getKnowledgeSpacesByIdStatus",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/stats": {
"get": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 1440
},
"required": false,
"name": "windowMinutes",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Low-cardinality KnowledgeSpace statistics",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeSpaceStats"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid stats request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getKnowledgeSpacesByIdStats",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/fsck": {
"get": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"enum": [
"raw-objects",
"artifact-segments",
"references"
],
"default": "raw-objects"
},
"required": false,
"name": "check",
"in": "query"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Bounded KnowledgeSpace fsck diagnostics",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeFsckReport"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid fsck request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getKnowledgeSpacesByIdFsck",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/gc/staged-objects": {
"get": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 1024,
"pattern": "^[A-Za-z0-9._=-]+(?:\\/[A-Za-z0-9._=-]+)*\\/?$"
},
"required": false,
"name": "stagedObjectPrefix",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Bounded staged object GC dry-run",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeFsGcDryRunReport"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid GC dry-run request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getKnowledgeSpacesByIdGcStagedObjects",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/gc/staged-objects/execute": {
"post": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"candidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"candidateType": {
"type": "string",
"enum": [
"staged-object",
"failed-commit",
"artifact-segment",
"parse-artifact",
"index-projection",
"answer-trace"
]
},
"count": {
"type": "integer",
"exclusiveMinimum": 0
},
"estimatedBytes": {
"type": "integer",
"minimum": 0
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"target": {
"type": "object",
"properties": {
"documentAssetId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"objectKey": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"parseArtifactId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"type": {
"type": "string",
"enum": [
"raw-object",
"artifact-object",
"artifact-segment",
"knowledge-path",
"knowledge-node",
"index-projection",
"staged-commit"
]
},
"virtualPath": {
"type": "string",
"maxLength": 384,
"pattern": "^\\/(?:sources|knowledge|evidence|workspaces)(?:\\/[^/\\s]+)*$"
}
},
"required": [
"type"
]
}
},
"required": [
"candidateType",
"count",
"estimatedBytes",
"idempotencyKey",
"reason",
"target"
]
},
"maxItems": 100
}
},
"required": [
"candidates"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Execute staged object GC candidates",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeFsStagedObjectGcExecuteResult"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid GC execute request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "postKnowledgeSpacesByIdGcStagedObjectsExecute",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/leases/active": {
"get": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"name": "limit",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Read-only active KnowledgeFS lease diagnostics",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/KnowledgeFsLease"
}
},
"nextCursor": {
"type": "string"
}
},
"required": [
"items"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid active lease diagnostic list request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getKnowledgeSpacesByIdLeasesActive",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/staged-commits": {
"get": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"name": "limit",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"received",
"object-staged",
"object-verified",
"metadata-prepared",
"artifacts-built",
"nodes-built",
"projections-built",
"published",
"failed-retryable",
"failed-terminal",
"canceled",
"gc-pending",
"gc-complete"
]
},
"required": false,
"name": "status",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Read-only staged commit diagnostics",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/KnowledgeSpaceStagedCommit"
}
},
"nextCursor": {
"type": "string"
}
},
"required": [
"items"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid staged commit diagnostic list request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getKnowledgeSpacesByIdStagedCommits",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/internal/knowledge-spaces/product-summaries/batch": {
"post": {
"operationId": "batchKnowledgeSpaceProductSummaries",
"tags": [
"Knowledge Spaces"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BatchKnowledgeSpaceProductSummariesRequest"
}
}
}
},
"responses": {
"200": {
"description": "Explicit Capability-scoped knowledge-space product summaries",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BatchKnowledgeSpaceProductSummariesResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or oversized batch request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"parameters": [
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/overview/stats": {
"get": {
"operationId": "getKnowledgeSpaceOverviewStats",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Bounded 24h, 7d and 30d product statistics",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"current": {
"type": "object",
"properties": {
"freshSourceCount": {
"type": "integer",
"minimum": 0
},
"knowledgeCount": {
"type": "integer",
"minimum": 0
},
"latestSourceSyncAt": {
"type": "string",
"format": "date-time"
},
"linkedAppCount": {
"type": "integer",
"minimum": 0
},
"sourceCount": {
"type": "integer",
"minimum": 0
},
"staleSourceCount": {
"type": "integer",
"minimum": 0
}
},
"required": [
"freshSourceCount",
"knowledgeCount",
"linkedAppCount",
"sourceCount",
"staleSourceCount"
],
"additionalProperties": false
},
"generatedAt": {
"type": "string",
"format": "date-time"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"windows": {
"type": "object",
"properties": {
"24h": {
"type": "object",
"properties": {
"answerRate": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"answeredQueryCount": {
"type": "integer",
"minimum": 0
},
"queryCount": {
"type": "integer",
"minimum": 0
},
"since": {
"type": "string",
"format": "date-time"
}
},
"required": [
"answerRate",
"answeredQueryCount",
"queryCount",
"since"
],
"additionalProperties": false
},
"30d": {
"type": "object",
"properties": {
"answerRate": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"answeredQueryCount": {
"type": "integer",
"minimum": 0
},
"queryCount": {
"type": "integer",
"minimum": 0
},
"since": {
"type": "string",
"format": "date-time"
}
},
"required": [
"answerRate",
"answeredQueryCount",
"queryCount",
"since"
],
"additionalProperties": false
},
"7d": {
"type": "object",
"properties": {
"answerRate": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"answeredQueryCount": {
"type": "integer",
"minimum": 0
},
"queryCount": {
"type": "integer",
"minimum": 0
},
"since": {
"type": "string",
"format": "date-time"
}
},
"required": [
"answerRate",
"answeredQueryCount",
"queryCount",
"since"
],
"additionalProperties": false
}
},
"required": [
"24h",
"30d",
"7d"
],
"additionalProperties": false
}
},
"required": [
"current",
"generatedAt",
"knowledgeSpaceId",
"windows"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Knowledge-space Overview backend is unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/overview/query-outcomes": {
"get": {
"operationId": "getKnowledgeSpaceOverviewQueryOutcomes",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"enum": [
"24h",
"7d",
"30d"
],
"default": "24h"
},
"required": false,
"name": "window",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Requester-scoped query outcome totals, comparison, and bounded time series",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"buckets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"answered": {
"type": "integer",
"minimum": 0
},
"endAt": {
"type": "string",
"format": "date-time"
},
"lowConfidence": {
"type": "integer",
"minimum": 0
},
"noEvidence": {
"type": "integer",
"minimum": 0
},
"queryCount": {
"type": "integer",
"minimum": 0
},
"startAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"answered",
"endAt",
"lowConfidence",
"noEvidence",
"queryCount",
"startAt"
],
"additionalProperties": false
}
},
"current": {
"type": "object",
"properties": {
"answerRate": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"answered": {
"type": "integer",
"minimum": 0
},
"lowConfidence": {
"type": "integer",
"minimum": 0
},
"noEvidence": {
"type": "integer",
"minimum": 0
},
"queryCount": {
"type": "integer",
"minimum": 0
}
},
"required": [
"answerRate",
"answered",
"lowConfidence",
"noEvidence",
"queryCount"
],
"additionalProperties": false
},
"generatedAt": {
"type": "string",
"format": "date-time"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"previous": {
"type": "object",
"properties": {
"answerRate": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"answered": {
"type": "integer",
"minimum": 0
},
"lowConfidence": {
"type": "integer",
"minimum": 0
},
"noEvidence": {
"type": "integer",
"minimum": 0
},
"queryCount": {
"type": "integer",
"minimum": 0
}
},
"required": [
"answerRate",
"answered",
"lowConfidence",
"noEvidence",
"queryCount"
],
"additionalProperties": false
},
"previousSince": {
"type": "string",
"format": "date-time"
},
"since": {
"type": "string",
"format": "date-time"
},
"window": {
"type": "string",
"enum": [
"24h",
"7d",
"30d"
]
}
},
"required": [
"buckets",
"current",
"generatedAt",
"knowledgeSpaceId",
"previous",
"previousSince",
"since",
"window"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Knowledge-space Overview backend is unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/overview/inventory": {
"get": {
"operationId": "getKnowledgeSpaceOverviewInventory",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Source, graph, and active index inventory",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"generatedAt": {
"type": "string",
"format": "date-time"
},
"graphEntities": {
"type": "object",
"properties": {
"addedLast7d": {
"type": "integer",
"minimum": 0
},
"total": {
"type": "integer",
"minimum": 0
}
},
"required": [
"addedLast7d",
"total"
],
"additionalProperties": false
},
"graphRelations": {
"type": "object",
"properties": {
"addedLast7d": {
"type": "integer",
"minimum": 0
},
"total": {
"type": "integer",
"minimum": 0
}
},
"required": [
"addedLast7d",
"total"
],
"additionalProperties": false
},
"indexCoverage": {
"type": "object",
"properties": {
"indexed": {
"type": "integer",
"minimum": 0
},
"percentage": {
"type": "number",
"minimum": 0,
"maximum": 100
},
"total": {
"type": "integer",
"minimum": 0
}
},
"required": [
"indexed",
"percentage",
"total"
],
"additionalProperties": false
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"sourceCategories": {
"type": "object",
"properties": {
"crawl": {
"type": "integer",
"minimum": 0
},
"onlineDocuments": {
"type": "integer",
"minimum": 0
},
"onlineDrives": {
"type": "integer",
"minimum": 0
},
"uploads": {
"type": "integer",
"minimum": 0
}
},
"required": [
"crawl",
"onlineDocuments",
"onlineDrives",
"uploads"
],
"additionalProperties": false
}
},
"required": [
"generatedAt",
"graphEntities",
"graphRelations",
"indexCoverage",
"knowledgeSpaceId",
"sourceCategories"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Knowledge-space Overview backend is unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/overview/activity": {
"get": {
"operationId": "listKnowledgeSpaceOverviewActivity",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"enum": [
"query.requested",
"query.completed",
"query.failed",
"document.published",
"document.failed",
"source.synced",
"source.failed",
"settings.updated",
"permission.updated",
"profile.published",
"worker.failed"
]
},
"required": false,
"name": "action",
"in": "query"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"required": false,
"name": "actorId",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"member",
"system"
]
},
"required": false,
"name": "actorType",
"in": "query"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "string",
"format": "date-time"
},
"required": false,
"name": "from",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"required": false,
"name": "limit",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"knowledge-space",
"query",
"document",
"source",
"permission",
"profile",
"publication",
"worker"
]
},
"required": false,
"name": "resourceType",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"pending",
"success",
"failure",
"canceled"
]
},
"required": false,
"name": "result",
"in": "query"
},
{
"schema": {
"type": "string",
"format": "date-time"
},
"required": false,
"name": "to",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Append-only product activity feed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"query.requested",
"query.completed",
"query.failed",
"document.published",
"document.failed",
"source.synced",
"source.failed",
"settings.updated",
"permission.updated",
"profile.published",
"worker.failed"
]
},
"actor": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"member",
"system"
]
}
},
"required": [
"type"
],
"additionalProperties": false
},
"details": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
}
]
}
},
"id": {
"type": "string",
"format": "uuid"
},
"occurredAt": {
"type": "string",
"format": "date-time"
},
"resource": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"knowledge-space",
"query",
"document",
"source",
"permission",
"profile",
"publication",
"worker"
]
}
},
"required": [
"type"
],
"additionalProperties": false
},
"result": {
"type": "string",
"enum": [
"pending",
"success",
"failure",
"canceled"
]
}
},
"required": [
"action",
"actor",
"details",
"id",
"occurredAt",
"resource",
"result"
],
"additionalProperties": false
}
},
"nextCursor": {
"type": "string"
}
},
"required": [
"items"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid activity filter or cursor",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Knowledge-space Overview backend is unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/overview/attention": {
"get": {
"operationId": "listKnowledgeSpaceOverviewAttention",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "boolean",
"default": false
},
"required": false,
"name": "includeDismissed",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"required": false,
"name": "limit",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Rule-backed Needs Attention findings",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"action": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"open-resource",
"review-permissions",
"review-models"
]
},
"resourceId": {
"type": "string"
},
"resourceType": {
"type": "string",
"enum": [
"knowledge-space",
"document",
"source",
"failed-query"
]
}
},
"required": [
"kind",
"resourceType"
],
"additionalProperties": false
},
"dismissedUntil": {
"type": "string",
"format": "date-time"
},
"evidence": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"observedAt": {
"type": "string",
"format": "date-time"
},
"value": {
"anyOf": [
{
"type": "number"
},
{
"type": "string"
}
]
}
},
"required": [
"code",
"observedAt"
],
"additionalProperties": false
}
},
"issueKey": {
"type": "string"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"resource": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"knowledge-space",
"document",
"source",
"failed-query"
]
}
},
"required": [
"id",
"type"
],
"additionalProperties": false
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
},
"ruleId": {
"type": "string",
"enum": [
"stale-source",
"failed-document",
"low-quality-query",
"permission-readiness",
"model-readiness"
]
},
"severity": {
"type": "string",
"enum": [
"critical",
"warning",
"info"
]
},
"status": {
"type": "string",
"enum": [
"active",
"dismissed",
"resolved"
]
},
"title": {
"type": "string"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"action",
"evidence",
"issueKey",
"knowledgeSpaceId",
"resource",
"revision",
"ruleId",
"severity",
"status",
"title",
"updatedAt"
],
"additionalProperties": false
}
}
},
"required": [
"items"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid attention list request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Knowledge-space Overview backend is unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/overview/attention/{issueKey}": {
"patch": {
"operationId": "transitionKnowledgeSpaceOverviewAttention",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"required": true,
"name": "issueKey",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"dismissedUntil": {
"type": "string",
"format": "date-time"
},
"expectedRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"status": {
"type": "string",
"enum": [
"active",
"dismissed",
"resolved"
]
}
},
"required": [
"expectedRevision",
"status"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "CAS-updated attention state",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"action": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"open-resource",
"review-permissions",
"review-models"
]
},
"resourceId": {
"type": "string"
},
"resourceType": {
"type": "string",
"enum": [
"knowledge-space",
"document",
"source",
"failed-query"
]
}
},
"required": [
"kind",
"resourceType"
],
"additionalProperties": false
},
"dismissedUntil": {
"type": "string",
"format": "date-time"
},
"evidence": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"observedAt": {
"type": "string",
"format": "date-time"
},
"value": {
"anyOf": [
{
"type": "number"
},
{
"type": "string"
}
]
}
},
"required": [
"code",
"observedAt"
],
"additionalProperties": false
}
},
"issueKey": {
"type": "string"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"resource": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"knowledge-space",
"document",
"source",
"failed-query"
]
}
},
"required": [
"id",
"type"
],
"additionalProperties": false
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
},
"ruleId": {
"type": "string",
"enum": [
"stale-source",
"failed-document",
"low-quality-query",
"permission-readiness",
"model-readiness"
]
},
"severity": {
"type": "string",
"enum": [
"critical",
"warning",
"info"
]
},
"status": {
"type": "string",
"enum": [
"active",
"dismissed",
"resolved"
]
},
"title": {
"type": "string"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"action",
"evidence",
"issueKey",
"knowledgeSpaceId",
"resource",
"revision",
"ruleId",
"severity",
"status",
"title",
"updatedAt"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space or attention issue not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Attention revision conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Knowledge-space Overview backend is unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/overview/health": {
"get": {
"operationId": "getKnowledgeSpaceProductHealth",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Stable product health contract",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"components": {
"type": "object",
"properties": {
"index": {
"type": "object",
"properties": {
"codes": {
"type": "array",
"items": {
"type": "string"
}
},
"state": {
"type": "string",
"enum": [
"healthy",
"degraded",
"unavailable",
"unknown"
]
}
},
"required": [
"codes",
"state"
],
"additionalProperties": false
},
"ingestion": {
"type": "object",
"properties": {
"codes": {
"type": "array",
"items": {
"type": "string"
}
},
"state": {
"type": "string",
"enum": [
"healthy",
"degraded",
"unavailable",
"unknown"
]
}
},
"required": [
"codes",
"state"
],
"additionalProperties": false
},
"profilePublication": {
"type": "object",
"properties": {
"codes": {
"type": "array",
"items": {
"type": "string"
}
},
"state": {
"type": "string",
"enum": [
"healthy",
"degraded",
"unavailable",
"unknown"
]
}
},
"required": [
"codes",
"state"
],
"additionalProperties": false
},
"queryAvailability": {
"type": "object",
"properties": {
"codes": {
"type": "array",
"items": {
"type": "string"
}
},
"state": {
"type": "string",
"enum": [
"healthy",
"degraded",
"unavailable",
"unknown"
]
}
},
"required": [
"codes",
"state"
],
"additionalProperties": false
},
"sourceFreshness": {
"type": "object",
"properties": {
"codes": {
"type": "array",
"items": {
"type": "string"
}
},
"state": {
"type": "string",
"enum": [
"healthy",
"degraded",
"unavailable",
"unknown"
]
}
},
"required": [
"codes",
"state"
],
"additionalProperties": false
},
"workerReadiness": {
"type": "object",
"properties": {
"codes": {
"type": "array",
"items": {
"type": "string"
}
},
"state": {
"type": "string",
"enum": [
"healthy",
"degraded",
"unavailable",
"unknown"
]
}
},
"required": [
"codes",
"state"
],
"additionalProperties": false
}
},
"required": [
"index",
"ingestion",
"profilePublication",
"queryAvailability",
"sourceFreshness",
"workerReadiness"
],
"additionalProperties": false
},
"generatedAt": {
"type": "string",
"format": "date-time"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"state": {
"type": "string",
"enum": [
"healthy",
"degraded",
"unavailable",
"unknown"
]
}
},
"required": [
"components",
"generatedAt",
"knowledgeSpaceId",
"state"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Knowledge-space Overview backend is unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/profile-migrations": {
"post": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 255
},
"required": true,
"name": "idempotency-key",
"in": "header"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"candidateRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"changedKind": {
"type": "string",
"enum": [
"embedding",
"retrieval"
]
}
},
"required": [
"candidateRevision",
"changedKind"
],
"additionalProperties": false
}
}
}
},
"responses": {
"202": {
"description": "Durable profile migration",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeSpaceProfileMigration"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid profile migration request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Profile migration not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Profile migration state, idempotency, or active-run conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Profile migration service unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "postKnowledgeSpacesByIdProfileMigrations",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/profile-migrations/{migrationId}": {
"get": {
"operationId": "getKnowledgeSpaceProfileMigration",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "migrationId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Durable profile migration",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeSpaceProfileMigration"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Profile migration not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
},
"delete": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "migrationId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 512
}
},
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Durable profile migration",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeSpaceProfileMigration"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Profile migration not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Profile migration state, idempotency, or active-run conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "deleteKnowledgeSpacesByIdProfileMigrationsByMigrationId",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/profile-migrations/{migrationId}/retry": {
"post": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "migrationId",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 255
},
"required": true,
"name": "idempotency-key",
"in": "header"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"202": {
"description": "Durable profile migration",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeSpaceProfileMigration"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Profile migration not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Profile migration state, idempotency, or active-run conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "postKnowledgeSpacesByIdProfileMigrationsByMigrationIdRetry",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/sources/{sourceId}": {
"delete": {
"operationId": "requestSourceDeletion",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "sourceId",
"in": "path"
},
{
"schema": {
"type": "string",
"enum": [
"cascade",
"keep"
],
"default": "cascade"
},
"required": false,
"name": "documents",
"in": "query"
},
{
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 255
},
"required": true,
"name": "idempotency-key",
"in": "header"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"expectedRevision": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"expectedRevision"
],
"additionalProperties": false
}
}
}
},
"responses": {
"202": {
"description": "Durable deletion accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DurableDeletionAccepted"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid deletion request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Deletion target or job not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Challenge, revision, idempotency, or job-state conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Durable deletion service unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
},
"get": {
"operationId": "getKnowledgeSpaceSource",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "sourceId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Source",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Source"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space or source not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
},
"patch": {
"operationId": "updateKnowledgeSpaceSource",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "sourceId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"expectedVersion": {
"type": "integer",
"minimum": 1
},
"expectedPolicyRevision": {
"type": "integer",
"minimum": 0
},
"syncPolicy": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"mode": {
"type": "string",
"enum": [
"manual",
"interval",
"custom"
]
},
"customIntervalSeconds": {
"type": "integer",
"minimum": 3600,
"maximum": 2592000
}
},
"required": [
"enabled",
"mode"
],
"additionalProperties": false
},
"metadata": {
"type": "object",
"additionalProperties": {}
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"providerParameters": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
}
]
}
},
"syncAfterUpdate": {
"type": "boolean"
},
"status": {
"type": "string",
"enum": [
"active",
"syncing",
"error",
"disabled"
]
},
"uri": {
"type": "string",
"minLength": 1,
"maxLength": 4096
}
},
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Updated source",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Source"
},
{
"type": "object",
"properties": {
"syncWorkflow": {
"$ref": "#/components/schemas/SourceWorkflowRun"
}
}
}
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space or source not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Source was modified concurrently, or protected legacy credential-bearing parameters cannot be replaced",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Source workflow service unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/documents/bulk": {
"delete": {
"operationId": "requestBulkDocumentDeletion",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 255
},
"required": true,
"name": "idempotency-key",
"in": "header"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"documents": {
"type": "array",
"items": {
"type": "object",
"properties": {
"documentId": {
"type": "string",
"format": "uuid"
},
"expectedRevision": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"documentId",
"expectedRevision"
],
"additionalProperties": false
},
"minItems": 1
}
},
"required": [
"documents"
],
"additionalProperties": false
}
}
}
},
"responses": {
"202": {
"description": "Per-document durable deletions accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DurableBulkDeletionAccepted"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid bulk deletion request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Deletion target or job not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Challenge, revision, idempotency, or job-state conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Durable deletion service unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
},
"post": {
"operationId": "bulkUploadDocuments",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"files": {
"type": "array",
"items": {
"format": "binary",
"type": "string"
}
},
"targets": {
"type": "string",
"description": "JSON array of explicit per-file revision targets: {index, documentId, expectedActiveRevision, expectedDocumentRowVersion}. Omitted indexes create new logical documents; filenames are never merge keys.",
"example": "[{\"index\":0,\"documentId\":\"00000000-0000-4000-8000-000000000001\",\"expectedActiveRevision\":2,\"expectedDocumentRowVersion\":2}]"
}
}
}
}
}
},
"responses": {
"202": {
"description": "Accepted bulk document upload for durable compilation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkDocumentUploadAccepted"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid bulk upload request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Knowledge space publication bootstrap is active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"413": {
"description": "Bulk upload too large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Document asset capacity exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"500": {
"description": "Bulk document upload failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Durable document compilation is not configured",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/logical-documents/bulk": {
"delete": {
"operationId": "requestBulkLogicalDocumentDeletion",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 255
},
"required": true,
"name": "idempotency-key",
"in": "header"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"documents": {
"type": "array",
"items": {
"type": "object",
"properties": {
"documentId": {
"type": "string",
"format": "uuid"
},
"expectedRevision": {
"type": "integer",
"minimum": 0
}
},
"required": [
"documentId",
"expectedRevision"
],
"additionalProperties": false
},
"minItems": 1
}
},
"required": [
"documents"
],
"additionalProperties": false
}
}
}
},
"responses": {
"202": {
"description": "Per-document durable deletions accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DurableBulkDeletionAccepted"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid bulk deletion request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Deletion target or job not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Challenge, revision, idempotency, or job-state conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Durable deletion service unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/documents/{documentId}": {
"delete": {
"operationId": "requestDocumentDeletion",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "documentId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 255
},
"required": true,
"name": "idempotency-key",
"in": "header"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"expectedRevision": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"expectedRevision"
],
"additionalProperties": false
}
}
}
},
"responses": {
"202": {
"description": "Durable deletion accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DurableDeletionAccepted"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid deletion request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Deletion target or job not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Challenge, revision, idempotency, or job-state conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Durable deletion service unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
},
"get": {
"operationId": "getDocument",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "documentId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Document asset",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentAsset"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Document asset not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/logical-documents/{documentId}": {
"delete": {
"operationId": "requestLogicalDocumentDeletion",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "documentId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 255
},
"required": true,
"name": "idempotency-key",
"in": "header"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"expectedRevision": {
"type": "integer",
"minimum": 0
}
},
"required": [
"expectedRevision"
],
"additionalProperties": false
}
}
}
},
"responses": {
"202": {
"description": "Durable deletion accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DurableDeletionAccepted"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid logical document deletion request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Deletion target or job not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Challenge, revision, idempotency, or job-state conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Durable deletion service unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
},
"get": {
"operationId": "getLogicalDocument",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "documentId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Logical document",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LogicalDocument"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Document resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/deletion-batches/{batchId}": {
"get": {
"operationId": "getDurableDeletionBatch",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "batchId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": false,
"name": "knowledgeSpaceId",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Durable deletion batch admission and child status",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DurableBulkDeletionAccepted"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Deletion target or job not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/deletion-jobs/{jobId}": {
"get": {
"operationId": "getDurableDeletionJob",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "jobId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": false,
"name": "knowledgeSpaceId",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Durable deletion status",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DurableDeletionJob"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Deletion target or job not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/deletion-jobs/{jobId}/retry": {
"post": {
"operationId": "retryDurableDeletionJob",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "jobId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": false,
"name": "knowledgeSpaceId",
"in": "query"
},
{
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 255
},
"required": true,
"name": "idempotency-key",
"in": "header"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"202": {
"description": "Durable deletion accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DurableDeletionAccepted"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Deletion target or job not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Challenge, revision, idempotency, or job-state conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Durable deletion service unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/model-catalog": {
"get": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"embedding",
"reasoning",
"rerank"
]
},
"required": false,
"name": "kind",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
},
"required": false,
"name": "limit",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Tenant-active Dify model catalog",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tokenLimits": {
"type": "object",
"properties": {
"contextTokens": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 1000000000
},
"maxOutputTokens": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 1000000000
},
"outputParameter": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"additionalProperties": false
},
"capabilities": {
"type": "object",
"additionalProperties": {},
"default": {}
},
"kinds": {
"type": "array",
"items": {
"type": "string",
"enum": [
"embedding",
"reasoning",
"rerank"
]
},
"minItems": 1
},
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginUniqueIdentifier": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"pluginVersion": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"schemaFingerprint": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$"
}
},
"required": [
"kinds",
"model",
"pluginId",
"pluginUniqueIdentifier",
"provider",
"schemaFingerprint"
],
"additionalProperties": false
},
"maxItems": 100
},
"nextCursor": {
"type": "string",
"minLength": 1,
"maxLength": 1024
}
},
"required": [
"items"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Model catalog unavailable",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ErrorResponse"
},
{
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 1
},
"retryable": {
"type": "boolean"
}
},
"required": [
"code"
]
}
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getKnowledgeSpacesByIdModelCatalog",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/model-preflights": {
"post": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"embedding",
"reasoning",
"rerank"
]
},
"selection": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
}
},
"required": [
"kind",
"selection"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Observed model capability snapshot",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"capabilityDigest": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$"
},
"checkedAt": {
"type": "string",
"format": "date-time"
},
"dimension": {
"type": "integer",
"exclusiveMinimum": 0
},
"distanceMetric": {
"type": "string",
"enum": [
"cosine",
"dot",
"l2"
]
},
"inputModalities": {
"type": "array",
"items": {
"type": "string",
"enum": [
"text",
"image"
]
},
"minItems": 1,
"maxItems": 2
},
"kind": {
"type": "string",
"enum": [
"embedding",
"reasoning",
"rerank"
]
},
"pluginUniqueIdentifier": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"pluginVersion": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"schemaFingerprint": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$"
},
"selection": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
}
},
"required": [
"capabilityDigest",
"checkedAt",
"kind",
"pluginUniqueIdentifier",
"schemaFingerprint",
"selection"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"422": {
"description": "Model selection or observed capability is invalid",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ErrorResponse"
},
{
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 1
},
"retryable": {
"type": "boolean"
}
},
"required": [
"code"
]
}
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Model capability preflight unavailable",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ErrorResponse"
},
{
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 1
},
"retryable": {
"type": "boolean"
}
},
"required": [
"code"
]
}
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "postKnowledgeSpacesByIdModelPreflights",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/profiles/{kind}/revisions": {
"get": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"enum": [
"embedding",
"retrieval"
]
},
"required": true,
"name": "kind",
"in": "path"
},
{
"schema": {
"type": "integer",
"exclusiveMinimum": 0
},
"required": false,
"name": "afterRevision",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"required": false,
"name": "limit",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Bounded immutable knowledge-space profile revision audit history",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeSpaceProfileAuditRevisionList"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid profile kind, revision cursor, or list limit",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Profile audit repository is unavailable or returned invalid data",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"KNOWLEDGE_SPACE_PROFILE_AUDIT_UNAVAILABLE"
]
},
"error": {
"type": "string",
"enum": [
"Knowledge-space profile audit is unavailable"
]
},
"retryable": {
"type": "boolean",
"enum": [
true
]
}
},
"required": [
"code",
"error",
"retryable"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getKnowledgeSpacesByIdProfilesByKindRevisions",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/golden-questions": {
"post": {
"operationId": "createGoldenQuestion",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"expectedEvidenceIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"default": []
},
"metadata": {
"type": "object",
"additionalProperties": {},
"default": {}
},
"question": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"tags": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"default": []
}
},
"required": [
"question"
],
"additionalProperties": false
}
}
}
},
"responses": {
"201": {
"description": "Created golden question",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GoldenQuestion"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Golden question capacity exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
},
"get": {
"operationId": "listGoldenQuestions",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string"
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"name": "limit",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Knowledge space golden questions",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GoldenQuestion"
}
},
"nextCursor": {
"type": "string"
}
},
"required": [
"items"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid golden question list request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/golden-questions/evidence-matches": {
"post": {
"operationId": "matchGoldenQuestionEvidence",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"evidenceTexts": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 8000
},
"minItems": 1,
"maxItems": 500
},
"minimumSimilarity": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.7
},
"nodeIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 50
},
"topK": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"default": 5
}
},
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Evidence candidates for golden questions",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"candidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"documentAssetId": {
"type": "string",
"format": "uuid"
},
"nodeId": {
"type": "string",
"format": "uuid"
},
"pageNumber": {
"type": "integer",
"exclusiveMinimum": 0
},
"projectionId": {
"type": "string",
"format": "uuid"
},
"score": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"sectionPath": {
"type": "array",
"items": {
"type": "string"
}
},
"text": {
"type": "string"
}
},
"required": [
"documentAssetId",
"nodeId",
"projectionId",
"score",
"sectionPath",
"text"
],
"additionalProperties": false
}
},
"evidenceText": {
"type": "string",
"minLength": 1,
"maxLength": 8000
},
"matched": {
"type": "boolean"
}
},
"required": [
"candidates",
"evidenceText",
"matched"
],
"additionalProperties": false
}
},
"resolvedEvidence": {
"type": "array",
"items": {
"type": "object",
"properties": {
"documentAssetId": {
"type": "string",
"format": "uuid"
},
"nodeId": {
"type": "string",
"format": "uuid"
},
"pageNumber": {
"type": "integer",
"exclusiveMinimum": 0
},
"sectionPath": {
"type": "array",
"items": {
"type": "string"
}
},
"text": {
"type": "string"
}
},
"required": [
"documentAssetId",
"nodeId",
"sectionPath",
"text"
],
"additionalProperties": false
}
}
},
"required": [
"items"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Evidence matching unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/golden-questions/bulk-import": {
"post": {
"operationId": "bulkImportGoldenQuestions",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"matchPolicy": {
"type": "string",
"enum": [
"all",
"any"
],
"default": "all"
},
"minimumSimilarity": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.7
},
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"evidence": {
"type": "string",
"minLength": 1,
"maxLength": 8000
},
"metadata": {
"type": "object",
"additionalProperties": {},
"default": {}
},
"question": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"tags": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"maxItems": 50,
"default": []
}
},
"required": [
"evidence",
"question"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 500
}
},
"required": [
"rows"
],
"additionalProperties": false
}
}
}
},
"responses": {
"201": {
"description": "Imported golden questions",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"activeCount": {
"type": "integer",
"minimum": 0
},
"draftCount": {
"type": "integer",
"minimum": 0
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"expectedEvidenceId": {
"type": "string",
"format": "uuid"
},
"questionId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"rowIndex": {
"type": "integer",
"minimum": 0
},
"similarity": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"status": {
"type": "string",
"enum": [
"active",
"draft"
]
}
},
"required": [
"questionId",
"rowIndex",
"status"
],
"additionalProperties": false
}
}
},
"required": [
"activeCount",
"draftCount",
"items"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Golden question capacity exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Evidence matching unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/golden-questions/{questionId}": {
"get": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "questionId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Golden question",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GoldenQuestion"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Golden question not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getKnowledgeSpacesByIdGoldenQuestionsByQuestionId",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
},
"patch": {
"operationId": "updateGoldenQuestion",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "questionId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"expectedEvidenceIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"metadata": {
"type": "object",
"additionalProperties": {}
},
"question": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"tags": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 80
}
}
},
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Updated golden question",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GoldenQuestion"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Golden question not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
},
"delete": {
"operationId": "deleteGoldenQuestion",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "questionId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Deleted golden question",
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Golden question not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/golden-questions/{questionId}/annotations": {
"post": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "questionId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"answerCorrectness": {
"type": "string",
"enum": [
"correct",
"incorrect",
"not-answerable",
"partially-correct"
]
},
"evidenceRelevance": {
"type": "array",
"items": {
"type": "object",
"properties": {
"evidenceId": {
"type": "string",
"format": "uuid"
},
"note": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"relevant": {
"type": "boolean"
}
},
"required": [
"evidenceId",
"relevant"
],
"additionalProperties": false
},
"maxItems": 50,
"default": []
},
"note": {
"type": "string",
"minLength": 1,
"maxLength": 1000
}
},
"required": [
"answerCorrectness"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Annotated golden question",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GoldenQuestion"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid annotation request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Golden question not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "postKnowledgeSpacesByIdGoldenQuestionsByQuestionIdAnnotations",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/production-bad-cases": {
"post": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"tags": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"maxItems": 20,
"default": []
},
"traceId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"traceId"
],
"additionalProperties": false
}
}
}
},
"responses": {
"201": {
"description": "Captured production bad case queued for evaluation review",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GoldenQuestion"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space or answer trace not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Golden question capacity exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "postKnowledgeSpacesByIdProductionBadCases",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/quality/traces": {
"get": {
"operationId": "listKnowledgeSpaceQualityTraces",
"tags": [
"Quality"
],
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"maxLength": 1000
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "string",
"format": "date-time"
},
"required": false,
"name": "from",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
},
"required": false,
"name": "limit",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"auto",
"deep",
"fast",
"research"
]
},
"required": false,
"name": "mode",
"in": "query"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"required": false,
"name": "query",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"retrieval_test",
"workflow",
"service_api",
"agent",
"mcp"
]
},
"required": false,
"name": "source",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"completed",
"failed"
]
},
"required": false,
"name": "status",
"in": "query"
},
{
"schema": {
"type": "string",
"format": "date-time"
},
"required": false,
"name": "to",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Subject-owned, candidate-authorized answer trace history",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/QualityAnswerTraceSummary"
}
},
"nextCursor": {
"type": "string"
}
},
"required": [
"items"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Quality resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Revision conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Quality runtime unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/quality/traces/{traceId}/missing/{itemKey}": {
"patch": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "traceId",
"in": "path"
},
{
"schema": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$"
},
"required": true,
"name": "itemKey",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"expectedRevision": {
"type": "integer",
"minimum": 0
},
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"status": {
"type": "string",
"enum": [
"active",
"dismissed"
]
}
},
"required": [
"expectedRevision",
"status"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Updated missing-evidence review",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MissingEvidenceReview"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Quality resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Revision conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Quality runtime unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "patchKnowledgeSpacesByIdQualityTracesByTraceIdMissingByItemKey",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/quality/traces/{traceId}/missing/{itemKey}/history": {
"get": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "traceId",
"in": "path"
},
{
"schema": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$"
},
"required": true,
"name": "itemKey",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Missing-evidence review history",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"action": {
"type": "string"
},
"actorSubjectId": {
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"fromStatus": {
"type": "string"
},
"id": {
"type": "string",
"format": "uuid"
},
"reason": {
"type": "string"
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
},
"toStatus": {
"type": "string"
}
},
"required": [
"action",
"actorSubjectId",
"createdAt",
"id",
"revision",
"toStatus"
]
}
}
},
"required": [
"items"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Quality resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Revision conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Quality runtime unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getKnowledgeSpacesByIdQualityTracesByTraceIdMissingByItemKeyHistory",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/quality/bad-cases": {
"post": {
"operationId": "createQualityBadCase",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"tags": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"maxItems": 50,
"default": []
},
"traceId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"reason",
"traceId"
],
"additionalProperties": false
}
}
}
},
"responses": {
"201": {
"description": "Captured production bad case",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProductionBadCase"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Quality resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Revision conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Quality runtime unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
},
"get": {
"operationId": "listQualityBadCases",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"maxLength": 1000
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
},
"required": false,
"name": "limit",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"open",
"replaying",
"fixed",
"dismissed"
]
},
"required": false,
"name": "status",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Production bad cases",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ProductionBadCase"
}
},
"nextCursor": {
"type": "string"
}
},
"required": [
"items"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Quality resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Revision conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Quality runtime unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/quality/bad-cases/{badCaseId}": {
"get": {
"operationId": "getQualityBadCase",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "badCaseId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Production bad case",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProductionBadCase"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Quality resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Revision conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Quality runtime unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
},
"patch": {
"operationId": "updateQualityBadCase",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "badCaseId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"expectedRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"replayRunId": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string",
"enum": [
"open",
"replaying",
"fixed",
"dismissed"
]
},
"tags": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"maxItems": 50
}
},
"required": [
"expectedRevision",
"status"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Updated production bad case",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProductionBadCase"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Quality resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Revision conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Quality runtime unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/quality/bad-cases/{badCaseId}/trace-reference": {
"get": {
"operationId": "getQualityBadCaseTraceReference",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "badCaseId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Authorized trace reference for a production bad case",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"traceId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"traceId"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Quality resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Revision conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Quality runtime unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/quality/bad-cases/{badCaseId}/history": {
"get": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "badCaseId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Production bad-case history",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"action": {
"type": "string"
},
"actorSubjectId": {
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"fromStatus": {
"type": "string"
},
"id": {
"type": "string",
"format": "uuid"
},
"reason": {
"type": "string"
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
},
"toStatus": {
"type": "string"
}
},
"required": [
"action",
"actorSubjectId",
"createdAt",
"id",
"revision",
"toStatus"
]
}
}
},
"required": [
"items"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Quality resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Revision conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Quality runtime unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getKnowledgeSpacesByIdQualityBadCasesByBadCaseIdHistory",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/quality/replay-runs": {
"post": {
"operationId": "createQualityReplay",
"x-knowledge-fs-max-response-bytes": 4194304,
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 255
},
"required": true,
"name": "idempotency-key",
"in": "header"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"goldenQuestionIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 1000
},
"mode": {
"type": "string",
"enum": [
"deep",
"fast",
"research"
]
}
},
"required": [
"goldenQuestionIds"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"deep",
"fast",
"research"
]
},
"selection": {
"type": "string",
"enum": [
"all-active"
]
}
},
"required": [
"selection"
],
"additionalProperties": false
}
]
}
}
}
},
"responses": {
"202": {
"description": "Durable replay queued",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QualityReplayRun"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Quality resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Revision conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Quality runtime unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
},
"get": {
"operationId": "listQualityReplays",
"x-knowledge-fs-max-response-bytes": 4194304,
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"maxLength": 1000
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "string",
"format": "date-time"
},
"required": false,
"name": "from",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
},
"required": false,
"name": "limit",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"deep",
"fast",
"research"
]
},
"required": false,
"name": "mode",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"queued",
"running",
"passed",
"failed",
"canceled"
]
},
"required": false,
"name": "state",
"in": "query"
},
{
"schema": {
"type": "string",
"format": "date-time"
},
"required": false,
"name": "to",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Bounded durable replay history",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/QualityReplayRun"
}
},
"nextCursor": {
"type": "string"
}
},
"required": [
"items"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Quality resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Revision conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Quality runtime unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/quality/replay-runs/{runId}": {
"get": {
"operationId": "getQualityReplay",
"x-knowledge-fs-max-response-bytes": 4194304,
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "runId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": false,
"name": "evidenceItemId",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Durable replay run",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QualityReplayRun"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Quality resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Revision conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Quality runtime unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/quality/replay-runs/{runId}/cancel": {
"post": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "runId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"expectedRevision": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"expectedRevision"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Canceled replay run",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QualityReplayRun"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Quality resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Revision conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Quality runtime unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "postKnowledgeSpacesByIdQualityReplayRunsByRunIdCancel",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/quality/replay-runs/{runId}/retry": {
"post": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "runId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"expectedRevision": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"expectedRevision"
],
"additionalProperties": false
}
}
}
},
"responses": {
"202": {
"description": "Replay requeued with fresh permission/profile snapshot",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QualityReplayRun"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Quality resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Revision conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Quality runtime unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "postKnowledgeSpacesByIdQualityReplayRunsByRunIdRetry",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/quality/trends": {
"get": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "date-time"
},
"required": false,
"name": "from",
"in": "query"
},
{
"schema": {
"type": "string",
"format": "date-time"
},
"required": false,
"name": "to",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"24h",
"7d",
"30d"
],
"default": "7d"
},
"required": false,
"name": "window",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Bounded quality trends and baseline comparison",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QualityTrendReport"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Quality resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Revision conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Quality runtime unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getKnowledgeSpacesByIdQualityTrends",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/documents": {
"get": {
"operationId": "listDocuments",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"required": false,
"name": "limit",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Document assets",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentAssetList"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Candidate visibility scan budget exceeded",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"CANDIDATE_VISIBILITY_SCAN_BUDGET_EXCEEDED"
]
},
"error": {
"type": "string",
"enum": [
"Candidate visibility scan budget exceeded"
]
}
},
"required": [
"code",
"error"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
},
"post": {
"operationId": "uploadDocument",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"documentId": {
"type": "string",
"format": "uuid"
},
"expectedActiveRevision": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0
},
{
"type": "string",
"enum": [
"null"
]
}
]
},
"expectedDocumentRowVersion": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"file": {
"type": "string",
"format": "binary"
},
"sourceId": {
"type": "string",
"format": "uuid"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Uploaded document asset",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentAsset"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Accepted document asset for durable compilation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentUploadAccepted"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid upload request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Logical document CAS conflict or knowledge space publication bootstrap is active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"413": {
"description": "Upload too large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Document asset capacity exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"500": {
"description": "Document upload failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Durable logical document compilation unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/documents/{documentId}/parse-artifacts/{version}": {
"get": {
"operationId": "getDocumentParseArtifact",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "documentId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "integer",
"exclusiveMinimum": 0
},
"required": true,
"name": "version",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Parse artifact",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ParseArtifact"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Parse artifact not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/documents/{documentId}/outline": {
"get": {
"operationId": "getDocumentOutline",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "documentId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Document outline",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentOutline"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Document outline not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/documents/{documentId}/multimodal": {
"get": {
"x-knowledge-fs-max-response-bytes": 4194304,
"operationId": "getDocumentMultimodalManifest",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "documentId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Document multimodal manifest",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentMultimodalManifest"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Document multimodal manifest not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/documents/{documentId}/multimodal/{itemId}/asset": {
"get": {
"operationId": "getDocumentMultimodalAsset",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "documentId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"required": true,
"name": "itemId",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"required": false,
"name": "expectedArtifactHash",
"in": "query"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9._=-]+$"
},
"required": false,
"name": "variant",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Document multimodal item asset",
"content": {
"application/octet-stream": {
"schema": {
"format": "binary",
"type": "string"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Document multimodal item asset not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Document multimodal item references an external asset",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"413": {
"description": "Document multimodal item asset exceeds the maximum readable size",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 26214400,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/metadata-fields": {
"get": {
"operationId": "listKnowledgeSpaceMetadataFields",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"required": false,
"name": "limit",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Knowledge-space custom metadata field catalog",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeSpaceMetadataFieldList"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid metadata field",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Metadata field or knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Metadata field name or row-version conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Metadata field repository unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
},
"post": {
"operationId": "createKnowledgeSpaceMetadataField",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"type": {
"type": "string",
"enum": [
"string",
"number",
"time"
]
}
},
"required": [
"name",
"type"
],
"additionalProperties": false
}
}
}
},
"responses": {
"201": {
"description": "Created metadata field",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeSpaceMetadataField"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid metadata field",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Metadata field or knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Metadata field name or row-version conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Metadata field repository unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/metadata-fields/{fieldId}": {
"patch": {
"operationId": "updateKnowledgeSpaceMetadataField",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "fieldId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"expectedRowVersion": {
"type": "integer",
"minimum": 0
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
}
},
"required": [
"expectedRowVersion",
"name"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Renamed metadata field and all bound document values",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeSpaceMetadataField"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid metadata field",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Metadata field or knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Metadata field name or row-version conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Metadata field repository unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
},
"delete": {
"operationId": "deleteKnowledgeSpaceMetadataField",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "fieldId",
"in": "path"
},
{
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"required": false,
"name": "expectedRowVersion",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Deleted metadata field and all bound document values",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"deleted": {
"type": "boolean",
"enum": [
true
]
}
},
"required": [
"deleted"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid metadata field",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Metadata field or knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Metadata field name or row-version conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Metadata field repository unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/logical-documents": {
"get": {
"operationId": "listLogicalDocuments",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 2048
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"required": false,
"name": "limit",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Logical documents",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LogicalDocumentList"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid pagination cursor",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Document resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/document-references/resolve": {
"get": {
"operationId": "resolveDocumentReference",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "documentAssetId",
"in": "query"
},
{
"schema": {
"type": "integer",
"exclusiveMinimum": 0
},
"required": true,
"name": "documentAssetVersion",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Logical document reference for an immutable asset version",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolvedDocumentReference"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Document resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/documents/{documentId}/revisions": {
"get": {
"operationId": "listDocumentRevisions",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "documentId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 2048
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"required": false,
"name": "limit",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Immutable document revision history",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentRevisionList"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid pagination cursor",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Document resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/documents/{documentId}/revisions/{revision}/rollback": {
"post": {
"operationId": "rollbackDocumentRevision",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "documentId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "integer",
"exclusiveMinimum": 0
},
"required": true,
"name": "revision",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"expectedActiveRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"expectedRowVersion": {
"type": "integer",
"minimum": 0
}
},
"required": [
"expectedActiveRevision",
"expectedRowVersion"
],
"additionalProperties": false
}
}
}
},
"responses": {
"202": {
"description": "Rollback candidate compilation accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentProcessingTask"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Document resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Document revision CAS conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Rollback coordinator unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/documents/{documentId}/metadata": {
"patch": {
"operationId": "patchDocumentMetadata",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "documentId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"expectedRowVersion": {
"type": "integer",
"minimum": 0
},
"patch": {
"type": "object",
"additionalProperties": {}
}
},
"required": [
"expectedRowVersion",
"patch"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Updated user metadata",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LogicalDocument"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Reserved or invalid metadata",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Document resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Metadata CAS conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/logical-documents/{documentId}/availability": {
"patch": {
"operationId": "patchLogicalDocumentAvailability",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "documentId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"expectedRowVersion": {
"type": "integer",
"minimum": 0
}
},
"required": [
"enabled",
"expectedRowVersion"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Updated logical document availability",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LogicalDocument"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Document resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Document availability CAS conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/logical-documents/bulk/availability": {
"patch": {
"operationId": "bulkPatchLogicalDocumentAvailability",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"documents": {
"type": "array",
"items": {
"type": "object",
"properties": {
"documentId": {
"type": "string",
"format": "uuid"
},
"expectedRowVersion": {
"type": "integer",
"minimum": 0
}
},
"required": [
"documentId",
"expectedRowVersion"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 100
},
"enabled": {
"type": "boolean"
}
},
"required": [
"documents",
"enabled"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Per-document availability results",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/LogicalDocument"
},
{
"type": "object",
"properties": {
"documentId": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string",
"enum": [
"conflict",
"not_found"
]
}
},
"required": [
"documentId",
"status"
]
}
]
}
},
"total": {
"type": "integer",
"minimum": 0
}
},
"required": [
"items",
"total"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Document resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/documents/{documentId}/revisions/{revision}/chunks": {
"get": {
"operationId": "listDocumentChunks",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "documentId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "integer",
"exclusiveMinimum": 0
},
"required": true,
"name": "revision",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 2048
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"required": false,
"name": "limit",
"in": "query"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"required": false,
"name": "query",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Revision-scoped chunks",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentChunkList"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Document resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/documents/{documentId}/revisions/{revision}/chunks/{chunkId}": {
"get": {
"operationId": "getDocumentChunk",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "documentId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "integer",
"exclusiveMinimum": 0
},
"required": true,
"name": "revision",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "chunkId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Revision-scoped chunk",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentRevisionChunk"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Document resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/documents/{documentId}/revisions/{revision}/chunks/{chunkId}/state": {
"post": {
"operationId": "changeDocumentChunkState",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "documentId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "integer",
"exclusiveMinimum": 0
},
"required": true,
"name": "revision",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "chunkId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
}
},
"required": [
"enabled"
],
"additionalProperties": false
}
}
}
},
"responses": {
"202": {
"description": "Candidate publication accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentChunkStateChangeAccepted"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid chunk state",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Document resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Candidate publication coordinator unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/processing-tasks": {
"get": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 2048
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"required": false,
"name": "limit",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Space processing tasks",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentProcessingTaskList"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid pagination cursor",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Document resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getKnowledgeSpacesByIdProcessingTasks",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/documents/{documentId}/processing-tasks": {
"get": {
"operationId": "listDocumentProcessingTasks",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "documentId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 2048
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"required": false,
"name": "limit",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Document processing tasks",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentProcessingTaskList"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid pagination cursor",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Document resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/documents/{documentId}/processing-tasks/{taskId}": {
"get": {
"operationId": "getDocumentProcessingTask",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "documentId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "taskId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Processing task polling snapshot",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentProcessingTask"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Document resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
},
"delete": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "documentId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "taskId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Canceled processing task",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentProcessingTask"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Document resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Task cannot be canceled",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "deleteKnowledgeSpacesByIdDocumentsByDocumentIdProcessingTasksByTaskId",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/documents/{documentId}/processing-tasks/{taskId}/events": {
"get": {
"description": "Streams named progress and terminal SSE events with raw JSON data. Resume after Last-Event-ID when it matches an event in the current snapshot; an unknown cursor returns the current snapshot. A terminal cursor closes without replay. This bounded stream sends heartbeat comments and closes on a terminal state or its deadline.",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "documentId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "taskId",
"in": "path"
},
{
"schema": {
"type": "string",
"description": "The id of the last received SSE event."
},
"required": false,
"description": "The id of the last received SSE event.",
"name": "last-event-id",
"in": "header"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Processing task SSE stream; reconnect with Last-Event-ID or poll the task",
"content": {
"text/event-stream": {
"schema": {
"type": "string",
"description": "SSE frames contain id, event and data fields. progress data contains activeOperations, phase, progressPercent, semanticEnrichment, stage, state and updatedAt. terminal data contains state (succeeded, failed, canceled or superseded), and optional errorCode and failure. These are raw data objects, without an event/data wrapper."
},
"examples": {
"progress": {
"value": "id: task-id:2026-07-14T12:00:00.000Z\nevent: progress\ndata: {\"activeOperations\":[],\"phase\":\"queued\",\"progressPercent\":0,\"semanticEnrichment\":{\"nodesCompleted\":0,\"state\":\"not_scheduled\"},\"stage\":\"queued\",\"state\":\"queued\",\"updatedAt\":\"2026-07-14T12:00:00.000Z\"}\n\n"
},
"terminal": {
"value": "id: task-id:terminal\nevent: terminal\ndata: {\"state\":\"succeeded\"}\n\n"
}
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Document resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getKnowledgeSpacesByIdDocumentsByDocumentIdProcessingTasksByTaskIdEvents",
"x-knowledge-fs-max-response-bytes": 67108864,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/documents/{documentId}/processing-tasks/{taskId}/retry": {
"post": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "documentId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "taskId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Retried processing task",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentProcessingTask"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Document resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Task cannot be retried",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"413": {
"description": "Workspace vector storage quota exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Workspace vector storage quota unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "postKnowledgeSpacesByIdDocumentsByDocumentIdProcessingTasksByTaskIdRetry",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/documents/{documentId}/settings": {
"get": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "documentId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Active document index settings",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentSettingsHead"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Document resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getKnowledgeSpacesByIdDocumentsByDocumentIdSettings",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
},
"put": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "documentId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"expectedSettingsHeadRevision": {
"type": [
"integer",
"null"
],
"exclusiveMinimum": 0
},
"settings": {
"type": "object",
"properties": {
"chunkOverlap": {
"type": "integer",
"minimum": 0,
"maximum": 8191
},
"chunkSize": {
"type": "integer",
"minimum": 128,
"maximum": 8192
},
"enableGraph": {
"type": "boolean"
},
"enablePageIndex": {
"type": "boolean"
},
"language": {
"type": "string",
"minLength": 2,
"maxLength": 64
}
},
"required": [
"chunkOverlap",
"chunkSize",
"enableGraph",
"enablePageIndex"
],
"additionalProperties": false
}
},
"required": [
"expectedSettingsHeadRevision",
"settings"
],
"additionalProperties": false
}
}
}
},
"responses": {
"202": {
"description": "Versioned settings reindex accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentReindexAccepted"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Document resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Settings CAS conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Settings reindex coordinator unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "putKnowledgeSpacesByIdDocumentsByDocumentIdSettings",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/jobs/{id}": {
"get": {
"operationId": "getDocumentCompilationJob",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": false,
"name": "knowledgeSpaceId",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Document compilation job status",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentCompilationJob"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Document compilation job not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Document compilation jobs unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
},
"delete": {
"operationId": "cancelDocumentCompilationJob",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": false,
"name": "knowledgeSpaceId",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Canceled document compilation job",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentCompilationJob"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Document compilation job not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Document compilation job cannot be canceled",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Document compilation jobs unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/jobs/{id}/retry": {
"post": {
"operationId": "retryDocumentCompilationJob",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": false,
"name": "knowledgeSpaceId",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Reactivated document compilation attempt",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentCompilationJob"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Document compilation job not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Document compilation job cannot be retried",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"413": {
"description": "Workspace vector storage quota exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Document compilation service or workspace vector storage quota unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/publication-bootstrap": {
"post": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"202": {
"description": "Durable whole-space publication bootstrap accepted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"checkpoint": {
"type": "string",
"enum": [
"pending_snapshot",
"snapshot_captured",
"rebuilding",
"verifying",
"published"
]
},
"completedAt": {
"type": "string",
"format": "date-time"
},
"completedDocuments": {
"type": "integer",
"minimum": 0
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"lastErrorCode": {
"type": "string"
},
"lastErrorMessage": {
"type": "string"
},
"publishedFingerprint": {
"type": "string"
},
"publishedHeadRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"publishedPublicationId": {
"type": "string",
"format": "uuid"
},
"rowVersion": {
"type": "integer",
"minimum": 0
},
"runState": {
"type": "string",
"enum": [
"queued",
"running",
"succeeded",
"failed",
"canceled"
]
},
"tenantId": {
"type": "string",
"minLength": 1
},
"totalDocuments": {
"type": "integer",
"minimum": 0
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"checkpoint",
"completedDocuments",
"createdAt",
"id",
"knowledgeSpaceId",
"rowVersion",
"runState",
"tenantId",
"totalDocuments",
"updatedAt"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space or bootstrap not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Bootstrap lifecycle conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Legacy publication bootstrap unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "postKnowledgeSpacesByIdPublicationBootstrap",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
},
"get": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Whole-space publication bootstrap status",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"checkpoint": {
"type": "string",
"enum": [
"pending_snapshot",
"snapshot_captured",
"rebuilding",
"verifying",
"published"
]
},
"completedAt": {
"type": "string",
"format": "date-time"
},
"completedDocuments": {
"type": "integer",
"minimum": 0
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"lastErrorCode": {
"type": "string"
},
"lastErrorMessage": {
"type": "string"
},
"publishedFingerprint": {
"type": "string"
},
"publishedHeadRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"publishedPublicationId": {
"type": "string",
"format": "uuid"
},
"rowVersion": {
"type": "integer",
"minimum": 0
},
"runState": {
"type": "string",
"enum": [
"queued",
"running",
"succeeded",
"failed",
"canceled"
]
},
"tenantId": {
"type": "string",
"minLength": 1
},
"totalDocuments": {
"type": "integer",
"minimum": 0
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"checkpoint",
"completedDocuments",
"createdAt",
"id",
"knowledgeSpaceId",
"rowVersion",
"runState",
"tenantId",
"totalDocuments",
"updatedAt"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space or bootstrap not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Bootstrap lifecycle conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Legacy publication bootstrap unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getKnowledgeSpacesByIdPublicationBootstrap",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/publication-bootstrap/retry": {
"post": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"202": {
"description": "Failed whole-space bootstrap requeued",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"checkpoint": {
"type": "string",
"enum": [
"pending_snapshot",
"snapshot_captured",
"rebuilding",
"verifying",
"published"
]
},
"completedAt": {
"type": "string",
"format": "date-time"
},
"completedDocuments": {
"type": "integer",
"minimum": 0
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"lastErrorCode": {
"type": "string"
},
"lastErrorMessage": {
"type": "string"
},
"publishedFingerprint": {
"type": "string"
},
"publishedHeadRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"publishedPublicationId": {
"type": "string",
"format": "uuid"
},
"rowVersion": {
"type": "integer",
"minimum": 0
},
"runState": {
"type": "string",
"enum": [
"queued",
"running",
"succeeded",
"failed",
"canceled"
]
},
"tenantId": {
"type": "string",
"minLength": 1
},
"totalDocuments": {
"type": "integer",
"minimum": 0
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"checkpoint",
"completedDocuments",
"createdAt",
"id",
"knowledgeSpaceId",
"rowVersion",
"runState",
"tenantId",
"totalDocuments",
"updatedAt"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space or bootstrap not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Bootstrap lifecycle conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Legacy publication bootstrap unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "postKnowledgeSpacesByIdPublicationBootstrapRetry",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/page-index-upgrade": {
"get": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Current head PageIndex upgrade status",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"completedAt": {
"type": "string",
"format": "date-time"
},
"completedItems": {
"type": "integer",
"minimum": 0
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"headRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"lastErrorCode": {
"type": "string"
},
"lastErrorMessage": {
"type": "string"
},
"publicationFingerprint": {
"type": "string",
"minLength": 1
},
"publicationId": {
"type": "string",
"format": "uuid"
},
"retryCount": {
"type": "integer",
"minimum": 0
},
"rowVersion": {
"type": "integer",
"minimum": 0
},
"runState": {
"type": "string",
"enum": [
"queued",
"running",
"succeeded",
"failed",
"superseded"
]
},
"tenantId": {
"type": "string",
"minLength": 1
},
"totalItems": {
"type": "integer",
"minimum": 0
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"completedItems",
"createdAt",
"headRevision",
"id",
"knowledgeSpaceId",
"publicationFingerprint",
"publicationId",
"retryCount",
"rowVersion",
"runState",
"tenantId",
"totalItems",
"updatedAt"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space or PageIndex upgrade backfill not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "PageIndex upgrade lifecycle conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "PageIndex upgrade control plane unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getKnowledgeSpacesByIdPageIndexUpgrade",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
},
"post": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Existing current-head PageIndex upgrade",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"completedAt": {
"type": "string",
"format": "date-time"
},
"completedItems": {
"type": "integer",
"minimum": 0
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"headRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"lastErrorCode": {
"type": "string"
},
"lastErrorMessage": {
"type": "string"
},
"publicationFingerprint": {
"type": "string",
"minLength": 1
},
"publicationId": {
"type": "string",
"format": "uuid"
},
"retryCount": {
"type": "integer",
"minimum": 0
},
"rowVersion": {
"type": "integer",
"minimum": 0
},
"runState": {
"type": "string",
"enum": [
"queued",
"running",
"succeeded",
"failed",
"superseded"
]
},
"tenantId": {
"type": "string",
"minLength": 1
},
"totalItems": {
"type": "integer",
"minimum": 0
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"completedItems",
"createdAt",
"headRevision",
"id",
"knowledgeSpaceId",
"publicationFingerprint",
"publicationId",
"retryCount",
"rowVersion",
"runState",
"tenantId",
"totalItems",
"updatedAt"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Current-head PageIndex upgrade accepted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"completedAt": {
"type": "string",
"format": "date-time"
},
"completedItems": {
"type": "integer",
"minimum": 0
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"headRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"lastErrorCode": {
"type": "string"
},
"lastErrorMessage": {
"type": "string"
},
"publicationFingerprint": {
"type": "string",
"minLength": 1
},
"publicationId": {
"type": "string",
"format": "uuid"
},
"retryCount": {
"type": "integer",
"minimum": 0
},
"rowVersion": {
"type": "integer",
"minimum": 0
},
"runState": {
"type": "string",
"enum": [
"queued",
"running",
"succeeded",
"failed",
"superseded"
]
},
"tenantId": {
"type": "string",
"minLength": 1
},
"totalItems": {
"type": "integer",
"minimum": 0
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"completedItems",
"createdAt",
"headRevision",
"id",
"knowledgeSpaceId",
"publicationFingerprint",
"publicationId",
"retryCount",
"rowVersion",
"runState",
"tenantId",
"totalItems",
"updatedAt"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"204": {
"description": "Current head is already fully PageIndex-ready",
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space or PageIndex upgrade backfill not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "PageIndex upgrade lifecycle conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "PageIndex upgrade control plane unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "postKnowledgeSpacesByIdPageIndexUpgrade",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/page-index-upgrade/retry": {
"post": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"202": {
"description": "Failed current-head PageIndex upgrade requeued",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"completedAt": {
"type": "string",
"format": "date-time"
},
"completedItems": {
"type": "integer",
"minimum": 0
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"headRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"lastErrorCode": {
"type": "string"
},
"lastErrorMessage": {
"type": "string"
},
"publicationFingerprint": {
"type": "string",
"minLength": 1
},
"publicationId": {
"type": "string",
"format": "uuid"
},
"retryCount": {
"type": "integer",
"minimum": 0
},
"rowVersion": {
"type": "integer",
"minimum": 0
},
"runState": {
"type": "string",
"enum": [
"queued",
"running",
"succeeded",
"failed",
"superseded"
]
},
"tenantId": {
"type": "string",
"minLength": 1
},
"totalItems": {
"type": "integer",
"minimum": 0
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"completedItems",
"createdAt",
"headRevision",
"id",
"knowledgeSpaceId",
"publicationFingerprint",
"publicationId",
"retryCount",
"rowVersion",
"runState",
"tenantId",
"totalItems",
"updatedAt"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space or PageIndex upgrade backfill not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "PageIndex upgrade lifecycle conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "PageIndex upgrade control plane unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "postKnowledgeSpacesByIdPageIndexUpgradeRetry",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/tidb-fts-posting-backfill": {
"get": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Current TiDB lexical-posting repair status",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"completedAt": {
"type": "string",
"format": "date-time"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"cursorProjectionId": {
"type": "string",
"format": "uuid"
},
"heartbeatAt": {
"type": "string",
"format": "date-time"
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"lastErrorCode": {
"type": "string"
},
"lastErrorMessage": {
"type": "string"
},
"leaseExpiresAt": {
"type": "string",
"format": "date-time"
},
"retryCount": {
"type": "integer",
"minimum": 0
},
"rowVersion": {
"type": "integer",
"minimum": 0
},
"runState": {
"type": "string",
"enum": [
"queued",
"running",
"succeeded",
"failed"
]
},
"scannedProjections": {
"type": "integer",
"minimum": 0
},
"tenantId": {
"type": "string",
"minLength": 1
},
"tokenizerVersion": {
"type": "string",
"minLength": 1
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"workerId": {
"type": "string"
},
"writtenPostings": {
"type": "integer",
"minimum": 0
}
},
"required": [
"createdAt",
"id",
"knowledgeSpaceId",
"retryCount",
"rowVersion",
"runState",
"scannedProjections",
"tenantId",
"tokenizerVersion",
"updatedAt",
"writtenPostings"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space or TiDB FTS posting backfill not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "TiDB FTS posting backfill lifecycle conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "TiDB FTS posting backfill control plane unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getKnowledgeSpacesByIdTidbFtsPostingBackfill",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
},
"post": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Existing TiDB lexical-posting repair",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"completedAt": {
"type": "string",
"format": "date-time"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"cursorProjectionId": {
"type": "string",
"format": "uuid"
},
"heartbeatAt": {
"type": "string",
"format": "date-time"
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"lastErrorCode": {
"type": "string"
},
"lastErrorMessage": {
"type": "string"
},
"leaseExpiresAt": {
"type": "string",
"format": "date-time"
},
"retryCount": {
"type": "integer",
"minimum": 0
},
"rowVersion": {
"type": "integer",
"minimum": 0
},
"runState": {
"type": "string",
"enum": [
"queued",
"running",
"succeeded",
"failed"
]
},
"scannedProjections": {
"type": "integer",
"minimum": 0
},
"tenantId": {
"type": "string",
"minLength": 1
},
"tokenizerVersion": {
"type": "string",
"minLength": 1
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"workerId": {
"type": "string"
},
"writtenPostings": {
"type": "integer",
"minimum": 0
}
},
"required": [
"createdAt",
"id",
"knowledgeSpaceId",
"retryCount",
"rowVersion",
"runState",
"scannedProjections",
"tenantId",
"tokenizerVersion",
"updatedAt",
"writtenPostings"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "TiDB lexical-posting repair accepted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"completedAt": {
"type": "string",
"format": "date-time"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"cursorProjectionId": {
"type": "string",
"format": "uuid"
},
"heartbeatAt": {
"type": "string",
"format": "date-time"
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"lastErrorCode": {
"type": "string"
},
"lastErrorMessage": {
"type": "string"
},
"leaseExpiresAt": {
"type": "string",
"format": "date-time"
},
"retryCount": {
"type": "integer",
"minimum": 0
},
"rowVersion": {
"type": "integer",
"minimum": 0
},
"runState": {
"type": "string",
"enum": [
"queued",
"running",
"succeeded",
"failed"
]
},
"scannedProjections": {
"type": "integer",
"minimum": 0
},
"tenantId": {
"type": "string",
"minLength": 1
},
"tokenizerVersion": {
"type": "string",
"minLength": 1
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"workerId": {
"type": "string"
},
"writtenPostings": {
"type": "integer",
"minimum": 0
}
},
"required": [
"createdAt",
"id",
"knowledgeSpaceId",
"retryCount",
"rowVersion",
"runState",
"scannedProjections",
"tenantId",
"tokenizerVersion",
"updatedAt",
"writtenPostings"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"204": {
"description": "Knowledge space already has complete TiDB lexical postings",
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space or TiDB FTS posting backfill not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "TiDB FTS posting backfill lifecycle conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "TiDB FTS posting backfill control plane unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "postKnowledgeSpacesByIdTidbFtsPostingBackfill",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/tidb-fts-posting-backfill/retry": {
"post": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"202": {
"description": "Failed TiDB lexical-posting repair requeued from its durable cursor",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"completedAt": {
"type": "string",
"format": "date-time"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"cursorProjectionId": {
"type": "string",
"format": "uuid"
},
"heartbeatAt": {
"type": "string",
"format": "date-time"
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"lastErrorCode": {
"type": "string"
},
"lastErrorMessage": {
"type": "string"
},
"leaseExpiresAt": {
"type": "string",
"format": "date-time"
},
"retryCount": {
"type": "integer",
"minimum": 0
},
"rowVersion": {
"type": "integer",
"minimum": 0
},
"runState": {
"type": "string",
"enum": [
"queued",
"running",
"succeeded",
"failed"
]
},
"scannedProjections": {
"type": "integer",
"minimum": 0
},
"tenantId": {
"type": "string",
"minLength": 1
},
"tokenizerVersion": {
"type": "string",
"minLength": 1
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"workerId": {
"type": "string"
},
"writtenPostings": {
"type": "integer",
"minimum": 0
}
},
"required": [
"createdAt",
"id",
"knowledgeSpaceId",
"retryCount",
"rowVersion",
"runState",
"scannedProjections",
"tenantId",
"tokenizerVersion",
"updatedAt",
"writtenPostings"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space or TiDB FTS posting backfill not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "TiDB FTS posting backfill lifecycle conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "TiDB FTS posting backfill control plane unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "postKnowledgeSpacesByIdTidbFtsPostingBackfillRetry",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/graph/traverse": {
"get": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 2,
"default": 2
},
"required": false,
"name": "depth",
"in": "query"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "entityId",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 20
},
"required": false,
"name": "fanout",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
},
"required": false,
"name": "maxNodes",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 5000,
"default": 250
},
"required": false,
"name": "timeoutMs",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Bounded graph traversal result",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"entities": {
"type": "array",
"items": {
"type": "object",
"properties": {
"aliases": {
"type": "array",
"items": {
"type": "string"
}
},
"canonicalKey": {
"type": "string"
},
"confidence": {
"type": "number"
},
"createdAt": {
"type": "string"
},
"depth": {
"type": "integer",
"minimum": 0
},
"extractionVersion": {
"type": "integer",
"exclusiveMinimum": 0
},
"id": {
"type": "string"
},
"knowledgeSpaceId": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": {}
},
"name": {
"type": "string"
},
"permissionScope": {
"type": "array",
"items": {
"type": "string"
}
},
"sourceNodeIds": {
"type": "array",
"items": {
"type": "string"
}
},
"type": {
"type": "string",
"enum": [
"date",
"metric",
"organization",
"person",
"policy",
"product",
"term"
]
},
"updatedAt": {
"type": "string"
}
},
"required": [
"aliases",
"canonicalKey",
"confidence",
"createdAt",
"depth",
"extractionVersion",
"id",
"knowledgeSpaceId",
"metadata",
"name",
"permissionScope",
"sourceNodeIds",
"type",
"updatedAt"
]
}
},
"metrics": {
"type": "object",
"properties": {
"depthReached": {
"type": "integer",
"minimum": 0
},
"elapsedMs": {
"type": "number",
"minimum": 0
},
"exploredRelations": {
"type": "integer",
"minimum": 0
},
"fanout": {
"type": "integer",
"exclusiveMinimum": 0
},
"maxDepth": {
"type": "integer",
"exclusiveMinimum": 0
},
"maxNodes": {
"type": "integer",
"exclusiveMinimum": 0
},
"timedOut": {
"type": "boolean"
}
},
"required": [
"depthReached",
"elapsedMs",
"exploredRelations",
"fanout",
"maxDepth",
"maxNodes",
"timedOut"
]
},
"relations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"confidence": {
"type": "number"
},
"createdAt": {
"type": "string"
},
"depth": {
"type": "integer",
"exclusiveMinimum": 0
},
"extractionVersion": {
"type": "integer",
"exclusiveMinimum": 0
},
"id": {
"type": "string"
},
"knowledgeSpaceId": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": {}
},
"objectEntityId": {
"type": "string"
},
"permissionScope": {
"type": "array",
"items": {
"type": "string"
}
},
"sourceNodeIds": {
"type": "array",
"items": {
"type": "string"
}
},
"subjectEntityId": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"contradicts",
"defines",
"depends_on",
"mentions",
"references",
"supersedes",
"responsible_for",
"member_of",
"reports_to",
"part_of",
"owns",
"provides",
"uses",
"collaborates_with"
]
},
"updatedAt": {
"type": "string"
}
},
"required": [
"confidence",
"createdAt",
"depth",
"extractionVersion",
"id",
"knowledgeSpaceId",
"metadata",
"objectEntityId",
"permissionScope",
"sourceNodeIds",
"subjectEntityId",
"type",
"updatedAt"
]
}
},
"truncated": {
"type": "boolean"
}
},
"required": [
"entities",
"metrics",
"relations",
"truncated"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space or graph entity not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Immutable published graph traversal is unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getKnowledgeSpacesByIdGraphTraverse",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/queries/{traceId}": {
"get": {
"operationId": "getAnswerTrace",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "traceId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": false,
"name": "knowledgeSpaceId",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Answer trace",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AnswerTrace"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Answer trace not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/queries/{traceId}/evidence": {
"get": {
"operationId": "listQueryEvidence",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "traceId",
"in": "path"
},
{
"schema": {
"type": "string"
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": false,
"name": "knowledgeSpaceId",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"required": false,
"name": "limit",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Query evidence virtual tree",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"consistencyClass": {
"type": "string",
"enum": [
"path-consistent",
"snapshot-consistent",
"cache-consistent",
"eventual-preview"
]
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"directory",
"resource"
]
},
"metadata": {
"type": "object",
"additionalProperties": {}
},
"name": {
"type": "string"
},
"path": {
"type": "string"
},
"resourceType": {
"type": "string",
"enum": [
"source",
"document",
"node",
"artifact",
"evidence",
"workspace"
]
},
"targetId": {
"type": "string"
},
"version": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"kind",
"metadata",
"name",
"path"
]
}
},
"nextCursor": {
"type": "string"
},
"path": {
"type": "string"
},
"preview": {
"type": "boolean"
},
"truncated": {
"type": "boolean"
}
},
"required": [
"items",
"path",
"truncated"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid query evidence request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Answer trace not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/queries/{traceId}/conflicts": {
"get": {
"operationId": "listQueryConflicts",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "traceId",
"in": "path"
},
{
"schema": {
"type": "string"
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": false,
"name": "knowledgeSpaceId",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"required": false,
"name": "limit",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Query evidence virtual tree",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"consistencyClass": {
"type": "string",
"enum": [
"path-consistent",
"snapshot-consistent",
"cache-consistent",
"eventual-preview"
]
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"directory",
"resource"
]
},
"metadata": {
"type": "object",
"additionalProperties": {}
},
"name": {
"type": "string"
},
"path": {
"type": "string"
},
"resourceType": {
"type": "string",
"enum": [
"source",
"document",
"node",
"artifact",
"evidence",
"workspace"
]
},
"targetId": {
"type": "string"
},
"version": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"kind",
"metadata",
"name",
"path"
]
}
},
"nextCursor": {
"type": "string"
},
"path": {
"type": "string"
},
"preview": {
"type": "boolean"
},
"truncated": {
"type": "boolean"
}
},
"required": [
"items",
"path",
"truncated"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid query evidence request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Answer trace not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/queries/{traceId}/missing": {
"get": {
"operationId": "listQueryMissing",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "traceId",
"in": "path"
},
{
"schema": {
"type": "string"
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": false,
"name": "knowledgeSpaceId",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"required": false,
"name": "limit",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Query evidence virtual tree",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"consistencyClass": {
"type": "string",
"enum": [
"path-consistent",
"snapshot-consistent",
"cache-consistent",
"eventual-preview"
]
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"directory",
"resource"
]
},
"metadata": {
"type": "object",
"additionalProperties": {}
},
"name": {
"type": "string"
},
"path": {
"type": "string"
},
"resourceType": {
"type": "string",
"enum": [
"source",
"document",
"node",
"artifact",
"evidence",
"workspace"
]
},
"targetId": {
"type": "string"
},
"version": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"kind",
"metadata",
"name",
"path"
]
}
},
"nextCursor": {
"type": "string"
},
"path": {
"type": "string"
},
"preview": {
"type": "boolean"
},
"truncated": {
"type": "boolean"
}
},
"required": [
"items",
"path",
"truncated"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid query evidence request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Answer trace not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/bulk-jobs/{id}": {
"get": {
"operationId": "getBulkOperation",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": false,
"name": "knowledgeSpaceId",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Bulk operation progress",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkOperationProgress"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Bulk operation not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Bulk progress dependencies unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/retention-policy": {
"get": {
"responses": {
"200": {
"description": "Tenant retention policy",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RetentionPolicy"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getRetentionPolicy",
"parameters": [
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
},
"patch": {
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"answerTraceRetentionDays": {
"type": "integer",
"exclusiveMinimum": 0
},
"evidenceCacheRetentionDays": {
"type": "integer",
"exclusiveMinimum": 0
},
"inactiveProjectionRetentionDays": {
"type": "integer",
"exclusiveMinimum": 0
},
"parseArtifactVersions": {
"type": "integer",
"exclusiveMinimum": 0
},
"rawDocumentRetentionDays": {
"type": [
"integer",
"null"
],
"exclusiveMinimum": 0
},
"sessionInactivityMinutes": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Updated tenant retention policy",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RetentionPolicy"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid retention policy",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "patchRetentionPolicy",
"parameters": [
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/retention-policy": {
"get": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Knowledge-space retention policy",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RetentionPolicy"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getKnowledgeSpacesByIdRetentionPolicy",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
},
"patch": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"answerTraceRetentionDays": {
"type": "integer",
"exclusiveMinimum": 0
},
"evidenceCacheRetentionDays": {
"type": "integer",
"exclusiveMinimum": 0
},
"inactiveProjectionRetentionDays": {
"type": "integer",
"exclusiveMinimum": 0
},
"parseArtifactVersions": {
"type": "integer",
"exclusiveMinimum": 0
},
"rawDocumentRetentionDays": {
"type": [
"integer",
"null"
],
"exclusiveMinimum": 0
},
"sessionInactivityMinutes": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Updated knowledge-space retention policy",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RetentionPolicy"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid retention policy",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "patchKnowledgeSpacesByIdRetentionPolicy",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/queries": {
"post": {
"operationId": "createQuery",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"activeDocumentIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 100,
"default": []
},
"activeEntityIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"maxItems": 100,
"default": []
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"mode": {
"type": "string",
"enum": [
"auto",
"deep",
"fast",
"research"
],
"description": "Explicit auto invokes the knowledge space reasoning model once to select fast, deep, or research; omission uses the published defaultMode."
},
"query": {
"type": "string",
"maxLength": 16000
},
"queryImages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uploadFileId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"uploadFileId"
],
"additionalProperties": false
},
"maxItems": 4,
"default": []
},
"sessionId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"knowledgeSpaceId"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Streaming generated answer. SSE data.traceId and x-query-run-id identify the durable AnswerTrace; x-trace-id is transport correlation.",
"headers": {
"x-query-run-id": {
"description": "Server-generated durable query-run and AnswerTrace UUID",
"schema": {
"format": "uuid",
"type": "string"
}
},
"x-session-id": {
"description": "Generated or reused query session UUID",
"schema": {
"format": "uuid",
"type": "string"
}
},
"x-trace-id": {
"description": "HTTP transport correlation ID; not the AnswerTrace resource ID",
"schema": {
"type": "string"
}
}
},
"content": {
"text/event-stream": {
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid query request",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"RETRIEVAL_PROFILE_SCORE_THRESHOLD_REQUIRES_RERANK"
]
},
"error": {
"type": "string",
"enum": [
"Fast/Deep mode-final score threshold requires the knowledge-space reranker to be enabled"
]
},
"mode": {
"type": "string",
"enum": [
"fast",
"research",
"deep"
]
}
},
"required": [
"code",
"error",
"mode"
],
"additionalProperties": false
},
{
"$ref": "#/components/schemas/ErrorResponse"
}
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Query admission rejected while knowledge deletion is active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Query generation unavailable",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ErrorResponse"
},
{
"type": "object",
"properties": {
"runState": {
"type": "string",
"enum": [
"queued",
"running",
"succeeded",
"failed",
"unregistered"
]
}
}
}
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"parameters": [
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"x-knowledge-fs-max-response-bytes": 67108864,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/retrieval-tests": {
"post": {
"operationId": "runRetrievalTest",
"x-knowledge-fs-max-response-bytes": 4194304,
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"filters": {
"type": "object",
"properties": {
"createdAfter": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"createdBefore": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"customMetadata": {
"type": "object",
"properties": {
"conditions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"comparisonOperator": {
"type": "string",
"enum": [
"contains",
"not contains",
"start with",
"end with",
"is",
"is not",
"empty",
"not empty",
"in",
"not in",
"=",
"≠",
">",
"<",
"≥",
"≤",
"before",
"after"
]
},
"fieldType": {
"type": "string",
"enum": [
"string",
"number",
"time"
]
},
"name": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]{0,254}$"
},
"value": {
"anyOf": [
{
"type": "string",
"maxLength": 1024
},
{
"type": "number"
}
]
}
},
"required": [
"comparisonOperator",
"fieldType",
"name"
],
"additionalProperties": false
},
"maxItems": 50
},
"logicalOperator": {
"type": "string",
"enum": [
"and",
"or"
]
}
},
"required": [
"conditions",
"logicalOperator"
],
"additionalProperties": false
},
"documentTypes": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"maxItems": 100
},
"entities": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"maxItems": 100
},
"freshnessStatuses": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"maxItems": 100
},
"languages": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"maxItems": 100
},
"nodeKinds": {
"type": "array",
"items": {
"type": "string",
"enum": [
"chunk",
"section",
"table",
"image",
"summary"
]
},
"maxItems": 100
},
"sourceIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"maxItems": 100
},
"tags": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"maxItems": 100
}
},
"additionalProperties": false
},
"includeText": {
"type": "boolean",
"default": false
},
"mode": {
"type": "string",
"enum": [
"fast",
"research",
"deep"
]
},
"query": {
"type": "string",
"maxLength": 32000,
"default": ""
},
"queryId": {
"type": "string",
"format": "uuid"
},
"queryImages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uploadFileId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"uploadFileId"
],
"additionalProperties": false
},
"maxItems": 4,
"default": []
}
},
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Bounded retrieval-stage diagnostics without answer generation",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"answerTraceId": {
"type": "string",
"format": "uuid"
},
"capabilityStatus": {
"type": "object",
"properties": {
"embedding": {
"type": "string",
"enum": [
"not-required",
"verified"
]
},
"reasoning": {
"type": "string",
"enum": [
"verified"
]
},
"rerank": {
"type": "string",
"enum": [
"disabled",
"not-required",
"verified"
]
}
},
"required": [
"embedding",
"reasoning",
"rerank"
],
"additionalProperties": false
},
"embeddingProfile": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"dimension": {
"type": "integer",
"exclusiveMinimum": 0
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
},
"vectorSpaceId": {
"type": "string",
"pattern": "^embedding-space-sha256:[a-f0-9]{64}$"
}
},
"required": [
"model",
"pluginId",
"provider",
"revision",
"vectorSpaceId"
],
"additionalProperties": false
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"citation": {
"type": "object",
"properties": {
"artifactHash": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"documentAssetId": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"documentTitle": {
"type": "string",
"maxLength": 512
},
"documentVersion": {
"type": "integer",
"exclusiveMinimum": 0
},
"endOffset": {
"type": "integer",
"minimum": 0
},
"knowledgeSpaceName": {
"type": "string",
"maxLength": 160
},
"logicalDocumentId": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"logicalDocumentRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"pageNumber": {
"type": "integer",
"minimum": 0
},
"sectionPath": {
"type": "array",
"items": {
"type": "string",
"maxLength": 512
},
"maxItems": 64
},
"startOffset": {
"type": "integer",
"minimum": 0
}
},
"required": [
"artifactHash",
"documentAssetId",
"documentVersion",
"sectionPath"
],
"additionalProperties": false
},
"nodeId": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"projectionIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"maxItems": 128
},
"score": {
"type": "number"
},
"sources": {
"type": "array",
"items": {
"type": "string",
"enum": [
"dense",
"fts",
"pageindex",
"visual"
]
},
"maxItems": 4
},
"text": {
"type": "string",
"maxLength": 16384
}
},
"required": [
"citation",
"nodeId",
"projectionIds",
"score",
"sources"
],
"additionalProperties": false
},
"maxItems": 100
},
"metrics": {
"type": "object",
"properties": {
"degradationFlags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 256
},
"maxItems": 32
},
"denseCandidates": {
"type": "integer",
"minimum": 0
},
"denseMs": {
"type": "number",
"minimum": 0
},
"documentOutlineMatchedItems": {
"type": "integer",
"minimum": 0
},
"ftsCandidates": {
"type": "integer",
"minimum": 0
},
"ftsMs": {
"type": "number",
"minimum": 0
},
"fusedCandidates": {
"type": "integer",
"minimum": 0
},
"fusionMs": {
"type": "number",
"minimum": 0
},
"graphExpansionCandidates": {
"type": "integer",
"minimum": 0
},
"graphExpansionMs": {
"type": "number",
"minimum": 0
},
"graphExpansionRelations": {
"type": "integer",
"minimum": 0
},
"graphExpansionSeeds": {
"type": "integer",
"minimum": 0
},
"graphExpansionTimedOut": {
"type": "boolean"
},
"graphExpansionTraversedEntities": {
"type": "integer",
"minimum": 0
},
"imageCandidates": {
"type": "integer",
"minimum": 0
},
"metadataFilteredCandidates": {
"type": "integer",
"minimum": 0
},
"multimodalCandidates": {
"type": "integer",
"minimum": 0
},
"pageIndexCandidateTruncated": {
"type": "boolean"
},
"pageIndexFallbackDocuments": {
"type": "integer",
"minimum": 0
},
"pageIndexFlattenedLevels": {
"type": "integer",
"minimum": 0
},
"pageIndexLayeredDocuments": {
"type": "integer",
"minimum": 0
},
"pageIndexLayeredSteps": {
"type": "integer",
"minimum": 0
},
"pageIndexMatchedNodes": {
"type": "integer",
"minimum": 0
},
"pageIndexOpenedRanges": {
"type": "integer",
"minimum": 0
},
"pageIndexScannedNodes": {
"type": "integer",
"minimum": 0
},
"pageIndexScannedOutlines": {
"type": "integer",
"minimum": 0
},
"pageIndexScoreVersion": {
"type": "string",
"maxLength": 256
},
"pageIndexSelectedDocuments": {
"type": "integer",
"minimum": 0
},
"pageIndexSerializedTreeTokens": {
"type": "integer",
"minimum": 0
},
"pageIndexWholeTreeDocuments": {
"type": "integer",
"minimum": 0
},
"permissionFilteredCandidates": {
"type": "integer",
"minimum": 0
},
"projectionFilteredCandidates": {
"type": "integer",
"minimum": 0
},
"researchBudgetExhaustedReasons": {
"type": "array",
"items": {
"type": "string",
"maxLength": 256
},
"maxItems": 6
},
"researchCandidateLists": {
"type": "integer",
"minimum": 0
},
"researchEvidenceJudgeMs": {
"type": "number",
"minimum": 0
},
"researchExecutionKind": {
"type": "string",
"enum": [
"durable",
"interactive"
]
},
"researchModelCalls": {
"type": "integer",
"minimum": 0
},
"researchOpenedResources": {
"type": "integer",
"minimum": 0
},
"researchOutlineLexicalCandidates": {
"type": "integer",
"minimum": 0
},
"researchPlanMs": {
"type": "number",
"minimum": 0
},
"researchQueryEmbeddingMs": {
"type": "number",
"minimum": 0
},
"researchRecallDenseCandidates": {
"type": "integer",
"minimum": 0
},
"researchRecallFtsCandidates": {
"type": "integer",
"minimum": 0
},
"researchRerankCandidateBudget": {
"type": "integer",
"minimum": 0
},
"researchRerankListCandidates": {
"type": "array",
"items": {
"type": "integer",
"minimum": 0
},
"maxItems": 5
},
"researchRetrievalSteps": {
"type": "integer",
"minimum": 0
},
"researchRrfCandidates": {
"type": "integer",
"minimum": 0
},
"researchRounds": {
"type": "integer",
"minimum": 0
},
"researchStrategyVersion": {
"type": "string",
"enum": [
"research-evidence-v3"
]
},
"researchSufficiencyReached": {
"type": "boolean"
},
"researchSupplementalSearches": {
"type": "integer",
"minimum": 0
},
"reasoningTreeSearchNodes": {
"type": "integer",
"minimum": 0
},
"rerankCandidates": {
"type": "integer",
"minimum": 0
},
"rerankMs": {
"type": "number",
"minimum": 0
},
"scoreThresholdFilteredCandidates": {
"type": "integer",
"minimum": 0
},
"summaryCandidates": {
"type": "integer",
"minimum": 0
},
"summarySelectedSections": {
"type": "integer",
"minimum": 0
},
"tableCandidates": {
"type": "integer",
"minimum": 0
},
"totalMs": {
"type": "number",
"minimum": 0
},
"visualEmbeddingCandidates": {
"type": "integer",
"minimum": 0
}
},
"required": [
"denseCandidates",
"denseMs",
"ftsCandidates",
"ftsMs",
"fusedCandidates",
"fusionMs",
"totalMs"
]
},
"mode": {
"type": "string",
"enum": [
"fast",
"research",
"deep"
]
},
"plan": {
"type": "object",
"properties": {
"denseTopK": {
"type": "integer",
"minimum": 0
},
"ftsTopK": {
"type": "integer",
"minimum": 0
},
"fusionLimit": {
"type": "integer",
"minimum": 0
},
"queryLanguage": {
"type": "string",
"enum": [
"cjk",
"latin",
"mixed-cjk-latin",
"other"
]
},
"requestedMode": {
"type": "string",
"enum": [
"fast",
"research",
"deep"
]
},
"rerankCandidateLimit": {
"type": "integer",
"minimum": 0
},
"resolvedMode": {
"type": "string",
"enum": [
"fast",
"research",
"deep"
]
},
"strategyVersion": {
"type": "string",
"enum": [
"retrieval-planner-v1",
"retrieval-planner-v2"
]
},
"topK": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"required": [
"denseTopK",
"ftsTopK",
"fusionLimit",
"queryLanguage",
"requestedMode",
"rerankCandidateLimit",
"resolvedMode",
"strategyVersion",
"topK"
],
"additionalProperties": false
},
"projectionSnapshot": {
"type": "object",
"properties": {
"fingerprint": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"headRevision": {
"type": "integer",
"minimum": 0
},
"projectionVersion": {
"type": "integer",
"minimum": 0
},
"publicationId": {
"type": "string",
"minLength": 1,
"maxLength": 512
}
},
"required": [
"fingerprint",
"headRevision",
"projectionVersion",
"publicationId"
],
"additionalProperties": false
},
"retrievalProfile": {
"type": "object",
"properties": {
"defaultMode": {
"type": "string",
"enum": [
"fast",
"research",
"deep"
]
},
"reasoningModel": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
},
"rerank": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"model": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"pluginId",
"provider"
],
"additionalProperties": false
}
},
"required": [
"enabled"
],
"additionalProperties": false
},
"scoreThreshold": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"stage": {
"type": "string",
"enum": [
"mode-final",
"rerank"
]
},
"value": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"enabled",
"stage"
],
"additionalProperties": false
},
"topK": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"defaultMode",
"reasoningModel",
"rerank",
"scoreThreshold",
"topK",
"revision"
],
"additionalProperties": false
},
"stages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"candidateCount": {
"type": "integer",
"minimum": 0
},
"durationMs": {
"type": "number",
"minimum": 0
},
"filteredCount": {
"type": "integer",
"minimum": 0
},
"name": {
"type": "string",
"enum": [
"embedding",
"dense",
"fts",
"fusion",
"summary",
"outline",
"pageindex",
"graph",
"rerank",
"permission_filter",
"publication_filter",
"threshold",
"top_k"
]
},
"status": {
"type": "string",
"enum": [
"executed",
"skipped"
]
}
},
"required": [
"name",
"status"
],
"additionalProperties": false
},
"maxItems": 13
},
"traceId": {
"type": "string",
"minLength": 1,
"maxLength": 512
}
},
"required": [
"capabilityStatus",
"items",
"metrics",
"mode",
"plan",
"projectionSnapshot",
"retrievalProfile",
"stages",
"traceId"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid retrieval test request",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"RETRIEVAL_PROFILE_SCORE_THRESHOLD_REQUIRES_RERANK"
]
},
"error": {
"type": "string",
"enum": [
"Fast/Deep mode-final score threshold requires the knowledge-space reranker to be enabled"
]
},
"mode": {
"type": "string",
"enum": [
"fast",
"research",
"deep"
]
}
},
"required": [
"code",
"error",
"mode"
],
"additionalProperties": false
},
{
"$ref": "#/components/schemas/ErrorResponse"
}
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Retrieval blocked by knowledge-space deletion",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ErrorResponse"
},
{
"type": "object",
"properties": {}
}
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"413": {
"description": "Query image count or size exceeds retrieval-test limits",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Published retrieval test capability unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/failed-queries": {
"get": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string"
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200
},
"required": false,
"name": "limit",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"pending-triage",
"triaged",
"pending-annotation",
"annotated",
"dismissed",
"promoted"
]
},
"required": false,
"name": "status",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Knowledge space failed queries",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FailedQuery"
}
},
"nextCursor": {
"type": "string"
}
},
"required": [
"items"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid failed-query list request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getKnowledgeSpacesByIdFailedQueries",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/failed-queries/metrics": {
"get": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Failed-query counts by status and the golden-question promotion rate",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FailedQueryMetrics"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getKnowledgeSpacesByIdFailedQueriesMetrics",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/failed-queries/triage": {
"post": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200
},
"required": false,
"name": "limit",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Triaged a batch of pending failed queries",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FailedQueryTriageResult"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"501": {
"description": "Relevance triage is not configured",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "postKnowledgeSpacesByIdFailedQueriesTriage",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/failed-queries/clusters": {
"get": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 1000
},
"required": false,
"name": "limit",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"pending-triage",
"triaged",
"pending-annotation",
"annotated",
"dismissed",
"promoted"
]
},
"required": false,
"name": "status",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Failed queries grouped into clusters, most frequent first",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FailedQueryClusters"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getKnowledgeSpacesByIdFailedQueriesClusters",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/failed-queries/{failedQueryId}": {
"patch": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "failedQueryId",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"expectedEvidenceIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 100
},
"note": {
"type": "string",
"maxLength": 2000
},
"verdict": {
"type": "string",
"enum": [
"retrieval-miss",
"coverage-gap",
"irrelevant"
]
}
},
"required": [
"verdict"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Annotated failed query (promoted to a golden question for retrieval-miss)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FailedQuery"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space or failed query not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Failed query was already promoted with different annotation input",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "patchKnowledgeSpacesByIdFailedQueriesByFailedQueryId",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/agent-investigations": {
"post": {
"operationId": "captureAgentKnowledgeInvestigation",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"investigationId": {
"type": "string",
"format": "uuid"
},
"query": {
"type": "string",
"maxLength": 16000
},
"answer": {
"type": "string",
"maxLength": 24000
},
"status": {
"type": "string",
"enum": [
"completed",
"interrupted"
]
},
"attempts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"command_id": {
"type": "string",
"format": "uuid"
},
"control_space_id": {
"type": "string",
"format": "uuid"
},
"command": {
"type": "string",
"enum": [
"search",
"find",
"grep",
"ls",
"tree",
"cat",
"stat",
"diff",
"open",
"images",
"image"
]
},
"query": {
"type": "string",
"maxLength": 8000
},
"path": {
"type": "string",
"maxLength": 8192
},
"outcome": {
"type": "string",
"enum": [
"evidence",
"empty",
"error"
]
},
"code": {
"type": [
"string",
"null"
],
"maxLength": 120
},
"started_at_ms": {
"type": "integer",
"minimum": 0
},
"elapsed_ms": {
"type": "integer",
"minimum": 0
},
"delivered": {
"type": "boolean"
},
"result_count": {
"type": "integer",
"minimum": 0
},
"truncated": {
"type": "boolean"
},
"evidence": {
"type": "string",
"maxLength": 4000
},
"receipt_ids": {
"type": "array",
"items": {
"type": "string",
"pattern": "^kfs_[a-f0-9]{32}$"
},
"maxItems": 50
},
"authorization_fingerprint": {
"type": [
"string",
"null"
],
"pattern": "^[a-f0-9]{64}$"
},
"trace_id": {
"type": [
"string",
"null"
],
"maxLength": 512
}
},
"required": [
"command_id",
"control_space_id",
"command",
"query",
"path",
"outcome",
"code",
"started_at_ms",
"elapsed_ms",
"delivered",
"evidence",
"receipt_ids",
"authorization_fingerprint",
"trace_id"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 64
}
},
"required": [
"investigationId",
"query",
"answer",
"status",
"attempts"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Investigation recorded and classified once",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"traceId": {
"type": "string",
"format": "uuid"
},
"outcome": {
"type": "string"
},
"records": {
"type": "array",
"items": {
"type": "object",
"properties": {
"failedQueryId": {
"type": "string",
"format": "uuid"
},
"badCaseId": {
"type": "string",
"format": "uuid"
},
"verdict": {
"type": "string"
}
},
"required": [
"failedQueryId",
"verdict"
]
}
}
},
"required": [
"traceId",
"outcome",
"records"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Investigation unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Investigation unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Investigation unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Investigation unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/failed-queries/workflow-retrieval-misses": {
"post": {
"operationId": "captureWorkflowFailedRetrieval",
"x-knowledge-fs-max-response-bytes": 1048576,
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"eventId": {
"type": "string",
"format": "uuid"
},
"mode": {
"type": "string",
"enum": [
"fast",
"deep",
"research"
]
},
"query": {
"type": "string",
"minLength": 1,
"maxLength": 32000
},
"retrievalTraceId": {
"type": "string",
"minLength": 1,
"maxLength": 1024
}
},
"required": [
"eventId",
"mode",
"query",
"retrievalTraceId"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Idempotently capture and classify a workflow retrieval with no evidence",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"badCaseId": {
"type": "string",
"format": "uuid"
},
"failedQueryId": {
"type": "string",
"format": "uuid"
},
"verdict": {
"type": "string",
"enum": [
"retrieval-miss",
"coverage-gap",
"irrelevant",
"uncertain"
]
}
},
"required": [
"failedQueryId",
"verdict"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Event id conflicts with a different workflow retrieval",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Failed-retrieval capture or LLM triage is unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/agent-workspace-snapshots": {
"post": {
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"commandLog": {
"type": "array",
"items": {
"type": "object",
"properties": {
"command": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"completedAt": {
"type": "string",
"format": "date-time"
},
"cost": {
"type": "object",
"additionalProperties": {}
},
"input": {
"type": "object",
"additionalProperties": {},
"default": {}
},
"outputSummary": {
"type": "string",
"maxLength": 4000
},
"startedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"command",
"startedAt"
],
"additionalProperties": false
},
"default": []
},
"evidenceBundles": {
"type": "array",
"items": {
"type": "object",
"properties": {
"createdAt": {
"type": "string",
"format": "date-time"
},
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"citations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"artifactHash": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"documentAssetId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"documentVersion": {
"type": "integer",
"exclusiveMinimum": 0
},
"endOffset": {
"type": "integer",
"minimum": 0
},
"pageNumber": {
"type": "integer",
"exclusiveMinimum": 0
},
"sectionPath": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"default": []
},
"startOffset": {
"type": "integer",
"minimum": 0
}
},
"required": [
"documentAssetId",
"documentVersion"
]
},
"minItems": 1
},
"conflicts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"severity": {
"type": "string",
"enum": [
"info",
"warning",
"blocking"
]
},
"withNodeId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
}
},
"required": [
"reason",
"severity"
]
},
"default": []
},
"freshness": {
"type": "object",
"properties": {
"observedAt": {
"type": "string",
"format": "date-time"
},
"sourceUpdatedAt": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string",
"enum": [
"fresh",
"stale",
"unknown"
]
}
},
"required": [
"status"
]
},
"metadata": {
"type": "object",
"additionalProperties": {},
"default": {}
},
"nodeId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"score": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"scores": {
"type": "object",
"properties": {
"final": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"freshness": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"rerank": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"retrieval": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"final",
"retrieval"
]
},
"text": {
"type": "string",
"minLength": 1
}
},
"required": [
"citations",
"freshness",
"nodeId",
"score",
"scores",
"text"
]
}
},
"missingEvidence": {
"type": "array",
"items": {
"type": "object",
"properties": {
"expectedEvidenceId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"metadata": {
"type": "object",
"additionalProperties": {},
"default": {}
},
"reason": {
"type": "string",
"enum": [
"not-retrieved",
"permission-filtered",
"stale",
"conflict",
"unknown"
]
},
"text": {
"type": "string",
"minLength": 1,
"maxLength": 4000
}
},
"required": [
"reason",
"text"
]
},
"default": []
},
"query": {
"type": "string"
},
"queryImages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"byteSize": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 10485760
},
"mimeType": {
"type": "string",
"enum": [
"image/gif",
"image/jpeg",
"image/png",
"image/webp"
]
},
"sha256": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"uploadFileId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
}
},
"required": [
"byteSize",
"mimeType",
"sha256",
"uploadFileId"
]
},
"maxItems": 4
},
"retrievalQuery": {
"type": "string",
"minLength": 1
},
"state": {
"type": "string",
"enum": [
"answerable",
"partial",
"not-enough-evidence",
"conflict",
"permission-limited"
]
},
"traceId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
}
},
"required": [
"createdAt",
"id",
"items",
"query",
"state"
]
},
"default": []
},
"indexProjection": {
"type": "object",
"properties": {
"fingerprint": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"projectionIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 240
},
"default": []
}
},
"required": [
"fingerprint"
],
"additionalProperties": false
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"manifestVersion": {
"type": "integer",
"exclusiveMinimum": 0,
"default": 1
},
"metadata": {
"type": "object",
"additionalProperties": {},
"default": {}
},
"mounts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"cachePolicy": {
"type": "object",
"properties": {
"maxBytes": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 1073741824
},
"strategy": {
"type": "string",
"enum": [
"none",
"memory",
"object-storage"
]
},
"ttlSeconds": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 86400
}
},
"default": {
"strategy": "none"
},
"required": [
"strategy"
]
},
"capabilities": {
"type": "array",
"items": {
"type": "string",
"enum": [
"ls",
"tree",
"cat",
"grep",
"find",
"stat",
"diff",
"sync",
"watch"
]
},
"default": []
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"freshnessPolicy": {
"type": "object",
"properties": {
"staleAfterSeconds": {
"type": "integer",
"exclusiveMinimum": 0
},
"strategy": {
"type": "string",
"enum": [
"realtime",
"ttl",
"manual",
"async"
]
}
},
"required": [
"strategy"
]
},
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"knowledgeSpaceId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"lastSyncedAt": {
"type": "string",
"format": "date-time"
},
"metadata": {
"type": "object",
"additionalProperties": {},
"default": {}
},
"mode": {
"type": "string",
"enum": [
"read",
"write",
"exec"
]
},
"mountPath": {
"type": "string",
"maxLength": 384,
"pattern": "^\\/(?:sources|knowledge|evidence|workspaces)(?:\\/[^/\\s]+)*$"
},
"permissionScope": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"default": []
},
"permissionSnapshotVersion": {
"type": "integer",
"exclusiveMinimum": 0
},
"provider": {
"type": "string",
"enum": [
"upload",
"object-storage",
"connector",
"web",
"database",
"github",
"slack",
"internal"
]
},
"resourceType": {
"type": "string",
"enum": [
"source",
"document",
"node",
"artifact",
"evidence",
"workspace"
]
},
"sourcePointer": {
"type": "string",
"minLength": 1
},
"tenantId": {
"type": "string",
"minLength": 1,
"maxLength": 255
}
},
"required": [
"createdAt",
"freshnessPolicy",
"id",
"knowledgeSpaceId",
"mode",
"mountPath",
"permissionSnapshotVersion",
"provider",
"resourceType",
"sourcePointer",
"tenantId"
]
},
"default": []
},
"pathVersions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"virtualPath": {
"type": "string",
"minLength": 1,
"maxLength": 1000
}
},
"required": [
"version",
"virtualPath"
],
"additionalProperties": false
},
"default": []
},
"researchTaskJobId": {
"type": "string",
"minLength": 1,
"maxLength": 240
},
"sourceVersions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"providerResourceKey": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"version": {
"type": "string",
"minLength": 1,
"maxLength": 512
}
},
"required": [
"provider",
"providerResourceKey",
"version"
],
"additionalProperties": false
},
"default": []
},
"traceIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"default": []
}
},
"required": [
"indexProjection",
"knowledgeSpaceId"
],
"additionalProperties": false
}
}
}
},
"responses": {
"201": {
"description": "Created agent workspace snapshot",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentWorkspaceSnapshot"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid agent workspace snapshot request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "postAgentWorkspaceSnapshots",
"parameters": [
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/agent-workspace-snapshots/{id}": {
"get": {
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 240
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Agent workspace snapshot",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentWorkspaceSnapshot"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Agent workspace snapshot not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getAgentWorkspaceSnapshotsById",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/agent-workspace-snapshots/{id}/replay": {
"post": {
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 240
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Agent workspace snapshot replay",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentWorkspaceReplay"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Agent workspace snapshot not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Agent workspace snapshot replay failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "postAgentWorkspaceSnapshotsByIdReplay",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/research-tasks": {
"get": {
"operationId": "listKnowledgeSpaceResearchTasks",
"tags": [
"Research Tasks"
],
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
},
"required": false,
"name": "limit",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Capability-grant-owned Research tasks in one knowledge space",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResearchTaskJobList"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid Research task list cursor",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Research task listing is unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/research-tasks/plan": {
"post": {
"operationId": "planResearchTask",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"budgetUsd": {
"type": "number",
"minimum": 0
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"mode": {
"type": "string",
"enum": [
"auto",
"deep",
"fast",
"research"
],
"description": "Explicit auto uses the frozen knowledge-space reasoning model once; retries never reclassify."
},
"query": {
"type": "string",
"maxLength": 16000
},
"queryImages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uploadFileId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"uploadFileId"
],
"additionalProperties": false
},
"maxItems": 4,
"default": []
},
"topK": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 50
}
},
"required": [
"knowledgeSpaceId"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Dry-run research task plan",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResearchTaskDryRunPlan"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid research task plan request",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"RETRIEVAL_PROFILE_SCORE_THRESHOLD_REQUIRES_RERANK"
]
},
"error": {
"type": "string",
"enum": [
"Fast/Deep mode-final score threshold requires the knowledge-space reranker to be enabled"
]
},
"mode": {
"type": "string",
"enum": [
"fast",
"research",
"deep"
]
}
},
"required": [
"code",
"error",
"mode"
],
"additionalProperties": false
},
{
"$ref": "#/components/schemas/ErrorResponse"
}
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Published runtime snapshot is unavailable or not query-ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"parameters": [
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/research-tasks": {
"post": {
"operationId": "createResearchTask",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 255
},
"required": false,
"name": "Idempotency-Key",
"in": "header"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"budgetUsd": {
"type": "number",
"minimum": 0
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"limits": {
"type": "object",
"properties": {
"maxRetrievalSteps": {
"type": "integer",
"exclusiveMinimum": 0
},
"maxScannedResources": {
"type": "integer",
"exclusiveMinimum": 0
},
"maxToolCalls": {
"type": "integer",
"exclusiveMinimum": 0
},
"timeoutMs": {
"type": "integer",
"exclusiveMinimum": 0
}
}
},
"metadata": {
"type": "object",
"additionalProperties": {},
"default": {}
},
"mode": {
"type": "string",
"enum": [
"auto",
"deep",
"fast",
"research"
],
"description": "Explicit auto uses the frozen knowledge-space reasoning model once; the durable task stores the resolved mode."
},
"query": {
"type": "string",
"maxLength": 16000
},
"queryImages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uploadFileId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"uploadFileId"
],
"additionalProperties": false
},
"maxItems": 4,
"default": []
},
"topK": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 50
}
},
"required": [
"knowledgeSpaceId"
],
"additionalProperties": false
}
}
}
},
"responses": {
"201": {
"description": "Created research task job",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResearchTaskJob"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid research task request",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"RETRIEVAL_PROFILE_SCORE_THRESHOLD_REQUIRES_RERANK"
]
},
"error": {
"type": "string",
"enum": [
"Fast/Deep mode-final score threshold requires the knowledge-space reranker to be enabled"
]
},
"mode": {
"type": "string",
"enum": [
"fast",
"research",
"deep"
]
}
},
"required": [
"code",
"error",
"mode"
],
"additionalProperties": false
},
{
"$ref": "#/components/schemas/ErrorResponse"
}
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Idempotency-Key is bound to a different request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"422": {
"description": "Research task limits exceeded",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"error": {
"type": "string"
},
"failure": {
"$ref": "#/components/schemas/KnowledgeFsPublicFailure"
},
"violations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"estimatedValue": {
"type": "number",
"minimum": 0
},
"limit": {
"type": "string",
"enum": [
"maxRetrievalSteps",
"maxScannedResources",
"maxToolCalls",
"timeoutMs"
]
},
"limitValue": {
"type": "number",
"exclusiveMinimum": 0
}
},
"required": [
"estimatedValue",
"limit",
"limitValue"
]
}
}
},
"required": [
"error",
"violations"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Published runtime snapshot is unavailable or not query-ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/research-tasks/{id}": {
"get": {
"operationId": "getResearchTask",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": false,
"name": "knowledgeSpaceId",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Research task job status",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResearchTaskJob"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Research task job not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
},
"delete": {
"operationId": "cancelResearchTask",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": false,
"name": "knowledgeSpaceId",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Canceled research task job",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResearchTaskJob"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Research task job not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Research task job cannot be canceled",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/research-tasks/{id}/partials": {
"get": {
"operationId": "listResearchTaskPartials",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string"
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": false,
"name": "knowledgeSpaceId",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"required": false,
"name": "limit",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Research task partial evidence bundles",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResearchTaskPartialResultList"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Research task job not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/research-tasks/{id}/events": {
"get": {
"operationId": "streamResearchTaskProgress",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string"
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": false,
"name": "knowledgeSpaceId",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"required": false,
"name": "limit",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Research task progress event stream",
"content": {
"text/event-stream": {
"schema": {
"type": "string"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Ambiguous Research progress cursor",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Research task job not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 67108864,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/research-tasks/{id}/resume": {
"post": {
"operationId": "resumeResearchTask",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": false,
"name": "knowledgeSpaceId",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Resumed research task, or the already running task",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResearchTaskJob"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Research task job not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Terminal or leased research task cannot be resumed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/fs/ls": {
"get": {
"operationId": "listKnowledgeFs",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"enum": [
"path-consistent",
"snapshot-consistent",
"cache-consistent",
"eventual-preview"
]
},
"required": false,
"name": "consistencyClass",
"in": "query"
},
{
"schema": {
"type": "string"
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1
},
"required": true,
"name": "limit",
"in": "query"
},
{
"schema": {
"type": "string",
"pattern": "^\\/(?:sources|knowledge|evidence|workspaces)(?:\\/[^/\\s]+)*$"
},
"required": true,
"name": "path",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "KnowledgeFS directory listing",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"consistencyClass": {
"type": "string",
"enum": [
"path-consistent",
"snapshot-consistent",
"cache-consistent",
"eventual-preview"
]
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"directory",
"resource"
]
},
"metadata": {
"type": "object",
"additionalProperties": {}
},
"name": {
"type": "string"
},
"path": {
"type": "string"
},
"resourceType": {
"type": "string",
"enum": [
"source",
"document",
"node",
"artifact",
"evidence",
"workspace"
]
},
"targetId": {
"type": "string"
},
"version": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"kind",
"metadata",
"name",
"path"
]
}
},
"nextCursor": {
"type": "string"
},
"path": {
"type": "string"
},
"preview": {
"type": "boolean"
},
"truncated": {
"type": "boolean"
}
},
"required": [
"items",
"path",
"truncated"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid KnowledgeFS list request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Candidate visibility scan budget exceeded",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"CANDIDATE_VISIBILITY_SCAN_BUDGET_EXCEEDED"
]
},
"error": {
"type": "string",
"enum": [
"Candidate visibility scan budget exceeded"
]
}
},
"required": [
"code",
"error"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/fs/tree": {
"get": {
"operationId": "treeKnowledgeFs",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"enum": [
"path-consistent",
"snapshot-consistent",
"cache-consistent",
"eventual-preview"
]
},
"required": false,
"name": "consistencyClass",
"in": "query"
},
{
"schema": {
"type": "string"
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 8
},
"required": false,
"name": "depth",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1
},
"required": true,
"name": "limit",
"in": "query"
},
{
"schema": {
"type": "string",
"pattern": "^\\/(?:sources|knowledge|evidence|workspaces)(?:\\/[^/\\s]+)*$"
},
"required": true,
"name": "path",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "KnowledgeFS directory tree",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"consistencyClass": {
"type": "string",
"enum": [
"path-consistent",
"snapshot-consistent",
"cache-consistent",
"eventual-preview"
]
},
"nextCursor": {
"type": "string"
},
"path": {
"type": "string"
},
"preview": {
"type": "boolean"
},
"root": {
"type": "object",
"additionalProperties": true
},
"truncated": {
"type": "boolean"
}
},
"required": [
"path",
"truncated"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid KnowledgeFS tree request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Candidate visibility scan budget exceeded",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"CANDIDATE_VISIBILITY_SCAN_BUDGET_EXCEEDED"
]
},
"error": {
"type": "string",
"enum": [
"Candidate visibility scan budget exceeded"
]
}
},
"required": [
"code",
"error"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/fs/grep": {
"get": {
"operationId": "grepKnowledgeFs",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"enum": [
"path-consistent",
"snapshot-consistent",
"cache-consistent",
"eventual-preview"
]
},
"required": false,
"name": "consistencyClass",
"in": "query"
},
{
"schema": {
"type": "string"
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1
},
"required": true,
"name": "limit",
"in": "query"
},
{
"schema": {
"type": "string",
"pattern": "^\\/(?:sources|knowledge|evidence|workspaces)(?:\\/[^/\\s]+)*$"
},
"required": true,
"name": "path",
"in": "query"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"required": true,
"name": "q",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"required": false,
"name": "timeoutMs",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "KnowledgeFS scoped text search",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"matches": {
"type": "array",
"items": {
"type": "object",
"properties": {
"endOffset": {
"type": "integer",
"minimum": 0
},
"kind": {
"type": "string",
"enum": [
"node",
"segment"
]
},
"metadata": {
"type": "object",
"additionalProperties": {}
},
"nodeId": {
"type": "string"
},
"path": {
"type": "string"
},
"segmentId": {
"type": "string"
},
"snippet": {
"type": "string"
},
"startOffset": {
"type": "integer",
"minimum": 0
}
},
"required": [
"endOffset",
"kind",
"metadata",
"path",
"snippet",
"startOffset"
]
}
},
"nextCursor": {
"type": "string"
},
"path": {
"type": "string"
},
"truncated": {
"type": "boolean"
}
},
"required": [
"matches",
"path",
"truncated"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid KnowledgeFS grep request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Candidate visibility scan budget exceeded",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"CANDIDATE_VISIBILITY_SCAN_BUDGET_EXCEEDED"
]
},
"error": {
"type": "string",
"enum": [
"Candidate visibility scan budget exceeded"
]
}
},
"required": [
"code",
"error"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/fs/find": {
"get": {
"operationId": "findKnowledgeFs",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"enum": [
"path-consistent",
"snapshot-consistent",
"cache-consistent",
"eventual-preview"
]
},
"required": false,
"name": "consistencyClass",
"in": "query"
},
{
"schema": {
"type": "string"
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1
},
"required": true,
"name": "limit",
"in": "query"
},
{
"schema": {
"type": "string",
"pattern": "^\\/(?:sources|knowledge|evidence|workspaces)(?:\\/[^/\\s]+)*$"
},
"required": true,
"name": "path",
"in": "query"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"required": false,
"name": "metadataKey",
"in": "query"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"required": false,
"name": "metadataValue",
"in": "query"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 240
},
"required": false,
"name": "nameContains",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"source",
"document",
"node",
"artifact",
"evidence",
"workspace"
]
},
"required": false,
"name": "resourceType",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "KnowledgeFS scoped metadata search",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"consistencyClass": {
"type": "string",
"enum": [
"path-consistent",
"snapshot-consistent",
"cache-consistent",
"eventual-preview"
]
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"directory",
"resource"
]
},
"metadata": {
"type": "object",
"additionalProperties": {}
},
"name": {
"type": "string"
},
"path": {
"type": "string"
},
"resourceType": {
"type": "string",
"enum": [
"source",
"document",
"node",
"artifact",
"evidence",
"workspace"
]
},
"targetId": {
"type": "string"
},
"version": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"kind",
"metadata",
"name",
"path"
]
}
},
"nextCursor": {
"type": "string"
},
"path": {
"type": "string"
},
"preview": {
"type": "boolean"
},
"truncated": {
"type": "boolean"
}
},
"required": [
"items",
"path",
"truncated"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid KnowledgeFS find request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Candidate visibility scan budget exceeded",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"CANDIDATE_VISIBILITY_SCAN_BUDGET_EXCEEDED"
]
},
"error": {
"type": "string",
"enum": [
"Candidate visibility scan budget exceeded"
]
}
},
"required": [
"code",
"error"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/fs/diff": {
"get": {
"operationId": "diffKnowledgeFs",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"enum": [
"path-consistent",
"snapshot-consistent",
"cache-consistent",
"eventual-preview"
]
},
"required": false,
"name": "consistencyClass",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"line",
"word"
]
},
"required": false,
"name": "mode",
"in": "query"
},
{
"schema": {
"type": "string",
"pattern": "^\\/(?:sources|knowledge|evidence|workspaces)(?:\\/[^/\\s]+)*$"
},
"required": true,
"name": "newPath",
"in": "query"
},
{
"schema": {
"type": "string",
"pattern": "^\\/(?:sources|knowledge|evidence|workspaces)(?:\\/[^/\\s]+)*$"
},
"required": true,
"name": "oldPath",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"true",
"false"
]
},
"required": false,
"name": "semantic",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "KnowledgeFS text diff",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"line",
"word"
]
},
"newPath": {
"type": "string"
},
"oldPath": {
"type": "string"
},
"operations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"equal",
"insert",
"delete"
]
},
"newEnd": {
"type": "integer",
"exclusiveMinimum": 0
},
"newStart": {
"type": "integer",
"exclusiveMinimum": 0
},
"oldEnd": {
"type": "integer",
"exclusiveMinimum": 0
},
"oldStart": {
"type": "integer",
"exclusiveMinimum": 0
},
"text": {
"type": "string"
}
},
"required": [
"kind",
"text"
]
}
},
"semantic": {
"type": "object",
"properties": {
"changes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"category": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"evidence": {
"type": "array",
"items": {
"type": "string",
"maxLength": 8000
},
"maxItems": 20
},
"summary": {
"type": "string",
"minLength": 1,
"maxLength": 8000
}
},
"required": [
"category",
"evidence",
"summary"
],
"additionalProperties": false
},
"maxItems": 100
},
"metadata": {
"type": "object",
"additionalProperties": {}
},
"model": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"summary": {
"type": "string",
"minLength": 1,
"maxLength": 8000
}
},
"required": [
"changes",
"metadata",
"summary"
],
"additionalProperties": false
},
"stats": {
"type": "object",
"properties": {
"delete": {
"type": "integer",
"minimum": 0
},
"equal": {
"type": "integer",
"minimum": 0
},
"insert": {
"type": "integer",
"minimum": 0
}
},
"required": [
"delete",
"equal",
"insert"
]
}
},
"required": [
"mode",
"newPath",
"oldPath",
"operations",
"stats"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid KnowledgeFS diff request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "KnowledgeFS path not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "KnowledgeFS diff unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/fs/open_node": {
"get": {
"operationId": "openNodeKnowledgeFs",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"enum": [
"path-consistent",
"snapshot-consistent",
"cache-consistent",
"eventual-preview"
]
},
"required": false,
"name": "consistencyClass",
"in": "query"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "nodeId",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Citation-ready KnowledgeFS node",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"citation": {
"type": "object",
"properties": {
"artifactHash": {
"type": "string"
},
"documentAssetId": {
"type": "string"
},
"documentTitle": {
"type": "string",
"maxLength": 512
},
"documentVersion": {
"type": "integer",
"exclusiveMinimum": 0
},
"endOffset": {
"type": "integer",
"minimum": 0
},
"pageNumber": {
"type": "integer",
"exclusiveMinimum": 0
},
"parseArtifactId": {
"type": "string"
},
"sectionPath": {
"type": "array",
"items": {
"type": "string"
}
},
"startOffset": {
"type": "integer",
"minimum": 0
}
},
"required": [
"artifactHash",
"documentAssetId",
"endOffset",
"parseArtifactId",
"sectionPath",
"startOffset"
]
},
"node": {
"type": "object",
"properties": {
"artifactHash": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"documentAssetId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"endOffset": {
"type": "integer",
"minimum": 0
},
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"kind": {
"type": "string",
"enum": [
"chunk",
"section",
"table",
"image",
"summary"
]
},
"knowledgeSpaceId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"metadata": {
"type": "object",
"additionalProperties": {},
"default": {}
},
"parseArtifactId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"permissionScope": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"default": []
},
"publicationGenerationId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"sourceLocation": {
"type": "object",
"properties": {
"endOffset": {
"type": "integer",
"minimum": 0
},
"pageNumber": {
"type": "integer",
"exclusiveMinimum": 0
},
"sectionPath": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"default": []
},
"startOffset": {
"type": "integer",
"minimum": 0
}
}
},
"startOffset": {
"type": "integer",
"minimum": 0
},
"text": {
"type": "string",
"minLength": 1
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"artifactHash",
"documentAssetId",
"endOffset",
"id",
"kind",
"knowledgeSpaceId",
"parseArtifactId",
"sourceLocation",
"startOffset",
"text"
]
}
},
"required": [
"citation",
"node"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "KnowledgeFS node not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/fs/cat": {
"get": {
"operationId": "catKnowledgeFs",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"enum": [
"path-consistent",
"snapshot-consistent",
"cache-consistent",
"eventual-preview"
]
},
"required": false,
"name": "consistencyClass",
"in": "query"
},
{
"schema": {
"type": "string"
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"name": "limit",
"in": "query"
},
{
"schema": {
"type": "string",
"pattern": "^\\/(?:sources|knowledge|evidence|workspaces)(?:\\/[^/\\s]+)*$"
},
"required": true,
"name": "path",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "KnowledgeFS file content",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"contentType": {
"type": "string"
},
"nextCursor": {
"type": "string"
},
"path": {
"type": "string"
},
"text": {
"type": "string"
},
"truncated": {
"type": "boolean"
}
},
"required": [
"contentType",
"path",
"text",
"truncated"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "KnowledgeFS path not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/fs/stat": {
"get": {
"operationId": "statKnowledgeFs",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"enum": [
"path-consistent",
"snapshot-consistent",
"cache-consistent",
"eventual-preview"
]
},
"required": false,
"name": "consistencyClass",
"in": "query"
},
{
"schema": {
"type": "string",
"pattern": "^\\/(?:sources|knowledge|evidence|workspaces)(?:\\/[^/\\s]+)*$"
},
"required": true,
"name": "path",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "KnowledgeFS path metadata",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"consistencyClass": {
"type": "string",
"enum": [
"path-consistent",
"snapshot-consistent",
"cache-consistent",
"eventual-preview"
]
},
"contentType": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": {}
},
"parserStatus": {
"type": "string",
"enum": [
"pending",
"parsed",
"failed"
]
},
"path": {
"type": "string"
},
"resourceType": {
"type": "string",
"enum": [
"source",
"document",
"node",
"artifact",
"evidence",
"workspace"
]
},
"sha256": {
"type": "string"
},
"sizeBytes": {
"type": "integer",
"minimum": 0
},
"targetId": {
"type": "string"
},
"preview": {
"type": "boolean"
},
"version": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"metadata",
"path",
"resourceType",
"targetId"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "KnowledgeFS path not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/fs/write": {
"post": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"path": {
"type": "string",
"pattern": "^\\/(?:sources|knowledge|evidence|workspaces)(?:\\/[^/\\s]+)*$"
},
"text": {
"type": "string",
"maxLength": 262144
}
},
"required": [
"path",
"text"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "KnowledgeFS file overwritten",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"bytesWritten": {
"type": "integer",
"minimum": 0
},
"mode": {
"type": "string",
"enum": [
"append",
"write"
]
},
"objectKey": {
"type": "string"
},
"path": {
"type": "string"
},
"targetId": {
"type": "string"
},
"version": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"bytesWritten",
"mode",
"objectKey",
"path",
"targetId",
"version"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid KnowledgeFS write request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "KnowledgeFS path not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Knowledge space document mutation is fenced by publication bootstrap",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "postKnowledgeSpacesByIdFsWrite",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/fs/append": {
"post": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"path": {
"type": "string",
"pattern": "^\\/(?:sources|knowledge|evidence|workspaces)(?:\\/[^/\\s]+)*$"
},
"text": {
"type": "string",
"maxLength": 262144
}
},
"required": [
"path",
"text"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "KnowledgeFS file appended",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"bytesWritten": {
"type": "integer",
"minimum": 0
},
"mode": {
"type": "string",
"enum": [
"append",
"write"
]
},
"objectKey": {
"type": "string"
},
"path": {
"type": "string"
},
"targetId": {
"type": "string"
},
"version": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"bytesWritten",
"mode",
"objectKey",
"path",
"targetId",
"version"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid KnowledgeFS append request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "KnowledgeFS path not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Knowledge space document mutation is fenced by publication bootstrap",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "postKnowledgeSpacesByIdFsAppend",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/semantic-views/topic/materialize": {
"post": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"generatedVersion": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"topicName": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"topicSlug": {
"type": "string",
"minLength": 1,
"maxLength": 120,
"pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
}
},
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Materialized KnowledgeFS topic view",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TopicViewMaterializationResult"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid topic materialization request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Server-issued semantic authorization context is unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "postKnowledgeSpacesByIdSemanticViewsTopicMaterialize",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/semantic-views/entities/extract": {
"post": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Extracted and indexed semantic entities",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SemanticEntityExtractionResult"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid entity extraction request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Server-issued semantic authorization context is unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "postKnowledgeSpacesByIdSemanticViewsEntitiesExtract",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/semantic-views/communities/materialize": {
"post": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"generatedVersion": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Materialized KnowledgeFS community view",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SemanticCommunityMaterializationResult"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid community materialization request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Server-issued semantic authorization context is unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "postKnowledgeSpacesByIdSemanticViewsCommunitiesMaterialize",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/documents/bulk/reindex": {
"post": {
"operationId": "bulkReindexDocuments",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 255
},
"required": false,
"name": "Idempotency-Key",
"in": "header"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"all": {
"type": "boolean"
},
"documentIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1
}
},
"additionalProperties": false
}
}
}
},
"responses": {
"202": {
"description": "Accepted bulk document reindex",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkDocumentReindexResult"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid bulk reindex request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Knowledge space publication bootstrap is active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"413": {
"description": "KnowledgeSpace quota exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Durable document compilation is not configured",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/background-tasks": {
"get": {
"operationId": "listBackgroundTasks",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"maxLength": 8192
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "string",
"maxLength": 3699,
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}(,[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}){0,99}$"
},
"required": false,
"name": "taskIds",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
},
"required": false,
"name": "limit",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Newest durable document and source background tasks",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"activeOperations": {
"type": "array",
"items": {
"type": "string",
"enum": [
"parse",
"outline_summary",
"chunk",
"fts_index",
"embedding",
"graph_admission",
"publication"
]
}
},
"canCancel": {
"type": "boolean"
},
"canRetry": {
"type": "boolean"
},
"completedAt": {
"type": "string"
},
"createdAt": {
"type": "string"
},
"documentId": {
"type": "string",
"format": "uuid"
},
"documentTitle": {
"type": "string",
"minLength": 1
},
"documentRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"errorCode": {
"type": "string",
"enum": [
"VECTOR_SPACE_QUOTA_EXCEEDED",
"VECTOR_SPACE_QUOTA_UNAVAILABLE",
"DOCUMENT_COUNT_QUOTA_EXCEEDED",
"DOCUMENT_COUNT_QUOTA_UNAVAILABLE",
"LOGICAL_DOCUMENT_CAS_CONFLICT",
"DURABLE_DELETION_IDEMPOTENCY_CONFLICT",
"SOURCE_VERSION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_COMPILATION_IN_PROGRESS",
"KNOWLEDGE_SPACE_SETTINGS_REVISION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_MIGRATION_REQUIRED",
"DOCUMENT_COMPILATION_PROFILE_CHANGED",
"DOCUMENT_COMPILATION_FAILED",
"DOCUMENT_COMPILATION_RETRYABLE",
"DOCUMENT_COMPILATION_LEASE_LOST",
"DOCUMENT_DISABLED",
"DOCUMENT_PARSER_INPUT_INVALID",
"DOCUMENT_PARSER_NOT_CONFIGURED",
"DOCUMENT_PARSER_RATE_LIMITED",
"DOCUMENT_PARSER_RESPONSE_INVALID",
"DOCUMENT_PARSER_TIMEOUT",
"DOCUMENT_PARSER_UNAVAILABLE",
"DOCUMENT_PARSER_UNSUPPORTED_TYPE",
"DOCUMENT_PDF_RENDER_FAILED",
"EMBEDDING_DIMENSION_INVALID",
"EMBEDDING_DIMENSION_UNSUPPORTED",
"EXECUTION_ATTEMPTS_EXHAUSTED",
"KNOWLEDGE_FS_ACCESS_DENIED",
"KNOWLEDGE_FS_CONFLICT",
"KNOWLEDGE_FS_INTERNAL_ERROR",
"KNOWLEDGE_FS_INVALID_REQUEST",
"KNOWLEDGE_FS_NOT_FOUND",
"KNOWLEDGE_FS_RATE_LIMITED",
"KNOWLEDGE_FS_TIMEOUT",
"KNOWLEDGE_FS_UNAVAILABLE",
"KNOWLEDGE_SPACE_MANIFEST_NOT_FOUND",
"KNOWLEDGE_SPACE_MODEL_CONFIGURATION_REQUIRED",
"MODEL_CAPABILITY_MISMATCH",
"MODEL_CONFIGURATION_STALE",
"MODEL_CREDENTIAL_INVALID",
"MODEL_CREDENTIAL_VALIDATION_UNAVAILABLE",
"MODEL_IDENTITY_MISMATCH",
"MODEL_PREFLIGHT_CANCELED",
"MODEL_PREFLIGHT_FAILED",
"MODEL_PREFLIGHT_TIMEOUT",
"MODEL_PREFLIGHT_UNAVAILABLE",
"MODEL_PROFILE_ACTIVATION_INCOMPLETE",
"MODEL_PROFILE_ACTIVATION_PERMISSION_REQUIRED",
"MODEL_RUNTIME_FAILED",
"MODEL_RUNTIME_RESPONSE_INVALID",
"MODEL_RUNTIME_OUTPUT_LIMIT",
"MODEL_RUNTIME_CONTEXT_LIMIT",
"MODEL_RUNTIME_TIMEOUT",
"MODEL_RUNTIME_UNAVAILABLE",
"MODEL_SELECTION_NOT_FOUND",
"RESEARCH_TASK_CAPABILITY_REVOKED",
"RESEARCH_TASK_DISPATCH_DEAD",
"RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED",
"RESEARCH_TASK_FAILED",
"RESEARCH_TASK_PERMISSION_SNAPSHOT_INVALID",
"RESEARCH_TASK_RUNTIME_SNAPSHOT_INVALID",
"RETRIEVAL_DELETION_IN_PROGRESS",
"RETRIEVAL_EXECUTION_LEASE_LOST",
"SOURCE_BULK_ACTION_FAILED",
"SOURCE_CONNECTION_UNAVAILABLE",
"SOURCE_CRAWL_PAGE_NOT_FOUND",
"SOURCE_CRAWL_PROVIDER_UNAVAILABLE",
"SOURCE_CRAWL_RESULT_LIMIT_EXCEEDED",
"SOURCE_CREDENTIAL_CONFIG_INVALID",
"SOURCE_CREDENTIAL_MUTATION_FAILED",
"SOURCE_CREDENTIAL_TEST_FAILED",
"SOURCE_CREDENTIAL_UNAVAILABLE",
"SOURCE_DOCUMENT_COMPILATION_FAILED",
"SOURCE_DOCUMENT_MATERIALIZATION_FAILED",
"SOURCE_DOCUMENT_REPLACEMENT_SAGA_REQUIRED",
"SOURCE_IMPORT_PARTIAL_FAILURE",
"SOURCE_ONLINE_DOCUMENT_CONFIG_INVALID",
"SOURCE_ONLINE_DOCUMENT_IMPORT_FAILED",
"SOURCE_ONLINE_DOCUMENT_PAGE_FETCH_FAILED",
"SOURCE_ONLINE_DOCUMENT_REQUEST_FAILED",
"SOURCE_ONLINE_DOCUMENT_UNAVAILABLE",
"SOURCE_ONLINE_DRIVE_CONFIG_INVALID",
"SOURCE_ONLINE_DRIVE_FILE_DOWNLOAD_FAILED",
"SOURCE_ONLINE_DRIVE_IMPORT_FAILED",
"SOURCE_ONLINE_DRIVE_REQUEST_FAILED",
"SOURCE_ONLINE_DRIVE_UNAVAILABLE",
"SOURCE_OPERATION_FAILED",
"SOURCE_PROVIDER_REJECTED",
"SOURCE_PROVIDER_TIMEOUT",
"SOURCE_PROVIDER_UNAVAILABLE",
"SOURCE_SYNC_SELECTION_MISMATCH",
"SOURCE_SECRET_INTEGRITY_FAILED",
"SOURCE_SECRET_REF_CONFLICT",
"SOURCE_SYNC_FAILED",
"SOURCE_WEBSITE_CRAWL_CONFIG_INVALID",
"SOURCE_WEBSITE_CRAWL_FAILED",
"SOURCE_WORKFLOW_FAILED",
"SOURCE_WORKFLOW_CONTENT_MISSING",
"SOURCE_WORKFLOW_CONTENT_TOO_LARGE",
"SOURCE_WORKFLOW_EXTERNAL_TIMEOUT",
"UPLOAD_INITIALIZATION_FAILED",
"UPLOAD_INTEGRITY_MISMATCH"
]
},
"errorMessage": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"failure": {
"$ref": "#/components/schemas/KnowledgeFsPublicFailure"
},
"failures": {
"type": "array",
"items": {
"type": "object",
"properties": {
"documentId": {
"type": "string",
"format": "uuid"
},
"documentTitle": {
"type": "string"
},
"errorCode": {
"type": "string",
"enum": [
"VECTOR_SPACE_QUOTA_EXCEEDED",
"VECTOR_SPACE_QUOTA_UNAVAILABLE",
"DOCUMENT_COUNT_QUOTA_EXCEEDED",
"DOCUMENT_COUNT_QUOTA_UNAVAILABLE",
"LOGICAL_DOCUMENT_CAS_CONFLICT",
"DURABLE_DELETION_IDEMPOTENCY_CONFLICT",
"SOURCE_VERSION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_COMPILATION_IN_PROGRESS",
"KNOWLEDGE_SPACE_SETTINGS_REVISION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_MIGRATION_REQUIRED",
"DOCUMENT_COMPILATION_PROFILE_CHANGED",
"DOCUMENT_COMPILATION_FAILED",
"DOCUMENT_COMPILATION_RETRYABLE",
"DOCUMENT_COMPILATION_LEASE_LOST",
"DOCUMENT_DISABLED",
"DOCUMENT_PARSER_INPUT_INVALID",
"DOCUMENT_PARSER_NOT_CONFIGURED",
"DOCUMENT_PARSER_RATE_LIMITED",
"DOCUMENT_PARSER_RESPONSE_INVALID",
"DOCUMENT_PARSER_TIMEOUT",
"DOCUMENT_PARSER_UNAVAILABLE",
"DOCUMENT_PARSER_UNSUPPORTED_TYPE",
"DOCUMENT_PDF_RENDER_FAILED",
"EMBEDDING_DIMENSION_INVALID",
"EMBEDDING_DIMENSION_UNSUPPORTED",
"EXECUTION_ATTEMPTS_EXHAUSTED",
"KNOWLEDGE_FS_ACCESS_DENIED",
"KNOWLEDGE_FS_CONFLICT",
"KNOWLEDGE_FS_INTERNAL_ERROR",
"KNOWLEDGE_FS_INVALID_REQUEST",
"KNOWLEDGE_FS_NOT_FOUND",
"KNOWLEDGE_FS_RATE_LIMITED",
"KNOWLEDGE_FS_TIMEOUT",
"KNOWLEDGE_FS_UNAVAILABLE",
"KNOWLEDGE_SPACE_MANIFEST_NOT_FOUND",
"KNOWLEDGE_SPACE_MODEL_CONFIGURATION_REQUIRED",
"MODEL_CAPABILITY_MISMATCH",
"MODEL_CONFIGURATION_STALE",
"MODEL_CREDENTIAL_INVALID",
"MODEL_CREDENTIAL_VALIDATION_UNAVAILABLE",
"MODEL_IDENTITY_MISMATCH",
"MODEL_PREFLIGHT_CANCELED",
"MODEL_PREFLIGHT_FAILED",
"MODEL_PREFLIGHT_TIMEOUT",
"MODEL_PREFLIGHT_UNAVAILABLE",
"MODEL_PROFILE_ACTIVATION_INCOMPLETE",
"MODEL_PROFILE_ACTIVATION_PERMISSION_REQUIRED",
"MODEL_RUNTIME_FAILED",
"MODEL_RUNTIME_RESPONSE_INVALID",
"MODEL_RUNTIME_OUTPUT_LIMIT",
"MODEL_RUNTIME_CONTEXT_LIMIT",
"MODEL_RUNTIME_TIMEOUT",
"MODEL_RUNTIME_UNAVAILABLE",
"MODEL_SELECTION_NOT_FOUND",
"RESEARCH_TASK_CAPABILITY_REVOKED",
"RESEARCH_TASK_DISPATCH_DEAD",
"RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED",
"RESEARCH_TASK_FAILED",
"RESEARCH_TASK_PERMISSION_SNAPSHOT_INVALID",
"RESEARCH_TASK_RUNTIME_SNAPSHOT_INVALID",
"RETRIEVAL_DELETION_IN_PROGRESS",
"RETRIEVAL_EXECUTION_LEASE_LOST",
"SOURCE_BULK_ACTION_FAILED",
"SOURCE_CONNECTION_UNAVAILABLE",
"SOURCE_CRAWL_PAGE_NOT_FOUND",
"SOURCE_CRAWL_PROVIDER_UNAVAILABLE",
"SOURCE_CRAWL_RESULT_LIMIT_EXCEEDED",
"SOURCE_CREDENTIAL_CONFIG_INVALID",
"SOURCE_CREDENTIAL_MUTATION_FAILED",
"SOURCE_CREDENTIAL_TEST_FAILED",
"SOURCE_CREDENTIAL_UNAVAILABLE",
"SOURCE_DOCUMENT_COMPILATION_FAILED",
"SOURCE_DOCUMENT_MATERIALIZATION_FAILED",
"SOURCE_DOCUMENT_REPLACEMENT_SAGA_REQUIRED",
"SOURCE_IMPORT_PARTIAL_FAILURE",
"SOURCE_ONLINE_DOCUMENT_CONFIG_INVALID",
"SOURCE_ONLINE_DOCUMENT_IMPORT_FAILED",
"SOURCE_ONLINE_DOCUMENT_PAGE_FETCH_FAILED",
"SOURCE_ONLINE_DOCUMENT_REQUEST_FAILED",
"SOURCE_ONLINE_DOCUMENT_UNAVAILABLE",
"SOURCE_ONLINE_DRIVE_CONFIG_INVALID",
"SOURCE_ONLINE_DRIVE_FILE_DOWNLOAD_FAILED",
"SOURCE_ONLINE_DRIVE_IMPORT_FAILED",
"SOURCE_ONLINE_DRIVE_REQUEST_FAILED",
"SOURCE_ONLINE_DRIVE_UNAVAILABLE",
"SOURCE_OPERATION_FAILED",
"SOURCE_PROVIDER_REJECTED",
"SOURCE_PROVIDER_TIMEOUT",
"SOURCE_PROVIDER_UNAVAILABLE",
"SOURCE_SYNC_SELECTION_MISMATCH",
"SOURCE_SECRET_INTEGRITY_FAILED",
"SOURCE_SECRET_REF_CONFLICT",
"SOURCE_SYNC_FAILED",
"SOURCE_WEBSITE_CRAWL_CONFIG_INVALID",
"SOURCE_WEBSITE_CRAWL_FAILED",
"SOURCE_WORKFLOW_FAILED",
"SOURCE_WORKFLOW_CONTENT_MISSING",
"SOURCE_WORKFLOW_CONTENT_TOO_LARGE",
"SOURCE_WORKFLOW_EXTERNAL_TIMEOUT",
"UPLOAD_INITIALIZATION_FAILED",
"UPLOAD_INTEGRITY_MISMATCH"
]
},
"errorMessage": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"failure": {
"$ref": "#/components/schemas/KnowledgeFsPublicFailure"
},
"jobId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"documentId",
"errorCode",
"errorMessage",
"failure"
],
"additionalProperties": false
}
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"operation": {
"type": "string",
"enum": [
"document_processing",
"document_upload",
"document_delete",
"document_reindex",
"source_crawl_preview",
"source_crawl_import",
"source_online_document_import",
"source_online_drive_import",
"source_sync",
"source_bulk"
]
},
"phase": {
"type": "string",
"enum": [
"queued",
"parsing",
"outline_summary",
"chunking_indexing",
"graph_admission",
"publication",
"complete"
]
},
"progressCompleted": {
"type": "integer",
"minimum": 0
},
"progressFailed": {
"type": "integer",
"minimum": 0
},
"progressPercent": {
"type": "integer",
"minimum": 0,
"maximum": 100
},
"progressTotal": {
"type": "integer",
"minimum": 0
},
"sourceId": {
"type": "string",
"format": "uuid"
},
"sourceTitle": {
"type": "string",
"minLength": 1
},
"state": {
"type": "string",
"enum": [
"queued",
"running",
"completed",
"failed",
"canceled"
]
},
"semanticEnrichment": {
"type": "object",
"properties": {
"errorCode": {
"type": "string",
"enum": [
"VECTOR_SPACE_QUOTA_EXCEEDED",
"VECTOR_SPACE_QUOTA_UNAVAILABLE",
"DOCUMENT_COUNT_QUOTA_EXCEEDED",
"DOCUMENT_COUNT_QUOTA_UNAVAILABLE",
"LOGICAL_DOCUMENT_CAS_CONFLICT",
"DURABLE_DELETION_IDEMPOTENCY_CONFLICT",
"SOURCE_VERSION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_COMPILATION_IN_PROGRESS",
"KNOWLEDGE_SPACE_SETTINGS_REVISION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_MIGRATION_REQUIRED",
"DOCUMENT_COMPILATION_PROFILE_CHANGED",
"DOCUMENT_COMPILATION_FAILED",
"DOCUMENT_COMPILATION_RETRYABLE",
"DOCUMENT_COMPILATION_LEASE_LOST",
"DOCUMENT_DISABLED",
"DOCUMENT_PARSER_INPUT_INVALID",
"DOCUMENT_PARSER_NOT_CONFIGURED",
"DOCUMENT_PARSER_RATE_LIMITED",
"DOCUMENT_PARSER_RESPONSE_INVALID",
"DOCUMENT_PARSER_TIMEOUT",
"DOCUMENT_PARSER_UNAVAILABLE",
"DOCUMENT_PARSER_UNSUPPORTED_TYPE",
"DOCUMENT_PDF_RENDER_FAILED",
"EMBEDDING_DIMENSION_INVALID",
"EMBEDDING_DIMENSION_UNSUPPORTED",
"EXECUTION_ATTEMPTS_EXHAUSTED",
"KNOWLEDGE_FS_ACCESS_DENIED",
"KNOWLEDGE_FS_CONFLICT",
"KNOWLEDGE_FS_INTERNAL_ERROR",
"KNOWLEDGE_FS_INVALID_REQUEST",
"KNOWLEDGE_FS_NOT_FOUND",
"KNOWLEDGE_FS_RATE_LIMITED",
"KNOWLEDGE_FS_TIMEOUT",
"KNOWLEDGE_FS_UNAVAILABLE",
"KNOWLEDGE_SPACE_MANIFEST_NOT_FOUND",
"KNOWLEDGE_SPACE_MODEL_CONFIGURATION_REQUIRED",
"MODEL_CAPABILITY_MISMATCH",
"MODEL_CONFIGURATION_STALE",
"MODEL_CREDENTIAL_INVALID",
"MODEL_CREDENTIAL_VALIDATION_UNAVAILABLE",
"MODEL_IDENTITY_MISMATCH",
"MODEL_PREFLIGHT_CANCELED",
"MODEL_PREFLIGHT_FAILED",
"MODEL_PREFLIGHT_TIMEOUT",
"MODEL_PREFLIGHT_UNAVAILABLE",
"MODEL_PROFILE_ACTIVATION_INCOMPLETE",
"MODEL_PROFILE_ACTIVATION_PERMISSION_REQUIRED",
"MODEL_RUNTIME_FAILED",
"MODEL_RUNTIME_RESPONSE_INVALID",
"MODEL_RUNTIME_OUTPUT_LIMIT",
"MODEL_RUNTIME_CONTEXT_LIMIT",
"MODEL_RUNTIME_TIMEOUT",
"MODEL_RUNTIME_UNAVAILABLE",
"MODEL_SELECTION_NOT_FOUND",
"RESEARCH_TASK_CAPABILITY_REVOKED",
"RESEARCH_TASK_DISPATCH_DEAD",
"RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED",
"RESEARCH_TASK_FAILED",
"RESEARCH_TASK_PERMISSION_SNAPSHOT_INVALID",
"RESEARCH_TASK_RUNTIME_SNAPSHOT_INVALID",
"RETRIEVAL_DELETION_IN_PROGRESS",
"RETRIEVAL_EXECUTION_LEASE_LOST",
"SOURCE_BULK_ACTION_FAILED",
"SOURCE_CONNECTION_UNAVAILABLE",
"SOURCE_CRAWL_PAGE_NOT_FOUND",
"SOURCE_CRAWL_PROVIDER_UNAVAILABLE",
"SOURCE_CRAWL_RESULT_LIMIT_EXCEEDED",
"SOURCE_CREDENTIAL_CONFIG_INVALID",
"SOURCE_CREDENTIAL_MUTATION_FAILED",
"SOURCE_CREDENTIAL_TEST_FAILED",
"SOURCE_CREDENTIAL_UNAVAILABLE",
"SOURCE_DOCUMENT_COMPILATION_FAILED",
"SOURCE_DOCUMENT_MATERIALIZATION_FAILED",
"SOURCE_DOCUMENT_REPLACEMENT_SAGA_REQUIRED",
"SOURCE_IMPORT_PARTIAL_FAILURE",
"SOURCE_ONLINE_DOCUMENT_CONFIG_INVALID",
"SOURCE_ONLINE_DOCUMENT_IMPORT_FAILED",
"SOURCE_ONLINE_DOCUMENT_PAGE_FETCH_FAILED",
"SOURCE_ONLINE_DOCUMENT_REQUEST_FAILED",
"SOURCE_ONLINE_DOCUMENT_UNAVAILABLE",
"SOURCE_ONLINE_DRIVE_CONFIG_INVALID",
"SOURCE_ONLINE_DRIVE_FILE_DOWNLOAD_FAILED",
"SOURCE_ONLINE_DRIVE_IMPORT_FAILED",
"SOURCE_ONLINE_DRIVE_REQUEST_FAILED",
"SOURCE_ONLINE_DRIVE_UNAVAILABLE",
"SOURCE_OPERATION_FAILED",
"SOURCE_PROVIDER_REJECTED",
"SOURCE_PROVIDER_TIMEOUT",
"SOURCE_PROVIDER_UNAVAILABLE",
"SOURCE_SYNC_SELECTION_MISMATCH",
"SOURCE_SECRET_INTEGRITY_FAILED",
"SOURCE_SECRET_REF_CONFLICT",
"SOURCE_SYNC_FAILED",
"SOURCE_WEBSITE_CRAWL_CONFIG_INVALID",
"SOURCE_WEBSITE_CRAWL_FAILED",
"SOURCE_WORKFLOW_FAILED",
"SOURCE_WORKFLOW_CONTENT_MISSING",
"SOURCE_WORKFLOW_CONTENT_TOO_LARGE",
"SOURCE_WORKFLOW_EXTERNAL_TIMEOUT",
"UPLOAD_INITIALIZATION_FAILED",
"UPLOAD_INTEGRITY_MISMATCH"
]
},
"errorMessage": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"failure": {
"$ref": "#/components/schemas/KnowledgeFsPublicFailure"
},
"nodesCompleted": {
"type": "integer",
"minimum": 0
},
"nodesTotal": {
"type": "integer",
"minimum": 0
},
"providerCalls": {
"type": "integer",
"minimum": 0
},
"providerCallsMaximum": {
"type": "integer",
"minimum": 0
},
"state": {
"type": "string",
"enum": [
"not_scheduled",
"pending",
"running",
"ready",
"failed",
"disabled"
]
},
"updatedAt": {
"type": "string"
}
},
"required": [
"nodesCompleted",
"state"
],
"additionalProperties": false
},
"taskKind": {
"type": "string",
"enum": [
"document",
"document_bulk",
"source"
]
},
"updatedAt": {
"type": "string"
}
},
"required": [
"canCancel",
"canRetry",
"createdAt",
"id",
"knowledgeSpaceId",
"operation",
"progressCompleted",
"progressFailed",
"progressPercent",
"progressTotal",
"state",
"taskKind",
"updatedAt"
]
}
},
"nextCursor": {
"type": "string"
}
},
"required": [
"items"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid background task request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Background task not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Background task cannot perform this transition",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/background-tasks/{taskKind}/{taskId}/cancel": {
"post": {
"operationId": "cancelBackgroundTask",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "taskId",
"in": "path"
},
{
"schema": {
"type": "string",
"enum": [
"document",
"document_bulk",
"source"
]
},
"required": true,
"name": "taskKind",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Canceled background task",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"activeOperations": {
"type": "array",
"items": {
"type": "string",
"enum": [
"parse",
"outline_summary",
"chunk",
"fts_index",
"embedding",
"graph_admission",
"publication"
]
}
},
"canCancel": {
"type": "boolean"
},
"canRetry": {
"type": "boolean"
},
"completedAt": {
"type": "string"
},
"createdAt": {
"type": "string"
},
"documentId": {
"type": "string",
"format": "uuid"
},
"documentTitle": {
"type": "string",
"minLength": 1
},
"documentRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"errorCode": {
"type": "string",
"enum": [
"VECTOR_SPACE_QUOTA_EXCEEDED",
"VECTOR_SPACE_QUOTA_UNAVAILABLE",
"DOCUMENT_COUNT_QUOTA_EXCEEDED",
"DOCUMENT_COUNT_QUOTA_UNAVAILABLE",
"LOGICAL_DOCUMENT_CAS_CONFLICT",
"DURABLE_DELETION_IDEMPOTENCY_CONFLICT",
"SOURCE_VERSION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_COMPILATION_IN_PROGRESS",
"KNOWLEDGE_SPACE_SETTINGS_REVISION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_MIGRATION_REQUIRED",
"DOCUMENT_COMPILATION_PROFILE_CHANGED",
"DOCUMENT_COMPILATION_FAILED",
"DOCUMENT_COMPILATION_RETRYABLE",
"DOCUMENT_COMPILATION_LEASE_LOST",
"DOCUMENT_DISABLED",
"DOCUMENT_PARSER_INPUT_INVALID",
"DOCUMENT_PARSER_NOT_CONFIGURED",
"DOCUMENT_PARSER_RATE_LIMITED",
"DOCUMENT_PARSER_RESPONSE_INVALID",
"DOCUMENT_PARSER_TIMEOUT",
"DOCUMENT_PARSER_UNAVAILABLE",
"DOCUMENT_PARSER_UNSUPPORTED_TYPE",
"DOCUMENT_PDF_RENDER_FAILED",
"EMBEDDING_DIMENSION_INVALID",
"EMBEDDING_DIMENSION_UNSUPPORTED",
"EXECUTION_ATTEMPTS_EXHAUSTED",
"KNOWLEDGE_FS_ACCESS_DENIED",
"KNOWLEDGE_FS_CONFLICT",
"KNOWLEDGE_FS_INTERNAL_ERROR",
"KNOWLEDGE_FS_INVALID_REQUEST",
"KNOWLEDGE_FS_NOT_FOUND",
"KNOWLEDGE_FS_RATE_LIMITED",
"KNOWLEDGE_FS_TIMEOUT",
"KNOWLEDGE_FS_UNAVAILABLE",
"KNOWLEDGE_SPACE_MANIFEST_NOT_FOUND",
"KNOWLEDGE_SPACE_MODEL_CONFIGURATION_REQUIRED",
"MODEL_CAPABILITY_MISMATCH",
"MODEL_CONFIGURATION_STALE",
"MODEL_CREDENTIAL_INVALID",
"MODEL_CREDENTIAL_VALIDATION_UNAVAILABLE",
"MODEL_IDENTITY_MISMATCH",
"MODEL_PREFLIGHT_CANCELED",
"MODEL_PREFLIGHT_FAILED",
"MODEL_PREFLIGHT_TIMEOUT",
"MODEL_PREFLIGHT_UNAVAILABLE",
"MODEL_PROFILE_ACTIVATION_INCOMPLETE",
"MODEL_PROFILE_ACTIVATION_PERMISSION_REQUIRED",
"MODEL_RUNTIME_FAILED",
"MODEL_RUNTIME_RESPONSE_INVALID",
"MODEL_RUNTIME_OUTPUT_LIMIT",
"MODEL_RUNTIME_CONTEXT_LIMIT",
"MODEL_RUNTIME_TIMEOUT",
"MODEL_RUNTIME_UNAVAILABLE",
"MODEL_SELECTION_NOT_FOUND",
"RESEARCH_TASK_CAPABILITY_REVOKED",
"RESEARCH_TASK_DISPATCH_DEAD",
"RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED",
"RESEARCH_TASK_FAILED",
"RESEARCH_TASK_PERMISSION_SNAPSHOT_INVALID",
"RESEARCH_TASK_RUNTIME_SNAPSHOT_INVALID",
"RETRIEVAL_DELETION_IN_PROGRESS",
"RETRIEVAL_EXECUTION_LEASE_LOST",
"SOURCE_BULK_ACTION_FAILED",
"SOURCE_CONNECTION_UNAVAILABLE",
"SOURCE_CRAWL_PAGE_NOT_FOUND",
"SOURCE_CRAWL_PROVIDER_UNAVAILABLE",
"SOURCE_CRAWL_RESULT_LIMIT_EXCEEDED",
"SOURCE_CREDENTIAL_CONFIG_INVALID",
"SOURCE_CREDENTIAL_MUTATION_FAILED",
"SOURCE_CREDENTIAL_TEST_FAILED",
"SOURCE_CREDENTIAL_UNAVAILABLE",
"SOURCE_DOCUMENT_COMPILATION_FAILED",
"SOURCE_DOCUMENT_MATERIALIZATION_FAILED",
"SOURCE_DOCUMENT_REPLACEMENT_SAGA_REQUIRED",
"SOURCE_IMPORT_PARTIAL_FAILURE",
"SOURCE_ONLINE_DOCUMENT_CONFIG_INVALID",
"SOURCE_ONLINE_DOCUMENT_IMPORT_FAILED",
"SOURCE_ONLINE_DOCUMENT_PAGE_FETCH_FAILED",
"SOURCE_ONLINE_DOCUMENT_REQUEST_FAILED",
"SOURCE_ONLINE_DOCUMENT_UNAVAILABLE",
"SOURCE_ONLINE_DRIVE_CONFIG_INVALID",
"SOURCE_ONLINE_DRIVE_FILE_DOWNLOAD_FAILED",
"SOURCE_ONLINE_DRIVE_IMPORT_FAILED",
"SOURCE_ONLINE_DRIVE_REQUEST_FAILED",
"SOURCE_ONLINE_DRIVE_UNAVAILABLE",
"SOURCE_OPERATION_FAILED",
"SOURCE_PROVIDER_REJECTED",
"SOURCE_PROVIDER_TIMEOUT",
"SOURCE_PROVIDER_UNAVAILABLE",
"SOURCE_SYNC_SELECTION_MISMATCH",
"SOURCE_SECRET_INTEGRITY_FAILED",
"SOURCE_SECRET_REF_CONFLICT",
"SOURCE_SYNC_FAILED",
"SOURCE_WEBSITE_CRAWL_CONFIG_INVALID",
"SOURCE_WEBSITE_CRAWL_FAILED",
"SOURCE_WORKFLOW_FAILED",
"SOURCE_WORKFLOW_CONTENT_MISSING",
"SOURCE_WORKFLOW_CONTENT_TOO_LARGE",
"SOURCE_WORKFLOW_EXTERNAL_TIMEOUT",
"UPLOAD_INITIALIZATION_FAILED",
"UPLOAD_INTEGRITY_MISMATCH"
]
},
"errorMessage": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"failure": {
"$ref": "#/components/schemas/KnowledgeFsPublicFailure"
},
"failures": {
"type": "array",
"items": {
"type": "object",
"properties": {
"documentId": {
"type": "string",
"format": "uuid"
},
"documentTitle": {
"type": "string"
},
"errorCode": {
"type": "string",
"enum": [
"VECTOR_SPACE_QUOTA_EXCEEDED",
"VECTOR_SPACE_QUOTA_UNAVAILABLE",
"DOCUMENT_COUNT_QUOTA_EXCEEDED",
"DOCUMENT_COUNT_QUOTA_UNAVAILABLE",
"LOGICAL_DOCUMENT_CAS_CONFLICT",
"DURABLE_DELETION_IDEMPOTENCY_CONFLICT",
"SOURCE_VERSION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_COMPILATION_IN_PROGRESS",
"KNOWLEDGE_SPACE_SETTINGS_REVISION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_MIGRATION_REQUIRED",
"DOCUMENT_COMPILATION_PROFILE_CHANGED",
"DOCUMENT_COMPILATION_FAILED",
"DOCUMENT_COMPILATION_RETRYABLE",
"DOCUMENT_COMPILATION_LEASE_LOST",
"DOCUMENT_DISABLED",
"DOCUMENT_PARSER_INPUT_INVALID",
"DOCUMENT_PARSER_NOT_CONFIGURED",
"DOCUMENT_PARSER_RATE_LIMITED",
"DOCUMENT_PARSER_RESPONSE_INVALID",
"DOCUMENT_PARSER_TIMEOUT",
"DOCUMENT_PARSER_UNAVAILABLE",
"DOCUMENT_PARSER_UNSUPPORTED_TYPE",
"DOCUMENT_PDF_RENDER_FAILED",
"EMBEDDING_DIMENSION_INVALID",
"EMBEDDING_DIMENSION_UNSUPPORTED",
"EXECUTION_ATTEMPTS_EXHAUSTED",
"KNOWLEDGE_FS_ACCESS_DENIED",
"KNOWLEDGE_FS_CONFLICT",
"KNOWLEDGE_FS_INTERNAL_ERROR",
"KNOWLEDGE_FS_INVALID_REQUEST",
"KNOWLEDGE_FS_NOT_FOUND",
"KNOWLEDGE_FS_RATE_LIMITED",
"KNOWLEDGE_FS_TIMEOUT",
"KNOWLEDGE_FS_UNAVAILABLE",
"KNOWLEDGE_SPACE_MANIFEST_NOT_FOUND",
"KNOWLEDGE_SPACE_MODEL_CONFIGURATION_REQUIRED",
"MODEL_CAPABILITY_MISMATCH",
"MODEL_CONFIGURATION_STALE",
"MODEL_CREDENTIAL_INVALID",
"MODEL_CREDENTIAL_VALIDATION_UNAVAILABLE",
"MODEL_IDENTITY_MISMATCH",
"MODEL_PREFLIGHT_CANCELED",
"MODEL_PREFLIGHT_FAILED",
"MODEL_PREFLIGHT_TIMEOUT",
"MODEL_PREFLIGHT_UNAVAILABLE",
"MODEL_PROFILE_ACTIVATION_INCOMPLETE",
"MODEL_PROFILE_ACTIVATION_PERMISSION_REQUIRED",
"MODEL_RUNTIME_FAILED",
"MODEL_RUNTIME_RESPONSE_INVALID",
"MODEL_RUNTIME_OUTPUT_LIMIT",
"MODEL_RUNTIME_CONTEXT_LIMIT",
"MODEL_RUNTIME_TIMEOUT",
"MODEL_RUNTIME_UNAVAILABLE",
"MODEL_SELECTION_NOT_FOUND",
"RESEARCH_TASK_CAPABILITY_REVOKED",
"RESEARCH_TASK_DISPATCH_DEAD",
"RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED",
"RESEARCH_TASK_FAILED",
"RESEARCH_TASK_PERMISSION_SNAPSHOT_INVALID",
"RESEARCH_TASK_RUNTIME_SNAPSHOT_INVALID",
"RETRIEVAL_DELETION_IN_PROGRESS",
"RETRIEVAL_EXECUTION_LEASE_LOST",
"SOURCE_BULK_ACTION_FAILED",
"SOURCE_CONNECTION_UNAVAILABLE",
"SOURCE_CRAWL_PAGE_NOT_FOUND",
"SOURCE_CRAWL_PROVIDER_UNAVAILABLE",
"SOURCE_CRAWL_RESULT_LIMIT_EXCEEDED",
"SOURCE_CREDENTIAL_CONFIG_INVALID",
"SOURCE_CREDENTIAL_MUTATION_FAILED",
"SOURCE_CREDENTIAL_TEST_FAILED",
"SOURCE_CREDENTIAL_UNAVAILABLE",
"SOURCE_DOCUMENT_COMPILATION_FAILED",
"SOURCE_DOCUMENT_MATERIALIZATION_FAILED",
"SOURCE_DOCUMENT_REPLACEMENT_SAGA_REQUIRED",
"SOURCE_IMPORT_PARTIAL_FAILURE",
"SOURCE_ONLINE_DOCUMENT_CONFIG_INVALID",
"SOURCE_ONLINE_DOCUMENT_IMPORT_FAILED",
"SOURCE_ONLINE_DOCUMENT_PAGE_FETCH_FAILED",
"SOURCE_ONLINE_DOCUMENT_REQUEST_FAILED",
"SOURCE_ONLINE_DOCUMENT_UNAVAILABLE",
"SOURCE_ONLINE_DRIVE_CONFIG_INVALID",
"SOURCE_ONLINE_DRIVE_FILE_DOWNLOAD_FAILED",
"SOURCE_ONLINE_DRIVE_IMPORT_FAILED",
"SOURCE_ONLINE_DRIVE_REQUEST_FAILED",
"SOURCE_ONLINE_DRIVE_UNAVAILABLE",
"SOURCE_OPERATION_FAILED",
"SOURCE_PROVIDER_REJECTED",
"SOURCE_PROVIDER_TIMEOUT",
"SOURCE_PROVIDER_UNAVAILABLE",
"SOURCE_SYNC_SELECTION_MISMATCH",
"SOURCE_SECRET_INTEGRITY_FAILED",
"SOURCE_SECRET_REF_CONFLICT",
"SOURCE_SYNC_FAILED",
"SOURCE_WEBSITE_CRAWL_CONFIG_INVALID",
"SOURCE_WEBSITE_CRAWL_FAILED",
"SOURCE_WORKFLOW_FAILED",
"SOURCE_WORKFLOW_CONTENT_MISSING",
"SOURCE_WORKFLOW_CONTENT_TOO_LARGE",
"SOURCE_WORKFLOW_EXTERNAL_TIMEOUT",
"UPLOAD_INITIALIZATION_FAILED",
"UPLOAD_INTEGRITY_MISMATCH"
]
},
"errorMessage": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"failure": {
"$ref": "#/components/schemas/KnowledgeFsPublicFailure"
},
"jobId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"documentId",
"errorCode",
"errorMessage",
"failure"
],
"additionalProperties": false
}
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"operation": {
"type": "string",
"enum": [
"document_processing",
"document_upload",
"document_delete",
"document_reindex",
"source_crawl_preview",
"source_crawl_import",
"source_online_document_import",
"source_online_drive_import",
"source_sync",
"source_bulk"
]
},
"phase": {
"type": "string",
"enum": [
"queued",
"parsing",
"outline_summary",
"chunking_indexing",
"graph_admission",
"publication",
"complete"
]
},
"progressCompleted": {
"type": "integer",
"minimum": 0
},
"progressFailed": {
"type": "integer",
"minimum": 0
},
"progressPercent": {
"type": "integer",
"minimum": 0,
"maximum": 100
},
"progressTotal": {
"type": "integer",
"minimum": 0
},
"sourceId": {
"type": "string",
"format": "uuid"
},
"sourceTitle": {
"type": "string",
"minLength": 1
},
"state": {
"type": "string",
"enum": [
"queued",
"running",
"completed",
"failed",
"canceled"
]
},
"semanticEnrichment": {
"type": "object",
"properties": {
"errorCode": {
"type": "string",
"enum": [
"VECTOR_SPACE_QUOTA_EXCEEDED",
"VECTOR_SPACE_QUOTA_UNAVAILABLE",
"DOCUMENT_COUNT_QUOTA_EXCEEDED",
"DOCUMENT_COUNT_QUOTA_UNAVAILABLE",
"LOGICAL_DOCUMENT_CAS_CONFLICT",
"DURABLE_DELETION_IDEMPOTENCY_CONFLICT",
"SOURCE_VERSION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_COMPILATION_IN_PROGRESS",
"KNOWLEDGE_SPACE_SETTINGS_REVISION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_MIGRATION_REQUIRED",
"DOCUMENT_COMPILATION_PROFILE_CHANGED",
"DOCUMENT_COMPILATION_FAILED",
"DOCUMENT_COMPILATION_RETRYABLE",
"DOCUMENT_COMPILATION_LEASE_LOST",
"DOCUMENT_DISABLED",
"DOCUMENT_PARSER_INPUT_INVALID",
"DOCUMENT_PARSER_NOT_CONFIGURED",
"DOCUMENT_PARSER_RATE_LIMITED",
"DOCUMENT_PARSER_RESPONSE_INVALID",
"DOCUMENT_PARSER_TIMEOUT",
"DOCUMENT_PARSER_UNAVAILABLE",
"DOCUMENT_PARSER_UNSUPPORTED_TYPE",
"DOCUMENT_PDF_RENDER_FAILED",
"EMBEDDING_DIMENSION_INVALID",
"EMBEDDING_DIMENSION_UNSUPPORTED",
"EXECUTION_ATTEMPTS_EXHAUSTED",
"KNOWLEDGE_FS_ACCESS_DENIED",
"KNOWLEDGE_FS_CONFLICT",
"KNOWLEDGE_FS_INTERNAL_ERROR",
"KNOWLEDGE_FS_INVALID_REQUEST",
"KNOWLEDGE_FS_NOT_FOUND",
"KNOWLEDGE_FS_RATE_LIMITED",
"KNOWLEDGE_FS_TIMEOUT",
"KNOWLEDGE_FS_UNAVAILABLE",
"KNOWLEDGE_SPACE_MANIFEST_NOT_FOUND",
"KNOWLEDGE_SPACE_MODEL_CONFIGURATION_REQUIRED",
"MODEL_CAPABILITY_MISMATCH",
"MODEL_CONFIGURATION_STALE",
"MODEL_CREDENTIAL_INVALID",
"MODEL_CREDENTIAL_VALIDATION_UNAVAILABLE",
"MODEL_IDENTITY_MISMATCH",
"MODEL_PREFLIGHT_CANCELED",
"MODEL_PREFLIGHT_FAILED",
"MODEL_PREFLIGHT_TIMEOUT",
"MODEL_PREFLIGHT_UNAVAILABLE",
"MODEL_PROFILE_ACTIVATION_INCOMPLETE",
"MODEL_PROFILE_ACTIVATION_PERMISSION_REQUIRED",
"MODEL_RUNTIME_FAILED",
"MODEL_RUNTIME_RESPONSE_INVALID",
"MODEL_RUNTIME_OUTPUT_LIMIT",
"MODEL_RUNTIME_CONTEXT_LIMIT",
"MODEL_RUNTIME_TIMEOUT",
"MODEL_RUNTIME_UNAVAILABLE",
"MODEL_SELECTION_NOT_FOUND",
"RESEARCH_TASK_CAPABILITY_REVOKED",
"RESEARCH_TASK_DISPATCH_DEAD",
"RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED",
"RESEARCH_TASK_FAILED",
"RESEARCH_TASK_PERMISSION_SNAPSHOT_INVALID",
"RESEARCH_TASK_RUNTIME_SNAPSHOT_INVALID",
"RETRIEVAL_DELETION_IN_PROGRESS",
"RETRIEVAL_EXECUTION_LEASE_LOST",
"SOURCE_BULK_ACTION_FAILED",
"SOURCE_CONNECTION_UNAVAILABLE",
"SOURCE_CRAWL_PAGE_NOT_FOUND",
"SOURCE_CRAWL_PROVIDER_UNAVAILABLE",
"SOURCE_CRAWL_RESULT_LIMIT_EXCEEDED",
"SOURCE_CREDENTIAL_CONFIG_INVALID",
"SOURCE_CREDENTIAL_MUTATION_FAILED",
"SOURCE_CREDENTIAL_TEST_FAILED",
"SOURCE_CREDENTIAL_UNAVAILABLE",
"SOURCE_DOCUMENT_COMPILATION_FAILED",
"SOURCE_DOCUMENT_MATERIALIZATION_FAILED",
"SOURCE_DOCUMENT_REPLACEMENT_SAGA_REQUIRED",
"SOURCE_IMPORT_PARTIAL_FAILURE",
"SOURCE_ONLINE_DOCUMENT_CONFIG_INVALID",
"SOURCE_ONLINE_DOCUMENT_IMPORT_FAILED",
"SOURCE_ONLINE_DOCUMENT_PAGE_FETCH_FAILED",
"SOURCE_ONLINE_DOCUMENT_REQUEST_FAILED",
"SOURCE_ONLINE_DOCUMENT_UNAVAILABLE",
"SOURCE_ONLINE_DRIVE_CONFIG_INVALID",
"SOURCE_ONLINE_DRIVE_FILE_DOWNLOAD_FAILED",
"SOURCE_ONLINE_DRIVE_IMPORT_FAILED",
"SOURCE_ONLINE_DRIVE_REQUEST_FAILED",
"SOURCE_ONLINE_DRIVE_UNAVAILABLE",
"SOURCE_OPERATION_FAILED",
"SOURCE_PROVIDER_REJECTED",
"SOURCE_PROVIDER_TIMEOUT",
"SOURCE_PROVIDER_UNAVAILABLE",
"SOURCE_SYNC_SELECTION_MISMATCH",
"SOURCE_SECRET_INTEGRITY_FAILED",
"SOURCE_SECRET_REF_CONFLICT",
"SOURCE_SYNC_FAILED",
"SOURCE_WEBSITE_CRAWL_CONFIG_INVALID",
"SOURCE_WEBSITE_CRAWL_FAILED",
"SOURCE_WORKFLOW_FAILED",
"SOURCE_WORKFLOW_CONTENT_MISSING",
"SOURCE_WORKFLOW_CONTENT_TOO_LARGE",
"SOURCE_WORKFLOW_EXTERNAL_TIMEOUT",
"UPLOAD_INITIALIZATION_FAILED",
"UPLOAD_INTEGRITY_MISMATCH"
]
},
"errorMessage": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"failure": {
"$ref": "#/components/schemas/KnowledgeFsPublicFailure"
},
"nodesCompleted": {
"type": "integer",
"minimum": 0
},
"nodesTotal": {
"type": "integer",
"minimum": 0
},
"providerCalls": {
"type": "integer",
"minimum": 0
},
"providerCallsMaximum": {
"type": "integer",
"minimum": 0
},
"state": {
"type": "string",
"enum": [
"not_scheduled",
"pending",
"running",
"ready",
"failed",
"disabled"
]
},
"updatedAt": {
"type": "string"
}
},
"required": [
"nodesCompleted",
"state"
],
"additionalProperties": false
},
"taskKind": {
"type": "string",
"enum": [
"document",
"document_bulk",
"source"
]
},
"updatedAt": {
"type": "string"
}
},
"required": [
"canCancel",
"canRetry",
"createdAt",
"id",
"knowledgeSpaceId",
"operation",
"progressCompleted",
"progressFailed",
"progressPercent",
"progressTotal",
"state",
"taskKind",
"updatedAt"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid background task request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Background task not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Background task cannot perform this transition",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/background-tasks/{taskKind}/{taskId}/retry": {
"post": {
"operationId": "retryBackgroundTask",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "taskId",
"in": "path"
},
{
"schema": {
"type": "string",
"enum": [
"document",
"document_bulk",
"source"
]
},
"required": true,
"name": "taskKind",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Retried background task",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"activeOperations": {
"type": "array",
"items": {
"type": "string",
"enum": [
"parse",
"outline_summary",
"chunk",
"fts_index",
"embedding",
"graph_admission",
"publication"
]
}
},
"canCancel": {
"type": "boolean"
},
"canRetry": {
"type": "boolean"
},
"completedAt": {
"type": "string"
},
"createdAt": {
"type": "string"
},
"documentId": {
"type": "string",
"format": "uuid"
},
"documentTitle": {
"type": "string",
"minLength": 1
},
"documentRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"errorCode": {
"type": "string",
"enum": [
"VECTOR_SPACE_QUOTA_EXCEEDED",
"VECTOR_SPACE_QUOTA_UNAVAILABLE",
"DOCUMENT_COUNT_QUOTA_EXCEEDED",
"DOCUMENT_COUNT_QUOTA_UNAVAILABLE",
"LOGICAL_DOCUMENT_CAS_CONFLICT",
"DURABLE_DELETION_IDEMPOTENCY_CONFLICT",
"SOURCE_VERSION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_COMPILATION_IN_PROGRESS",
"KNOWLEDGE_SPACE_SETTINGS_REVISION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_MIGRATION_REQUIRED",
"DOCUMENT_COMPILATION_PROFILE_CHANGED",
"DOCUMENT_COMPILATION_FAILED",
"DOCUMENT_COMPILATION_RETRYABLE",
"DOCUMENT_COMPILATION_LEASE_LOST",
"DOCUMENT_DISABLED",
"DOCUMENT_PARSER_INPUT_INVALID",
"DOCUMENT_PARSER_NOT_CONFIGURED",
"DOCUMENT_PARSER_RATE_LIMITED",
"DOCUMENT_PARSER_RESPONSE_INVALID",
"DOCUMENT_PARSER_TIMEOUT",
"DOCUMENT_PARSER_UNAVAILABLE",
"DOCUMENT_PARSER_UNSUPPORTED_TYPE",
"DOCUMENT_PDF_RENDER_FAILED",
"EMBEDDING_DIMENSION_INVALID",
"EMBEDDING_DIMENSION_UNSUPPORTED",
"EXECUTION_ATTEMPTS_EXHAUSTED",
"KNOWLEDGE_FS_ACCESS_DENIED",
"KNOWLEDGE_FS_CONFLICT",
"KNOWLEDGE_FS_INTERNAL_ERROR",
"KNOWLEDGE_FS_INVALID_REQUEST",
"KNOWLEDGE_FS_NOT_FOUND",
"KNOWLEDGE_FS_RATE_LIMITED",
"KNOWLEDGE_FS_TIMEOUT",
"KNOWLEDGE_FS_UNAVAILABLE",
"KNOWLEDGE_SPACE_MANIFEST_NOT_FOUND",
"KNOWLEDGE_SPACE_MODEL_CONFIGURATION_REQUIRED",
"MODEL_CAPABILITY_MISMATCH",
"MODEL_CONFIGURATION_STALE",
"MODEL_CREDENTIAL_INVALID",
"MODEL_CREDENTIAL_VALIDATION_UNAVAILABLE",
"MODEL_IDENTITY_MISMATCH",
"MODEL_PREFLIGHT_CANCELED",
"MODEL_PREFLIGHT_FAILED",
"MODEL_PREFLIGHT_TIMEOUT",
"MODEL_PREFLIGHT_UNAVAILABLE",
"MODEL_PROFILE_ACTIVATION_INCOMPLETE",
"MODEL_PROFILE_ACTIVATION_PERMISSION_REQUIRED",
"MODEL_RUNTIME_FAILED",
"MODEL_RUNTIME_RESPONSE_INVALID",
"MODEL_RUNTIME_OUTPUT_LIMIT",
"MODEL_RUNTIME_CONTEXT_LIMIT",
"MODEL_RUNTIME_TIMEOUT",
"MODEL_RUNTIME_UNAVAILABLE",
"MODEL_SELECTION_NOT_FOUND",
"RESEARCH_TASK_CAPABILITY_REVOKED",
"RESEARCH_TASK_DISPATCH_DEAD",
"RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED",
"RESEARCH_TASK_FAILED",
"RESEARCH_TASK_PERMISSION_SNAPSHOT_INVALID",
"RESEARCH_TASK_RUNTIME_SNAPSHOT_INVALID",
"RETRIEVAL_DELETION_IN_PROGRESS",
"RETRIEVAL_EXECUTION_LEASE_LOST",
"SOURCE_BULK_ACTION_FAILED",
"SOURCE_CONNECTION_UNAVAILABLE",
"SOURCE_CRAWL_PAGE_NOT_FOUND",
"SOURCE_CRAWL_PROVIDER_UNAVAILABLE",
"SOURCE_CRAWL_RESULT_LIMIT_EXCEEDED",
"SOURCE_CREDENTIAL_CONFIG_INVALID",
"SOURCE_CREDENTIAL_MUTATION_FAILED",
"SOURCE_CREDENTIAL_TEST_FAILED",
"SOURCE_CREDENTIAL_UNAVAILABLE",
"SOURCE_DOCUMENT_COMPILATION_FAILED",
"SOURCE_DOCUMENT_MATERIALIZATION_FAILED",
"SOURCE_DOCUMENT_REPLACEMENT_SAGA_REQUIRED",
"SOURCE_IMPORT_PARTIAL_FAILURE",
"SOURCE_ONLINE_DOCUMENT_CONFIG_INVALID",
"SOURCE_ONLINE_DOCUMENT_IMPORT_FAILED",
"SOURCE_ONLINE_DOCUMENT_PAGE_FETCH_FAILED",
"SOURCE_ONLINE_DOCUMENT_REQUEST_FAILED",
"SOURCE_ONLINE_DOCUMENT_UNAVAILABLE",
"SOURCE_ONLINE_DRIVE_CONFIG_INVALID",
"SOURCE_ONLINE_DRIVE_FILE_DOWNLOAD_FAILED",
"SOURCE_ONLINE_DRIVE_IMPORT_FAILED",
"SOURCE_ONLINE_DRIVE_REQUEST_FAILED",
"SOURCE_ONLINE_DRIVE_UNAVAILABLE",
"SOURCE_OPERATION_FAILED",
"SOURCE_PROVIDER_REJECTED",
"SOURCE_PROVIDER_TIMEOUT",
"SOURCE_PROVIDER_UNAVAILABLE",
"SOURCE_SYNC_SELECTION_MISMATCH",
"SOURCE_SECRET_INTEGRITY_FAILED",
"SOURCE_SECRET_REF_CONFLICT",
"SOURCE_SYNC_FAILED",
"SOURCE_WEBSITE_CRAWL_CONFIG_INVALID",
"SOURCE_WEBSITE_CRAWL_FAILED",
"SOURCE_WORKFLOW_FAILED",
"SOURCE_WORKFLOW_CONTENT_MISSING",
"SOURCE_WORKFLOW_CONTENT_TOO_LARGE",
"SOURCE_WORKFLOW_EXTERNAL_TIMEOUT",
"UPLOAD_INITIALIZATION_FAILED",
"UPLOAD_INTEGRITY_MISMATCH"
]
},
"errorMessage": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"failure": {
"$ref": "#/components/schemas/KnowledgeFsPublicFailure"
},
"failures": {
"type": "array",
"items": {
"type": "object",
"properties": {
"documentId": {
"type": "string",
"format": "uuid"
},
"documentTitle": {
"type": "string"
},
"errorCode": {
"type": "string",
"enum": [
"VECTOR_SPACE_QUOTA_EXCEEDED",
"VECTOR_SPACE_QUOTA_UNAVAILABLE",
"DOCUMENT_COUNT_QUOTA_EXCEEDED",
"DOCUMENT_COUNT_QUOTA_UNAVAILABLE",
"LOGICAL_DOCUMENT_CAS_CONFLICT",
"DURABLE_DELETION_IDEMPOTENCY_CONFLICT",
"SOURCE_VERSION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_COMPILATION_IN_PROGRESS",
"KNOWLEDGE_SPACE_SETTINGS_REVISION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_MIGRATION_REQUIRED",
"DOCUMENT_COMPILATION_PROFILE_CHANGED",
"DOCUMENT_COMPILATION_FAILED",
"DOCUMENT_COMPILATION_RETRYABLE",
"DOCUMENT_COMPILATION_LEASE_LOST",
"DOCUMENT_DISABLED",
"DOCUMENT_PARSER_INPUT_INVALID",
"DOCUMENT_PARSER_NOT_CONFIGURED",
"DOCUMENT_PARSER_RATE_LIMITED",
"DOCUMENT_PARSER_RESPONSE_INVALID",
"DOCUMENT_PARSER_TIMEOUT",
"DOCUMENT_PARSER_UNAVAILABLE",
"DOCUMENT_PARSER_UNSUPPORTED_TYPE",
"DOCUMENT_PDF_RENDER_FAILED",
"EMBEDDING_DIMENSION_INVALID",
"EMBEDDING_DIMENSION_UNSUPPORTED",
"EXECUTION_ATTEMPTS_EXHAUSTED",
"KNOWLEDGE_FS_ACCESS_DENIED",
"KNOWLEDGE_FS_CONFLICT",
"KNOWLEDGE_FS_INTERNAL_ERROR",
"KNOWLEDGE_FS_INVALID_REQUEST",
"KNOWLEDGE_FS_NOT_FOUND",
"KNOWLEDGE_FS_RATE_LIMITED",
"KNOWLEDGE_FS_TIMEOUT",
"KNOWLEDGE_FS_UNAVAILABLE",
"KNOWLEDGE_SPACE_MANIFEST_NOT_FOUND",
"KNOWLEDGE_SPACE_MODEL_CONFIGURATION_REQUIRED",
"MODEL_CAPABILITY_MISMATCH",
"MODEL_CONFIGURATION_STALE",
"MODEL_CREDENTIAL_INVALID",
"MODEL_CREDENTIAL_VALIDATION_UNAVAILABLE",
"MODEL_IDENTITY_MISMATCH",
"MODEL_PREFLIGHT_CANCELED",
"MODEL_PREFLIGHT_FAILED",
"MODEL_PREFLIGHT_TIMEOUT",
"MODEL_PREFLIGHT_UNAVAILABLE",
"MODEL_PROFILE_ACTIVATION_INCOMPLETE",
"MODEL_PROFILE_ACTIVATION_PERMISSION_REQUIRED",
"MODEL_RUNTIME_FAILED",
"MODEL_RUNTIME_RESPONSE_INVALID",
"MODEL_RUNTIME_OUTPUT_LIMIT",
"MODEL_RUNTIME_CONTEXT_LIMIT",
"MODEL_RUNTIME_TIMEOUT",
"MODEL_RUNTIME_UNAVAILABLE",
"MODEL_SELECTION_NOT_FOUND",
"RESEARCH_TASK_CAPABILITY_REVOKED",
"RESEARCH_TASK_DISPATCH_DEAD",
"RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED",
"RESEARCH_TASK_FAILED",
"RESEARCH_TASK_PERMISSION_SNAPSHOT_INVALID",
"RESEARCH_TASK_RUNTIME_SNAPSHOT_INVALID",
"RETRIEVAL_DELETION_IN_PROGRESS",
"RETRIEVAL_EXECUTION_LEASE_LOST",
"SOURCE_BULK_ACTION_FAILED",
"SOURCE_CONNECTION_UNAVAILABLE",
"SOURCE_CRAWL_PAGE_NOT_FOUND",
"SOURCE_CRAWL_PROVIDER_UNAVAILABLE",
"SOURCE_CRAWL_RESULT_LIMIT_EXCEEDED",
"SOURCE_CREDENTIAL_CONFIG_INVALID",
"SOURCE_CREDENTIAL_MUTATION_FAILED",
"SOURCE_CREDENTIAL_TEST_FAILED",
"SOURCE_CREDENTIAL_UNAVAILABLE",
"SOURCE_DOCUMENT_COMPILATION_FAILED",
"SOURCE_DOCUMENT_MATERIALIZATION_FAILED",
"SOURCE_DOCUMENT_REPLACEMENT_SAGA_REQUIRED",
"SOURCE_IMPORT_PARTIAL_FAILURE",
"SOURCE_ONLINE_DOCUMENT_CONFIG_INVALID",
"SOURCE_ONLINE_DOCUMENT_IMPORT_FAILED",
"SOURCE_ONLINE_DOCUMENT_PAGE_FETCH_FAILED",
"SOURCE_ONLINE_DOCUMENT_REQUEST_FAILED",
"SOURCE_ONLINE_DOCUMENT_UNAVAILABLE",
"SOURCE_ONLINE_DRIVE_CONFIG_INVALID",
"SOURCE_ONLINE_DRIVE_FILE_DOWNLOAD_FAILED",
"SOURCE_ONLINE_DRIVE_IMPORT_FAILED",
"SOURCE_ONLINE_DRIVE_REQUEST_FAILED",
"SOURCE_ONLINE_DRIVE_UNAVAILABLE",
"SOURCE_OPERATION_FAILED",
"SOURCE_PROVIDER_REJECTED",
"SOURCE_PROVIDER_TIMEOUT",
"SOURCE_PROVIDER_UNAVAILABLE",
"SOURCE_SYNC_SELECTION_MISMATCH",
"SOURCE_SECRET_INTEGRITY_FAILED",
"SOURCE_SECRET_REF_CONFLICT",
"SOURCE_SYNC_FAILED",
"SOURCE_WEBSITE_CRAWL_CONFIG_INVALID",
"SOURCE_WEBSITE_CRAWL_FAILED",
"SOURCE_WORKFLOW_FAILED",
"SOURCE_WORKFLOW_CONTENT_MISSING",
"SOURCE_WORKFLOW_CONTENT_TOO_LARGE",
"SOURCE_WORKFLOW_EXTERNAL_TIMEOUT",
"UPLOAD_INITIALIZATION_FAILED",
"UPLOAD_INTEGRITY_MISMATCH"
]
},
"errorMessage": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"failure": {
"$ref": "#/components/schemas/KnowledgeFsPublicFailure"
},
"jobId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"documentId",
"errorCode",
"errorMessage",
"failure"
],
"additionalProperties": false
}
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"operation": {
"type": "string",
"enum": [
"document_processing",
"document_upload",
"document_delete",
"document_reindex",
"source_crawl_preview",
"source_crawl_import",
"source_online_document_import",
"source_online_drive_import",
"source_sync",
"source_bulk"
]
},
"phase": {
"type": "string",
"enum": [
"queued",
"parsing",
"outline_summary",
"chunking_indexing",
"graph_admission",
"publication",
"complete"
]
},
"progressCompleted": {
"type": "integer",
"minimum": 0
},
"progressFailed": {
"type": "integer",
"minimum": 0
},
"progressPercent": {
"type": "integer",
"minimum": 0,
"maximum": 100
},
"progressTotal": {
"type": "integer",
"minimum": 0
},
"sourceId": {
"type": "string",
"format": "uuid"
},
"sourceTitle": {
"type": "string",
"minLength": 1
},
"state": {
"type": "string",
"enum": [
"queued",
"running",
"completed",
"failed",
"canceled"
]
},
"semanticEnrichment": {
"type": "object",
"properties": {
"errorCode": {
"type": "string",
"enum": [
"VECTOR_SPACE_QUOTA_EXCEEDED",
"VECTOR_SPACE_QUOTA_UNAVAILABLE",
"DOCUMENT_COUNT_QUOTA_EXCEEDED",
"DOCUMENT_COUNT_QUOTA_UNAVAILABLE",
"LOGICAL_DOCUMENT_CAS_CONFLICT",
"DURABLE_DELETION_IDEMPOTENCY_CONFLICT",
"SOURCE_VERSION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_COMPILATION_IN_PROGRESS",
"KNOWLEDGE_SPACE_SETTINGS_REVISION_CONFLICT",
"KNOWLEDGE_SPACE_SETTINGS_MIGRATION_REQUIRED",
"DOCUMENT_COMPILATION_PROFILE_CHANGED",
"DOCUMENT_COMPILATION_FAILED",
"DOCUMENT_COMPILATION_RETRYABLE",
"DOCUMENT_COMPILATION_LEASE_LOST",
"DOCUMENT_DISABLED",
"DOCUMENT_PARSER_INPUT_INVALID",
"DOCUMENT_PARSER_NOT_CONFIGURED",
"DOCUMENT_PARSER_RATE_LIMITED",
"DOCUMENT_PARSER_RESPONSE_INVALID",
"DOCUMENT_PARSER_TIMEOUT",
"DOCUMENT_PARSER_UNAVAILABLE",
"DOCUMENT_PARSER_UNSUPPORTED_TYPE",
"DOCUMENT_PDF_RENDER_FAILED",
"EMBEDDING_DIMENSION_INVALID",
"EMBEDDING_DIMENSION_UNSUPPORTED",
"EXECUTION_ATTEMPTS_EXHAUSTED",
"KNOWLEDGE_FS_ACCESS_DENIED",
"KNOWLEDGE_FS_CONFLICT",
"KNOWLEDGE_FS_INTERNAL_ERROR",
"KNOWLEDGE_FS_INVALID_REQUEST",
"KNOWLEDGE_FS_NOT_FOUND",
"KNOWLEDGE_FS_RATE_LIMITED",
"KNOWLEDGE_FS_TIMEOUT",
"KNOWLEDGE_FS_UNAVAILABLE",
"KNOWLEDGE_SPACE_MANIFEST_NOT_FOUND",
"KNOWLEDGE_SPACE_MODEL_CONFIGURATION_REQUIRED",
"MODEL_CAPABILITY_MISMATCH",
"MODEL_CONFIGURATION_STALE",
"MODEL_CREDENTIAL_INVALID",
"MODEL_CREDENTIAL_VALIDATION_UNAVAILABLE",
"MODEL_IDENTITY_MISMATCH",
"MODEL_PREFLIGHT_CANCELED",
"MODEL_PREFLIGHT_FAILED",
"MODEL_PREFLIGHT_TIMEOUT",
"MODEL_PREFLIGHT_UNAVAILABLE",
"MODEL_PROFILE_ACTIVATION_INCOMPLETE",
"MODEL_PROFILE_ACTIVATION_PERMISSION_REQUIRED",
"MODEL_RUNTIME_FAILED",
"MODEL_RUNTIME_RESPONSE_INVALID",
"MODEL_RUNTIME_OUTPUT_LIMIT",
"MODEL_RUNTIME_CONTEXT_LIMIT",
"MODEL_RUNTIME_TIMEOUT",
"MODEL_RUNTIME_UNAVAILABLE",
"MODEL_SELECTION_NOT_FOUND",
"RESEARCH_TASK_CAPABILITY_REVOKED",
"RESEARCH_TASK_DISPATCH_DEAD",
"RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED",
"RESEARCH_TASK_FAILED",
"RESEARCH_TASK_PERMISSION_SNAPSHOT_INVALID",
"RESEARCH_TASK_RUNTIME_SNAPSHOT_INVALID",
"RETRIEVAL_DELETION_IN_PROGRESS",
"RETRIEVAL_EXECUTION_LEASE_LOST",
"SOURCE_BULK_ACTION_FAILED",
"SOURCE_CONNECTION_UNAVAILABLE",
"SOURCE_CRAWL_PAGE_NOT_FOUND",
"SOURCE_CRAWL_PROVIDER_UNAVAILABLE",
"SOURCE_CRAWL_RESULT_LIMIT_EXCEEDED",
"SOURCE_CREDENTIAL_CONFIG_INVALID",
"SOURCE_CREDENTIAL_MUTATION_FAILED",
"SOURCE_CREDENTIAL_TEST_FAILED",
"SOURCE_CREDENTIAL_UNAVAILABLE",
"SOURCE_DOCUMENT_COMPILATION_FAILED",
"SOURCE_DOCUMENT_MATERIALIZATION_FAILED",
"SOURCE_DOCUMENT_REPLACEMENT_SAGA_REQUIRED",
"SOURCE_IMPORT_PARTIAL_FAILURE",
"SOURCE_ONLINE_DOCUMENT_CONFIG_INVALID",
"SOURCE_ONLINE_DOCUMENT_IMPORT_FAILED",
"SOURCE_ONLINE_DOCUMENT_PAGE_FETCH_FAILED",
"SOURCE_ONLINE_DOCUMENT_REQUEST_FAILED",
"SOURCE_ONLINE_DOCUMENT_UNAVAILABLE",
"SOURCE_ONLINE_DRIVE_CONFIG_INVALID",
"SOURCE_ONLINE_DRIVE_FILE_DOWNLOAD_FAILED",
"SOURCE_ONLINE_DRIVE_IMPORT_FAILED",
"SOURCE_ONLINE_DRIVE_REQUEST_FAILED",
"SOURCE_ONLINE_DRIVE_UNAVAILABLE",
"SOURCE_OPERATION_FAILED",
"SOURCE_PROVIDER_REJECTED",
"SOURCE_PROVIDER_TIMEOUT",
"SOURCE_PROVIDER_UNAVAILABLE",
"SOURCE_SYNC_SELECTION_MISMATCH",
"SOURCE_SECRET_INTEGRITY_FAILED",
"SOURCE_SECRET_REF_CONFLICT",
"SOURCE_SYNC_FAILED",
"SOURCE_WEBSITE_CRAWL_CONFIG_INVALID",
"SOURCE_WEBSITE_CRAWL_FAILED",
"SOURCE_WORKFLOW_FAILED",
"SOURCE_WORKFLOW_CONTENT_MISSING",
"SOURCE_WORKFLOW_CONTENT_TOO_LARGE",
"SOURCE_WORKFLOW_EXTERNAL_TIMEOUT",
"UPLOAD_INITIALIZATION_FAILED",
"UPLOAD_INTEGRITY_MISMATCH"
]
},
"errorMessage": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"failure": {
"$ref": "#/components/schemas/KnowledgeFsPublicFailure"
},
"nodesCompleted": {
"type": "integer",
"minimum": 0
},
"nodesTotal": {
"type": "integer",
"minimum": 0
},
"providerCalls": {
"type": "integer",
"minimum": 0
},
"providerCallsMaximum": {
"type": "integer",
"minimum": 0
},
"state": {
"type": "string",
"enum": [
"not_scheduled",
"pending",
"running",
"ready",
"failed",
"disabled"
]
},
"updatedAt": {
"type": "string"
}
},
"required": [
"nodesCompleted",
"state"
],
"additionalProperties": false
},
"taskKind": {
"type": "string",
"enum": [
"document",
"document_bulk",
"source"
]
},
"updatedAt": {
"type": "string"
}
},
"required": [
"canCancel",
"canRetry",
"createdAt",
"id",
"knowledgeSpaceId",
"operation",
"progressCompleted",
"progressFailed",
"progressPercent",
"progressTotal",
"state",
"taskKind",
"updatedAt"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid background task request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Background task not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Background task cannot perform this transition",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"413": {
"description": "Workspace vector storage quota exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Workspace vector storage quota unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/sources": {
"post": {
"operationId": "createKnowledgeSpaceSource",
"tags": [
"Sources"
],
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"connectionId": {
"type": "string",
"format": "uuid"
},
"credentials": {
"type": "object",
"additionalProperties": {}
},
"metadata": {
"type": "object",
"additionalProperties": {}
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"permissionScope": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"status": {
"type": "string",
"enum": [
"active",
"syncing",
"error",
"disabled"
]
},
"type": {
"type": "string",
"enum": [
"upload",
"object-storage",
"connector",
"web"
]
},
"uri": {
"type": "string",
"minLength": 1
}
},
"required": [
"name",
"type",
"uri"
],
"additionalProperties": false
}
}
}
},
"responses": {
"201": {
"description": "Created source",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Source"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space or source not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Source connection is not active or input bindings conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Source capacity exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Source SecretStore is required for credential-bearing writes",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
},
"get": {
"operationId": "listKnowledgeSpaceSources",
"tags": [
"Sources"
],
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string"
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200
},
"required": false,
"name": "limit",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Knowledge space sources",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Source"
},
{
"type": "object",
"properties": {
"syncWorkflow": {
"$ref": "#/components/schemas/SourceWorkflowRun"
}
}
}
]
}
},
"nextCursor": {
"type": "string"
}
},
"required": [
"items"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space or source not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Candidate visibility scan budget exceeded",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"CANDIDATE_VISIBILITY_SCAN_BUDGET_EXCEEDED"
]
},
"error": {
"type": "string",
"enum": [
"Candidate visibility scan budget exceeded"
]
}
},
"required": [
"code",
"error"
],
"additionalProperties": false
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/sources/{sourceId}/credentials": {
"put": {
"operationId": "rotateKnowledgeSpaceSourceCredentials",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "sourceId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"credentials": {
"type": "object",
"additionalProperties": {}
},
"expectedVersion": {
"type": "integer",
"minimum": 1
}
},
"required": [
"credentials",
"expectedVersion"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Rotated source credentials; secret bytes are returned neither here nor later",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Source"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space or source not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Source was modified concurrently (expectedVersion mismatch)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Source SecretStore is not configured or unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
},
"delete": {
"operationId": "revokeKnowledgeSpaceSourceCredentials",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "sourceId",
"in": "path"
},
{
"schema": {
"type": "integer",
"minimum": 1
},
"required": true,
"name": "expectedVersion",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Revoked source credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Source"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space or source not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Source was modified concurrently (expectedVersion mismatch)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Source SecretStore is not configured or unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/sources/{sourceId}/crawl": {
"post": {
"operationId": "crawlKnowledgeSpaceSource",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "sourceId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Website crawl result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebsiteCrawlResult"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Source is not a website crawl source",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space or source not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Source was modified concurrently (expectedVersion mismatch)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"501": {
"description": "Website crawl connector is not configured",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"502": {
"description": "Website crawl failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/sources/{sourceId}/pages": {
"get": {
"operationId": "listKnowledgeSpaceSourcePages",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "sourceId",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
},
"required": false,
"name": "limit",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Authorized online-document pages",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OnlineDocumentPages"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Source is not an online-document connector",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space or source not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"501": {
"description": "Online-document connector is not configured",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"502": {
"description": "Online-document provider request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/sources/{sourceId}/import": {
"post": {
"operationId": "importKnowledgeSpaceSourcePages",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "sourceId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"pages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"lastEditedTime": {
"type": "string",
"minLength": 1
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"pageId": {
"type": "string",
"minLength": 1
},
"type": {
"type": "string",
"minLength": 1
},
"workspaceId": {
"type": "string",
"minLength": 1
}
},
"required": [
"pageId",
"type",
"workspaceId"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 200
}
},
"required": [
"pages"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Imported online-document pages",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SourceImportResult"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Source is not an online-document connector",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space or source not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Source was modified concurrently (expectedVersion mismatch)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"501": {
"description": "Online-document connector is not configured",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"502": {
"description": "Online-document provider request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/sources/{sourceId}/test": {
"post": {
"operationId": "testKnowledgeSpaceSource",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "sourceId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Source credential validation result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SourceCredentialTest"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space or source not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"501": {
"description": "Source credential tester is not configured",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"502": {
"description": "Source credential provider request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/sources/{sourceId}/files": {
"get": {
"operationId": "listKnowledgeSpaceSourceFiles",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "sourceId",
"in": "path"
},
{
"schema": {
"type": "string"
},
"required": false,
"name": "bucket",
"in": "query"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"required": false,
"name": "continuationToken",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 1000
},
"required": false,
"name": "maxKeys",
"in": "query"
},
{
"schema": {
"type": "string"
},
"required": false,
"name": "prefix",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Online-drive files",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OnlineDriveFiles"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Source is not an online-document connector",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space or source not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"501": {
"description": "Online-document connector is not configured",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"502": {
"description": "Online-document provider request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/sources/{sourceId}/import-files": {
"post": {
"operationId": "importKnowledgeSpaceSourceFiles",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "sourceId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"files": {
"type": "array",
"items": {
"type": "object",
"properties": {
"bucket": {
"type": "string"
},
"id": {
"type": "string",
"minLength": 1
},
"mimeType": {
"type": "string"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
}
},
"required": [
"id",
"name"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 200
}
},
"required": [
"files"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Imported online-drive files",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SourceImportResult"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Source is not an online-document connector",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Knowledge space or source not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Source was modified concurrently (expectedVersion mismatch)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"501": {
"description": "Online-document connector is not configured",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"502": {
"description": "Online-document provider request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/source-providers": {
"get": {
"operationId": "listSourceProviders",
"responses": {
"200": {
"description": "Source provider capability catalog",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"authKinds": {
"type": "array",
"items": {
"type": "string",
"enum": [
"api-key",
"endpoint",
"oauth2"
]
}
},
"available": {
"type": "boolean"
},
"capabilities": {
"type": "array",
"items": {
"type": "string",
"enum": [
"website-crawl",
"online-document",
"online-drive"
]
}
},
"configuration": {
"type": "array",
"items": {
"type": "object",
"properties": {
"description": {
"type": "string"
},
"format": {
"type": "string",
"enum": [
"password",
"uri"
]
},
"name": {
"type": "string"
},
"required": {
"type": "boolean"
},
"secret": {
"type": "boolean"
},
"type": {
"type": "string",
"enum": [
"boolean",
"integer",
"string"
]
}
},
"required": [
"name",
"required",
"secret",
"type"
]
}
},
"displayName": {
"type": "string"
},
"id": {
"type": "string"
},
"unavailableReason": {
"type": "string"
}
},
"required": [
"authKinds",
"available",
"capabilities",
"configuration",
"displayName",
"id"
]
}
}
},
"required": [
"items"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"parameters": [
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/source-connections": {
"post": {
"operationId": "createSourceConnection",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"authKind": {
"type": "string",
"enum": [
"api-key",
"endpoint"
]
},
"configuration": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
}
]
}
},
"credentials": {
"type": "object",
"additionalProperties": {}
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 160
},
"providerId": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"required": [
"authKind",
"credentials",
"name",
"providerId"
],
"additionalProperties": false
}
}
}
},
"responses": {
"201": {
"description": "Source connection created",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"authKind": {
"type": "string",
"enum": [
"api-key",
"endpoint",
"oauth2"
]
},
"configuration": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
}
]
}
},
"createdAt": {
"type": "string"
},
"errorCode": {
"type": "string"
},
"expiresAt": {
"type": "string"
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"providerId": {
"type": "string"
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"provisioning",
"active",
"expired",
"error",
"revoked"
]
},
"updatedAt": {
"type": "string"
},
"version": {
"type": "integer"
}
},
"required": [
"authKind",
"configuration",
"createdAt",
"id",
"knowledgeSpaceId",
"name",
"providerId",
"scopes",
"status",
"updatedAt",
"version"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"502": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
},
"get": {
"operationId": "listSourceConnections",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"maxLength": 4096
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
},
"required": false,
"name": "limit",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Source connections",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"authKind": {
"type": "string",
"enum": [
"api-key",
"endpoint",
"oauth2"
]
},
"configuration": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
}
]
}
},
"createdAt": {
"type": "string"
},
"errorCode": {
"type": "string"
},
"expiresAt": {
"type": "string"
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"providerId": {
"type": "string"
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"provisioning",
"active",
"expired",
"error",
"revoked"
]
},
"updatedAt": {
"type": "string"
},
"version": {
"type": "integer"
}
},
"required": [
"authKind",
"configuration",
"createdAt",
"id",
"knowledgeSpaceId",
"name",
"providerId",
"scopes",
"status",
"updatedAt",
"version"
]
}
},
"nextCursor": {
"type": "string"
}
},
"required": [
"items"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/source-connections/oauth": {
"post": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"configuration": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
}
]
}
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 160
},
"providerId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"redirectUri": {
"type": "string",
"minLength": 1,
"maxLength": 2048
},
"scopes": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"maxItems": 100,
"default": []
}
},
"required": [
"name",
"providerId",
"redirectUri"
],
"additionalProperties": false
}
}
}
},
"responses": {
"201": {
"description": "OAuth authorization started",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"authorizationUrl": {
"type": "string"
},
"connection": {
"type": "object",
"properties": {
"authKind": {
"type": "string",
"enum": [
"api-key",
"endpoint",
"oauth2"
]
},
"configuration": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
}
]
}
},
"createdAt": {
"type": "string"
},
"errorCode": {
"type": "string"
},
"expiresAt": {
"type": "string"
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"providerId": {
"type": "string"
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"provisioning",
"active",
"expired",
"error",
"revoked"
]
},
"updatedAt": {
"type": "string"
},
"version": {
"type": "integer"
}
},
"required": [
"authKind",
"configuration",
"createdAt",
"id",
"knowledgeSpaceId",
"name",
"providerId",
"scopes",
"status",
"updatedAt",
"version"
]
}
},
"required": [
"authorizationUrl",
"connection"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"502": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "postKnowledgeSpacesByIdSourceConnectionsOauth",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/source-oauth/callback": {
"post": {
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 1,
"maxLength": 8192
},
"state": {
"type": "string",
"minLength": 32,
"maxLength": 256
}
},
"required": [
"code",
"state"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "OAuth connection activated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"authKind": {
"type": "string",
"enum": [
"api-key",
"endpoint",
"oauth2"
]
},
"configuration": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
}
]
}
},
"createdAt": {
"type": "string"
},
"errorCode": {
"type": "string"
},
"expiresAt": {
"type": "string"
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"providerId": {
"type": "string"
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"provisioning",
"active",
"expired",
"error",
"revoked"
]
},
"updatedAt": {
"type": "string"
},
"version": {
"type": "integer"
}
},
"required": [
"authKind",
"configuration",
"createdAt",
"id",
"knowledgeSpaceId",
"name",
"providerId",
"scopes",
"status",
"updatedAt",
"version"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"502": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"503": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "postSourceOauthCallback",
"parameters": [
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/source-connections/{connectionId}": {
"get": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "connectionId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Source connection",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"authKind": {
"type": "string",
"enum": [
"api-key",
"endpoint",
"oauth2"
]
},
"configuration": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
}
]
}
},
"createdAt": {
"type": "string"
},
"errorCode": {
"type": "string"
},
"expiresAt": {
"type": "string"
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"providerId": {
"type": "string"
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"provisioning",
"active",
"expired",
"error",
"revoked"
]
},
"updatedAt": {
"type": "string"
},
"version": {
"type": "integer"
}
},
"required": [
"authKind",
"configuration",
"createdAt",
"id",
"knowledgeSpaceId",
"name",
"providerId",
"scopes",
"status",
"updatedAt",
"version"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getKnowledgeSpacesByIdSourceConnectionsByConnectionId",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
},
"delete": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "connectionId",
"in": "path"
},
{
"schema": {
"type": "integer",
"minimum": 1
},
"required": true,
"name": "expectedVersion",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Source connection locally revoked",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"authKind": {
"type": "string",
"enum": [
"api-key",
"endpoint",
"oauth2"
]
},
"configuration": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
}
]
}
},
"createdAt": {
"type": "string"
},
"errorCode": {
"type": "string"
},
"expiresAt": {
"type": "string"
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"providerId": {
"type": "string"
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"provisioning",
"active",
"expired",
"error",
"revoked"
]
},
"updatedAt": {
"type": "string"
},
"version": {
"type": "integer"
}
},
"required": [
"authKind",
"configuration",
"createdAt",
"id",
"knowledgeSpaceId",
"name",
"providerId",
"scopes",
"status",
"updatedAt",
"version"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "deleteKnowledgeSpacesByIdSourceConnectionsByConnectionId",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/source-connections/{connectionId}/refresh": {
"post": {
"operationId": "refreshSourceConnection",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "connectionId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"expectedVersion": {
"type": "integer",
"minimum": 1
}
},
"required": [
"expectedVersion"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Source connection refreshed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"authKind": {
"type": "string",
"enum": [
"api-key",
"endpoint",
"oauth2"
]
},
"configuration": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
}
]
}
},
"createdAt": {
"type": "string"
},
"errorCode": {
"type": "string"
},
"expiresAt": {
"type": "string"
},
"id": {
"type": "string",
"format": "uuid"
},
"knowledgeSpaceId": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"providerId": {
"type": "string"
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"provisioning",
"active",
"expired",
"error",
"revoked"
]
},
"updatedAt": {
"type": "string"
},
"version": {
"type": "integer"
}
},
"required": [
"authKind",
"configuration",
"createdAt",
"id",
"knowledgeSpaceId",
"name",
"providerId",
"scopes",
"status",
"updatedAt",
"version"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"502": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/sources/{sourceId}/sync": {
"post": {
"operationId": "createSourceSyncWorkflow",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "sourceId",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"required": true,
"name": "Idempotency-Key",
"in": "header"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"202": {
"description": "Durable source sync accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SourceWorkflowRun"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/sources/{sourceId}/crawl-preview": {
"post": {
"operationId": "createSourceCrawlPreviewWorkflow",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "sourceId",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"required": true,
"name": "Idempotency-Key",
"in": "header"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"202": {
"description": "Durable crawl preview accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SourceWorkflowRun"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/sources/{sourceId}/workflow-imports": {
"post": {
"operationId": "createSourceImportWorkflow",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "sourceId",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 255
},
"required": true,
"name": "Idempotency-Key",
"in": "header"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "object",
"properties": {
"sourceUpdate": {
"type": "object",
"properties": {
"expectedVersion": {
"type": "integer",
"minimum": 1
},
"metadata": {
"type": "object",
"additionalProperties": {}
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"providerParameters": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
}
]
}
},
"status": {
"type": "string",
"enum": [
"active",
"syncing",
"error",
"disabled"
]
},
"uri": {
"type": "string",
"minLength": 1,
"maxLength": 4096
}
},
"required": [
"expectedVersion"
],
"additionalProperties": false
},
"desiredSyncPolicy": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"mode": {
"type": "string",
"enum": [
"manual",
"interval",
"custom"
]
},
"customIntervalSeconds": {
"type": "integer",
"minimum": 3600,
"maximum": 2592000
}
},
"required": [
"enabled",
"mode"
],
"additionalProperties": false
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"etag": {
"type": "string",
"maxLength": 1024
},
"lastEditedTime": {
"type": "string",
"maxLength": 128
},
"name": {
"type": "string",
"maxLength": 500
},
"pageId": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"providerItemId": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"type": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"workspaceId": {
"type": "string",
"minLength": 1,
"maxLength": 1024
}
},
"required": [
"pageId",
"providerItemId",
"type",
"workspaceId"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 200
},
"kind": {
"type": "string",
"enum": [
"online-document-import"
]
}
},
"required": [
"items",
"kind"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"sourceUpdate": {
"type": "object",
"properties": {
"expectedVersion": {
"type": "integer",
"minimum": 1
},
"metadata": {
"type": "object",
"additionalProperties": {}
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"providerParameters": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
}
]
}
},
"status": {
"type": "string",
"enum": [
"active",
"syncing",
"error",
"disabled"
]
},
"uri": {
"type": "string",
"minLength": 1,
"maxLength": 4096
}
},
"required": [
"expectedVersion"
],
"additionalProperties": false
},
"desiredSyncPolicy": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"mode": {
"type": "string",
"enum": [
"manual",
"interval",
"custom"
]
},
"customIntervalSeconds": {
"type": "integer",
"minimum": 3600,
"maximum": 2592000
}
},
"required": [
"enabled",
"mode"
],
"additionalProperties": false
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"bucket": {
"type": "string",
"maxLength": 1024
},
"etag": {
"type": "string",
"maxLength": 1024
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"mimeType": {
"type": "string",
"maxLength": 255
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"providerItemId": {
"type": "string",
"minLength": 1,
"maxLength": 1024
}
},
"required": [
"id",
"name",
"providerItemId"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 200
},
"kind": {
"type": "string",
"enum": [
"online-drive-import"
]
}
},
"required": [
"items",
"kind"
],
"additionalProperties": false
}
]
}
}
}
},
"responses": {
"202": {
"description": "Durable provider import accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SourceWorkflowRun"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/sources/{sourceId}/sync-policy": {
"get": {
"operationId": "getSourceSyncPolicy",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "sourceId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Source sync policy",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SourceSyncPolicy"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
},
"put": {
"operationId": "putSourceSyncPolicy",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "sourceId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"customIntervalSeconds": {
"type": "integer",
"minimum": 3600,
"maximum": 2592000
},
"enabled": {
"type": "boolean"
},
"expectedRevision": {
"type": "integer",
"minimum": 0
},
"expectedSourceVersion": {
"type": "integer",
"minimum": 1
},
"mode": {
"type": "string",
"enum": [
"manual",
"interval",
"custom"
]
}
},
"required": [
"enabled",
"expectedRevision",
"expectedSourceVersion",
"mode"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Source sync policy updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SourceSyncPolicy"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/sources/bulk": {
"post": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"required": true,
"name": "Idempotency-Key",
"in": "header"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"sync",
"disable",
"remove"
]
},
"sourceIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 200
}
},
"required": [
"action",
"sourceIds"
],
"additionalProperties": false
}
}
}
},
"responses": {
"202": {
"description": "Durable bulk source workflow accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SourceWorkflowRun"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "postKnowledgeSpacesByIdSourcesBulk",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/sources/{sourceId}/crawl-import": {
"post": {
"operationId": "createSourceCrawlImportWorkflow",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "sourceId",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 255
},
"required": true,
"name": "Idempotency-Key",
"in": "header"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"sourceUpdate": {
"type": "object",
"properties": {
"expectedVersion": {
"type": "integer",
"minimum": 1
},
"metadata": {
"type": "object",
"additionalProperties": {}
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"providerParameters": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
}
]
}
},
"status": {
"type": "string",
"enum": [
"active",
"syncing",
"error",
"disabled"
]
},
"uri": {
"type": "string",
"minLength": 1,
"maxLength": 4096
}
},
"required": [
"expectedVersion"
],
"additionalProperties": false
},
"desiredSyncPolicy": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"mode": {
"type": "string",
"enum": [
"manual",
"interval",
"custom"
]
},
"customIntervalSeconds": {
"type": "integer",
"minimum": 3600,
"maximum": 2592000
}
},
"required": [
"enabled",
"mode"
],
"additionalProperties": false
},
"pages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"content": {
"type": "string",
"maxLength": 10000000
},
"description": {
"type": [
"string",
"null"
]
},
"sourceUrl": {
"type": "string",
"maxLength": 4096,
"format": "uri"
},
"title": {
"type": [
"string",
"null"
]
}
},
"required": [
"content",
"sourceUrl"
]
},
"minItems": 1,
"maxItems": 200
},
"replaceExistingSelection": {
"type": "boolean"
},
"sourceUrls": {
"type": "array",
"items": {
"type": "string",
"maxLength": 4096,
"format": "uri"
},
"minItems": 1,
"maxItems": 200
}
},
"required": [
"sourceUrls"
],
"additionalProperties": false
}
}
}
},
"responses": {
"202": {
"description": "Durable selected website crawl import accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SourceWorkflowRun"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/source-workflows": {
"get": {
"operationId": "listSourceWorkflows",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"maxLength": 4096
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
},
"required": false,
"name": "limit",
"in": "query"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": false,
"name": "sourceId",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Source workflow history",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SourceWorkflowRun"
}
},
"nextCursor": {
"type": "string"
}
},
"required": [
"items"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/source-workflows/{runId}": {
"get": {
"operationId": "getSourceWorkflow",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "runId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Source workflow",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SourceWorkflowRun"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/source-workflows/{runId}/bulk-items": {
"get": {
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "runId",
"in": "path"
},
{
"schema": {
"type": "string",
"maxLength": 4096
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
},
"required": false,
"name": "limit",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Per-source bulk workflow results",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"sync",
"disable",
"remove"
]
},
"errorCode": {
"type": "string"
},
"id": {
"type": "string",
"format": "uuid"
},
"reason": {
"type": "string"
},
"sourceId": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string",
"enum": [
"eligible",
"running",
"skipped",
"failed",
"completed"
]
},
"updatedAt": {
"type": "string"
}
},
"required": [
"action",
"id",
"sourceId",
"status",
"updatedAt"
]
}
},
"nextCursor": {
"type": "string"
}
},
"required": [
"items"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"operationId": "getKnowledgeSpacesByIdSourceWorkflowsByRunIdBulkItems",
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/source-workflows/{runId}/cancel": {
"post": {
"operationId": "cancelSourceWorkflow",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "runId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"maxLength": 1000
}
},
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Source workflow canceled",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SourceWorkflowRun"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/source-workflows/{runId}/retry": {
"post": {
"operationId": "retrySourceWorkflow",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "runId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Source workflow retried",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SourceWorkflowRun"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/source-workflows/{runId}/pages": {
"get": {
"operationId": "listCrawlPreviewPages",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "runId",
"in": "path"
},
{
"schema": {
"type": "string",
"maxLength": 4096
},
"required": false,
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
},
"required": false,
"name": "limit",
"in": "query"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Crawl preview pages (content excluded)",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"description": {
"type": "string"
},
"etag": {
"type": "string"
},
"pageId": {
"type": "string"
},
"sourceUrl": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"pageId",
"sourceUrl"
]
}
},
"nextCursor": {
"type": "string"
}
},
"required": [
"items"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
}
},
"/knowledge-spaces/{id}/source-workflows/{runId}/selection": {
"post": {
"operationId": "selectCrawlPreviewPages",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "runId",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"required": true,
"name": "Idempotency-Key",
"in": "header"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"pageIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"minItems": 1,
"maxItems": 200
}
},
"required": [
"pageIds"
],
"additionalProperties": false
}
}
}
},
"responses": {
"202": {
"description": "Crawl import selection accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SourceWorkflowRun"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/namespace/source-preview-jobs": {
"post": {
"operationId": "createNamespaceSourcePreview",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"credentialId": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"pluginId": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"datasource": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"parameters": {
"type": "object",
"additionalProperties": {}
},
"rootUrl": {
"type": "string",
"maxLength": 4096,
"format": "uri"
},
"configurationFingerprint": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"required": [
"credentialId",
"pluginId",
"provider",
"datasource",
"parameters",
"rootUrl",
"configurationFingerprint"
],
"additionalProperties": false
}
}
}
},
"responses": {
"202": {
"description": "Website preview queued",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"jobId": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string",
"enum": [
"queued",
"running",
"completed",
"failed",
"canceled",
"consumed"
]
},
"configurationFingerprint": {
"type": "string"
},
"expiresAt": {
"type": "string"
},
"errorCode": {
"type": "string"
},
"importWorkflowId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"jobId",
"status",
"configurationFingerprint",
"expiresAt"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"parameters": [
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/namespace/source-preview-jobs/{jobId}": {
"get": {
"operationId": "getNamespaceSourcePreview",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "jobId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Website preview status",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"jobId": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string",
"enum": [
"queued",
"running",
"completed",
"failed",
"canceled",
"consumed"
]
},
"configurationFingerprint": {
"type": "string"
},
"expiresAt": {
"type": "string"
},
"errorCode": {
"type": "string"
},
"importWorkflowId": {
"type": "string",
"format": "uuid"
},
"pages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"pageId": {
"type": "string"
},
"sourceUrl": {
"type": "string",
"format": "uri"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"pageId",
"sourceUrl"
]
}
}
},
"required": [
"jobId",
"status",
"configurationFingerprint",
"expiresAt",
"pages"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:read"
},
"delete": {
"operationId": "cancelNamespaceSourcePreview",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "jobId",
"in": "path"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Website preview canceled",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"jobId": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string",
"enum": [
"queued",
"running",
"completed",
"failed",
"canceled",
"consumed"
]
},
"configurationFingerprint": {
"type": "string"
},
"expiresAt": {
"type": "string"
},
"errorCode": {
"type": "string"
},
"importWorkflowId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"jobId",
"status",
"configurationFingerprint",
"expiresAt"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
},
"/knowledge-spaces/{id}/sources/{sourceId}/namespace-preview-import": {
"post": {
"operationId": "consumeNamespaceSourcePreview",
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "id",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "sourceId",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 255
},
"required": true,
"name": "Idempotency-Key",
"in": "header"
},
{
"description": "Optional caller trace identifier; invalid values are replaced by the gateway",
"in": "header",
"name": "x-trace-id",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"previewJobId": {
"type": "string",
"format": "uuid"
},
"pageIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"minItems": 1,
"maxItems": 200
},
"configurationFingerprint": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"required": [
"previewJobId",
"pageIds",
"configurationFingerprint"
],
"additionalProperties": false
}
}
}
},
"responses": {
"202": {
"description": "Preview import accepted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"workflowId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"workflowId"
]
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"headers": {
"x-trace-id": {
"description": "Trace identifier assigned to the request",
"schema": {
"type": "string"
}
}
}
}
},
"x-knowledge-fs-max-response-bytes": 1048576,
"x-knowledge-fs-required-scope": "knowledge-spaces:write"
}
}
},
"webhooks": {},
"servers": [
{
"url": "/"
}
]
}
Reference in new issue View Git Blame Copy Permalink