mirror of
https://github.com/simstudioai/sim.git
synced 2026-11-22 05:07:51 +08:00
* improvement(credentials): resolve agent fallback credentials once, Vanta 401 grace, true refusal codes, headless client-credential modes, and registry cleanups * fix(credentials): name refused hosts in token responses and drop the S3 saved-credential setup flag
10334 lines
356 KiB
JSON
10334 lines
356 KiB
JSON
{
|
||
"openapi": "3.1.0",
|
||
"info": {
|
||
"title": "Sim API v2 — Knowledge Bases",
|
||
"description": "Version 2 of the Sim REST API for knowledge bases, document ingestion, resumable uploads, folders, and semantic or tag-based search.",
|
||
"version": "2.0.0",
|
||
"contact": {
|
||
"name": "Sim Support",
|
||
"email": "help@sim.ai",
|
||
"url": "https://www.sim.ai"
|
||
},
|
||
"license": {
|
||
"name": "Apache 2.0",
|
||
"url": "https://www.apache.org/licenses/LICENSE-2.0.html"
|
||
}
|
||
},
|
||
"servers": [
|
||
{
|
||
"url": "https://www.sim.ai",
|
||
"description": "Production"
|
||
}
|
||
],
|
||
"tags": [
|
||
{
|
||
"name": "Knowledge Bases",
|
||
"description": "Create and organize knowledge bases, ingest documents, and search indexed content."
|
||
}
|
||
],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": []
|
||
}
|
||
],
|
||
"paths": {
|
||
"/api/v2/knowledge": {
|
||
"get": {
|
||
"operationId": "listKnowledgeBases",
|
||
"summary": "List knowledge bases",
|
||
"description": "List active knowledge bases in a workspace with folder filtering, search, sorting, and cursor pagination. Use `scope=archived` to find knowledge bases available for restoration. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
|
||
"x-sim-operation": "knowledge.list",
|
||
"x-oauth-scope": "api:read",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:read"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace whose knowledge bases should be listed.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace whose knowledge bases should be listed."
|
||
}
|
||
},
|
||
{
|
||
"name": "scope",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Lifecycle scope: active or archived knowledge bases. Use Restore knowledge base to recover archived entries. Folder paths resolve only active folders, so filtering by an archived folder returns no matches.",
|
||
"schema": {
|
||
"default": "active",
|
||
"description": "Lifecycle scope: active or archived knowledge bases. Use Restore knowledge base to recover archived entries. Folder paths resolve only active folders, so filtering by an archived folder returns no matches.",
|
||
"type": "string",
|
||
"enum": ["active", "archived"]
|
||
}
|
||
},
|
||
{
|
||
"name": "folderPath",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Restrict results to knowledge bases in this folder. Unknown folder paths contribute no matches.",
|
||
"schema": {
|
||
"description": "Restrict results to knowledge bases in this folder. Unknown folder paths contribute no matches.",
|
||
"$ref": "#/components/schemas/FolderPathInput"
|
||
}
|
||
},
|
||
{
|
||
"name": "search",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Case-insensitive substring match against the resource name.",
|
||
"schema": {
|
||
"description": "Case-insensitive substring match against the resource name.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 200
|
||
}
|
||
},
|
||
{
|
||
"name": "sortBy",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
|
||
"schema": {
|
||
"default": "createdAt",
|
||
"description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
|
||
"type": "string",
|
||
"enum": ["name", "createdAt", "updatedAt"]
|
||
}
|
||
},
|
||
{
|
||
"name": "sortOrder",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Sort direction.",
|
||
"schema": {
|
||
"default": "asc",
|
||
"description": "Sort direction.",
|
||
"type": "string",
|
||
"enum": ["asc", "desc"]
|
||
}
|
||
},
|
||
{
|
||
"name": "limit",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Maximum knowledge bases to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"schema": {
|
||
"default": 50,
|
||
"description": "Maximum knowledge bases to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 100
|
||
}
|
||
},
|
||
{
|
||
"name": "cursor",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"schema": {
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "A page of knowledge bases.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeBaseListResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"post": {
|
||
"operationId": "createKnowledgeBase",
|
||
"summary": "Create knowledge base",
|
||
"description": "Create a knowledge base in a workspace with optional folder placement and chunking configuration. An unknown `folderPath` returns `404`. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.create",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace, name, description, chunking configuration, and folder placement.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateKnowledgeBaseRequest"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Request example 1",
|
||
"value": {
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"name": "Product Documentation",
|
||
"folderPath": "/Product"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"201": {
|
||
"description": "The created knowledge base.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeBaseResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}": {
|
||
"get": {
|
||
"operationId": "getKnowledgeBase",
|
||
"summary": "Get knowledge base",
|
||
"description": "Get a knowledge base's metadata and document counts. Inaccessible knowledge bases return `404`. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
|
||
"x-sim-operation": "knowledge.read",
|
||
"x-oauth-scope": "api:read",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:read"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The requested knowledge base.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeBaseResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"patch": {
|
||
"operationId": "updateKnowledgeBase",
|
||
"summary": "Update knowledge base",
|
||
"description": "Update a knowledge base's name, description, chunking configuration, or folder placement. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.update",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace scope and fields to update. At least one mutable field is required.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/UpdateKnowledgeBaseRequest"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Request example 1",
|
||
"value": {
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"name": "Updated Product Documentation"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "The updated knowledge base.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeBaseResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"delete": {
|
||
"operationId": "deleteKnowledgeBase",
|
||
"summary": "Delete knowledge base",
|
||
"description": "Archive a knowledge base, its documents, and its connectors, pausing synchronization. Use List knowledge bases with `scope=archived` to find it and Restore knowledge base to recover it.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.delete",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Knowledge base deletion acknowledgement.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeDeleteResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/export": {
|
||
"get": {
|
||
"operationId": "exportKnowledgeBase",
|
||
"summary": "Export knowledge base",
|
||
"description": "Stream a knowledge base as a bundle archive: its configuration, tag definitions, each workspace-visible document's file and chunk text, and optionally chunk vectors. Access-control lists, connector links, and credentials never leave. More than 2000 documents returns `413`. Exports record an audit event. `HEAD` checks access with the same authorization as `GET` but skips side effects, returning an empty `200` without payload headers on success. `HEAD` omits `Content-Length` and cannot determine the download size.\n\nOAuth scope: `api:read`.",
|
||
"x-sim-operation": "knowledge.export",
|
||
"x-oauth-scope": "api:read",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:read"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
},
|
||
{
|
||
"name": "vectors",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Include chunk vectors so an import into a deployment with the same embedding model reuses them instead of re-embedding.",
|
||
"schema": {
|
||
"description": "Include chunk vectors so an import into a deployment with the same embedding model reuses them instead of re-embedding.",
|
||
"type": "boolean"
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The knowledge base as a zip archive.",
|
||
"headers": {
|
||
"Content-Type": {
|
||
"$ref": "#/components/headers/Content-Type"
|
||
},
|
||
"Content-Disposition": {
|
||
"$ref": "#/components/headers/Content-Disposition"
|
||
},
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/zip": {
|
||
"schema": {
|
||
"type": "string",
|
||
"format": "binary"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/imports": {
|
||
"post": {
|
||
"operationId": "createKnowledgeImport",
|
||
"summary": "Create knowledge base import",
|
||
"description": "Start importing a knowledge base bundle produced by an export. The response carries signed transfer instructions for the archive; once its bytes are uploaded, complete the import to create the knowledge base. Bundles must be `.zip` archives of at most 5 GiB.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.imports.create",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace, bundle archive, and an optional name for the new knowledge base.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateKnowledgeImportRequest"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Request example 1",
|
||
"value": {
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"name": "Product Documentation",
|
||
"source": {
|
||
"type": "upload",
|
||
"name": "product-documentation.simkb.zip",
|
||
"contentType": "application/zip",
|
||
"size": 7340032
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"201": {
|
||
"description": "The created import and its upload instructions.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2CreateKnowledgeImportResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"402": {
|
||
"$ref": "#/components/responses/UsageLimitExceeded"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/imports/{importId}": {
|
||
"get": {
|
||
"operationId": "getKnowledgeImport",
|
||
"summary": "Get knowledge base import",
|
||
"description": "Get an import's progress and outcome. During `uploading`, the signed upload token is required; omitting it returns `404`.\n\nOAuth scope: `api:read`.",
|
||
"x-sim-operation": "knowledge.imports.read",
|
||
"x-oauth-scope": "api:read",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:read"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "importId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge-base import identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge-base import identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the import.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the import."
|
||
}
|
||
},
|
||
{
|
||
"name": "upload-token",
|
||
"in": "header",
|
||
"required": false,
|
||
"description": "Signed upload control token returned when the import was created; required to read or cancel the import before its upload completes.",
|
||
"schema": {
|
||
"description": "Signed upload control token returned when the import was created; required to read or cancel the import before its upload completes.",
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The requested knowledge base import.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeImportResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"delete": {
|
||
"operationId": "cancelKnowledgeImport",
|
||
"summary": "Cancel knowledge base import",
|
||
"description": "Cancel an import. During its upload the transfer is aborted; while processing, it stops after the document in flight and the documents already imported stay in the new knowledge base. Settled imports return `409`.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.imports.cancel",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "importId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge-base import identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge-base import identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the import.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the import."
|
||
}
|
||
},
|
||
{
|
||
"name": "upload-token",
|
||
"in": "header",
|
||
"required": false,
|
||
"description": "Signed upload control token returned when the import was created; required to read or cancel the import before its upload completes.",
|
||
"schema": {
|
||
"description": "Signed upload control token returned when the import was created; required to read or cancel the import before its upload completes.",
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The canceled knowledge base import.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2CancelKnowledgeImportResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/imports/{importId}/parts": {
|
||
"post": {
|
||
"operationId": "createKnowledgeImportPartUrls",
|
||
"summary": "Create knowledge base import part URLs",
|
||
"description": "Create signed URLs for multipart bundle upload parts. Requires the `uploading` state; other states return `409`.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.imports.parts",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "importId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge-base import identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge-base import identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the import.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the import."
|
||
}
|
||
},
|
||
{
|
||
"name": "upload-token",
|
||
"in": "header",
|
||
"required": true,
|
||
"description": "Signed upload control token returned when the upload session was created.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Signed upload control token returned when the upload session was created."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Multipart part numbers for which signed URLs should be created.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateKnowledgeImportPartUrlsRequest"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Request example 1",
|
||
"value": {
|
||
"partNumbers": [1, 2, 3]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "The signed multipart upload URLs.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2CreateKnowledgeImportPartUrlsResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/imports/{importId}/complete": {
|
||
"post": {
|
||
"operationId": "completeKnowledgeImport",
|
||
"summary": "Complete knowledge base import upload",
|
||
"description": "Verify the uploaded bundle and start creating the knowledge base under the same import ID. Vectors are reused when the bundle was embedded with this deployment's model; otherwise documents are re-indexed. Completion records an audit event. Repeating it returns the running import.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.imports.complete",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "importId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge-base import identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge-base import identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the import.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the import."
|
||
}
|
||
},
|
||
{
|
||
"name": "upload-token",
|
||
"in": "header",
|
||
"required": true,
|
||
"description": "Signed upload control token returned when the upload session was created.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Signed upload control token returned when the upload session was created."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The knowledge base import after its upload completed.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2CompleteKnowledgeImportResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"402": {
|
||
"$ref": "#/components/responses/UsageLimitExceeded"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/connectors": {
|
||
"get": {
|
||
"operationId": "listKnowledgeConnectors",
|
||
"summary": "List knowledge connectors",
|
||
"description": "List external sources connected to a knowledge base with cursor pagination. Stored API keys are never returned. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
|
||
"x-sim-operation": "knowledge.connectors.list",
|
||
"x-oauth-scope": "api:read",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:read"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
},
|
||
{
|
||
"name": "sortBy",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Field used to sort the result.",
|
||
"schema": {
|
||
"default": "createdAt",
|
||
"description": "Field used to sort the result.",
|
||
"type": "string",
|
||
"enum": ["connectorType", "createdAt", "updatedAt"]
|
||
}
|
||
},
|
||
{
|
||
"name": "sortOrder",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Sort direction.",
|
||
"schema": {
|
||
"default": "desc",
|
||
"description": "Sort direction.",
|
||
"type": "string",
|
||
"enum": ["asc", "desc"]
|
||
}
|
||
},
|
||
{
|
||
"name": "limit",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Maximum connectors to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"schema": {
|
||
"default": 50,
|
||
"description": "Maximum connectors to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 100
|
||
}
|
||
},
|
||
{
|
||
"name": "cursor",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"schema": {
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "A page of knowledge connectors.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeConnectorListResponse"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Response example 1",
|
||
"value": {
|
||
"data": [
|
||
{
|
||
"id": "kc-9f8e7d6c",
|
||
"knowledgeBaseId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
|
||
"connectorType": "notion",
|
||
"credentialId": "cred-4b3a2c1d",
|
||
"sourceConfig": {
|
||
"pageIds": ["page-123"]
|
||
},
|
||
"syncMode": "full",
|
||
"syncIntervalMinutes": 1440,
|
||
"status": "active",
|
||
"lastSyncAt": "2026-06-20T14:02:11.000Z",
|
||
"lastSyncError": null,
|
||
"lastSyncDocCount": 42,
|
||
"nextSyncAt": "2026-06-21T14:02:11.000Z",
|
||
"consecutiveFailures": 0,
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z"
|
||
}
|
||
],
|
||
"nextCursor": null
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"post": {
|
||
"operationId": "createKnowledgeConnector",
|
||
"summary": "Create knowledge connector",
|
||
"description": "Validate and connect an external source, then queue its initial synchronization. The `apiKey` field is never returned. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.connectors.create",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace, connector type, authentication reference, source configuration, and sync schedule.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateKnowledgeConnectorRequest"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Request example 1",
|
||
"value": {
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"connectorType": "notion",
|
||
"credentialId": "cred-4b3a2c1d",
|
||
"sourceConfig": {
|
||
"pageIds": ["page-123"]
|
||
},
|
||
"syncIntervalMinutes": 1440
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"201": {
|
||
"description": "The created connector without secret material.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeConnectorResponse"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Response example 1",
|
||
"value": {
|
||
"data": {
|
||
"id": "kc-9f8e7d6c",
|
||
"knowledgeBaseId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
|
||
"connectorType": "notion",
|
||
"credentialId": "cred-4b3a2c1d",
|
||
"sourceConfig": {
|
||
"pageIds": ["page-123"]
|
||
},
|
||
"syncMode": "full",
|
||
"syncIntervalMinutes": 1440,
|
||
"status": "active",
|
||
"lastSyncAt": "2026-06-20T14:02:11.000Z",
|
||
"lastSyncError": null,
|
||
"lastSyncDocCount": 42,
|
||
"nextSyncAt": "2026-06-21T14:02:11.000Z",
|
||
"consecutiveFailures": 0,
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/connectors/{connectorId}": {
|
||
"get": {
|
||
"operationId": "getKnowledgeConnector",
|
||
"summary": "Get knowledge connector",
|
||
"description": "Get one connector and its ten most recent synchronization attempts. Stored API keys are never returned. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
|
||
"x-sim-operation": "knowledge.connectors.read",
|
||
"x-oauth-scope": "api:read",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:read"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "connectorId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Connector selected for the operation.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Connector selected for the operation."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Knowledge base that owns the connector.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Knowledge base that owns the connector."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The connector and recent synchronization history.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeConnectorDetailResponse"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Response example 1",
|
||
"value": {
|
||
"data": {
|
||
"id": "kc-9f8e7d6c",
|
||
"knowledgeBaseId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
|
||
"connectorType": "notion",
|
||
"credentialId": "cred-4b3a2c1d",
|
||
"sourceConfig": {
|
||
"pageIds": ["page-123"]
|
||
},
|
||
"syncMode": "full",
|
||
"syncIntervalMinutes": 1440,
|
||
"status": "active",
|
||
"lastSyncAt": "2026-06-20T14:02:11.000Z",
|
||
"lastSyncError": null,
|
||
"lastSyncDocCount": 42,
|
||
"nextSyncAt": "2026-06-21T14:02:11.000Z",
|
||
"consecutiveFailures": 0,
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z",
|
||
"syncLogs": []
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"patch": {
|
||
"operationId": "updateKnowledgeConnector",
|
||
"summary": "Update knowledge connector",
|
||
"description": "Update connector source configuration, schedule, or active state. Replacing source configuration on a runnable connector queues an immediate synchronization; paused connectors retain the change without synchronizing until resumed. Source configuration cannot be replaced while synchronization is already in progress. Authentication material cannot be changed through this operation. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.connectors.update",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "connectorId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Connector selected for the operation.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Connector selected for the operation."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Knowledge base that owns the connector.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Knowledge base that owns the connector."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace scope and at least one mutable connector field.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/UpdateKnowledgeConnectorRequest"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Request example 1",
|
||
"value": {
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"status": "paused"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "The updated connector.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/UpdateKnowledgeConnectorResponse"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Response example 1",
|
||
"value": {
|
||
"data": {
|
||
"id": "kc-9f8e7d6c",
|
||
"knowledgeBaseId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
|
||
"connectorType": "notion",
|
||
"credentialId": "cred-4b3a2c1d",
|
||
"sourceConfig": {
|
||
"pageIds": ["page-123"]
|
||
},
|
||
"syncMode": "full",
|
||
"syncIntervalMinutes": 1440,
|
||
"status": "paused",
|
||
"lastSyncAt": "2026-06-20T14:02:11.000Z",
|
||
"lastSyncError": null,
|
||
"lastSyncDocCount": 42,
|
||
"nextSyncAt": "2026-06-21T14:02:11.000Z",
|
||
"consecutiveFailures": 0,
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:03:00.000Z"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"delete": {
|
||
"operationId": "deleteKnowledgeConnector",
|
||
"summary": "Delete knowledge connector",
|
||
"description": "Delete a connector and optionally its synchronized documents. Documents are retained by default. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.connectors.delete",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "connectorId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Connector selected for the operation.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Connector selected for the operation."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Knowledge base that owns the connector.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Knowledge base that owns the connector."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
},
|
||
{
|
||
"name": "deleteDocuments",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Also permanently delete documents produced by this connector.",
|
||
"schema": {
|
||
"description": "Also permanently delete documents produced by this connector.",
|
||
"type": "boolean"
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Connector deletion acknowledgement and document counts.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeConnectorDeleteResponse"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Response example 1",
|
||
"value": {
|
||
"data": {
|
||
"id": "kc-9f8e7d6c",
|
||
"deleted": true,
|
||
"documentsDeleted": 0,
|
||
"documentsKept": 42
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/connectors/{connectorId}/sync": {
|
||
"post": {
|
||
"operationId": "syncKnowledgeConnector",
|
||
"summary": "Sync knowledge connector",
|
||
"description": "Queue a connector synchronization. Rehydration forces existing documents to be fetched and indexed again. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.connectors.sync",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "connectorId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Connector selected for the operation.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Connector selected for the operation."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Knowledge base that owns the connector.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Knowledge base that owns the connector."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace scope and optional full rehydration control.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/SyncKnowledgeConnectorRequest"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Request example 1",
|
||
"value": {
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"rehydrate": false
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "Synchronization was queued.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeConnectorSyncResponse"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Response example 1",
|
||
"value": {
|
||
"data": {
|
||
"id": "kc-9f8e7d6c",
|
||
"syncTriggered": true
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/connectors/{connectorId}/documents": {
|
||
"get": {
|
||
"operationId": "listKnowledgeConnectorDocuments",
|
||
"summary": "List knowledge connector documents",
|
||
"description": "List documents produced by one connector with opaque cursor pagination. Excluded documents are omitted unless explicitly requested. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
|
||
"x-sim-operation": "knowledge.connectors.documents.list",
|
||
"x-oauth-scope": "api:read",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:read"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "connectorId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Connector selected for the operation.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Connector selected for the operation."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Knowledge base that owns the connector.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Knowledge base that owns the connector."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
},
|
||
{
|
||
"name": "includeExcluded",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Include documents explicitly excluded by a user.",
|
||
"schema": {
|
||
"description": "Include documents explicitly excluded by a user.",
|
||
"type": "boolean"
|
||
}
|
||
},
|
||
{
|
||
"name": "limit",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Maximum connector documents to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"schema": {
|
||
"default": 50,
|
||
"description": "Maximum connector documents to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 100
|
||
}
|
||
},
|
||
{
|
||
"name": "cursor",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"schema": {
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "A page of connector documents.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeConnectorDocumentListResponse"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Response example 1",
|
||
"value": {
|
||
"data": [
|
||
{
|
||
"id": "doc-8a7b6c5d",
|
||
"filename": "Product requirements",
|
||
"externalId": "page-123",
|
||
"sourceUrl": "https://www.notion.so/page-123",
|
||
"enabled": true,
|
||
"userExcluded": false,
|
||
"createdAt": "2026-06-01T09:15:00.000Z",
|
||
"processingStatus": "completed"
|
||
}
|
||
],
|
||
"nextCursor": null
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"patch": {
|
||
"operationId": "updateKnowledgeConnectorDocuments",
|
||
"summary": "Update knowledge connector documents",
|
||
"description": "Exclude connector documents from knowledge search or restore previously excluded documents. Only documents produced by the selected connector can change. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.connectors.documents.update",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "connectorId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Connector selected for the operation.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Connector selected for the operation."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Knowledge base that owns the connector.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Knowledge base that owns the connector."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace, restore or exclude operation, and selected document identifiers.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/UpdateKnowledgeConnectorDocumentsRequest"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Request example 1",
|
||
"value": {
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"operation": "exclude",
|
||
"documentIds": ["doc-8a7b6c5d"]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "The selected connector documents were updated.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeConnectorDocumentsUpdateResponse"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Response example 1",
|
||
"value": {
|
||
"data": {
|
||
"operation": "exclude",
|
||
"updatedCount": 1,
|
||
"documentIds": ["doc-8a7b6c5d"]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/search": {
|
||
"post": {
|
||
"operationId": "searchKnowledge",
|
||
"summary": "Search knowledge",
|
||
"description": "Search one or more knowledge bases with semantic vector retrieval, optional hybrid full-text retrieval, and structured tag filters. Every result names the `knowledgeBaseId` it came from. A request body over 2 MiB is a `413`. Reranking returns `409` when the stored results cannot pass secret-provenance enforcement.\n\nOAuth scope: `api:read`.",
|
||
"x-sim-operation": "knowledge.search",
|
||
"x-oauth-scope": "api:read",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:read"]
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Knowledge bases, query, result limit, retrieval mode, and optional tag filters.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/SearchKnowledgeRequest"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Request example 1",
|
||
"value": {
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"knowledgeBaseIds": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"],
|
||
"query": "How do I reset my password?",
|
||
"topK": 10
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "Matching document chunks ordered by relevance.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeSearchResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"402": {
|
||
"$ref": "#/components/responses/UsageLimitExceeded"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/tags": {
|
||
"get": {
|
||
"operationId": "listKnowledgeTags",
|
||
"summary": "List tags",
|
||
"description": "List the knowledge base's tag definitions with display names, write slots, and field types. Filters and document reads use display names; document writes use slots. Returns one page; `nextCursor` is always null.\n\nOAuth scope: `api:read`.",
|
||
"x-sim-operation": "knowledge.tags.list",
|
||
"x-oauth-scope": "api:read",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:read"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The knowledge base tag vocabulary.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeTagListResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"post": {
|
||
"operationId": "createKnowledgeTag",
|
||
"summary": "Create tag",
|
||
"description": "Create a tag definition. Write document values by `tagSlot` and filter by `displayName`. Omitting `tagSlot` selects a free slot; exhaustion returns `400`. An occupied slot or duplicate name returns `409`. Use Bulk save tag definitions for multiple definitions. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.tags.create",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace scope, display name, field type, and optional slot.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateKnowledgeTagRequest"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Request example 1",
|
||
"value": {
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"displayName": "category",
|
||
"fieldType": "text"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"201": {
|
||
"description": "The created tag definition.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeTagResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"put": {
|
||
"operationId": "bulkSaveKnowledgeTagDefinitions",
|
||
"summary": "Bulk save tag definitions",
|
||
"description": "Create or update tag definitions, preserving unspecified slots. Updates require `originalDisplayName`; other entries create tags. Slot and name conflicts appear in per-definition `errors` with HTTP `200`, leaving conflicting values unchanged. Use Update document to set tag values. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.tags.bulk_save",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace scope and the tag definitions to create or update.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/BulkSaveKnowledgeTagDefinitionsRequest"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Request example 1",
|
||
"value": {
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"definitions": [
|
||
{
|
||
"tagSlot": "tag1",
|
||
"displayName": "category",
|
||
"fieldType": "text"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "Definitions created and updated by the save.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2BulkSaveKnowledgeTagDefinitionsResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"delete": {
|
||
"operationId": "deleteKnowledgeTagDefinitions",
|
||
"summary": "Delete tag definitions",
|
||
"description": "Delete unused tag definitions by default. With `unused=false`, permanently delete all definitions and their values from documents and chunks. Use Delete tag to remove one definition. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.tags.cleanup",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
},
|
||
{
|
||
"name": "unused",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Whether to remove only the tag definitions no document in the knowledge base still carries a value for. Defaults to true. Pass `unused=false` to delete every definition on the knowledge base, which also clears its slot on every document and chunk and is not recoverable.",
|
||
"schema": {
|
||
"description": "Whether to remove only the tag definitions no document in the knowledge base still carries a value for. Defaults to true. Pass `unused=false` to delete every definition on the knowledge base, which also clears its slot on every document and chunk and is not recoverable.",
|
||
"type": "boolean"
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Number of tag definitions removed.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2DeleteKnowledgeTagDefinitionsResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/documents": {
|
||
"get": {
|
||
"operationId": "listKnowledgeDocuments",
|
||
"summary": "List documents",
|
||
"description": "List documents with filename search, state and tag filters, sorting, and cursor pagination. Tag values use display names; use List tags to resolve the slots required for writes.\n\nOAuth scope: `api:read`.",
|
||
"x-sim-operation": "knowledge.documents.list",
|
||
"x-oauth-scope": "api:read",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:read"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
},
|
||
{
|
||
"name": "limit",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Maximum documents to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"schema": {
|
||
"default": 50,
|
||
"description": "Maximum documents to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 100
|
||
}
|
||
},
|
||
{
|
||
"name": "search",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Case-insensitive substring match against the document filename.",
|
||
"schema": {
|
||
"description": "Case-insensitive substring match against the document filename.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 200
|
||
}
|
||
},
|
||
{
|
||
"name": "enabledFilter",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Filter by whether documents are enabled for search.",
|
||
"schema": {
|
||
"default": "all",
|
||
"description": "Filter by whether documents are enabled for search.",
|
||
"type": "string",
|
||
"enum": ["all", "enabled", "disabled"]
|
||
}
|
||
},
|
||
{
|
||
"name": "sortBy",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `filename`.",
|
||
"schema": {
|
||
"default": "uploadedAt",
|
||
"description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `filename`.",
|
||
"type": "string",
|
||
"enum": [
|
||
"filename",
|
||
"fileSize",
|
||
"tokenCount",
|
||
"chunkCount",
|
||
"uploadedAt",
|
||
"processingStatus",
|
||
"enabled"
|
||
]
|
||
}
|
||
},
|
||
{
|
||
"name": "sortOrder",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Sort direction.",
|
||
"schema": {
|
||
"default": "desc",
|
||
"description": "Sort direction.",
|
||
"type": "string",
|
||
"enum": ["asc", "desc"]
|
||
}
|
||
},
|
||
{
|
||
"name": "cursor",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"schema": {
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
},
|
||
{
|
||
"name": "tagFilters",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "A JSON-encoded array of at most 10 tag filters, using the same display-name shape as knowledge search: `[{\"tagName\":\"category\",\"operator\":\"eq\",\"value\":\"billing\"}]`. Every filter must hold, including two that name the same tag. A name that is not defined in this knowledge base is rejected, never ignored.",
|
||
"schema": {
|
||
"description": "A JSON-encoded array of at most 10 tag filters, using the same display-name shape as knowledge search: `[{\"tagName\":\"category\",\"operator\":\"eq\",\"value\":\"billing\"}]`. Every filter must hold, including two that name the same tag. A name that is not defined in this knowledge base is rejected, never ignored.",
|
||
"examples": [
|
||
"[{\"tagName\":\"category\",\"operator\":\"eq\",\"value\":\"billing\"}]"
|
||
],
|
||
"type": "string"
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "A page of knowledge documents.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeDocumentListResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"patch": {
|
||
"operationId": "bulkUpdateKnowledgeDocuments",
|
||
"summary": "Bulk enable or disable documents",
|
||
"description": "Enable or disable selected documents, or use `selectAll` for the entire knowledge base. Use Delete document to remove documents individually. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.documents.bulk",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Operation and the documents it applies to.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/BulkUpdateKnowledgeDocumentsRequest"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Request example 1",
|
||
"value": {
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"operation": "disable",
|
||
"documentIds": ["b2d4f8a0-1c3e-4a5b-9d7c-2e6f0a8b4c12"]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "The number and identifiers of the documents that changed.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2BulkKnowledgeDocumentsResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"post": {
|
||
"operationId": "uploadKnowledgeDocument",
|
||
"summary": "Upload document",
|
||
"description": "Upload one document as multipart form data. Processing continues asynchronously after the document is accepted.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.documents.upload",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Multipart form containing the document file.",
|
||
"content": {
|
||
"multipart/form-data": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/UploadKnowledgeDocumentForm"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"201": {
|
||
"description": "The accepted document queued for processing.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeDocumentSummaryResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"402": {
|
||
"$ref": "#/components/responses/UsageLimitExceeded"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/documents/uploads": {
|
||
"post": {
|
||
"operationId": "createKnowledgeDocumentUpload",
|
||
"summary": "Create document upload",
|
||
"description": "Create a resumable upload session and receive direct PUT or multipart transfer instructions.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.documents.upload.create",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Document metadata used to authorize and initialize the upload.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateKnowledgeDocumentUploadRequest"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Request example 1",
|
||
"value": {
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"name": "getting-started.pdf",
|
||
"contentType": "application/pdf",
|
||
"size": 248913
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"201": {
|
||
"description": "The created upload session and transfer instructions.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2CreateKnowledgeDocumentUploadResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"402": {
|
||
"$ref": "#/components/responses/UsageLimitExceeded"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/documents/uploads/{uploadId}": {
|
||
"delete": {
|
||
"operationId": "abortKnowledgeDocumentUpload",
|
||
"summary": "Abort document upload",
|
||
"description": "Abort an incomplete upload session and discard its uploaded data. Completed uploads cannot be aborted.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.documents.upload.cancel",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "uploadId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Upload session identifier returned when the upload was created.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Upload session identifier returned when the upload was created."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
},
|
||
{
|
||
"name": "upload-token",
|
||
"in": "header",
|
||
"required": true,
|
||
"description": "Signed upload control token returned when the upload session was created.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Signed upload control token returned when the upload session was created."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The aborted upload session.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeDocumentUploadResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/documents/uploads/{uploadId}/parts": {
|
||
"post": {
|
||
"operationId": "createKnowledgeDocumentUploadPartUrls",
|
||
"summary": "Create document upload part URLs",
|
||
"description": "Create short-lived signed PUT URLs for up to 100 multipart part numbers.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.documents.upload.parts",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "uploadId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Upload session identifier returned when the upload was created.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Upload session identifier returned when the upload was created."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
},
|
||
{
|
||
"name": "upload-token",
|
||
"in": "header",
|
||
"required": true,
|
||
"description": "Signed upload control token returned when the upload session was created.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Signed upload control token returned when the upload session was created."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Multipart part numbers for which signed URLs should be created.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateKnowledgeDocumentUploadPartUrlsRequest"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Request example 1",
|
||
"value": {
|
||
"partNumbers": [1, 2, 3]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "Signed URLs for the requested upload parts.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeDocumentUploadPartUrlsResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/documents/uploads/{uploadId}/complete": {
|
||
"post": {
|
||
"operationId": "completeKnowledgeDocumentUpload",
|
||
"summary": "Complete document upload",
|
||
"description": "Verify a direct upload or assemble multipart parts, create the knowledge document, and queue asynchronous processing.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.documents.upload.complete",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "uploadId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Upload session identifier returned when the upload was created.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Upload session identifier returned when the upload was created."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
},
|
||
{
|
||
"name": "upload-token",
|
||
"in": "header",
|
||
"required": true,
|
||
"description": "Signed upload control token returned when the upload session was created.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Signed upload control token returned when the upload session was created."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The completed upload and queued document.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeDocumentUploadResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}": {
|
||
"get": {
|
||
"operationId": "getKnowledgeDocument",
|
||
"summary": "Get document",
|
||
"description": "Get document metadata, processing status, and source connector details.\n\nOAuth scope: `api:read`.",
|
||
"x-sim-operation": "knowledge.documents.read",
|
||
"x-oauth-scope": "api:read",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:read"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "documentId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge document identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge document identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The requested knowledge document.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeDocumentResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"patch": {
|
||
"operationId": "updateKnowledgeDocument",
|
||
"summary": "Update document",
|
||
"description": "Rename a document, change search availability, update tag slots, or requeue processing. Omitted fields remain unchanged; indexing state is read-only. Use List tags to resolve names to slots and Get document for source connector details, which this response omits. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.documents.update",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "documentId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge document identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge document identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Filename, search state, tag slot values, or a processing retry.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/UpdateKnowledgeDocumentRequest"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Request example 1",
|
||
"value": {
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"enabled": false,
|
||
"tag1": "billing"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "The updated document, or the requeue acknowledgement.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2UpdateKnowledgeDocumentResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"delete": {
|
||
"operationId": "deleteKnowledgeDocument",
|
||
"summary": "Delete document",
|
||
"description": "Remove a document from listings and search. Uploaded documents and their chunks are deleted. Connector documents are excluded while retaining their stored data; later synchronization does not re-add them.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.documents.delete",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "documentId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge document identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge document identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Knowledge document deletion acknowledgement.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeDeleteResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/folders": {
|
||
"get": {
|
||
"operationId": "listKnowledgeFolders",
|
||
"summary": "List folders",
|
||
"description": "List folders in the knowledge-base folder tree with filtering and sorting. Returns one page; `nextCursor` is always null. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
|
||
"x-sim-operation": "knowledge.folders.list",
|
||
"x-oauth-scope": "api:read",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:read"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace whose folders should be listed.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace whose folders should be listed."
|
||
}
|
||
},
|
||
{
|
||
"name": "parentPath",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Restrict results to direct children of this parent path. Unknown folder paths contribute no matches.",
|
||
"schema": {
|
||
"description": "Restrict results to direct children of this parent path. Unknown folder paths contribute no matches.",
|
||
"$ref": "#/components/schemas/FolderPathInput"
|
||
}
|
||
},
|
||
{
|
||
"name": "search",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Case-insensitive substring match against the folder name.",
|
||
"schema": {
|
||
"description": "Case-insensitive substring match against the folder name.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 200
|
||
}
|
||
},
|
||
{
|
||
"name": "sortBy",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
|
||
"schema": {
|
||
"default": "name",
|
||
"description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
|
||
"type": "string",
|
||
"enum": ["name", "createdAt", "updatedAt"]
|
||
}
|
||
},
|
||
{
|
||
"name": "sortOrder",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Sort direction.",
|
||
"schema": {
|
||
"default": "asc",
|
||
"description": "Sort direction.",
|
||
"type": "string",
|
||
"enum": ["asc", "desc"]
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "A page of knowledge-base folders.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeFolderListResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"post": {
|
||
"operationId": "createKnowledgeFolder",
|
||
"summary": "Create folder",
|
||
"description": "Create a folder in the knowledge-base folder tree. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.folders.create",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace and canonical path for a new knowledge-base folder.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateKnowledgeFolderRequest"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Request example 1",
|
||
"value": {
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"path": "/Product"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"201": {
|
||
"description": "The created knowledge-base folder.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeFolderResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"patch": {
|
||
"operationId": "relocateKnowledgeFolder",
|
||
"summary": "Rename or move folder",
|
||
"description": "Rename or move a folder and atomically rewrite descendant paths. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.folders.relocate",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Current and destination canonical paths for a knowledge-base folder.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/RelocateKnowledgeFolderRequest"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Request example 1",
|
||
"value": {
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"path": "/Product",
|
||
"destinationPath": "/Archive/Product"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "The relocated knowledge-base folder.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeFolderResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"delete": {
|
||
"operationId": "deleteKnowledgeFolder",
|
||
"summary": "Delete folder",
|
||
"description": "Archive an empty folder, or set `recursive=true` to archive its subfolders and knowledge bases. Use Restore knowledge base to recover knowledge bases.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.folders.delete",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace containing the folder.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace containing the folder."
|
||
}
|
||
},
|
||
{
|
||
"name": "path",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Path of the folder to delete.",
|
||
"schema": {
|
||
"description": "Path of the folder to delete.",
|
||
"$ref": "#/components/schemas/NonRootFolderPathInput"
|
||
}
|
||
},
|
||
{
|
||
"name": "recursive",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Delete the folder's contents and nested folders too. Required for a non-empty folder. Only the listed case-sensitive spellings are accepted.",
|
||
"schema": {
|
||
"description": "Delete the folder's contents and nested folders too. Required for a non-empty folder. Only the listed case-sensitive spellings are accepted.",
|
||
"enum": [
|
||
"true",
|
||
"1",
|
||
"yes",
|
||
"on",
|
||
"y",
|
||
"enabled",
|
||
"false",
|
||
"0",
|
||
"no",
|
||
"off",
|
||
"n",
|
||
"disabled"
|
||
],
|
||
"default": "false",
|
||
"type": "string"
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Folder deletion acknowledgement and deleted item counts.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2DeleteKnowledgeFolderResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/restore": {
|
||
"post": {
|
||
"operationId": "restoreKnowledgeBase",
|
||
"summary": "Restore knowledge base",
|
||
"description": "Restore a knowledge base and the documents and connectors archived with it. Active knowledge bases return unchanged without a new audit event. An archived workspace returns `409`; an archived containing folder moves the restored knowledge base to the workspace root. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.restore",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace scope for the knowledge base.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/RestoreKnowledgeBaseRequest"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Request example 1",
|
||
"value": {
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "The restored knowledge base.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeBaseResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/documents/from-workspace-files": {
|
||
"post": {
|
||
"operationId": "addWorkspaceFilesToKnowledgeBase",
|
||
"summary": "Index workspace files",
|
||
"description": "Queue stored workspace files for indexing without re-uploading bytes. Unreadable, unsupported, or over-100 MiB files appear in `failed`; valid files are queued. Partial success returns `200`. Use Get document to poll processing after receiving document IDs. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.documents.add_workspace_files",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace scope and the workspace file references to index.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/AddWorkspaceFilesToKnowledgeBaseRequest"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Request example 1",
|
||
"value": {
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"fileReferences": ["handbook.pdf"]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "Files queued for indexing, with any that could not be.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2AddWorkspaceFilesToKnowledgeBaseResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"402": {
|
||
"$ref": "#/components/responses/UsageLimitExceeded"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}/chunks": {
|
||
"get": {
|
||
"operationId": "listKnowledgeChunks",
|
||
"summary": "List chunks",
|
||
"description": "List document chunks with content search, enabled filtering, sorting, and cursor pagination. Tags use slots; use List tags to resolve display names. Documents that have not finished processing return `409` with their current status. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
|
||
"x-sim-operation": "knowledge.chunks.list",
|
||
"x-oauth-scope": "api:read",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:read"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "documentId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge document identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge document identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
},
|
||
{
|
||
"name": "search",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Case-insensitive substring match against chunk content.",
|
||
"schema": {
|
||
"description": "Case-insensitive substring match against chunk content.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 200
|
||
}
|
||
},
|
||
{
|
||
"name": "enabled",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Restrict to enabled or disabled chunks. `all` returns both.",
|
||
"schema": {
|
||
"default": "all",
|
||
"description": "Restrict to enabled or disabled chunks. `all` returns both.",
|
||
"type": "string",
|
||
"enum": ["true", "false", "all"]
|
||
}
|
||
},
|
||
{
|
||
"name": "sortBy",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Field used to sort the result.",
|
||
"schema": {
|
||
"default": "chunkIndex",
|
||
"description": "Field used to sort the result.",
|
||
"type": "string",
|
||
"enum": ["chunkIndex", "tokenCount", "enabled"]
|
||
}
|
||
},
|
||
{
|
||
"name": "sortOrder",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Sort direction.",
|
||
"schema": {
|
||
"default": "asc",
|
||
"description": "Sort direction.",
|
||
"type": "string",
|
||
"enum": ["asc", "desc"]
|
||
}
|
||
},
|
||
{
|
||
"name": "limit",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Maximum chunks to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"schema": {
|
||
"default": 50,
|
||
"description": "Maximum chunks to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 100
|
||
}
|
||
},
|
||
{
|
||
"name": "cursor",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"schema": {
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "A page of document chunks.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeChunkListResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"post": {
|
||
"operationId": "createKnowledgeChunk",
|
||
"summary": "Create chunk",
|
||
"description": "Append a chunk and embed it before returning. It inherits the document's tags and next `chunkIndex`. Search includes it when the chunk and document are enabled and the document has completed processing. Connector-synced chunks are read-only and return `403` with `error.details.code: \"CONNECTOR_MANAGED_RESOURCE_READ_ONLY\"`; change the source and re-sync, or exclude the document. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.chunks.create",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "documentId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge document identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge document identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace scope and the text to embed.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateKnowledgeChunkRequest"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Request example 1",
|
||
"value": {
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"content": "To reset your password, open Settings and choose Security."
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"201": {
|
||
"description": "The created chunk.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeChunkResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"patch": {
|
||
"operationId": "bulkUpdateKnowledgeChunks",
|
||
"summary": "Bulk update chunks",
|
||
"description": "Enable, disable, or delete multiple chunks in one best-effort request. Unknown chunk IDs appear in `errors` without failing the request; `processed` counts matched chunks, not changes. Connector-synced chunks are read-only and return `403` with `error.details.code: \"CONNECTOR_MANAGED_RESOURCE_READ_ONLY\"`; change the source and re-sync, or exclude the document. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.chunks.bulk",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "documentId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge document identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge document identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace scope, the operation to apply, and the chunks to apply it to.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/BulkUpdateKnowledgeChunksRequest"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Request example 1",
|
||
"value": {
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"operation": "disable",
|
||
"chunkIds": ["4c1f9e77-2b3a-4f8d-9e10-6a2c8d4b1e05"]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "Outcome of the bulk chunk operation.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2BulkKnowledgeChunksResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}/chunks/{chunkId}": {
|
||
"get": {
|
||
"operationId": "getKnowledgeChunk",
|
||
"summary": "Get chunk",
|
||
"description": "Get one chunk of a document, including the exact text that was embedded. Documents that have not finished processing return `409` with their current status. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
|
||
"x-sim-operation": "knowledge.chunks.read",
|
||
"x-oauth-scope": "api:read",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:read"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "documentId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge document identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge document identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "chunkId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique chunk identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique chunk identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The requested chunk.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeChunkResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"patch": {
|
||
"operationId": "updateKnowledgeChunk",
|
||
"summary": "Update chunk",
|
||
"description": "Correct chunk text or disable it from search. Changing `content` re-embeds immediately and recalculates document token and character counts; disabling retains the index. Connector-synced chunks are read-only and return `403` with `error.details.code: \"CONNECTOR_MANAGED_RESOURCE_READ_ONLY\"`; change the source and re-sync, or exclude the document. Documents that have not finished processing return `409` with their current status. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.chunks.update",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "documentId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge document identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge document identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "chunkId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique chunk identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique chunk identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace scope and the fields to update. At least one is required.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/UpdateKnowledgeChunkRequest"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Request example 1",
|
||
"value": {
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"enabled": false
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "The updated chunk.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeChunkResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"delete": {
|
||
"operationId": "deleteKnowledgeChunk",
|
||
"summary": "Delete chunk",
|
||
"description": "Permanently remove one chunk and subtract it from document counts. Remaining `chunkIndex` values stay stable and may become non-contiguous. Connector-synced chunks are read-only and return `403` with `error.details.code: \"CONNECTOR_MANAGED_RESOURCE_READ_ONLY\"`; change the source and re-sync, or exclude the document. Documents that have not finished processing return `409` with their current status. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.chunks.delete",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "documentId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge document identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge document identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "chunkId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique chunk identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique chunk identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Chunk deletion acknowledgement.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeDeleteResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/tags/{tagId}": {
|
||
"patch": {
|
||
"operationId": "updateKnowledgeTag",
|
||
"summary": "Update tag",
|
||
"description": "Rename a tag or change its slot-compatible `fieldType`. Renaming changes read and filter names without moving the slot or its values. Slots are fixed for a tag's lifetime; an incompatible type returns `400` and requires creating a new tag. A duplicate display name returns `409`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.tags.update",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "tagId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique tag definition identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique tag definition identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace scope and the fields to update. At least one is required.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/UpdateKnowledgeTagRequest"
|
||
},
|
||
"examples": {
|
||
"example1": {
|
||
"summary": "Request example 1",
|
||
"value": {
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"displayName": "topic"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "The updated tag definition.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeTagResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"delete": {
|
||
"operationId": "deleteKnowledgeTag",
|
||
"summary": "Delete tag",
|
||
"description": "Permanently delete a tag definition and its values from every document and chunk in the knowledge base. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
|
||
"x-sim-operation": "knowledge.tags.delete",
|
||
"x-oauth-scope": "api:write",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:write"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "tagId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique tag definition identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique tag definition identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Tag deletion acknowledgement.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2DeleteKnowledgeTagResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/tags/next-slot": {
|
||
"get": {
|
||
"operationId": "getNextKnowledgeTagSlot",
|
||
"summary": "Get next tag slot",
|
||
"description": "Get the next available slot and remaining capacity for a field type. This does not reserve a slot. Create tag selects a free slot when `tagSlot` is omitted. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
|
||
"x-sim-operation": "knowledge.tags.read_next_slot",
|
||
"x-oauth-scope": "api:read",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:read"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
},
|
||
{
|
||
"name": "fieldType",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Value type stored in the slot; it decides which slots are usable and which filter operators apply. Slot capacity per type: text 7, number 5, date 2, boolean 3.",
|
||
"schema": {
|
||
"type": "string",
|
||
"enum": ["text", "number", "date", "boolean"],
|
||
"description": "Value type stored in the slot; it decides which slots are usable and which filter operators apply. Slot capacity per type: text 7, number 5, date 2, boolean 3.",
|
||
"examples": ["text"]
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Slot availability for the requested field type.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2NextKnowledgeTagSlotResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/tags/usage": {
|
||
"get": {
|
||
"operationId": "listKnowledgeTagUsage",
|
||
"summary": "List tag usage",
|
||
"description": "Count the documents and chunks with a value for each defined tag. Returns one page; `nextCursor` is always null. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
|
||
"x-sim-operation": "knowledge.tags.read_usage",
|
||
"x-oauth-scope": "api:read",
|
||
"tags": ["Knowledge Bases"],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
},
|
||
{
|
||
"oauthBearer": ["api:read"]
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Usage counts for every defined tag.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeTagUsageListResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"components": {
|
||
"securitySchemes": {
|
||
"apiKey": {
|
||
"type": "apiKey",
|
||
"in": "header",
|
||
"name": "X-API-Key",
|
||
"description": "Send a personal or workspace API key in `X-API-Key`. See [key types and access](https://docs.sim.ai/api-reference/authentication#key-types); operations that reject workspace keys say so in their description."
|
||
},
|
||
"oauthBearer": {
|
||
"type": "oauth2",
|
||
"description": "Send a Sim OAuth access token in `Authorization: Bearer`. See [OAuth authentication and scopes](https://docs.sim.ai/api-reference/authentication#oauth-access-tokens).",
|
||
"flows": {
|
||
"authorizationCode": {
|
||
"authorizationUrl": "https://www.sim.ai/api/auth/oauth2/authorize",
|
||
"tokenUrl": "https://www.sim.ai/api/auth/oauth2/token",
|
||
"refreshUrl": "https://www.sim.ai/api/auth/oauth2/token",
|
||
"scopes": {
|
||
"api:read": "Read your workspaces, workflows, files, tables, and logs",
|
||
"api:write": "Read, create, change, run, and delete resources in your workspaces",
|
||
"offline_access": "Stay signed in without asking again"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"headers": {
|
||
"Content-Type": {
|
||
"description": "MIME type of the file, defaulting to application/octet-stream when the stored type is unavailable.",
|
||
"schema": {
|
||
"type": "string",
|
||
"title": "Content type",
|
||
"description": "MIME type of the file, defaulting to application/octet-stream when the stored type is unavailable."
|
||
}
|
||
},
|
||
"Content-Disposition": {
|
||
"description": "Attachment disposition containing sanitized and RFC 5987 encoded filenames.",
|
||
"schema": {
|
||
"type": "string",
|
||
"title": "Content disposition",
|
||
"description": "Attachment disposition containing sanitized and RFC 5987 encoded filenames."
|
||
}
|
||
},
|
||
"Content-Length": {
|
||
"description": "File size in bytes.",
|
||
"schema": {
|
||
"type": "string",
|
||
"pattern": "^(0|[1-9]\\d*)$",
|
||
"title": "Content length",
|
||
"description": "File size in bytes."
|
||
}
|
||
},
|
||
"X-RateLimit-Limit": {
|
||
"description": "Maximum requests allowed in the current window.",
|
||
"schema": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"title": "Rate limit",
|
||
"description": "Maximum requests allowed in the current window."
|
||
}
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"description": "Requests remaining in the current window.",
|
||
"schema": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"title": "Rate limit remaining",
|
||
"description": "Requests remaining in the current window."
|
||
}
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"description": "ISO 8601 timestamp when the current rate-limit window resets.",
|
||
"schema": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"title": "Rate limit reset",
|
||
"description": "ISO 8601 timestamp when the current rate-limit window resets."
|
||
}
|
||
},
|
||
"Retry-After": {
|
||
"description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.",
|
||
"schema": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"title": "Retry after",
|
||
"description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset."
|
||
}
|
||
},
|
||
"X-Run-Id": {
|
||
"description": "Identifier assigned to the workflow run.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"title": "Run identifier",
|
||
"description": "Identifier assigned to the workflow run."
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"BadRequest": {
|
||
"description": "The request is invalid. This includes a query parameter sent with no value (`?limit=`, `?search=`), which is rejected rather than read as zero, empty, or the parameter default — omit the parameter instead.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2Error"
|
||
},
|
||
"example": {
|
||
"error": {
|
||
"code": "BAD_REQUEST",
|
||
"message": "Invalid request"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"Unauthorized": {
|
||
"description": "The API credential is missing or invalid.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2Error"
|
||
},
|
||
"example": {
|
||
"error": {
|
||
"code": "UNAUTHORIZED",
|
||
"message": "Authentication required"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"UsageLimitExceeded": {
|
||
"description": "The workspace has exceeded its usage or billing limits.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2Error"
|
||
},
|
||
"example": {
|
||
"error": {
|
||
"code": "USAGE_LIMIT_EXCEEDED",
|
||
"message": "Usage limit exceeded. Please upgrade your plan to continue."
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"Forbidden": {
|
||
"description": "The caller lacks the rights this operation requires. When the cause is one a caller can act on, `error.details.code` names it. A resource in a workspace the caller cannot reach at all answers `404` instead, so absence and denial are indistinguishable.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2Error"
|
||
},
|
||
"example": {
|
||
"error": {
|
||
"code": "FORBIDDEN",
|
||
"message": "Insufficient workspace permissions",
|
||
"details": {
|
||
"code": "INSUFFICIENT_WORKSPACE_ROLE"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"NotFound": {
|
||
"description": "The requested resource was not found.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2Error"
|
||
},
|
||
"example": {
|
||
"error": {
|
||
"code": "NOT_FOUND",
|
||
"message": "Not found"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"Conflict": {
|
||
"description": "The request conflicts with current resource state.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2Error"
|
||
},
|
||
"example": {
|
||
"error": {
|
||
"code": "CONFLICT",
|
||
"message": "The request conflicts with current knowledge resource state"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"PayloadTooLarge": {
|
||
"description": "The request, or a resource collection it must materialize, exceeds the allowed size: an oversized request body, a generated artifact past the download ceiling, or a workspace folder tree too large to load in full.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2Error"
|
||
},
|
||
"example": {
|
||
"error": {
|
||
"code": "PAYLOAD_TOO_LARGE",
|
||
"message": "Request body is too large"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"UnsupportedMediaType": {
|
||
"description": "The request uses an unsupported media type.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2Error"
|
||
},
|
||
"example": {
|
||
"error": {
|
||
"code": "UNSUPPORTED_MEDIA_TYPE",
|
||
"message": "Request body must be sent as application/json"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"RateLimited": {
|
||
"description": "The caller exceeded the request rate limit.",
|
||
"headers": {
|
||
"Retry-After": {
|
||
"$ref": "#/components/headers/Retry-After"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2Error"
|
||
},
|
||
"example": {
|
||
"error": {
|
||
"code": "RATE_LIMITED",
|
||
"message": "API rate limit exceeded",
|
||
"details": {
|
||
"retryAfter": "2026-01-01T00:00:30.000Z"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"InternalError": {
|
||
"description": "An unexpected server error occurred.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2Error"
|
||
},
|
||
"example": {
|
||
"error": {
|
||
"code": "INTERNAL_ERROR",
|
||
"message": "Internal server error"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"ServiceUnavailable": {
|
||
"description": "A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.",
|
||
"headers": {
|
||
"Retry-After": {
|
||
"$ref": "#/components/headers/Retry-After"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2Error"
|
||
},
|
||
"example": {
|
||
"error": {
|
||
"code": "SERVICE_UNAVAILABLE",
|
||
"message": "Service temporarily unavailable"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"schemas": {
|
||
"V2ActionableForbiddenDetails": {
|
||
"type": "object",
|
||
"properties": {
|
||
"code": {
|
||
"$ref": "#/components/schemas/V2ForbiddenDetailCode"
|
||
}
|
||
},
|
||
"required": ["code"],
|
||
"additionalProperties": {
|
||
"description": "Additional context for this refusal."
|
||
},
|
||
"title": "Actionable forbidden details",
|
||
"description": "Machine-readable cause and optional context for an actionable `403` response."
|
||
},
|
||
"V2ForbiddenDetailCode": {
|
||
"type": "string",
|
||
"enum": [
|
||
"INSUFFICIENT_WORKSPACE_ROLE",
|
||
"PERSONAL_API_KEYS_DISABLED",
|
||
"WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
|
||
"PRINCIPAL_KIND_NOT_PERMITTED",
|
||
"ORGANIZATION_MEMBERSHIP_REQUIRED",
|
||
"ORGANIZATION_ADMIN_REQUIRED",
|
||
"ENTERPRISE_PLAN_REQUIRED",
|
||
"SSO_DISABLED",
|
||
"SSO_DOMAIN_NOT_VERIFIED",
|
||
"SSO_PROVIDER_LIMIT_REACHED",
|
||
"ORGANIZATION_PLAN_REQUIRED",
|
||
"AUDIT_LOGS_DISABLED",
|
||
"ACCESS_REQUESTS_DISABLED",
|
||
"ACCESS_REQUEST_ORGANIZATION_REQUIRED",
|
||
"SKILL_EDITOR_ACCESS_REQUIRED",
|
||
"SECRET_ADMIN_ACCESS_REQUIRED",
|
||
"WORKSPACE_RESOURCE_LIMIT_REACHED",
|
||
"PUBLIC_SHARING_NOT_ALLOWED",
|
||
"CREDENTIAL_ADMIN_ACCESS_REQUIRED",
|
||
"MCP_SERVER_URL_NOT_ALLOWED",
|
||
"WORKSPACE_PLAN_CAPABILITY_REQUIRED",
|
||
"CHAT_AUTH_MODE_NOT_PERMITTED",
|
||
"CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
|
||
"PERMISSION_GROUP_CAPABILITY_BLOCKED",
|
||
"INTEGRATION_NOT_ALLOWED",
|
||
"INSUFFICIENT_SCOPE",
|
||
"READ_ONLY_API_KEY",
|
||
"SCIM_MANAGED_MEMBERSHIP"
|
||
],
|
||
"title": "Forbidden detail code",
|
||
"description": "Stable cause code for an actionable `403` response."
|
||
},
|
||
"V2Error": {
|
||
"type": "object",
|
||
"properties": {
|
||
"error": {
|
||
"type": "object",
|
||
"properties": {
|
||
"code": {
|
||
"type": "string",
|
||
"description": "Stable machine-readable error code."
|
||
},
|
||
"message": {
|
||
"type": "string",
|
||
"description": "Human-readable explanation of the error."
|
||
},
|
||
"details": {
|
||
"description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
|
||
"anyOf": [
|
||
{
|
||
"$ref": "#/components/schemas/V2ActionableForbiddenDetails"
|
||
},
|
||
{
|
||
"description": "Other structured context defined by the specific error."
|
||
}
|
||
]
|
||
},
|
||
"requestId": {
|
||
"description": "Identifier of this request, the same id as the `x-request-id` response header. Quote it when contacting support.",
|
||
"type": "string"
|
||
}
|
||
},
|
||
"required": ["code", "message"],
|
||
"additionalProperties": false,
|
||
"description": "Canonical error details."
|
||
}
|
||
},
|
||
"required": ["error"],
|
||
"additionalProperties": false,
|
||
"title": "v2 error response",
|
||
"description": "Canonical error envelope returned by the public v2 API.",
|
||
"examples": [
|
||
{
|
||
"error": {
|
||
"code": "BAD_REQUEST",
|
||
"message": "The request is invalid."
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"FolderPathInput": {
|
||
"title": "Folder path input",
|
||
"description": "Folder path. A missing leading slash is normalized before validation. Segments are percent-encoded, so a folder shown as \"New folder\" is `/New%20folder`: everything outside `A-Z a-z 0-9 - _ . ~` is escaped as uppercase hex, and only that exact encoding is accepted. A trailing slash, an empty segment, and a literal `.` or `..` segment are rejected. At most 64 segments and 4096 encoded bytes.",
|
||
"maxLength": 4096,
|
||
"type": "string"
|
||
},
|
||
"V2KnowledgeBase": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Unique knowledge base identifier.",
|
||
"examples": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"]
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"description": "Human-readable knowledge base name.",
|
||
"examples": ["Product Documentation"]
|
||
},
|
||
"description": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Knowledge base description, or null when none is set.",
|
||
"examples": ["All product documentation and guides"]
|
||
},
|
||
"tokenCount": {
|
||
"type": "number",
|
||
"description": "Total tokens across indexed documents.",
|
||
"examples": [48213]
|
||
},
|
||
"embeddingModel": {
|
||
"type": "string",
|
||
"description": "Embedding model used to index documents.",
|
||
"examples": ["text-embedding-3-small"]
|
||
},
|
||
"embeddingDimension": {
|
||
"type": "number",
|
||
"description": "Dimensionality of the embedding vectors.",
|
||
"examples": [1536]
|
||
},
|
||
"chunkingConfig": {
|
||
"$ref": "#/components/schemas/V2KnowledgeChunkingConfig"
|
||
},
|
||
"docCount": {
|
||
"description": "Number of documents in the knowledge base.",
|
||
"examples": [12],
|
||
"type": "number"
|
||
},
|
||
"connectorTypes": {
|
||
"description": "External connector types that have synced documents into the knowledge base.",
|
||
"examples": [["notion", "google_drive"]],
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
"createdAt": {
|
||
"type": "string",
|
||
"description": "ISO 8601 timestamp when the knowledge base was created.",
|
||
"format": "date-time",
|
||
"examples": ["2025-01-10T09:00:00Z"]
|
||
},
|
||
"updatedAt": {
|
||
"type": "string",
|
||
"description": "ISO 8601 timestamp when the knowledge base was last modified.",
|
||
"format": "date-time",
|
||
"examples": ["2025-06-18T16:45:00Z"]
|
||
},
|
||
"webUrl": {
|
||
"type": "string",
|
||
"format": "uri",
|
||
"description": "Canonical absolute URL for opening this resource in the Sim web application."
|
||
},
|
||
"ownerEmail": {
|
||
"type": "string",
|
||
"format": "email",
|
||
"pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
|
||
"description": "Current email address of the knowledge base owner.",
|
||
"examples": ["owner@example.com"]
|
||
},
|
||
"folderPath": {
|
||
"type": "string",
|
||
"title": "Folder path",
|
||
"description": "Canonical containing-folder path; `/` is the workspace root. Resolved against active folders only, so an archived knowledge base whose containing folder was archived with it reports `/`.",
|
||
"maxLength": 4096,
|
||
"examples": ["/Product"]
|
||
},
|
||
"deletedAt": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "ISO 8601 archive timestamp, or null while active. Use List knowledge bases with `scope=archived` to find archived knowledge bases.",
|
||
"format": "date-time",
|
||
"examples": ["2026-01-16T09:00:00Z"]
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"name",
|
||
"description",
|
||
"tokenCount",
|
||
"embeddingModel",
|
||
"embeddingDimension",
|
||
"chunkingConfig",
|
||
"createdAt",
|
||
"updatedAt",
|
||
"webUrl",
|
||
"ownerEmail",
|
||
"folderPath",
|
||
"deletedAt"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge base",
|
||
"description": "A collection of documents indexed for vector and tag search."
|
||
},
|
||
"V2KnowledgeChunkingConfig": {
|
||
"type": "object",
|
||
"properties": {
|
||
"maxSize": {
|
||
"type": "number",
|
||
"description": "Maximum chunk size in tokens.",
|
||
"examples": [1024]
|
||
},
|
||
"minSize": {
|
||
"type": "number",
|
||
"description": "Minimum chunk size in characters.",
|
||
"examples": [100]
|
||
},
|
||
"overlap": {
|
||
"type": "number",
|
||
"description": "Requested overlap in tokens between adjacent chunks.",
|
||
"examples": [200]
|
||
},
|
||
"strategy": {
|
||
"description": "Chunking strategy applied during document processing.",
|
||
"type": "string",
|
||
"enum": ["auto", "text", "regex", "recursive", "sentence", "token"]
|
||
},
|
||
"strategyOptions": {
|
||
"description": "Strategy-specific tuning options.",
|
||
"type": "object",
|
||
"properties": {
|
||
"pattern": {
|
||
"description": "Regular expression used by the regex chunking strategy.",
|
||
"type": "string",
|
||
"maxLength": 500
|
||
},
|
||
"separators": {
|
||
"description": "Ordered separators used to split content into chunks.",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
"recipe": {
|
||
"description": "Content-aware recipe used by the automatic chunking strategy.",
|
||
"type": "string",
|
||
"enum": ["plain", "markdown", "code"]
|
||
},
|
||
"strictBoundaries": {
|
||
"description": "Whether regex matches must form strict chunk boundaries.",
|
||
"type": "boolean"
|
||
}
|
||
},
|
||
"additionalProperties": false
|
||
}
|
||
},
|
||
"required": ["maxSize", "minSize", "overlap"],
|
||
"additionalProperties": {
|
||
"description": "Additional forward-compatible chunking configuration property."
|
||
},
|
||
"title": "Knowledge chunking configuration",
|
||
"description": "How documents in a knowledge base are split into chunks before embedding."
|
||
},
|
||
"V2KnowledgeBaseListResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2KnowledgeBase"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge base list response",
|
||
"description": "A cursor-paginated page of knowledge bases."
|
||
},
|
||
"V2KnowledgeBaseResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2KnowledgeBase"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge base response",
|
||
"description": "A single knowledge base."
|
||
},
|
||
"V2KnowledgeChunkingConfigInput": {
|
||
"type": "object",
|
||
"properties": {
|
||
"maxSize": {
|
||
"default": 1024,
|
||
"description": "Maximum chunk size in tokens.",
|
||
"examples": [1024],
|
||
"type": "number",
|
||
"minimum": 100,
|
||
"maximum": 4000
|
||
},
|
||
"minSize": {
|
||
"default": 100,
|
||
"description": "Minimum chunk size in characters.",
|
||
"examples": [100],
|
||
"type": "number",
|
||
"minimum": 1,
|
||
"maximum": 2000
|
||
},
|
||
"overlap": {
|
||
"default": 200,
|
||
"description": "Requested overlap in tokens between adjacent chunks.",
|
||
"examples": [200],
|
||
"type": "number",
|
||
"minimum": 0,
|
||
"maximum": 500
|
||
},
|
||
"strategy": {
|
||
"description": "Chunking strategy applied during document processing. `regex` additionally requires `strategyOptions.pattern`.",
|
||
"type": "string",
|
||
"enum": ["auto", "text", "regex", "recursive", "sentence", "token"]
|
||
},
|
||
"strategyOptions": {
|
||
"description": "Strategy-specific tuning options. `strictBoundaries` is accepted only with `strategy: \"regex\"`.",
|
||
"type": "object",
|
||
"properties": {
|
||
"pattern": {
|
||
"description": "Regular expression used by the regex chunking strategy.",
|
||
"type": "string",
|
||
"maxLength": 500
|
||
},
|
||
"separators": {
|
||
"description": "Ordered separators used to split content into chunks.",
|
||
"maxItems": 32,
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string",
|
||
"maxLength": 100
|
||
}
|
||
},
|
||
"recipe": {
|
||
"description": "Content-aware recipe used by the automatic chunking strategy.",
|
||
"type": "string",
|
||
"enum": ["plain", "markdown", "code"]
|
||
},
|
||
"strictBoundaries": {
|
||
"description": "Whether regex matches must form strict chunk boundaries.",
|
||
"type": "boolean"
|
||
}
|
||
},
|
||
"additionalProperties": false
|
||
}
|
||
},
|
||
"additionalProperties": false,
|
||
"title": "Knowledge chunking configuration input",
|
||
"description": "Chunking configuration applied when processing documents. On update this object is replaced wholesale rather than merged, so a caller preserving one key must read, modify, and write the whole object back."
|
||
},
|
||
"CreateKnowledgeBaseRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace in which to create the knowledge base."
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Human-readable knowledge base name.",
|
||
"examples": ["Product Documentation"]
|
||
},
|
||
"description": {
|
||
"description": "Optional knowledge base description.",
|
||
"examples": ["All product documentation and guides"],
|
||
"type": "string",
|
||
"maxLength": 10000
|
||
},
|
||
"chunkingConfig": {
|
||
"default": {
|
||
"maxSize": 1024,
|
||
"minSize": 100,
|
||
"overlap": 200
|
||
},
|
||
"description": "Chunking configuration; defaults are applied when omitted.",
|
||
"$ref": "#/components/schemas/V2KnowledgeChunkingConfigInput"
|
||
},
|
||
"folderPath": {
|
||
"description": "Containing folder path; omission creates the knowledge base at the root.",
|
||
"$ref": "#/components/schemas/FolderPathInput"
|
||
}
|
||
},
|
||
"required": ["workspaceId", "name"],
|
||
"additionalProperties": false,
|
||
"title": "Create knowledge base request",
|
||
"description": "Workspace, name, description, chunking configuration, and folder placement."
|
||
},
|
||
"V2KnowledgeImportFailure": {
|
||
"type": "object",
|
||
"properties": {
|
||
"filename": {
|
||
"type": "string",
|
||
"description": "Filename of the document that was not imported."
|
||
},
|
||
"message": {
|
||
"type": "string",
|
||
"description": "Why the document was not imported."
|
||
}
|
||
},
|
||
"required": ["filename", "message"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge import failure",
|
||
"description": "One bundle document the import could not bring over."
|
||
},
|
||
"V2KnowledgeImport": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Unique knowledge-base import identifier."
|
||
},
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"description": "Workspace that owns the import."
|
||
},
|
||
"status": {
|
||
"type": "string",
|
||
"enum": ["uploading", "processing", "completed", "failed", "canceled", "expired"],
|
||
"description": "Current import lifecycle state."
|
||
},
|
||
"knowledgeBaseId": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Knowledge base the import created, or null until it exists."
|
||
},
|
||
"documentsTotal": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Documents the bundle carries; zero until its manifest has been read."
|
||
},
|
||
"documentsImported": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Documents created so far. A document whose vectors could not be reused is indexed afterwards, as an upload is, so it may still be processing in the knowledge base."
|
||
},
|
||
"documentsFailed": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Documents that could not be imported. Non-zero still allows `completed`."
|
||
},
|
||
"vectorsReused": {
|
||
"type": "boolean",
|
||
"description": "Whether the bundle's vectors matched this deployment's embedding model and were stored without re-embedding."
|
||
},
|
||
"failures": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2KnowledgeImportFailure"
|
||
},
|
||
"description": "Bounded sample of the documents that could not be imported."
|
||
},
|
||
"error": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Terminal failure reason, or null."
|
||
},
|
||
"createdAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "ISO 8601 creation timestamp."
|
||
},
|
||
"updatedAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "ISO 8601 last-update timestamp."
|
||
},
|
||
"completedAt": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "ISO 8601 completion timestamp, or null."
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"workspaceId",
|
||
"status",
|
||
"knowledgeBaseId",
|
||
"documentsTotal",
|
||
"documentsImported",
|
||
"documentsFailed",
|
||
"vectorsReused",
|
||
"failures",
|
||
"error",
|
||
"createdAt",
|
||
"updatedAt",
|
||
"completedAt"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge base import",
|
||
"description": "Durable lifecycle resource for importing a knowledge base bundle."
|
||
},
|
||
"V2PutUploadTransfer": {
|
||
"type": "object",
|
||
"properties": {
|
||
"method": {
|
||
"type": "string",
|
||
"const": "put",
|
||
"description": "Upload strategy discriminator."
|
||
},
|
||
"url": {
|
||
"type": "string",
|
||
"format": "uri",
|
||
"description": "Signed URL to which the file bytes are uploaded. Upload bytes with `PUT` and exactly the supplied headers; never construct or modify the signed URL. Treat any `2xx` as success. Sim-hosted URLs return an empty `204` and v2 JSON errors. Object-storage URLs may return `200` or `201` and provider-specific errors, often XML."
|
||
},
|
||
"headers": {
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"type": "string"
|
||
},
|
||
"description": "Headers that must be included with the upload request."
|
||
},
|
||
"expiresAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "ISO 8601 expiration time for this signed URL. This is the URL's own expiry and is normally earlier than the upload session's expiresAt: the session stays open for later part, status, completion, and abort requests, but the bytes must be uploaded before this time. Once it passes, the storage provider rejects the upload and a new upload session must be created."
|
||
}
|
||
},
|
||
"required": ["method", "url", "headers", "expiresAt"],
|
||
"additionalProperties": false,
|
||
"title": "Direct upload transfer",
|
||
"description": "Instructions for uploading bytes to one signed URL."
|
||
},
|
||
"V2MultipartUploadTransfer": {
|
||
"type": "object",
|
||
"properties": {
|
||
"method": {
|
||
"type": "string",
|
||
"const": "multipart",
|
||
"description": "Upload strategy discriminator."
|
||
},
|
||
"partSize": {
|
||
"type": "integer",
|
||
"exclusiveMinimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Required size of each non-final part in bytes."
|
||
},
|
||
"partCount": {
|
||
"type": "integer",
|
||
"exclusiveMinimum": 0,
|
||
"maximum": 640,
|
||
"description": "Total number of upload parts."
|
||
}
|
||
},
|
||
"required": ["method", "partSize", "partCount"],
|
||
"additionalProperties": false,
|
||
"title": "Multipart upload transfer",
|
||
"description": "Instructions for splitting bytes into a multipart upload."
|
||
},
|
||
"V2CreateKnowledgeImportData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"session": {
|
||
"description": "Created import, waiting for its upload.",
|
||
"$ref": "#/components/schemas/V2KnowledgeImport"
|
||
},
|
||
"uploadToken": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Signed token for upload control requests."
|
||
},
|
||
"transfer": {
|
||
"oneOf": [
|
||
{
|
||
"$ref": "#/components/schemas/V2PutUploadTransfer"
|
||
},
|
||
{
|
||
"$ref": "#/components/schemas/V2MultipartUploadTransfer"
|
||
}
|
||
],
|
||
"description": "Signed bundle upload instructions."
|
||
}
|
||
},
|
||
"required": ["session", "uploadToken", "transfer"],
|
||
"additionalProperties": false,
|
||
"title": "Create knowledge base import data",
|
||
"description": "Created import and the instructions for uploading its bundle."
|
||
},
|
||
"V2CreateKnowledgeImportResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2CreateKnowledgeImportData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Create knowledge base import response",
|
||
"description": "The import and the instructions for uploading its bundle."
|
||
},
|
||
"V2KnowledgeImportSource": {
|
||
"type": "object",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"const": "upload",
|
||
"description": "Upload-backed import discriminator."
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Bundle filename, as produced by a knowledge base export."
|
||
},
|
||
"contentType": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Bundle MIME type, normally application/zip."
|
||
},
|
||
"size": {
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 5368709120,
|
||
"description": "Exact bundle size in bytes; the maximum is 5 GiB."
|
||
}
|
||
},
|
||
"required": ["type", "name", "contentType", "size"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge base import source",
|
||
"description": "Bundle archive uploaded through signed transfer instructions."
|
||
},
|
||
"CreateKnowledgeImportRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace in which to create the knowledge base."
|
||
},
|
||
"name": {
|
||
"description": "Name for the new knowledge base; defaults to the bundle's own name.",
|
||
"examples": ["Product Documentation"],
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255
|
||
},
|
||
"source": {
|
||
"$ref": "#/components/schemas/V2KnowledgeImportSource"
|
||
}
|
||
},
|
||
"required": ["workspaceId", "source"],
|
||
"additionalProperties": false,
|
||
"title": "Create knowledge base import request",
|
||
"description": "Workspace, bundle archive, and an optional name for the new knowledge base.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"name": "Product Documentation",
|
||
"source": {
|
||
"type": "upload",
|
||
"name": "product-documentation.simkb.zip",
|
||
"contentType": "application/zip",
|
||
"size": 7340032
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"V2KnowledgeImportResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2KnowledgeImport"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge base import response",
|
||
"description": "A knowledge base import lifecycle resource."
|
||
},
|
||
"V2CancelKnowledgeImportResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2KnowledgeImport"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Cancel knowledge base import response",
|
||
"description": "The canceled knowledge base import."
|
||
},
|
||
"V2UploadPartUrl": {
|
||
"type": "object",
|
||
"properties": {
|
||
"partNumber": {
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 9007199254740991,
|
||
"description": "Multipart part number."
|
||
},
|
||
"url": {
|
||
"type": "string",
|
||
"format": "uri",
|
||
"description": "Signed URL for this upload part. Upload bytes with `PUT` and exactly the supplied headers; never construct or modify the signed URL. Treat any `2xx` as success. Sim-hosted URLs return an empty `204` and v2 JSON errors. Object-storage URLs may return `200` or `201` and provider-specific errors, often XML. Do not retain part `ETag` values; after every part succeeds, call the completion endpoint without a request body."
|
||
},
|
||
"headers": {
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"type": "string"
|
||
},
|
||
"description": "Headers that must be included with the part upload."
|
||
},
|
||
"expiresAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "ISO 8601 expiration time for the signed URL."
|
||
}
|
||
},
|
||
"required": ["partNumber", "url", "headers", "expiresAt"],
|
||
"additionalProperties": false,
|
||
"title": "Upload part URL",
|
||
"description": "A signed URL and required headers for one multipart upload part."
|
||
},
|
||
"V2PartUrlsData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"parts": {
|
||
"maxItems": 100,
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2UploadPartUrl"
|
||
},
|
||
"description": "Signed URLs for requested parts."
|
||
}
|
||
},
|
||
"required": ["parts"],
|
||
"additionalProperties": false,
|
||
"title": "Upload part URLs",
|
||
"description": "Signed transfer URLs for the requested multipart upload parts."
|
||
},
|
||
"V2CreateKnowledgeImportPartUrlsResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2PartUrlsData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Create knowledge base import part URLs response",
|
||
"description": "Signed URLs and required headers for each requested upload part."
|
||
},
|
||
"CreateKnowledgeImportPartUrlsRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"partNumbers": {
|
||
"minItems": 1,
|
||
"maxItems": 100,
|
||
"type": "array",
|
||
"items": {
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 9007199254740991
|
||
},
|
||
"description": "Multipart part numbers for which signed URLs should be created."
|
||
}
|
||
},
|
||
"required": ["partNumbers"],
|
||
"additionalProperties": false,
|
||
"title": "Create knowledge base import part URLs request",
|
||
"description": "Multipart part numbers for which signed URLs should be created.",
|
||
"examples": [
|
||
{
|
||
"partNumbers": [1, 2, 3]
|
||
}
|
||
]
|
||
},
|
||
"V2CompleteKnowledgeImportResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2KnowledgeImport"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Complete knowledge base import response",
|
||
"description": "The import lifecycle resource once processing has started."
|
||
},
|
||
"UpdateKnowledgeBaseRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
},
|
||
"name": {
|
||
"description": "New knowledge base name.",
|
||
"examples": ["Updated Product Documentation"],
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255
|
||
},
|
||
"description": {
|
||
"description": "New knowledge base description.",
|
||
"examples": ["Refreshed product documentation and guides"],
|
||
"type": "string",
|
||
"maxLength": 10000
|
||
},
|
||
"chunkingConfig": {
|
||
"description": "New document chunking configuration.",
|
||
"$ref": "#/components/schemas/V2KnowledgeChunkingConfigInput"
|
||
},
|
||
"folderPath": {
|
||
"description": "New containing-folder path.",
|
||
"$ref": "#/components/schemas/FolderPathInput"
|
||
}
|
||
},
|
||
"required": ["workspaceId"],
|
||
"additionalProperties": false,
|
||
"title": "Update knowledge base request",
|
||
"description": "Workspace scope and fields to update. At least one mutable field is required."
|
||
},
|
||
"V2KnowledgeDeleteData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Identifier of the deleted resource.",
|
||
"examples": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"]
|
||
},
|
||
"deleted": {
|
||
"type": "boolean",
|
||
"const": true,
|
||
"description": "Confirms that the resource was deleted."
|
||
}
|
||
},
|
||
"required": ["id", "deleted"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge deletion data",
|
||
"description": "Acknowledgement for a deleted knowledge base or document."
|
||
},
|
||
"V2KnowledgeDeleteResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2KnowledgeDeleteData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge deletion response",
|
||
"description": "Deletion acknowledgement containing the removed resource identifier."
|
||
},
|
||
"V2KnowledgeConnector": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique connector identifier."
|
||
},
|
||
"knowledgeBaseId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Knowledge base synced by the connector."
|
||
},
|
||
"connectorType": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Registered external source type."
|
||
},
|
||
"credentialId": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "OAuth credential identifier, or the saved credential an `apiKey` source syncs with (see `auth.savedCredential`); null for unauthenticated sources and for `apiKey` sources that use an inline API key."
|
||
},
|
||
"sourceConfig": {
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"description": "Connector-specific source configuration value."
|
||
},
|
||
"description": "Connector-specific source selection and filtering configuration."
|
||
},
|
||
"syncMode": {
|
||
"type": "string",
|
||
"description": "Synchronization mode used by the connector."
|
||
},
|
||
"syncIntervalMinutes": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Scheduled synchronization interval in minutes; zero disables scheduled syncs."
|
||
},
|
||
"status": {
|
||
"type": "string",
|
||
"enum": ["active", "paused", "pending", "syncing", "error", "disabled"],
|
||
"description": "Current connector state. `pending` means a sync is queued but not yet running."
|
||
},
|
||
"lastSyncAt": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Time of the most recent synchronization, or null before the first sync."
|
||
},
|
||
"lastSyncError": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Most recent synchronization error, or null when none is recorded."
|
||
},
|
||
"lastSyncDocCount": {
|
||
"anyOf": [
|
||
{
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Documents observed by the most recent synchronization."
|
||
},
|
||
"nextSyncAt": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Next scheduled synchronization time, or null when not scheduled."
|
||
},
|
||
"consecutiveFailures": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Number of consecutive synchronization failures."
|
||
},
|
||
"createdAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "Time the connector was created."
|
||
},
|
||
"updatedAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "Time the connector was last updated."
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"knowledgeBaseId",
|
||
"connectorType",
|
||
"credentialId",
|
||
"sourceConfig",
|
||
"syncMode",
|
||
"syncIntervalMinutes",
|
||
"status",
|
||
"lastSyncAt",
|
||
"lastSyncError",
|
||
"lastSyncDocCount",
|
||
"nextSyncAt",
|
||
"consecutiveFailures",
|
||
"createdAt",
|
||
"updatedAt"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector",
|
||
"description": "An external document source linked to a knowledge base, without secret material."
|
||
},
|
||
"V2KnowledgeConnectorListResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2KnowledgeConnector"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector list response",
|
||
"description": "A cursor-paginated page of connectors without secret material.",
|
||
"examples": [
|
||
{
|
||
"data": [
|
||
{
|
||
"id": "kc-9f8e7d6c",
|
||
"knowledgeBaseId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
|
||
"connectorType": "notion",
|
||
"credentialId": "cred-4b3a2c1d",
|
||
"sourceConfig": {
|
||
"pageIds": ["page-123"]
|
||
},
|
||
"syncMode": "full",
|
||
"syncIntervalMinutes": 1440,
|
||
"status": "active",
|
||
"lastSyncAt": "2026-06-20T14:02:11.000Z",
|
||
"lastSyncError": null,
|
||
"lastSyncDocCount": 42,
|
||
"nextSyncAt": "2026-06-21T14:02:11.000Z",
|
||
"consecutiveFailures": 0,
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z"
|
||
}
|
||
],
|
||
"nextCursor": null
|
||
}
|
||
]
|
||
},
|
||
"V2KnowledgeConnectorResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2KnowledgeConnector"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector response",
|
||
"description": "A single connector without secret material.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "kc-9f8e7d6c",
|
||
"knowledgeBaseId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
|
||
"connectorType": "notion",
|
||
"credentialId": "cred-4b3a2c1d",
|
||
"sourceConfig": {
|
||
"pageIds": ["page-123"]
|
||
},
|
||
"syncMode": "full",
|
||
"syncIntervalMinutes": 1440,
|
||
"status": "active",
|
||
"lastSyncAt": "2026-06-20T14:02:11.000Z",
|
||
"lastSyncError": null,
|
||
"lastSyncDocCount": 42,
|
||
"nextSyncAt": "2026-06-21T14:02:11.000Z",
|
||
"consecutiveFailures": 0,
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z"
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"CreateKnowledgeConnectorRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
},
|
||
"connectorType": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 100,
|
||
"description": "Registered connector type."
|
||
},
|
||
"credentialId": {
|
||
"description": "OAuth credential identifier for connector types whose `auth.mode` is `oauth` (see connector types), or a saved credential for an `apiKey` connector type that declares `auth.savedCredential` (such as Amazon S3 with a saved AWS credential); otherwise omit it for `apiKey` connectors.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255
|
||
},
|
||
"apiKey": {
|
||
"description": "Write-only API key for connector types whose `auth.mode` is `apiKey` (see connector types), or a personal access token for an OAuth connector that also accepts one, such as GitHub. Send it instead of `credentialId`. Pass a raw key, or a secret reference written as the whole value `{{SECRET_NAME}}`, which the server resolves; `$SECRET_NAME` is not a reference.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 10000
|
||
},
|
||
"sourceConfig": {
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"description": "Connector-specific source configuration value."
|
||
},
|
||
"description": "Connector-specific source selection and filtering configuration."
|
||
},
|
||
"syncIntervalMinutes": {
|
||
"default": 1440,
|
||
"description": "Scheduled synchronization interval in minutes; zero disables scheduling.",
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 525600
|
||
}
|
||
},
|
||
"required": ["workspaceId", "connectorType", "sourceConfig"],
|
||
"additionalProperties": false,
|
||
"title": "Create knowledge connector request",
|
||
"description": "Workspace, connector type, authentication reference, source configuration, and sync schedule.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"connectorType": "notion",
|
||
"credentialId": "cred-4b3a2c1d",
|
||
"sourceConfig": {
|
||
"pageIds": ["page-123"]
|
||
},
|
||
"syncIntervalMinutes": 1440
|
||
}
|
||
]
|
||
},
|
||
"V2KnowledgeConnectorSyncLog": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique synchronization log identifier."
|
||
},
|
||
"connectorId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Connector that produced the log."
|
||
},
|
||
"status": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Synchronization outcome or current state."
|
||
},
|
||
"startedAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "Time synchronization started."
|
||
},
|
||
"completedAt": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Time synchronization completed, or null while it is running."
|
||
},
|
||
"docsAdded": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Documents added."
|
||
},
|
||
"docsUpdated": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Documents updated."
|
||
},
|
||
"docsDeleted": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Documents deleted."
|
||
},
|
||
"docsUnchanged": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Documents unchanged."
|
||
},
|
||
"docsSkipped": {
|
||
"default": 0,
|
||
"description": "Documents intentionally skipped because they could not be indexed safely.",
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991
|
||
},
|
||
"docsFailed": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Documents that failed to synchronize."
|
||
},
|
||
"errorMessage": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Synchronization error, or null."
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"connectorId",
|
||
"status",
|
||
"startedAt",
|
||
"completedAt",
|
||
"docsAdded",
|
||
"docsUpdated",
|
||
"docsDeleted",
|
||
"docsUnchanged",
|
||
"docsSkipped",
|
||
"docsFailed",
|
||
"errorMessage"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector sync log",
|
||
"description": "One synchronization attempt for a knowledge connector."
|
||
},
|
||
"V2KnowledgeConnectorDetail": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique connector identifier."
|
||
},
|
||
"knowledgeBaseId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Knowledge base synced by the connector."
|
||
},
|
||
"connectorType": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Registered external source type."
|
||
},
|
||
"credentialId": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "OAuth credential identifier, or the saved credential an `apiKey` source syncs with (see `auth.savedCredential`); null for unauthenticated sources and for `apiKey` sources that use an inline API key."
|
||
},
|
||
"sourceConfig": {
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"description": "Connector-specific source configuration value."
|
||
},
|
||
"description": "Connector-specific source selection and filtering configuration."
|
||
},
|
||
"syncMode": {
|
||
"type": "string",
|
||
"description": "Synchronization mode used by the connector."
|
||
},
|
||
"syncIntervalMinutes": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Scheduled synchronization interval in minutes; zero disables scheduled syncs."
|
||
},
|
||
"status": {
|
||
"type": "string",
|
||
"enum": ["active", "paused", "pending", "syncing", "error", "disabled"],
|
||
"description": "Current connector state. `pending` means a sync is queued but not yet running."
|
||
},
|
||
"lastSyncAt": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Time of the most recent synchronization, or null before the first sync."
|
||
},
|
||
"lastSyncError": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Most recent synchronization error, or null when none is recorded."
|
||
},
|
||
"lastSyncDocCount": {
|
||
"anyOf": [
|
||
{
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Documents observed by the most recent synchronization."
|
||
},
|
||
"nextSyncAt": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Next scheduled synchronization time, or null when not scheduled."
|
||
},
|
||
"consecutiveFailures": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Number of consecutive synchronization failures."
|
||
},
|
||
"createdAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "Time the connector was created."
|
||
},
|
||
"updatedAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "Time the connector was last updated."
|
||
},
|
||
"syncLogs": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2KnowledgeConnectorSyncLog"
|
||
},
|
||
"description": "The ten most recent synchronization attempts."
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"knowledgeBaseId",
|
||
"connectorType",
|
||
"credentialId",
|
||
"sourceConfig",
|
||
"syncMode",
|
||
"syncIntervalMinutes",
|
||
"status",
|
||
"lastSyncAt",
|
||
"lastSyncError",
|
||
"lastSyncDocCount",
|
||
"nextSyncAt",
|
||
"consecutiveFailures",
|
||
"createdAt",
|
||
"updatedAt",
|
||
"syncLogs"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector detail",
|
||
"description": "A knowledge connector and its recent synchronization history."
|
||
},
|
||
"V2KnowledgeConnectorDetailResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2KnowledgeConnectorDetail"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector detail response",
|
||
"description": "A connector and recent synchronization history without secret material.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "kc-9f8e7d6c",
|
||
"knowledgeBaseId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
|
||
"connectorType": "notion",
|
||
"credentialId": "cred-4b3a2c1d",
|
||
"sourceConfig": {
|
||
"pageIds": ["page-123"]
|
||
},
|
||
"syncMode": "full",
|
||
"syncIntervalMinutes": 1440,
|
||
"status": "active",
|
||
"lastSyncAt": "2026-06-20T14:02:11.000Z",
|
||
"lastSyncError": null,
|
||
"lastSyncDocCount": 42,
|
||
"nextSyncAt": "2026-06-21T14:02:11.000Z",
|
||
"consecutiveFailures": 0,
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z",
|
||
"syncLogs": []
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"UpdateKnowledgeConnectorResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2KnowledgeConnector"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Update knowledge connector response",
|
||
"description": "A single connector without secret material.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "kc-9f8e7d6c",
|
||
"knowledgeBaseId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
|
||
"connectorType": "notion",
|
||
"credentialId": "cred-4b3a2c1d",
|
||
"sourceConfig": {
|
||
"pageIds": ["page-123"]
|
||
},
|
||
"syncMode": "full",
|
||
"syncIntervalMinutes": 1440,
|
||
"status": "paused",
|
||
"lastSyncAt": "2026-06-20T14:02:11.000Z",
|
||
"lastSyncError": null,
|
||
"lastSyncDocCount": 42,
|
||
"nextSyncAt": "2026-06-21T14:02:11.000Z",
|
||
"consecutiveFailures": 0,
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:03:00.000Z"
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"UpdateKnowledgeConnectorRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
},
|
||
"sourceConfig": {
|
||
"description": "Replacement source selection and filtering configuration. Updating a runnable connector queues synchronization; paused connectors remain paused.",
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"description": "Connector-specific source configuration value."
|
||
}
|
||
},
|
||
"syncIntervalMinutes": {
|
||
"description": "New scheduled synchronization interval in minutes.",
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 525600
|
||
},
|
||
"status": {
|
||
"description": "New connector state.",
|
||
"type": "string",
|
||
"enum": ["active", "paused"]
|
||
}
|
||
},
|
||
"required": ["workspaceId"],
|
||
"additionalProperties": false,
|
||
"title": "Update knowledge connector request",
|
||
"description": "Workspace scope and at least one mutable connector field.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"status": "paused"
|
||
}
|
||
]
|
||
},
|
||
"V2KnowledgeConnectorDeleteData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Deleted connector identifier."
|
||
},
|
||
"deleted": {
|
||
"type": "boolean",
|
||
"const": true,
|
||
"description": "Whether the connector was deleted."
|
||
},
|
||
"documentsDeleted": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Connector documents deleted."
|
||
},
|
||
"documentsKept": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Connector documents retained."
|
||
}
|
||
},
|
||
"required": ["id", "deleted", "documentsDeleted", "documentsKept"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector deletion data",
|
||
"description": "Connector deletion acknowledgement and affected document counts."
|
||
},
|
||
"V2KnowledgeConnectorDeleteResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2KnowledgeConnectorDeleteData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector delete response",
|
||
"description": "Deletion acknowledgement and affected document counts.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "kc-9f8e7d6c",
|
||
"deleted": true,
|
||
"documentsDeleted": 0,
|
||
"documentsKept": 42
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"V2KnowledgeConnectorSyncData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Connector queued for synchronization."
|
||
},
|
||
"syncTriggered": {
|
||
"type": "boolean",
|
||
"const": true,
|
||
"description": "Whether synchronization was queued."
|
||
}
|
||
},
|
||
"required": ["id", "syncTriggered"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector sync data",
|
||
"description": "Acknowledgement that connector synchronization was queued."
|
||
},
|
||
"V2KnowledgeConnectorSyncResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2KnowledgeConnectorSyncData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector sync response",
|
||
"description": "Acknowledgement that synchronization was queued.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "kc-9f8e7d6c",
|
||
"syncTriggered": true
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"SyncKnowledgeConnectorRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
},
|
||
"rehydrate": {
|
||
"default": false,
|
||
"description": "Re-fetch and re-index every existing connector document.",
|
||
"type": "boolean"
|
||
}
|
||
},
|
||
"required": ["workspaceId"],
|
||
"additionalProperties": false,
|
||
"title": "Sync knowledge connector request",
|
||
"description": "Workspace scope and optional full rehydration control.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"rehydrate": false
|
||
}
|
||
]
|
||
},
|
||
"V2KnowledgeConnectorDocument": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique document identifier."
|
||
},
|
||
"filename": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Document filename."
|
||
},
|
||
"externalId": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Identifier assigned by the external source."
|
||
},
|
||
"sourceUrl": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Original external source URL."
|
||
},
|
||
"enabled": {
|
||
"type": "boolean",
|
||
"description": "Whether the document is enabled for knowledge search."
|
||
},
|
||
"userExcluded": {
|
||
"type": "boolean",
|
||
"description": "Whether a user explicitly excluded the document from connector sync results."
|
||
},
|
||
"createdAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "Time the document was first synchronized."
|
||
},
|
||
"processingStatus": {
|
||
"type": "string",
|
||
"description": "Current document processing state."
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"filename",
|
||
"externalId",
|
||
"sourceUrl",
|
||
"enabled",
|
||
"userExcluded",
|
||
"createdAt",
|
||
"processingStatus"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector document",
|
||
"description": "A knowledge document produced by an external connector."
|
||
},
|
||
"V2KnowledgeConnectorDocumentListResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2KnowledgeConnectorDocument"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector document list response",
|
||
"description": "A cursor-paginated page of connector documents.",
|
||
"examples": [
|
||
{
|
||
"data": [
|
||
{
|
||
"id": "doc-8a7b6c5d",
|
||
"filename": "Product requirements",
|
||
"externalId": "page-123",
|
||
"sourceUrl": "https://www.notion.so/page-123",
|
||
"enabled": true,
|
||
"userExcluded": false,
|
||
"createdAt": "2026-06-01T09:15:00.000Z",
|
||
"processingStatus": "completed"
|
||
}
|
||
],
|
||
"nextCursor": null
|
||
}
|
||
]
|
||
},
|
||
"V2KnowledgeConnectorDocumentsUpdateData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"operation": {
|
||
"type": "string",
|
||
"enum": ["restore", "exclude"],
|
||
"description": "Operation that was applied."
|
||
},
|
||
"updatedCount": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Documents changed."
|
||
},
|
||
"documentIds": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "Identifiers of documents changed."
|
||
}
|
||
},
|
||
"required": ["operation", "updatedCount", "documentIds"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector documents update data",
|
||
"description": "Outcome of restoring or excluding connector documents."
|
||
},
|
||
"V2KnowledgeConnectorDocumentsUpdateResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2KnowledgeConnectorDocumentsUpdateData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector documents update response",
|
||
"description": "Operation result and identifiers actually changed.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"operation": "exclude",
|
||
"updatedCount": 1,
|
||
"documentIds": ["doc-8a7b6c5d"]
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"UpdateKnowledgeConnectorDocumentsRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
},
|
||
"operation": {
|
||
"type": "string",
|
||
"enum": ["restore", "exclude"],
|
||
"description": "Whether to restore or exclude the selected documents."
|
||
},
|
||
"documentIds": {
|
||
"minItems": 1,
|
||
"maxItems": 100,
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255
|
||
},
|
||
"description": "Connector document identifiers to update."
|
||
}
|
||
},
|
||
"required": ["workspaceId", "operation", "documentIds"],
|
||
"additionalProperties": false,
|
||
"title": "Update knowledge connector documents request",
|
||
"description": "Workspace, restore or exclude operation, and selected document identifiers.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"operation": "exclude",
|
||
"documentIds": ["doc-8a7b6c5d"]
|
||
}
|
||
]
|
||
},
|
||
"V2KnowledgeSearchResult": {
|
||
"type": "object",
|
||
"properties": {
|
||
"knowledgeBaseId": {
|
||
"type": "string",
|
||
"description": "Knowledge base the matching chunk came from; a search may span up to 20.",
|
||
"examples": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"]
|
||
},
|
||
"documentId": {
|
||
"type": "string",
|
||
"description": "Identifier of the document containing the matching chunk.",
|
||
"examples": ["b2d4f8a0-1c3e-4a5b-9d7c-2e6f0a8b4c12"]
|
||
},
|
||
"documentName": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Filename of the source document, or null when unavailable.",
|
||
"examples": ["getting-started.pdf"]
|
||
},
|
||
"sourceUrl": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Original source URL, or null for a directly uploaded document."
|
||
},
|
||
"content": {
|
||
"type": "string",
|
||
"description": "Text content of the matching chunk.",
|
||
"examples": ["To reset your password, open Settings and choose Security."]
|
||
},
|
||
"chunkIndex": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Zero-based chunk index within the document.",
|
||
"examples": [3]
|
||
},
|
||
"metadata": {
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"description": "User-defined string, number, boolean, or date tag value."
|
||
},
|
||
"description": "Document tag values keyed by tag display name.",
|
||
"examples": [
|
||
{
|
||
"category": "billing",
|
||
"priority": 2
|
||
}
|
||
]
|
||
},
|
||
"similarity": {
|
||
"type": "number",
|
||
"description": "Cosine similarity between the query embedding and the chunk (1 - cosine distance), reported the same way in `vector` and `hybrid` mode; tag-only matches use 1. In `hybrid` mode results are not ordered by this value — see `rankScore`.",
|
||
"examples": [0.8423]
|
||
},
|
||
"rankScore": {
|
||
"type": "number",
|
||
"description": "The retrieval score, or reranker score when reranked. In `vector` mode it equals `similarity`; in `hybrid` mode it is the reciprocal-rank-fusion score (a sum of 1/(60 + rank) over the lexical and vector legs, so a chunk both legs ranked first scores 2/61); when a reranker ordered the results it is `rerankerScore`. Recency boosting may reorder retrieval results without changing this score; `rank` always reflects returned order.",
|
||
"examples": [0.0328]
|
||
},
|
||
"rank": {
|
||
"type": "integer",
|
||
"exclusiveMinimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "1-based position in the returned order.",
|
||
"examples": [1]
|
||
},
|
||
"rerankerScore": {
|
||
"description": "Relevance score assigned by the reranker, present only on results a reranker ordered. Results are ordered by this score when it is present, which is why it can disagree with `similarity`.",
|
||
"examples": [0.9312],
|
||
"type": "number"
|
||
}
|
||
},
|
||
"required": [
|
||
"knowledgeBaseId",
|
||
"documentId",
|
||
"documentName",
|
||
"sourceUrl",
|
||
"content",
|
||
"chunkIndex",
|
||
"metadata",
|
||
"similarity",
|
||
"rankScore",
|
||
"rank"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge search result",
|
||
"description": "A matching document chunk returned by knowledge search."
|
||
},
|
||
"V2KnowledgeSearchData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"results": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2KnowledgeSearchResult"
|
||
},
|
||
"description": "Matching chunks ordered by relevance."
|
||
},
|
||
"query": {
|
||
"type": "string",
|
||
"description": "Executed query, or an empty string for tag-only search.",
|
||
"examples": ["How do I reset my password?"]
|
||
},
|
||
"knowledgeBaseIds": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "Knowledge base identifiers that were searched.",
|
||
"examples": [["7c9e6679-7425-40de-944b-e07fc1f90ae7"]]
|
||
},
|
||
"topK": {
|
||
"type": "integer",
|
||
"exclusiveMinimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Maximum number of results requested.",
|
||
"examples": [10]
|
||
},
|
||
"totalResults": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Number of results returned.",
|
||
"examples": [4]
|
||
},
|
||
"rerankerStatus": {
|
||
"type": "string",
|
||
"enum": ["not_requested", "skipped", "unavailable", "applied"],
|
||
"description": "Reranking outcome. `applied` means results carry `rerankerScore` and follow that score. `unavailable` means reranking could not produce a usable order; the search succeeded in retrieval order without `rerankerScore`. Retry if reranking is needed. `skipped` means there was nothing to rank. `not_requested` means `rerankerEnabled` was absent or false.",
|
||
"examples": ["applied"]
|
||
}
|
||
},
|
||
"required": [
|
||
"results",
|
||
"query",
|
||
"knowledgeBaseIds",
|
||
"topK",
|
||
"totalResults",
|
||
"rerankerStatus"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge search data",
|
||
"description": "Results and execution context for a knowledge search."
|
||
},
|
||
"V2KnowledgeSearchResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2KnowledgeSearchData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge search response",
|
||
"description": "Matching chunks and search execution context."
|
||
},
|
||
"V2KnowledgeSearchTagFilter": {
|
||
"type": "object",
|
||
"properties": {
|
||
"tagName": {
|
||
"type": "string",
|
||
"description": "Display name of the tag to filter.",
|
||
"examples": ["category"]
|
||
},
|
||
"fieldType": {
|
||
"description": "Tag field type.",
|
||
"type": "string",
|
||
"enum": ["text", "number", "date", "boolean"]
|
||
},
|
||
"operator": {
|
||
"default": "eq",
|
||
"description": "Comparison operator; valid operators depend on the field type. Text tags accept eq, neq, contains, not_contains, starts_with, ends_with; number and date tags accept eq, neq, gt, gte, lt, lte, between; boolean tags accept eq, neq. An operator the tag's field type does not implement is rejected, never ignored.",
|
||
"examples": ["eq"],
|
||
"type": "string",
|
||
"enum": [
|
||
"eq",
|
||
"neq",
|
||
"contains",
|
||
"not_contains",
|
||
"starts_with",
|
||
"ends_with",
|
||
"gt",
|
||
"gte",
|
||
"lt",
|
||
"lte",
|
||
"between"
|
||
]
|
||
},
|
||
"value": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "number"
|
||
},
|
||
{
|
||
"type": "boolean"
|
||
}
|
||
],
|
||
"description": "Tag value to compare against.",
|
||
"examples": ["billing"]
|
||
},
|
||
"valueTo": {
|
||
"description": "Upper bound for the `between` operator, and required whenever that operator is used.",
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "number"
|
||
}
|
||
]
|
||
}
|
||
},
|
||
"required": ["tagName", "value"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge search tag filter",
|
||
"description": "A structured tag filter applied to knowledge search."
|
||
},
|
||
"SearchKnowledgeRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge bases."
|
||
},
|
||
"knowledgeBaseIds": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string",
|
||
"minLength": 1
|
||
},
|
||
{
|
||
"minItems": 1,
|
||
"maxItems": 20,
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
],
|
||
"description": "One knowledge base ID or an array of up to 20 IDs. Query searches require the same embedding model and dimensions across all selected bases; search incompatible bases separately. Tag-only searches do not require this.",
|
||
"examples": [["7c9e6679-7425-40de-944b-e07fc1f90ae7"]]
|
||
},
|
||
"query": {
|
||
"description": "Natural-language query; required when tag filters are omitted. At most 32768 characters — longer text exceeds the embedding model's per-input token ceiling and would be truncated before the billed search ran.",
|
||
"examples": ["How do I reset my password?"],
|
||
"type": "string",
|
||
"maxLength": 32768
|
||
},
|
||
"topK": {
|
||
"default": 10,
|
||
"description": "Maximum number of search results to return. Must be a whole number between 1 and 100.",
|
||
"type": "number",
|
||
"minimum": 1,
|
||
"maximum": 100
|
||
},
|
||
"tagFilters": {
|
||
"description": "Up to 10 filters combined with AND; repeating a tag narrows results. To express OR, run separate searches. Every tag must exist with the same slot and field type in each selected knowledge base or the request is rejected. List valid names with the knowledge-base tag-list operation.",
|
||
"maxItems": 10,
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2KnowledgeSearchTagFilter"
|
||
}
|
||
},
|
||
"searchMode": {
|
||
"description": "Retrieval strategy: `vector` uses semantic search; `hybrid` also runs full-text search. Omit to use the workspace policy.",
|
||
"anyOf": [
|
||
{
|
||
"type": "string",
|
||
"enum": ["vector", "hybrid"]
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
]
|
||
},
|
||
"rerankerEnabled": {
|
||
"description": "Reorder retrieved chunks with a reranking model before truncating to `topK`. Ignored for tag-only searches. A completed reranking call adds a search unit. If reranking is unavailable, results keep their retrieval order; check `rerankerStatus`.",
|
||
"type": "boolean"
|
||
},
|
||
"rerankerModel": {
|
||
"default": "rerank-v4.0-fast",
|
||
"description": "Reranking model to use when `rerankerEnabled` is true. Defaults to `rerank-v4.0-fast`.",
|
||
"type": "string",
|
||
"enum": ["rerank-v4.0-pro", "rerank-v4.0-fast", "rerank-v3.5"]
|
||
},
|
||
"rerankerInputCount": {
|
||
"description": "How many candidate chunks to retrieve before reranking. Defaults to four times `topK`, capped at 100. A larger pool costs more retrieval work but gives the reranker more to choose from.",
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 100
|
||
}
|
||
},
|
||
"required": ["workspaceId", "knowledgeBaseIds"],
|
||
"additionalProperties": false,
|
||
"title": "Search knowledge request",
|
||
"description": "Knowledge bases, query, result limit, retrieval mode, and optional tag filters."
|
||
},
|
||
"V2KnowledgeTag": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Tag definition ID used by Update tag and Delete tag."
|
||
},
|
||
"displayName": {
|
||
"type": "string",
|
||
"description": "Display name used by tag filters and by tag values on document reads.",
|
||
"examples": ["category"]
|
||
},
|
||
"tagSlot": {
|
||
"type": "string",
|
||
"description": "Slot used by document updates: `tag1`–`tag7`, `number1`–`number5`, `date1`–`date2`, or `boolean1`–`boolean3`. Upload creation accepts text slots; use Update document for other types.",
|
||
"examples": ["tag1"]
|
||
},
|
||
"fieldType": {
|
||
"type": "string",
|
||
"description": "Value type stored in the slot; it determines the valid filter operators.",
|
||
"examples": ["text"]
|
||
}
|
||
},
|
||
"required": ["id", "displayName", "tagSlot", "fieldType"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge tag",
|
||
"description": "A tag defined on a knowledge base, and the slot it is stored in."
|
||
},
|
||
"V2KnowledgeTagListResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2KnowledgeTag"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Always `null`. This list has no `cursor` or `limit` parameters; see the operation for inventory limits."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge tag list response",
|
||
"description": "The full tag vocabulary of one knowledge base."
|
||
},
|
||
"V2KnowledgeTaggedDocument": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Unique document identifier.",
|
||
"examples": ["b2d4f8a0-1c3e-4a5b-9d7c-2e6f0a8b4c12"]
|
||
},
|
||
"knowledgeBaseId": {
|
||
"type": "string",
|
||
"description": "Knowledge base to which the document belongs.",
|
||
"examples": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"]
|
||
},
|
||
"filename": {
|
||
"type": "string",
|
||
"description": "Original filename of the uploaded document.",
|
||
"examples": ["getting-started.pdf"]
|
||
},
|
||
"fileSize": {
|
||
"type": "number",
|
||
"description": "File size in bytes.",
|
||
"examples": [248913]
|
||
},
|
||
"mimeType": {
|
||
"type": "string",
|
||
"description": "MIME type of the document file.",
|
||
"examples": ["application/pdf"]
|
||
},
|
||
"processingStatus": {
|
||
"type": "string",
|
||
"enum": ["pending", "processing", "completed", "failed"],
|
||
"description": "Current document processing state.",
|
||
"examples": ["completed"]
|
||
},
|
||
"chunkCount": {
|
||
"type": "number",
|
||
"description": "Number of indexed chunks; zero until processing completes.",
|
||
"examples": [24]
|
||
},
|
||
"tokenCount": {
|
||
"type": "number",
|
||
"description": "Total tokens extracted from the document.",
|
||
"examples": [8123]
|
||
},
|
||
"characterCount": {
|
||
"type": "number",
|
||
"description": "Total characters extracted from the document.",
|
||
"examples": [41205]
|
||
},
|
||
"enabled": {
|
||
"type": "boolean",
|
||
"description": "Whether the document is enabled for search.",
|
||
"examples": [true]
|
||
},
|
||
"createdAt": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "ISO 8601 timestamp when the document was uploaded, or null.",
|
||
"format": "date-time",
|
||
"examples": ["2025-06-18T16:45:00Z"]
|
||
},
|
||
"tags": {
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "number"
|
||
},
|
||
{
|
||
"type": "boolean"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Tag value; dates are ISO 8601 strings and an unset tag is null."
|
||
},
|
||
"description": "Document tag values keyed by display name. Writes use slots such as `tag1`; use List tags to map names to slots.",
|
||
"examples": [
|
||
{
|
||
"category": "billing",
|
||
"priority": 2
|
||
}
|
||
]
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"knowledgeBaseId",
|
||
"filename",
|
||
"fileSize",
|
||
"mimeType",
|
||
"processingStatus",
|
||
"chunkCount",
|
||
"tokenCount",
|
||
"characterCount",
|
||
"enabled",
|
||
"createdAt",
|
||
"tags"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge document list item",
|
||
"description": "Document summary with the document tag values keyed by display name."
|
||
},
|
||
"V2KnowledgeDocumentListResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2KnowledgeTaggedDocument"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge document list response",
|
||
"description": "A cursor-paginated page of knowledge documents."
|
||
},
|
||
"V2BulkKnowledgeDocumentsData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"operation": {
|
||
"type": "string",
|
||
"enum": ["enable", "disable"],
|
||
"description": "Operation that was applied."
|
||
},
|
||
"updatedCount": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Number of documents the operation changed.",
|
||
"examples": [42]
|
||
},
|
||
"documentIds": {
|
||
"description": "Identifiers of the documents the operation changed. Present only for an explicit `documentIds` request, which is bounded to 100 documents; a `selectAll` request omits it because the selection is unbounded, and reports `updatedCount` instead.",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"required": ["operation", "updatedCount"],
|
||
"additionalProperties": false,
|
||
"title": "Bulk knowledge document update data",
|
||
"description": "Outcome of a bulk enable or disable across knowledge documents."
|
||
},
|
||
"V2BulkKnowledgeDocumentsResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2BulkKnowledgeDocumentsData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Bulk knowledge document response",
|
||
"description": "Outcome of a bulk enable or disable."
|
||
},
|
||
"BulkUpdateKnowledgeDocumentsRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
},
|
||
"operation": {
|
||
"type": "string",
|
||
"enum": ["enable", "disable"],
|
||
"description": "Whether the selected documents become enabled or disabled for search."
|
||
},
|
||
"documentIds": {
|
||
"description": "Documents to update, by identifier.",
|
||
"minItems": 1,
|
||
"maxItems": 100,
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
},
|
||
"selectAll": {
|
||
"description": "Update every document in the knowledge base instead of an explicit list, narrowed by `enabledFilter`.",
|
||
"type": "boolean",
|
||
"const": true
|
||
},
|
||
"enabledFilter": {
|
||
"description": "With `selectAll`, restrict the update to documents in this state.",
|
||
"type": "string",
|
||
"enum": ["all", "enabled", "disabled"]
|
||
}
|
||
},
|
||
"required": ["workspaceId", "operation"],
|
||
"additionalProperties": false,
|
||
"title": "Bulk knowledge document request",
|
||
"description": "Operation and the documents it applies to.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"operation": "disable",
|
||
"documentIds": ["b2d4f8a0-1c3e-4a5b-9d7c-2e6f0a8b4c12"]
|
||
}
|
||
]
|
||
},
|
||
"V2KnowledgeDocumentSummary": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Unique document identifier.",
|
||
"examples": ["b2d4f8a0-1c3e-4a5b-9d7c-2e6f0a8b4c12"]
|
||
},
|
||
"knowledgeBaseId": {
|
||
"type": "string",
|
||
"description": "Knowledge base to which the document belongs.",
|
||
"examples": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"]
|
||
},
|
||
"filename": {
|
||
"type": "string",
|
||
"description": "Original filename of the uploaded document.",
|
||
"examples": ["getting-started.pdf"]
|
||
},
|
||
"fileSize": {
|
||
"type": "number",
|
||
"description": "File size in bytes.",
|
||
"examples": [248913]
|
||
},
|
||
"mimeType": {
|
||
"type": "string",
|
||
"description": "MIME type of the document file.",
|
||
"examples": ["application/pdf"]
|
||
},
|
||
"processingStatus": {
|
||
"type": "string",
|
||
"enum": ["pending", "processing", "completed", "failed"],
|
||
"description": "Current document processing state.",
|
||
"examples": ["completed"]
|
||
},
|
||
"chunkCount": {
|
||
"type": "number",
|
||
"description": "Number of indexed chunks; zero until processing completes.",
|
||
"examples": [24]
|
||
},
|
||
"tokenCount": {
|
||
"type": "number",
|
||
"description": "Total tokens extracted from the document.",
|
||
"examples": [8123]
|
||
},
|
||
"characterCount": {
|
||
"type": "number",
|
||
"description": "Total characters extracted from the document.",
|
||
"examples": [41205]
|
||
},
|
||
"enabled": {
|
||
"type": "boolean",
|
||
"description": "Whether the document is enabled for search.",
|
||
"examples": [true]
|
||
},
|
||
"createdAt": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "ISO 8601 timestamp when the document was uploaded, or null.",
|
||
"format": "date-time",
|
||
"examples": ["2025-06-18T16:45:00Z"]
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"knowledgeBaseId",
|
||
"filename",
|
||
"fileSize",
|
||
"mimeType",
|
||
"processingStatus",
|
||
"chunkCount",
|
||
"tokenCount",
|
||
"characterCount",
|
||
"enabled",
|
||
"createdAt"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge document summary",
|
||
"description": "Summary returned by document lists and upload acknowledgements."
|
||
},
|
||
"V2KnowledgeDocumentSummaryResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2KnowledgeDocumentSummary"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge document summary response",
|
||
"description": "An accepted knowledge document summary."
|
||
},
|
||
"UploadKnowledgeDocumentForm": {
|
||
"type": "object",
|
||
"properties": {
|
||
"file": {
|
||
"type": "string",
|
||
"format": "binary",
|
||
"contentEncoding": "binary",
|
||
"maxLength": 104857600,
|
||
"description": "Document file to upload; the maximum size is 100 MiB."
|
||
}
|
||
},
|
||
"required": ["file"],
|
||
"additionalProperties": {
|
||
"description": "Additional multipart form fields are ignored."
|
||
},
|
||
"title": "Upload knowledge document form",
|
||
"description": "Multipart form containing the document file."
|
||
},
|
||
"V2KnowledgeDocumentUpload": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Upload session identifier."
|
||
},
|
||
"knowledgeBaseId": {
|
||
"type": "string",
|
||
"description": "Knowledge base that will own the document."
|
||
},
|
||
"status": {
|
||
"type": "string",
|
||
"enum": [
|
||
"uploading",
|
||
"completing",
|
||
"finalizing",
|
||
"completed",
|
||
"failed",
|
||
"aborting",
|
||
"aborted",
|
||
"expired"
|
||
],
|
||
"description": "Current upload-session state."
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"description": "Filename recorded on the knowledge document."
|
||
},
|
||
"contentType": {
|
||
"type": "string",
|
||
"description": "MIME type declared for the document."
|
||
},
|
||
"size": {
|
||
"type": "integer",
|
||
"exclusiveMinimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Exact file size in bytes."
|
||
},
|
||
"expiresAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "ISO 8601 upload-session expiration time."
|
||
},
|
||
"error": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Terminal upload error, or null when none occurred."
|
||
},
|
||
"document": {
|
||
"anyOf": [
|
||
{
|
||
"$ref": "#/components/schemas/V2KnowledgeDocumentSummary"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Queued document after completion, or null before completion."
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"knowledgeBaseId",
|
||
"status",
|
||
"name",
|
||
"contentType",
|
||
"size",
|
||
"expiresAt",
|
||
"error",
|
||
"document"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge document upload",
|
||
"description": "State of a resumable knowledge-document upload session."
|
||
},
|
||
"V2KnowledgeUploadTransfer": {
|
||
"oneOf": [
|
||
{
|
||
"$ref": "#/components/schemas/V2PutUploadTransfer"
|
||
},
|
||
{
|
||
"$ref": "#/components/schemas/V2MultipartUploadTransfer"
|
||
}
|
||
],
|
||
"description": "Provider transfer strategy for a knowledge document upload.",
|
||
"title": "Knowledge upload transfer"
|
||
},
|
||
"V2CreateKnowledgeDocumentUploadData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"session": {
|
||
"$ref": "#/components/schemas/V2KnowledgeDocumentUpload"
|
||
},
|
||
"uploadToken": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Signed control token required by subsequent upload-session requests."
|
||
},
|
||
"transfer": {
|
||
"$ref": "#/components/schemas/V2KnowledgeUploadTransfer"
|
||
}
|
||
},
|
||
"required": ["session", "uploadToken", "transfer"],
|
||
"additionalProperties": false,
|
||
"title": "Create knowledge document upload data",
|
||
"description": "Upload session, signed control token, and transfer instructions."
|
||
},
|
||
"V2CreateKnowledgeDocumentUploadResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2CreateKnowledgeDocumentUploadData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Create knowledge document upload response",
|
||
"description": "Upload session, signed control token, and transfer instructions."
|
||
},
|
||
"CreateKnowledgeDocumentUploadRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Filename recorded on the knowledge document.",
|
||
"examples": ["getting-started.pdf"]
|
||
},
|
||
"contentType": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Supported MIME type for the document.",
|
||
"examples": ["application/pdf"]
|
||
},
|
||
"size": {
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 104857600,
|
||
"description": "Exact file size in bytes.",
|
||
"examples": [248913]
|
||
},
|
||
"tag1": {
|
||
"description": "Value for tag slot 1.",
|
||
"type": "string",
|
||
"maxLength": 1000
|
||
},
|
||
"tag2": {
|
||
"description": "Value for tag slot 2.",
|
||
"type": "string",
|
||
"maxLength": 1000
|
||
},
|
||
"tag3": {
|
||
"description": "Value for tag slot 3.",
|
||
"type": "string",
|
||
"maxLength": 1000
|
||
},
|
||
"tag4": {
|
||
"description": "Value for tag slot 4.",
|
||
"type": "string",
|
||
"maxLength": 1000
|
||
},
|
||
"tag5": {
|
||
"description": "Value for tag slot 5.",
|
||
"type": "string",
|
||
"maxLength": 1000
|
||
},
|
||
"tag6": {
|
||
"description": "Value for tag slot 6.",
|
||
"type": "string",
|
||
"maxLength": 1000
|
||
},
|
||
"tag7": {
|
||
"description": "Value for tag slot 7.",
|
||
"type": "string",
|
||
"maxLength": 1000
|
||
},
|
||
"processingOptions": {
|
||
"description": "Optional processing recipe and language.",
|
||
"type": "object",
|
||
"properties": {
|
||
"recipe": {
|
||
"description": "Optional document processing recipe. One of: default, plain, markdown, code.",
|
||
"type": "string",
|
||
"enum": ["default", "plain", "markdown", "code"]
|
||
},
|
||
"lang": {
|
||
"description": "Optional document language: hyphen-separated letter and digit subtags such as `en`, `en-US`, or `zh-Hant-TW`. Only that shape is validated, not full BCP-47 conformance.",
|
||
"type": "string",
|
||
"maxLength": 35,
|
||
"pattern": "^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$"
|
||
}
|
||
},
|
||
"additionalProperties": false
|
||
}
|
||
},
|
||
"required": ["workspaceId", "name", "contentType", "size"],
|
||
"additionalProperties": false,
|
||
"title": "Create knowledge document upload request",
|
||
"description": "Document metadata used to authorize and initialize the upload.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"name": "getting-started.pdf",
|
||
"contentType": "application/pdf",
|
||
"size": 248913
|
||
}
|
||
]
|
||
},
|
||
"V2KnowledgeDocumentUploadResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2KnowledgeDocumentUpload"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge document upload response",
|
||
"description": "Current state of a knowledge document upload session."
|
||
},
|
||
"V2KnowledgeDocumentUploadPartUrlsResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2PartUrlsData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge document upload part URLs response",
|
||
"description": "Signed provider URLs for requested multipart parts."
|
||
},
|
||
"CreateKnowledgeDocumentUploadPartUrlsRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"partNumbers": {
|
||
"minItems": 1,
|
||
"maxItems": 100,
|
||
"type": "array",
|
||
"items": {
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 9007199254740991
|
||
},
|
||
"description": "Multipart part numbers for which signed URLs should be created."
|
||
}
|
||
},
|
||
"required": ["partNumbers"],
|
||
"additionalProperties": false,
|
||
"title": "Create upload part URLs request",
|
||
"description": "Multipart part numbers for which signed URLs should be created.",
|
||
"examples": [
|
||
{
|
||
"partNumbers": [1, 2, 3]
|
||
}
|
||
]
|
||
},
|
||
"V2KnowledgeDocument": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Unique document identifier.",
|
||
"examples": ["b2d4f8a0-1c3e-4a5b-9d7c-2e6f0a8b4c12"]
|
||
},
|
||
"knowledgeBaseId": {
|
||
"type": "string",
|
||
"description": "Knowledge base to which the document belongs.",
|
||
"examples": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"]
|
||
},
|
||
"filename": {
|
||
"type": "string",
|
||
"description": "Original filename of the uploaded document.",
|
||
"examples": ["getting-started.pdf"]
|
||
},
|
||
"fileSize": {
|
||
"type": "number",
|
||
"description": "File size in bytes.",
|
||
"examples": [248913]
|
||
},
|
||
"mimeType": {
|
||
"type": "string",
|
||
"description": "MIME type of the document file.",
|
||
"examples": ["application/pdf"]
|
||
},
|
||
"processingStatus": {
|
||
"type": "string",
|
||
"enum": ["pending", "processing", "completed", "failed"],
|
||
"description": "Current document processing state.",
|
||
"examples": ["completed"]
|
||
},
|
||
"chunkCount": {
|
||
"type": "number",
|
||
"description": "Number of indexed chunks; zero until processing completes.",
|
||
"examples": [24]
|
||
},
|
||
"tokenCount": {
|
||
"type": "number",
|
||
"description": "Total tokens extracted from the document.",
|
||
"examples": [8123]
|
||
},
|
||
"characterCount": {
|
||
"type": "number",
|
||
"description": "Total characters extracted from the document.",
|
||
"examples": [41205]
|
||
},
|
||
"enabled": {
|
||
"type": "boolean",
|
||
"description": "Whether the document is enabled for search.",
|
||
"examples": [true]
|
||
},
|
||
"createdAt": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "ISO 8601 timestamp when the document was uploaded, or null.",
|
||
"format": "date-time",
|
||
"examples": ["2025-06-18T16:45:00Z"]
|
||
},
|
||
"tags": {
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "number"
|
||
},
|
||
{
|
||
"type": "boolean"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Tag value; dates are ISO 8601 strings and an unset tag is null."
|
||
},
|
||
"description": "Document tag values keyed by display name. Writes use slots such as `tag1`; use List tags to map names to slots.",
|
||
"examples": [
|
||
{
|
||
"category": "billing",
|
||
"priority": 2
|
||
}
|
||
]
|
||
},
|
||
"processingError": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Processing error message, or null when processing has not failed."
|
||
},
|
||
"processingStartedAt": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "ISO 8601 timestamp when processing started, or null.",
|
||
"format": "date-time",
|
||
"examples": ["2025-06-18T16:45:05Z"]
|
||
},
|
||
"processingCompletedAt": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "ISO 8601 timestamp when processing completed, or null.",
|
||
"format": "date-time",
|
||
"examples": ["2025-06-18T16:45:42Z"]
|
||
},
|
||
"connectorId": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Connector identifier for a synced document, or null for a direct upload."
|
||
},
|
||
"connectorType": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Connector type for a synced document, or null for a direct upload."
|
||
},
|
||
"sourceUrl": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Original source URL for a synced document, or null for a direct upload."
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"knowledgeBaseId",
|
||
"filename",
|
||
"fileSize",
|
||
"mimeType",
|
||
"processingStatus",
|
||
"chunkCount",
|
||
"tokenCount",
|
||
"characterCount",
|
||
"enabled",
|
||
"createdAt",
|
||
"tags",
|
||
"processingError",
|
||
"processingStartedAt",
|
||
"processingCompletedAt",
|
||
"connectorId",
|
||
"connectorType",
|
||
"sourceUrl"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge document",
|
||
"description": "Full document detail including processing state and connector provenance."
|
||
},
|
||
"V2KnowledgeDocumentResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2KnowledgeDocument"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge document response",
|
||
"description": "Full knowledge document detail."
|
||
},
|
||
"V2KnowledgeDocumentProcessing": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Identifier of the requeued document."
|
||
},
|
||
"queued": {
|
||
"type": "boolean",
|
||
"const": true,
|
||
"description": "Confirms that processing was requeued."
|
||
},
|
||
"processingStatus": {
|
||
"type": "string",
|
||
"description": "Processing state the document was moved to.",
|
||
"examples": ["pending"]
|
||
},
|
||
"message": {
|
||
"type": "string",
|
||
"description": "Human-readable outcome of the requeue."
|
||
}
|
||
},
|
||
"required": ["id", "queued", "processingStatus", "message"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge document processing acknowledgement",
|
||
"description": "Acknowledgement returned when a document is requeued for processing."
|
||
},
|
||
"V2UpdateKnowledgeDocumentResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"anyOf": [
|
||
{
|
||
"$ref": "#/components/schemas/V2KnowledgeTaggedDocument"
|
||
},
|
||
{
|
||
"$ref": "#/components/schemas/V2KnowledgeDocumentProcessing"
|
||
}
|
||
],
|
||
"description": "Response data."
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Update knowledge document response",
|
||
"description": "The updated document, or the processing requeue acknowledgement."
|
||
},
|
||
"UpdateKnowledgeDocumentRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
},
|
||
"filename": {
|
||
"description": "New filename for the document.",
|
||
"examples": ["getting-started-v2.pdf"],
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255
|
||
},
|
||
"enabled": {
|
||
"description": "Whether the document participates in search. Disabling keeps it indexed.",
|
||
"type": "boolean"
|
||
},
|
||
"tag1": {
|
||
"description": "New value for tag slot 1.",
|
||
"type": "string",
|
||
"maxLength": 1000
|
||
},
|
||
"tag2": {
|
||
"description": "New value for tag slot 2.",
|
||
"type": "string",
|
||
"maxLength": 1000
|
||
},
|
||
"tag3": {
|
||
"description": "New value for tag slot 3.",
|
||
"type": "string",
|
||
"maxLength": 1000
|
||
},
|
||
"tag4": {
|
||
"description": "New value for tag slot 4.",
|
||
"type": "string",
|
||
"maxLength": 1000
|
||
},
|
||
"tag5": {
|
||
"description": "New value for tag slot 5.",
|
||
"type": "string",
|
||
"maxLength": 1000
|
||
},
|
||
"tag6": {
|
||
"description": "New value for tag slot 6.",
|
||
"type": "string",
|
||
"maxLength": 1000
|
||
},
|
||
"tag7": {
|
||
"description": "New value for tag slot 7.",
|
||
"type": "string",
|
||
"maxLength": 1000
|
||
},
|
||
"number1": {
|
||
"description": "New value for number tag slot 1.",
|
||
"type": "number"
|
||
},
|
||
"number2": {
|
||
"description": "New value for number tag slot 2.",
|
||
"type": "number"
|
||
},
|
||
"number3": {
|
||
"description": "New value for number tag slot 3.",
|
||
"type": "number"
|
||
},
|
||
"number4": {
|
||
"description": "New value for number tag slot 4.",
|
||
"type": "number"
|
||
},
|
||
"number5": {
|
||
"description": "New value for number tag slot 5.",
|
||
"type": "number"
|
||
},
|
||
"date1": {
|
||
"description": "New value for date tag slot 1, formatted YYYY-MM-DD.",
|
||
"type": "string",
|
||
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
|
||
},
|
||
"date2": {
|
||
"description": "New value for date tag slot 2, formatted YYYY-MM-DD.",
|
||
"type": "string",
|
||
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
|
||
},
|
||
"boolean1": {
|
||
"description": "New value for boolean tag slot 1.",
|
||
"type": "boolean"
|
||
},
|
||
"boolean2": {
|
||
"description": "New value for boolean tag slot 2.",
|
||
"type": "boolean"
|
||
},
|
||
"boolean3": {
|
||
"description": "New value for boolean tag slot 3.",
|
||
"type": "boolean"
|
||
},
|
||
"retryProcessing": {
|
||
"description": "Requeue a failed or stuck document for processing. Send it alone — no other field may accompany it — and it answers with a queue acknowledgement rather than the document.",
|
||
"type": "boolean",
|
||
"const": true
|
||
}
|
||
},
|
||
"required": ["workspaceId"],
|
||
"additionalProperties": false,
|
||
"title": "Update knowledge document request",
|
||
"description": "Filename, search state, tag slot values, or a processing retry.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"enabled": false,
|
||
"tag1": "billing"
|
||
}
|
||
]
|
||
},
|
||
"V2Folder": {
|
||
"type": "object",
|
||
"properties": {
|
||
"name": {
|
||
"type": "string",
|
||
"description": "Folder name."
|
||
},
|
||
"path": {
|
||
"type": "string",
|
||
"title": "Non-root folder path",
|
||
"description": "Canonical folder path used as the public folder identifier.",
|
||
"maxLength": 4096
|
||
},
|
||
"parentPath": {
|
||
"type": "string",
|
||
"title": "Folder path",
|
||
"description": "Canonical parent path; `/` is the root.",
|
||
"maxLength": 4096
|
||
},
|
||
"createdAt": {
|
||
"type": "string",
|
||
"description": "ISO 8601 timestamp when the folder was created.",
|
||
"format": "date-time"
|
||
},
|
||
"updatedAt": {
|
||
"type": "string",
|
||
"description": "ISO 8601 timestamp when the folder was last updated.",
|
||
"format": "date-time"
|
||
}
|
||
},
|
||
"required": ["name", "path", "parentPath", "createdAt", "updatedAt"],
|
||
"additionalProperties": false,
|
||
"title": "Folder",
|
||
"description": "A canonical workspace folder."
|
||
},
|
||
"V2KnowledgeFolderListResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2Folder"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Always `null`. This list has no `cursor` or `limit` parameters; see the operation for inventory limits."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge folder list response",
|
||
"description": "The whole bounded set of knowledge-base folders, in one page."
|
||
},
|
||
"V2KnowledgeFolderResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2Folder"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge folder response",
|
||
"description": "A single knowledge-base folder."
|
||
},
|
||
"NonRootFolderPathInput": {
|
||
"title": "Non-root folder path input",
|
||
"description": "Non-root folder path. A missing leading slash is normalized before validation. Segments are percent-encoded, so a folder shown as \"New folder\" is `/New%20folder`: everything outside `A-Z a-z 0-9 - _ . ~` is escaped as uppercase hex, and only that exact encoding is accepted. A trailing slash, an empty segment, and a literal `.` or `..` segment are rejected. At most 64 segments and 4096 encoded bytes.",
|
||
"maxLength": 4096,
|
||
"type": "string"
|
||
},
|
||
"CreateKnowledgeFolderRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace in which to create the folder."
|
||
},
|
||
"path": {
|
||
"description": "Path of the folder to create.",
|
||
"$ref": "#/components/schemas/NonRootFolderPathInput"
|
||
}
|
||
},
|
||
"required": ["workspaceId", "path"],
|
||
"additionalProperties": false,
|
||
"title": "Create knowledge folder request",
|
||
"description": "Workspace and canonical path for a new knowledge-base folder."
|
||
},
|
||
"RelocateKnowledgeFolderRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace containing the folder."
|
||
},
|
||
"path": {
|
||
"description": "Current folder path.",
|
||
"$ref": "#/components/schemas/NonRootFolderPathInput"
|
||
},
|
||
"destinationPath": {
|
||
"description": "Where the folder lands, with `mv` semantics. A path naming an existing folder receives the source as a child under its current name; `/` moves it to the workspace root under its current name; any other path becomes the folder’s new full path (a rename, a relocation, or both).",
|
||
"$ref": "#/components/schemas/FolderPathInput"
|
||
}
|
||
},
|
||
"required": ["workspaceId", "path", "destinationPath"],
|
||
"additionalProperties": false,
|
||
"title": "Relocate knowledge folder request",
|
||
"description": "Current and destination canonical paths for a knowledge-base folder."
|
||
},
|
||
"V2DeleteKnowledgeFolderData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"path": {
|
||
"type": "string",
|
||
"title": "Folder path",
|
||
"description": "Canonical path of the deleted folder.",
|
||
"maxLength": 4096
|
||
},
|
||
"deleted": {
|
||
"type": "boolean",
|
||
"const": true,
|
||
"description": "Confirms that the folder was deleted."
|
||
},
|
||
"deletedItems": {
|
||
"type": "object",
|
||
"properties": {
|
||
"folders": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Number of deleted folders."
|
||
},
|
||
"knowledgeBases": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Number of deleted knowledge bases."
|
||
}
|
||
},
|
||
"required": ["folders", "knowledgeBases"],
|
||
"additionalProperties": false,
|
||
"description": "Counts of deleted resources."
|
||
}
|
||
},
|
||
"required": ["path", "deleted", "deletedItems"],
|
||
"additionalProperties": false,
|
||
"title": "Delete knowledge folder data",
|
||
"description": "Folder deletion acknowledgement and deleted-resource counts."
|
||
},
|
||
"V2DeleteKnowledgeFolderResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2DeleteKnowledgeFolderData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Delete knowledge folder response",
|
||
"description": "Folder deletion acknowledgement and deleted-resource counts."
|
||
},
|
||
"RestoreKnowledgeBaseRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
},
|
||
"required": ["workspaceId"],
|
||
"additionalProperties": false,
|
||
"title": "Restore knowledge base request",
|
||
"description": "Workspace scope for the knowledge base.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64"
|
||
}
|
||
]
|
||
},
|
||
"V2AddedWorkspaceFileDocument": {
|
||
"type": "object",
|
||
"properties": {
|
||
"documentId": {
|
||
"type": "string",
|
||
"description": "Identifier of the queued knowledge document."
|
||
},
|
||
"filename": {
|
||
"type": "string",
|
||
"description": "Filename recorded on the knowledge document."
|
||
},
|
||
"mimeType": {
|
||
"type": "string",
|
||
"description": "MIME type of the source workspace file."
|
||
},
|
||
"fileSize": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "File size in bytes."
|
||
}
|
||
},
|
||
"required": ["documentId", "filename", "mimeType", "fileSize"],
|
||
"additionalProperties": false,
|
||
"title": "Indexed workspace file",
|
||
"description": "A workspace file that was queued for indexing into a knowledge base."
|
||
},
|
||
"V2AddWorkspaceFilesToKnowledgeBaseData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"knowledgeBaseId": {
|
||
"type": "string",
|
||
"description": "Knowledge base the files were added to."
|
||
},
|
||
"added": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2AddedWorkspaceFileDocument"
|
||
},
|
||
"description": "Files queued for indexing, in request order."
|
||
},
|
||
"failed": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "References that could not be indexed, echoed exactly as they were sent."
|
||
}
|
||
},
|
||
"required": ["knowledgeBaseId", "added", "failed"],
|
||
"additionalProperties": false,
|
||
"title": "Add workspace files data",
|
||
"description": "Outcome of indexing workspace files into a knowledge base."
|
||
},
|
||
"V2AddWorkspaceFilesToKnowledgeBaseResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2AddWorkspaceFilesToKnowledgeBaseData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Index workspace files response",
|
||
"description": "Documents queued for indexing and references that could not be."
|
||
},
|
||
"AddWorkspaceFilesToKnowledgeBaseRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns both the files and the base."
|
||
},
|
||
"fileReferences": {
|
||
"minItems": 1,
|
||
"maxItems": 100,
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
},
|
||
"description": "Workspace file IDs or paths to index. Prefer IDs or canonical `files/<folder>/<name>` paths. Duplicates resolving to the same file are indexed once."
|
||
}
|
||
},
|
||
"required": ["workspaceId", "fileReferences"],
|
||
"additionalProperties": false,
|
||
"title": "Index workspace files request",
|
||
"description": "Workspace scope and the workspace file references to index.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"fileReferences": ["handbook.pdf"]
|
||
}
|
||
]
|
||
},
|
||
"V2KnowledgeChunk": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Unique chunk identifier.",
|
||
"examples": ["4c1f9e77-2b3a-4f8d-9e10-6a2c8d4b1e05"]
|
||
},
|
||
"chunkIndex": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Zero-based position of the chunk within its document.",
|
||
"examples": [3]
|
||
},
|
||
"content": {
|
||
"type": "string",
|
||
"description": "Text content of the chunk, exactly as it was embedded.",
|
||
"examples": ["To reset your password, open Settings and choose Security."]
|
||
},
|
||
"contentLength": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Character count of `content`.",
|
||
"examples": [58]
|
||
},
|
||
"tokenCount": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Tokens the chunk consumed when embedded.",
|
||
"examples": [14]
|
||
},
|
||
"enabled": {
|
||
"type": "boolean",
|
||
"description": "Whether the chunk participates in search. A disabled chunk stays indexed."
|
||
},
|
||
"startOffset": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Character offset of the chunk within the extracted document text."
|
||
},
|
||
"endOffset": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Character offset just past the end of the chunk."
|
||
},
|
||
"tag1": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Text tag value inherited from the document, or null when the slot is unset."
|
||
},
|
||
"tag2": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Text tag value inherited from the document, or null when the slot is unset."
|
||
},
|
||
"tag3": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Text tag value inherited from the document, or null when the slot is unset."
|
||
},
|
||
"tag4": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Text tag value inherited from the document, or null when the slot is unset."
|
||
},
|
||
"tag5": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Text tag value inherited from the document, or null when the slot is unset."
|
||
},
|
||
"tag6": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Text tag value inherited from the document, or null when the slot is unset."
|
||
},
|
||
"tag7": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Text tag value inherited from the document, or null when the slot is unset."
|
||
},
|
||
"createdAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "ISO 8601 timestamp when the chunk was created."
|
||
},
|
||
"updatedAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "ISO 8601 timestamp when the chunk was last modified."
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"chunkIndex",
|
||
"content",
|
||
"contentLength",
|
||
"tokenCount",
|
||
"enabled",
|
||
"startOffset",
|
||
"endOffset",
|
||
"tag1",
|
||
"tag2",
|
||
"tag3",
|
||
"tag4",
|
||
"tag5",
|
||
"tag6",
|
||
"tag7",
|
||
"createdAt",
|
||
"updatedAt"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge chunk",
|
||
"description": "One embedded passage of a knowledge document."
|
||
},
|
||
"V2KnowledgeChunkListResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2KnowledgeChunk"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge chunk list response",
|
||
"description": "A cursor-paginated page of document chunks."
|
||
},
|
||
"V2KnowledgeChunkResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2KnowledgeChunk"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge chunk response",
|
||
"description": "A single document chunk."
|
||
},
|
||
"CreateKnowledgeChunkRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
},
|
||
"content": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 10000,
|
||
"description": "Text embedded before the response. Search includes it when the chunk and document are enabled and the document has completed processing."
|
||
},
|
||
"enabled": {
|
||
"default": true,
|
||
"description": "Whether the new chunk participates in search.",
|
||
"type": "boolean"
|
||
}
|
||
},
|
||
"required": ["workspaceId", "content"],
|
||
"additionalProperties": false,
|
||
"title": "Create knowledge chunk request",
|
||
"description": "Workspace scope and the text to embed.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"content": "To reset your password, open Settings and choose Security."
|
||
}
|
||
]
|
||
},
|
||
"V2BulkKnowledgeChunksData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"operation": {
|
||
"type": "string",
|
||
"enum": ["enable", "disable", "delete"],
|
||
"description": "Operation that was applied."
|
||
},
|
||
"processed": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Number of chunks in this document the operation matched. Chunks already in the requested state are counted too, so this is not a count of changes.",
|
||
"examples": [12]
|
||
},
|
||
"errors": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "Per-chunk failures, including any identifier that named no chunk in the document. A populated array still answers 200."
|
||
}
|
||
},
|
||
"required": ["operation", "processed", "errors"],
|
||
"additionalProperties": false,
|
||
"title": "Bulk knowledge chunk update data",
|
||
"description": "Outcome of a bulk enable, disable, or delete across knowledge chunks."
|
||
},
|
||
"V2BulkKnowledgeChunksResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2BulkKnowledgeChunksData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Bulk knowledge chunk response",
|
||
"description": "Counts and per-chunk failures from a bulk chunk operation."
|
||
},
|
||
"BulkUpdateKnowledgeChunksRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
},
|
||
"operation": {
|
||
"type": "string",
|
||
"enum": ["enable", "disable", "delete"],
|
||
"description": "What to do with the selected chunks."
|
||
},
|
||
"chunkIds": {
|
||
"minItems": 1,
|
||
"maxItems": 100,
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
},
|
||
"description": "Chunks to operate on, by identifier. An id naming no chunk in the document is reported in errors and does not fail the request."
|
||
}
|
||
},
|
||
"required": ["workspaceId", "operation", "chunkIds"],
|
||
"additionalProperties": false,
|
||
"title": "Bulk knowledge chunk request",
|
||
"description": "Workspace scope, the operation to apply, and the chunks to apply it to.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"operation": "disable",
|
||
"chunkIds": ["4c1f9e77-2b3a-4f8d-9e10-6a2c8d4b1e05"]
|
||
}
|
||
]
|
||
},
|
||
"UpdateKnowledgeChunkRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
},
|
||
"content": {
|
||
"description": "Replacement text. Changing it re-embeds the chunk and re-derives its token and character counts.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 10000
|
||
},
|
||
"enabled": {
|
||
"description": "Whether the chunk participates in search. Disabling keeps it indexed.",
|
||
"type": "boolean"
|
||
}
|
||
},
|
||
"required": ["workspaceId"],
|
||
"additionalProperties": false,
|
||
"title": "Update knowledge chunk request",
|
||
"description": "Workspace scope and the fields to update. At least one is required.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"enabled": false
|
||
}
|
||
]
|
||
},
|
||
"V2KnowledgeTagResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2KnowledgeTag"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge tag response",
|
||
"description": "A single tag definition."
|
||
},
|
||
"CreateKnowledgeTagRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
},
|
||
"displayName": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 100,
|
||
"description": "Name tag filters and document reads use for this tag.",
|
||
"examples": ["category"]
|
||
},
|
||
"fieldType": {
|
||
"default": "text",
|
||
"type": "string",
|
||
"enum": ["text", "number", "date", "boolean"],
|
||
"description": "Value type stored in the slot; it decides which slots are usable and which filter operators apply. Slot capacity per type: text 7, number 5, date 2, boolean 3.",
|
||
"examples": ["text"]
|
||
},
|
||
"tagSlot": {
|
||
"description": "Slot to store the tag in. Omit to take the next free slot for the field type; a slot that does not belong to the field type, or one already in use, is rejected.",
|
||
"type": "string",
|
||
"enum": [
|
||
"tag1",
|
||
"tag2",
|
||
"tag3",
|
||
"tag4",
|
||
"tag5",
|
||
"tag6",
|
||
"tag7",
|
||
"number1",
|
||
"number2",
|
||
"number3",
|
||
"number4",
|
||
"number5",
|
||
"date1",
|
||
"date2",
|
||
"boolean1",
|
||
"boolean2",
|
||
"boolean3"
|
||
],
|
||
"examples": ["tag1"]
|
||
}
|
||
},
|
||
"required": ["workspaceId", "displayName"],
|
||
"additionalProperties": false,
|
||
"title": "Create knowledge tag request",
|
||
"description": "Workspace scope, display name, field type, and optional slot.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"displayName": "category",
|
||
"fieldType": "text"
|
||
}
|
||
]
|
||
},
|
||
"UpdateKnowledgeTagRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
},
|
||
"displayName": {
|
||
"description": "New tag display name.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 100,
|
||
"examples": ["category"]
|
||
},
|
||
"fieldType": {
|
||
"description": "New value type for the tag.",
|
||
"type": "string",
|
||
"enum": ["text", "number", "date", "boolean"],
|
||
"examples": ["text"]
|
||
}
|
||
},
|
||
"required": ["workspaceId"],
|
||
"additionalProperties": false,
|
||
"title": "Update knowledge tag request",
|
||
"description": "Workspace scope and the fields to update. At least one is required.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"displayName": "topic"
|
||
}
|
||
]
|
||
},
|
||
"V2DeleteKnowledgeTagData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Identifier of the deleted tag definition."
|
||
},
|
||
"tagSlot": {
|
||
"type": "string",
|
||
"description": "Slot the deleted tag occupied; its values are now cleared."
|
||
},
|
||
"displayName": {
|
||
"type": "string",
|
||
"description": "Display name the deleted tag carried."
|
||
},
|
||
"deleted": {
|
||
"type": "boolean",
|
||
"const": true,
|
||
"description": "Confirms that the tag definition was deleted."
|
||
}
|
||
},
|
||
"required": ["id", "tagSlot", "displayName", "deleted"],
|
||
"additionalProperties": false,
|
||
"title": "Delete knowledge tag data",
|
||
"description": "Acknowledgement for a deleted tag definition."
|
||
},
|
||
"V2DeleteKnowledgeTagResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2DeleteKnowledgeTagData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Delete knowledge tag response",
|
||
"description": "Acknowledgement naming the deleted definition and the slot it freed."
|
||
},
|
||
"V2NextKnowledgeTagSlotData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"nextAvailableSlot": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "The free slot a create would take, or null when the field type is exhausted.",
|
||
"examples": ["tag3"]
|
||
},
|
||
"fieldType": {
|
||
"type": "string",
|
||
"description": "Field type the slots were counted for."
|
||
},
|
||
"usedSlots": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "Slots of this field type already holding a tag."
|
||
},
|
||
"totalSlots": {
|
||
"type": "integer",
|
||
"exclusiveMinimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Total slots this field type has: 7 for text, 5 for number, 2 for date, 3 for boolean."
|
||
},
|
||
"availableSlots": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Slots of this field type still free, or 0 when the field type is exhausted."
|
||
}
|
||
},
|
||
"required": ["nextAvailableSlot", "fieldType", "usedSlots", "totalSlots", "availableSlots"],
|
||
"additionalProperties": false,
|
||
"title": "Next knowledge tag slot",
|
||
"description": "Slot availability for one tag field type."
|
||
},
|
||
"V2NextKnowledgeTagSlotResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2NextKnowledgeTagSlotData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Next knowledge tag slot response",
|
||
"description": "Slot availability for one tag field type."
|
||
},
|
||
"V2KnowledgeTagUsage": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Tag definition ID used by Update Tag and Delete Tag.",
|
||
"examples": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"]
|
||
},
|
||
"tagSlot": {
|
||
"type": "string",
|
||
"description": "Slot the tag occupies.",
|
||
"examples": ["tag1"]
|
||
},
|
||
"displayName": {
|
||
"type": "string",
|
||
"description": "Tag display name.",
|
||
"examples": ["category"]
|
||
},
|
||
"fieldType": {
|
||
"type": "string",
|
||
"description": "Value type stored in the slot.",
|
||
"examples": ["text"]
|
||
},
|
||
"documentCount": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Documents in the knowledge base carrying a value in this slot."
|
||
},
|
||
"chunkCount": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Indexed chunks carrying a value in this slot."
|
||
}
|
||
},
|
||
"required": ["id", "tagSlot", "displayName", "fieldType", "documentCount", "chunkCount"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge tag usage",
|
||
"description": "How widely one tag is populated across a knowledge base."
|
||
},
|
||
"V2KnowledgeTagUsageListResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2KnowledgeTagUsage"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Always `null`. This list has no `cursor` or `limit` parameters; see the operation for inventory limits."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge tag usage response",
|
||
"description": "Usage counts for every tag defined on one knowledge base."
|
||
},
|
||
"V2BulkSaveKnowledgeTagDefinitionsData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"created": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2KnowledgeTag"
|
||
},
|
||
"description": "Definitions that did not previously exist."
|
||
},
|
||
"updated": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2KnowledgeTag"
|
||
},
|
||
"description": "Definitions whose slot was already defined."
|
||
},
|
||
"errors": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "Per-definition failures. A populated array still answers 200."
|
||
}
|
||
},
|
||
"required": ["created", "updated", "errors"],
|
||
"additionalProperties": false,
|
||
"title": "Bulk save knowledge tag definitions data",
|
||
"description": "Definitions created and updated by a bulk tag-definition save."
|
||
},
|
||
"V2BulkSaveKnowledgeTagDefinitionsResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2BulkSaveKnowledgeTagDefinitionsData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Bulk save tag definitions response",
|
||
"description": "Definitions created and updated, with any per-definition failures."
|
||
},
|
||
"V2BulkSaveKnowledgeTagDefinition": {
|
||
"type": "object",
|
||
"properties": {
|
||
"tagSlot": {
|
||
"type": "string",
|
||
"enum": [
|
||
"tag1",
|
||
"tag2",
|
||
"tag3",
|
||
"tag4",
|
||
"tag5",
|
||
"tag6",
|
||
"tag7",
|
||
"number1",
|
||
"number2",
|
||
"number3",
|
||
"number4",
|
||
"number5",
|
||
"date1",
|
||
"date2",
|
||
"boolean1",
|
||
"boolean2",
|
||
"boolean3"
|
||
],
|
||
"description": "Storage slot the tag occupies. It must belong to the tag’s `fieldType`.",
|
||
"examples": ["tag1"]
|
||
},
|
||
"displayName": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 100,
|
||
"description": "Name tag filters and document reads use for this tag.",
|
||
"examples": ["category"]
|
||
},
|
||
"fieldType": {
|
||
"type": "string",
|
||
"enum": ["text", "number", "date", "boolean"],
|
||
"description": "Value type stored in the slot; it decides which slots are usable and which filter operators apply. Slot capacity per type: text 7, number 5, date 2, boolean 3.",
|
||
"examples": ["text"]
|
||
},
|
||
"originalDisplayName": {
|
||
"description": "Previous display name, when this entry renames an existing definition.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 100,
|
||
"examples": ["category"]
|
||
}
|
||
},
|
||
"required": ["tagSlot", "displayName", "fieldType"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge tag definition input",
|
||
"description": "One tag definition declared in a bulk save."
|
||
},
|
||
"BulkSaveKnowledgeTagDefinitionsRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
},
|
||
"definitions": {
|
||
"minItems": 1,
|
||
"maxItems": 17,
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2BulkSaveKnowledgeTagDefinition"
|
||
},
|
||
"description": "Tag definitions to create or update on the knowledge base."
|
||
}
|
||
},
|
||
"required": ["workspaceId", "definitions"],
|
||
"additionalProperties": false,
|
||
"title": "Bulk save tag definitions request",
|
||
"description": "Workspace scope and the tag definitions to create or update.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"definitions": [
|
||
{
|
||
"tagSlot": "tag1",
|
||
"displayName": "category",
|
||
"fieldType": "text"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
},
|
||
"V2DeleteKnowledgeTagDefinitionsData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"unused": {
|
||
"type": "boolean",
|
||
"description": "Whether the delete was restricted to definitions no document still uses."
|
||
},
|
||
"count": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Number of tag definitions removed."
|
||
}
|
||
},
|
||
"required": ["unused", "count"],
|
||
"additionalProperties": false,
|
||
"title": "Delete knowledge tag definitions data",
|
||
"description": "Outcome of a knowledge-base tag-definition delete."
|
||
},
|
||
"V2DeleteKnowledgeTagDefinitionsResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2DeleteKnowledgeTagDefinitionsData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Delete tag definitions response",
|
||
"description": "Number of tag definitions that were removed."
|
||
}
|
||
}
|
||
},
|
||
"x-generated-by": "scripts/generate-openapi.ts"
|
||
}
|