opensource/sim
3
0
Fork 0
mirror of https://github.com/simstudioai/sim.git synced 2026-09-21 13:00:04 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
f6a9f0dd8799daeb25ef16b42266a0f68b93cb7e
sim/apps/docs/openapi-v2-knowledge.json
T
Waleed 4f9d5f33b0 improvement(search): search every folder, and document real API error bodies (#6861) 
* improvement(search): search every folder, and document real API error bodies

Search on Files, Tables, and Knowledge was ANDed with the open folder, so a
query only ever matched that folder's direct children — and the query was not
cleared when you entered a folder, filtering the folder you just opened down to
the same matches. A non-empty query now searches the whole workspace, a
Location column names each result's folder, and opening a folder ends the
search.

Also gives GET /api/v2/files a `recursive` flag, and replaces the single shared
OpenAPI error example — which showed `BAD_REQUEST` under every status tab — with
one real body per status.

* fix(search): discard the search term on clear instead of masking it

`useSearchFilterValue` returned the debounced term whenever the input was
non-empty, so clearing only hid the settled needle. The mask lifted on the next
keystroke while the debounce still held the pre-clear term — opening a folder
and typing within the window searched the whole workspace for the query the
user had just abandoned.

A clear now resets the settled term rather than hiding it, adjusted during
render so the reset is visible to the render that follows the clear. The
initial state is seeded from the first value so a deep-linked `?search=` still
filters on the first render.
2026-08-19 13:55:53 -07:00

4259 lines
148 KiB
JSON
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
{
"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": []
}
],
"paths": {
"/api/v2/knowledge": {
"get": {
"operationId": "listKnowledgeBases",
"summary": "List Knowledge Bases",
"description": "List knowledge bases in a workspace with folder filtering, search, sorting, and opaque cursor pagination. A workspace folder tree over 10,000 folders is a `413`.",
"tags": ["Knowledge Bases"],
"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": "folderPath",
"in": "query",
"required": false,
"description": "Restrict results to knowledge bases in this folder. A path that names no folder narrows the result to nothing, so the response is an empty page rather than an error.",
"schema": {
"description": "Restrict results to knowledge bases in this folder. A path that names no folder narrows the result to nothing, so the response is an empty page rather than an error.",
"$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. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
"schema": {
"default": "createdAt",
"description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
"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` is a `404`. A workspace folder tree over 10,000 folders is a `413`.",
"tags": ["Knowledge Bases"],
"requestBody": {
"required": true,
"description": "Workspace, name, description, chunking configuration, and folder placement.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateKnowledgeBaseRequest"
}
}
}
},
"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"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/knowledge/{id}": {
"get": {
"operationId": "getKnowledgeBase",
"summary": "Get Knowledge Base",
"description": "Retrieve a knowledge base by identifier. Inaccessible knowledge bases are reported as not found. A workspace folder tree over 10,000 folders is a `413`.",
"tags": ["Knowledge Bases"],
"parameters": [
{
"name": "id",
"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 name, description, chunking configuration, or folder placement. A workspace folder tree over 10,000 folders is a `413`.",
"tags": ["Knowledge Bases"],
"parameters": [
{
"name": "id",
"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"
}
}
}
},
"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"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
},
"delete": {
"operationId": "deleteKnowledgeBase",
"summary": "Delete Knowledge Base",
"description": "Delete a knowledge base and its documents.",
"tags": ["Knowledge Bases"],
"parameters": [
{
"name": "id",
"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/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`.",
"tags": ["Knowledge Bases"],
"requestBody": {
"required": true,
"description": "Knowledge bases, query, result limit, retrieval mode, and optional tag filters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchKnowledgeRequest"
}
}
}
},
"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"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/knowledge/{id}/tags": {
"get": {
"operationId": "listKnowledgeTags",
"summary": "List Tags",
"description": "List the knowledge base's tag vocabulary: each tag's display name, the slot it is stored in, and its field type. Filters and document reads use display names; document writes address slots. The bounded set is returned in one page; `nextCursor` is always null.",
"tags": ["Knowledge Bases"],
"parameters": [
{
"name": "id",
"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"
}
}
}
},
"/api/v2/knowledge/{id}/documents": {
"get": {
"operationId": "listKnowledgeDocuments",
"summary": "List Documents",
"description": "List documents in a knowledge base with filename search, state filtering, tag filtering, sorting, and opaque cursor pagination. Tag values are keyed by display name; resolve those to write slots with `GET /api/v2/knowledge/{id}/tags`.",
"tags": ["Knowledge Bases"],
"parameters": [
{
"name": "id",
"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. Sorting by `filename` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
"schema": {
"default": "uploadedAt",
"description": "Field used to sort the result. Sorting by `filename` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
"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 many documents in one request, either by identifier or, with `selectAll`, every document in the knowledge base. Bulk delete is not offered; delete documents one at a time with `DELETE /api/v2/knowledge/{id}/documents/{documentId}`. A workspace API key is rejected with `403`; use a personal API key.",
"tags": ["Knowledge Bases"],
"parameters": [
{
"name": "id",
"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"
}
}
}
},
"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"
},
"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.",
"tags": ["Knowledge Bases"],
"parameters": [
{
"name": "id",
"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/{id}/documents/uploads": {
"post": {
"operationId": "createKnowledgeDocumentUpload",
"summary": "Create Document Upload",
"description": "Create a resumable upload session and receive direct PUT or multipart transfer instructions.",
"tags": ["Knowledge Bases"],
"parameters": [
{
"name": "id",
"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"
}
}
}
},
"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/{id}/documents/uploads/{uploadId}": {
"delete": {
"operationId": "abortKnowledgeDocumentUpload",
"summary": "Abort Document Upload",
"description": "Abort an incomplete upload and discard provider-side multipart state.",
"tags": ["Knowledge Bases"],
"parameters": [
{
"name": "id",
"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/{id}/documents/uploads/{uploadId}/parts": {
"post": {
"operationId": "createKnowledgeDocumentUploadPartUrls",
"summary": "Create Document Upload Part URLs",
"description": "Issue short-lived signed PUT URLs for up to 100 multipart part numbers.",
"tags": ["Knowledge Bases"],
"parameters": [
{
"name": "id",
"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"
}
}
}
},
"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"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/knowledge/{id}/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.",
"tags": ["Knowledge Bases"],
"parameters": [
{
"name": "id",
"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"
},
"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/{id}/documents/{documentId}": {
"get": {
"operationId": "getKnowledgeDocument",
"summary": "Get Document",
"description": "Retrieve document detail, processing state, and connector provenance.",
"tags": ["Knowledge Bases"],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Unique knowledge base identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique knowledge base identifier."
}
},
{
"name": "documentId",
"in": "path",
"required": true,
"description": "Unique knowledge document identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique knowledge document 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, enable or disable it for search, set any of its 17 tag slots, or requeue it for processing. Absent fields are unchanged, and derived indexing state is read-only. Resolve a tag display name to its slot with `GET /api/v2/knowledge/{id}/tags`. The returned document omits the connector provenance the detail read carries. A workspace API key is rejected with `403`; use a personal API key.",
"tags": ["Knowledge Bases"],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Unique knowledge base identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique knowledge base identifier."
}
},
{
"name": "documentId",
"in": "path",
"required": true,
"description": "Unique knowledge document identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique knowledge document identifier."
}
}
],
"requestBody": {
"required": true,
"description": "Filename, search state, tag slot values, or a processing retry.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateKnowledgeDocumentRequest"
}
}
}
},
"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"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
},
"delete": {
"operationId": "deleteKnowledgeDocument",
"summary": "Delete Document",
"description": "Remove one document from a knowledge base. An uploaded document is deleted outright with its indexed chunks. A connector-backed document is instead excluded — its row and embeddings survive, but it stops being searchable and a later sync does not re-add it. Either way it no longer appears in listings or search results.",
"tags": ["Knowledge Bases"],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Unique knowledge base identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique knowledge base identifier."
}
},
{
"name": "documentId",
"in": "path",
"required": true,
"description": "Unique knowledge document identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique knowledge document 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. The bounded set is returned in one page; `nextCursor` is always null. A workspace folder tree over 10,000 folders is a `413`.",
"tags": ["Knowledge Bases"],
"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.",
"schema": {
"description": "Restrict results to direct children of this parent path.",
"$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. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
"schema": {
"default": "name",
"description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
"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. A workspace folder tree over 10,000 folders is a `413`.",
"tags": ["Knowledge Bases"],
"requestBody": {
"required": true,
"description": "Workspace and canonical path for a new knowledge-base folder.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateKnowledgeFolderRequest"
}
}
}
},
"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"
},
"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. A workspace folder tree over 10,000 folders is a `413`.",
"tags": ["Knowledge Bases"],
"requestBody": {
"required": true,
"description": "Current and destination canonical paths for a knowledge-base folder.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RelocateKnowledgeFolderRequest"
}
}
}
},
"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"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
},
"delete": {
"operationId": "deleteKnowledgeFolder",
"summary": "Delete Folder",
"description": "Delete a folder, optionally including nested folders and knowledge bases.",
"tags": ["Knowledge Bases"],
"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 nested files and folders too. An empty folder deletes either way; a non-empty one needs this. The listed spellings are the whole accepted vocabulary and are case-sensitive; any other value is rejected.",
"schema": {
"description": "Delete the folder's nested files and folders too. An empty folder deletes either way; a non-empty one needs this. The listed spellings are the whole accepted vocabulary and are case-sensitive; any other value is rejected.",
"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"
}
}
}
}
},
"components": {
"securitySchemes": {
"apiKey": {
"type": "apiKey",
"in": "header",
"name": "X-API-Key",
"description": "Your Sim API key, personal or workspace-scoped. Generate one under Settings, then API Keys. Operations that reject workspace keys say so in their own description."
}
},
"headers": {
"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 key is missing or invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Error"
},
"example": {
"error": {
"code": "UNAUTHORIZED",
"message": "API key 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": "Upload has already been completed"
}
}
}
}
},
"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. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `ASYNC_ENQUEUE_AMBIGUOUS`, because the run may already have started — reconcile against the returned run id instead of retrying.",
"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": {
"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 details. On a `403` whose cause a caller can act on, this carries a `code` from a closed set:\n- `INSUFFICIENT_WORKSPACE_ROLE` — The caller has access to the workspace but its role is below the one this operation requires.\n- `PERSONAL_API_KEYS_DISABLED` — The workspace's organization does not allow personal API keys. Use a workspace API key.\n- `WORKSPACE_KEY_OPERATION_NOT_PERMITTED` — This operation is not available to a workspace-scoped API key. Use a personal API key.\n- `PRINCIPAL_KIND_NOT_PERMITTED` — This operation does not accept the caller’s kind of API key.\n- `ORGANIZATION_MEMBERSHIP_REQUIRED` — The caller is not a member of the organization it named.\n- `ORGANIZATION_ADMIN_REQUIRED` — The caller is a member of the organization but not an admin or owner.\n- `ENTERPRISE_PLAN_REQUIRED` — The organization has no active enterprise subscription.\n- `AUDIT_LOGS_DISABLED` — Audit logging is not enabled for this deployment.\n- `SKILL_EDITOR_ACCESS_REQUIRED` — The caller can write in the workspace but is not an editor of this skill.\n- `SECRET_ADMIN_ACCESS_REQUIRED` — The caller can write in the workspace but is not an admin of this secret. Ask a workspace admin, or someone holding admin on the secret, to grant access or set the value.\n- `WORKSPACE_RESOURCE_LIMIT_REACHED` — The workspace already holds the maximum number of resources of this kind. Delete one, or contact Sim to raise the limit; the message names the ceiling.\n- `PUBLIC_SHARING_NOT_ALLOWED` — The workspace's organization does not permit sharing this resource publicly. An organization admin controls the policy.\n- `CREDENTIAL_ADMIN_ACCESS_REQUIRED` — The caller can reach the workspace but cannot administer this credential.\n- `MCP_SERVER_URL_NOT_ALLOWED` — The supplied MCP server URL is outside the allowed domains or resolves to an internal address."
}
},
"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"]
},
"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.",
"maxLength": 4096,
"examples": ["/Product"]
}
},
"required": [
"id",
"name",
"description",
"tokenCount",
"embeddingModel",
"embeddingDimension",
"chunkingConfig",
"createdAt",
"updatedAt",
"ownerEmail",
"folderPath"
],
"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": "Number of overlapping characters 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 is nothing further to fetch. Never construct one 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": "Number of overlapping characters between adjacent chunks.",
"examples": [200],
"type": "number",
"minimum": 0,
"maximum": 500
}
},
"title": "Knowledge chunking configuration input",
"description": "Chunking configuration applied when processing documents."
},
"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."
},
"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."
},
"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": "Similarity score for vector search; tag-only matches use 1.",
"examples": [0.8423]
},
"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"
],
"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": "What the reranker did on this search. `applied` means it ordered the results, which carry `rerankerScore`. `unavailable` means it was attempted but could not complete, so results are in vector order with no `rerankerScore` — the search still succeeded, and is worth retrying. `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 identifier or an array of up to 20 identifiers.",
"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; the boundary schema only bounds the range, so a fractional value is admitted here and then rejected with 400 during search.",
"type": "number",
"minimum": 1,
"maximum": 100
},
"tagFilters": {
"description": "Structured tag filters, at most 10 of them. Every filter must hold, including two that name the same tag: repeating one tag narrows the result rather than widening it, matching `GET /api/v2/knowledge/{id}/documents`. To match either of two values for one tag, issue a search per value. Each filtered tag must resolve to the same slot and field type in every knowledge base selected; one missing from any of them, or defined inconsistently across them, is rejected rather than ignored, and those knowledge bases must be searched separately. List the available names with `GET /api/v2/knowledge/{id}/tags`.",
"maxItems": 10,
"type": "array",
"items": {
"$ref": "#/components/schemas/V2KnowledgeSearchTagFilter"
}
},
"searchMode": {
"description": "Retrieval strategy: vector is semantic-only, while hybrid also runs full-text search.",
"default": "vector",
"anyOf": [
{
"type": "string",
"enum": ["vector", "hybrid"]
},
{
"type": "null"
}
]
},
"rerankerEnabled": {
"description": "Re-order retrieved chunks with a reranking model before truncating to `topK`. Ignored for a tag-only search, and billed as an additional search unit. Reranking is best-effort — a provider failure falls back to vector ordering, so check `rerankerStatus` on the response.",
"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": {
"displayName": {
"type": "string",
"description": "Display name used by tag filters and by tag values on document reads.",
"examples": ["category"]
},
"tagSlot": {
"type": "string",
"description": "Storage slot the tag occupies. Document writes set tag values by slot (`tag1`..`tag7`).",
"examples": ["tag1"]
},
"fieldType": {
"type": "string",
"description": "Value type stored in the slot; it determines the valid filter operators.",
"examples": ["text"]
}
},
"required": ["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` param and returns its whole bounded set in one page. Present so the list can gain pages later without a shape change."
}
},
"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 tag display name. Writes address the same tags by slot (`tag1`..`tag7`); resolve names to slots with GET /api/v2/knowledge/{id}/tags.",
"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 is nothing further to fetch. Never construct one 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 MB."
}
},
"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"
},
"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. Send the bytes with `PUT` to this URL, including exactly the headers in `headers` and nothing that alters the body. Success is `204` with an empty body. A failure is the same `{ \"error\": { \"code\", \"message\" } }` envelope as every other v2 response: `400` when the body does not match the size or content type the session was created for, `403` when the token is invalid, expired, or belongs to another session, and `409` when the session is no longer accepting bytes. The URL is signed and self-describing — construct it from this field only, never by hand."
},
"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."
},
"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.",
"type": "string",
"maxLength": 255
},
"lang": {
"description": "Optional document language code.",
"type": "string",
"maxLength": 35
}
},
"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."
},
"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. Send the bytes with `PUT` to this URL, including exactly the headers in `headers` and nothing that alters the body. Success is `204` with an empty body. A failure is the same `{ \"error\": { \"code\", \"message\" } }` envelope as every other v2 response: `400` when the body does not match the size or content type the session was created for, `403` when the token is invalid, expired, or belongs to another session, and `409` when the session is no longer accepting bytes. The URL is signed and self-describing — construct it from this field only, never by hand."
},
"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."
},
"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 tag display name. Writes address the same tags by slot (`tag1`..`tag7`); resolve names to slots with GET /api/v2/knowledge/{id}/tags.",
"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` param and returns its whole bounded set in one page. Present so the list can gain pages later without a shape change."
}
},
"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": "New full path for the folder and its descendants.",
"$ref": "#/components/schemas/NonRootFolderPathInput"
}
},
"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."
}
}
},
"x-generated-by": "scripts/generate-openapi.ts"
}
Reference in New Issue View Git Blame Copy Permalink