mirror of
https://github.com/simstudioai/sim.git
synced 2026-09-21 13:00:04 +08:00
Waleed
c930830310
* fix(chat): resolve a caller-supplied conversation id through its owner The v2 chat route used the caller-supplied conversationId verbatim, with no existence, owner, or workspace check, against a store keyed by bare text with no owner column. A caller who knew another user's conversation id reached that conversation. Ids now resolve through the same owner-scoped loader the web chat path uses, and anything unresolvable answers one uniform 404 before any lifecycle work runs. Omitting the id mints a server-issued conversation. The contract also accepted any 1-128 character string for a column typed uuid, so a malformed id raised a driver error and rendered 500 while an unknown but well-formed id rendered 404 - a shape oracle, and a 500 on ordinary input. The ownership predicate had no coverage anywhere: the route test mocked the module and the lifecycle test drove a chain mock that ignores its where clause, so deleting the owner condition left both suites green. It is now asserted by composition and by condition count, which is what catches a dropped condition. Also renames the reply's model identifier away from a term the project's own copy rules forbid on a user-facing surface. * fix(v2): conceal workspace absence, and stop archived tables faulting their page Two reads answered a caller more than they were entitled to know. A workspace a caller cannot reach at all returned FORBIDDEN while one that does not exist returned NOT_FOUND, so a workspace-key holder could enumerate which workspace ids exist by diffing the two. Both now answer the same absence, using the concealment policy the billing routes already use. A refusal from inside the workspace - a member whose role is too low - still answers FORBIDDEN, because that caller already knows the workspace exists. Separately, archiving a folder cascades onto its tables but leaves each table pointing at the archived folder row. The archived listing resolved those paths strictly, so one such row faulted the whole page and no cursor could step past it - which also made the ids undiscoverable and left restore unreachable for exactly the tables that need it. The archived scope now resolves leniently to the root, where a restore would place them, matching the shipped workflows behavior. Active listings still fault loudly on a dangling folder. * fix(knowledge): validate upload processing options without stranding live sessions recipe and lang were accepted as free strings up to their length caps, silently discarded, and echoed back nowhere, so a typo was unobservable: uploading with a misspelled recipe returned 200 and quietly used the default. Both are now validated at the boundary and a bad value answers 400 naming what is accepted. The accepted recipe set deliberately includes the sentinel every first-party caller sends today alongside the three real chunker recipes, and the three are derived from the chunker's own union so removing one there is a compile error here rather than a silent 400 in production. The same schema also parses metadata read back off a persisted upload session, so tightening it would have thrown out of resume and complete for any session created before this - a 500 on work that could then never finish. The read-back path now drops a value it no longer recognises instead of rejecting it; the request boundary stays strict. Neither field reaches chunking, so nothing here moves chunk boundaries, embeddings, or search results. * fix(v2): honour a requested stats window, and answer a claimed graph id with a conflict Log statistics accepted a start and an end, filtered the totals by them, and then built the series against wall-clock now. Bucket width was computed over a span the caller never asked for, and every bucket past the requested end was structurally empty - so a bounded historical query returned a wrong-width series with fabricated trailing buckets, under a window label that disagreed with the request. Each edge now honours the bound it was given and keeps its previous derivation when omitted, so an unbounded request is unchanged. Separately, block, edge and subflow ids are global primary keys while the delete that precedes a state replace is scoped to one workflow. An id owned by another workflow survived that delete, the insert violated the key, and because callers pass their own transaction the driver error escaped unclassified as a server fault. The write now refuses such an id up front with a conflict naming it, and re-classifies the same violation if one races past the check, since the lock covers only the workflow being written. The dry run checks the ids a commit would insert and reports the warnings a commit would report, which is what its own contract already promised. * fix(secrets): let a workspace secret change its metadata without resending the value Restoring redaction cost more than removing it. The only way to flip a secret back to redacted was to re-send the plaintext, because the write required a value and omitting it fell into an interactive prompt that cannot run in CI. A workspace secret can now change its description or visibility on its own; the stored value is never re-encrypted or rewritten, a write that names no existing secret answers not-found rather than creating one, and a personal secret still requires a value because it has no other writable field. The path parameter was also one shared schema across the write and the delete, so a single description had to cover both and the delete documented an argument that could create and replace. Split, mirroring the credentials pair. The metadata write is a new update against the credentials table, so its scope is asserted by composition and by condition count: an unscoped update would let one workspace flip another workspace's identically-named secret out of redaction, and the cache invalidation would then carry that flag into the other workspace's runtime catalog. * fix(v2): say what an error means in terms the caller can act on A size-limit refusal collapsed every value under a kilobyte to "0 Bytes", so a 28-byte file over a 27-byte ceiling read "is 0 Bytes, above the 0 Bytes limit" - self-contradictory, and useless for choosing a value that would work. Errors and field descriptions also told callers to invoke raw HTTP endpoints. These strings serve the REST reference and the CLI's own help equally, so they now name the operation and its object rather than a method and a path. A sweep test walks every v2 schema description and holds the line, with the remaining offenders in files this change does not own recorded explicitly rather than left to be rediscovered. Listing the editors of a built-in skill claimed the skill did not exist, while reading the same id succeeded - a well-formed request for a real resource is not malformed, so the list answers an empty roster and only the mutations refuse. Bulk folder deletion recorded only the leaf name in its audit trail while the single delete recorded the full path, leaving two same-named folders under different parents indistinguishable after the fact. Bulk chunk enable, disable and delete each treated an unmatched id differently behind one sentence of documentation. They now follow one rule. A workspace-scoped list refused with the name of a resource the caller never addressed, which reads as an empty workspace rather than an unreachable one. * fix(cli): stop a config value forging a section it was never meant to write The config file is written by joining names and values into INI lines, and nothing checked what was in them. A profile name carrying a newline and a section header wrote a section that merged into a different profile and took over its endpoint - and the next command sent that profile's stored API key there. A workspace value could do the same from the other side, since only the endpoint flag validated its input. The refusal now lives at the writer, the single place untrusted text enters the document, with the flag-level checks kept for the better message. Either alone blocks the forgery; the pair is deliberate. Rejecting rather than escaping, because the format has no escape syntax and these files are hand-edited and read by other tools that would not decode one we invented. The forbidden set covers control characters and the two Unicode line separators, which the previous guard missed - those parse as an unreadable line, so the key silently vanished on read and the next write appended a duplicate while the command reported success. Login also wrote the key before the settings, so a malformed response from the deployment could leave a key on disk with no endpoint beside it, and the next command would send it to the default host. Settings are written first, and the response is checked before anything touches disk. Name validation applies only when creating a profile, so a hand-written one that predates the rule keeps working. * fix(docs): tell the reader which key a command needs, and stop the ids contradicting the CLI Around sixty v2 operations refuse a workspace API key, and the CLI's help said nothing about it - the caller found out from a 403 after the request went out. The restriction is already stated in the API spec, so the generator now reads it from there and the command description carries it. The sentinel sentences are imported from the spec's own constants rather than copied, so a reword cannot silently unmark every command, and the test pins the count as well as named operations because a reword confined to one family would otherwise slip past. The generated reference also rendered an empty default as a sentence pointing at nothing - "Defaults to ." - for every repeatable filter. Omitted now, while false and zero still render, which is the trap that shape of check usually walks into. The hand-written guides used a workflow-shaped id for workflows that the CLI's own help says never names one, and five other families were equally wrong. All of them now match the scheme the CLI declares, consistently per entity across pages, with the shared ones taken from that help text so the two read as one voice. The page documenting every flag was linked from nowhere; both landing links pointed at the overview instead. And the generator's test file was absent from the hand-maintained list CI runs, so its guards never executed. * fix(cli): stop a page-size default capping a destructive filter Every request field named limit inherited the pager's default of 100, but only a cursor-paginated command interprets that flag. The two filter-based row mutations declare no cursor, so the default went onto the wire as a row cap: a filter matching 250 rows deleted 100, exited 0, and said nothing - while the confirmation the user had just answered promised every matching row. The flag's own help offered 0 for everything, which those endpoints reject; the unbounded form is the field being absent. The pager's default now applies only where the pager runs, and the tests pin the omission on the request body rather than in help text. A cap typed alongside an explicit row list was silently ignored; it is now refused on the client, where refusing costs nothing to already-installed versions. Lists also truncated at a hundred with no signal in any format, and the two inventory endpoints that do report truncation had that field dropped on the way out - so a caller reconciling against a clipped list could not tell. One note now goes to stderr while stdout stays a bare array, and a flag raised on a later page survives the fold. Also: a folder whose name contains the separator no longer prints a path that resolves to a different folder; validation errors name the flag the user typed instead of the wire field; an unknown subcommand with --help exits non-zero instead of printing the parent's help; a fractional or negative page size is refused rather than floored; an empty query filter is refused rather than silently returning everything; and the two spellings of the missing-workspace message became one. * fix(cli): gate destructive table imports and fix follow-mode rendering A `tables import --mode replace` empties the table before its first batch, so the only warning was in the describe. It now confirms, and the wording tells the truth per mode: cancelling a replace leaves a prefix of the new file with the originals already gone, while an append re-adds its rows if the file is imported twice. `--yes` skips the gate, and the gate runs before the file is opened. Import and export cancellation carried no describe at all; the import one now confirms, the export one records why it deliberately does not. Follow-mode output truncated cells to whatever the first row happened to measure, so a longer status or workflow name arrived clipped with no signal. Cells now clamp at a shared ceiling and pad to the lock, and the log columns carry width floors so a short first page cannot pin a column narrower than its own values. Interrupting a staged download left the staging directory behind; it is now removed on SIGINT and SIGTERM before the signal is re-raised. `--select-output` without `--follow` selected from a response that does not carry outputs, and said nothing. It is refused client-side, with a separate message for `--async`. Its describe now names what the path addresses. `secrets set` always read a value, even when only metadata flags were passed. Off a TTY that was an immediate refusal, so a metadata-only edit exited 1 in CI for a value it was never asked for; on a TTY it stopped to prompt, and the prompt rejects an empty entry, so there was no way to say "leave the stored value alone" short of re-typing the secret. The read is now skipped and the field omitted, which is what lets a metadata-only edit run unattended. On a TTY, setting only a description no longer prompts. Passing both spellings of the reveal flag is refused rather than silently resolved. Four mandatory hand-authored flags now say so, `billing logs` names its key-type scope, and the dispatch list declares its columns. * fix: close the gaps an adversarial review of this branch found A conflict handler added earlier in this branch was dead code. It read the Postgres error code off the thrown object, but the driver error arrives wrapped with the real one on `cause`, so the check returned false on its first line and the 409 never fired. Its test passed only because it threw a flat shape production never produces. It now reads through the cause chain with the shared helpers, compares the constraint name exactly instead of matching a substring of the SQL, and its test throws the real wrapped error. Resuming a conversation checked its workflow and its workspace but not its type, so a conversation created by the web surface could be continued as a CLI turn. It now refuses through the same uniform 404 as every other mismatch, which closes the same omission on the web posting path. Minting one no longer leaves a blank untitled row at the top of the Chat list. The pre-write check on a minted API key refused fewer characters than the writer does, so a key the check accepted could still fail at the write — after the endpoint beside it was already stored, pairing a new endpoint with the previous key. The two had drifted because the set was spelled three times; there is now one. A description claimed a processed count reported only the chunks that changed. The update returns every row it matched, so re-enabling chunks that were already enabled counts them all. Two OpenAPI sentences promised no conflict detection and no persistence warnings in a dry run, both of which the same branch had just made false. A described window was wrong whenever a start was supplied without an end. Listing the editors of a built-in skill answered a read with a modification refusal on the internal surface. Archived table listings could reach the strict folder projector again through a third scope value the input type still allowed. A metadata-only secret write skipped the guard its personal-scope twin has. The internal document boundary still took the two processing fields as unbounded strings. Truncation was reported only from the response envelope, so a clipped file body, row search and workflow-stats list said nothing. A staged download stopped watching for signals before it finished removing its directory, and cleared every listener for the signal rather than its own. Three tests asserted a contract constant against itself; they now drive rendered help, real argv, or real render output. * chore: regenerate the API reference, CLI surface, and CLI docs The published reference still marked a secret value required and described the delete parameter as one that also creates, the CLI surface still lacked the marker that says which operations refuse a workspace key, and the reference rendered an empty sentence for every repeatable filter whose default is an empty list. * test(cli): use the package's own delay helper in the staging poll The audit bans a hand-rolled setTimeout promise. `sim-cli` does not depend on the shared utils package, and its own idiom is `node:timers/promises`. * fix: act on a second review round, and correct two earlier claims The conflict pre-check read block ids from the wrong side. The writer inserts each block's own `id` field while the check read the record key, and the two can diverge because preparation copies a value under its key without reconciling them. Edges already read the value and subflows are genuinely keyed by the record key, so only blocks were wrong — collecting every family from the values, as first suggested, would have broken subflows instead. A minted API key carrying leading or trailing whitespace passed the pre-write check but failed the writer, leaving the new endpoint on disk beside the previous key. It is refused up front now rather than trimmed: a key is opaque, so trimming would store a value the server never issued and turn a loud failure into an unexplained 401 later. The endpoint normalizer does trim, which is what made a padded `--endpoint` fail only after the browser flow had already minted a key. A metadata-only secret write raced with deletion returned 500, because the follow-up read that only assembles the response body threw an unclassified error; it now reports the same not-found the non-racing miss already gave. An unusable output format in the environment silently printed a table instead of refusing. Two validation messages printed control characters verbatim. A dry run now reports the preparation warnings its own commit path returns. The chat route created a titled conversation and never wrote a message, so it appeared in the Chat list promising content it did not have. Both sides of a successful turn are now persisted; a failed turn still writes nothing, so a question is never stored without its answer. Two claims of mine were wrong. The earlier commit message said `secrets set` sent an empty value that overwrote the stored secret — it did not; the prompt refuses off a TTY and rejects empty on one, so the old behaviour was a clean refusal. And the delay helper commit said this package's idiom is `node:timers/promises`; the package carries its own `sleep`, which is the audit's sanctioned home and has five callers. It uses that now. Also: a test asserting a deadlock stays unclassified could not fail, since every candidate rejects it; it now pins a unique violation carrying no constraint name. Workflow ids spelled with the file prefix are corrected in the remaining fixtures, leaving the genuine file ids alone. * fix: close a credential-misdirection path this branch had opened Making the endpoint normalizer trim handled whitespace around a value but not a control character inside one, and the URL parser removes those from anywhere in its input — so a value that reads as one host could resolve to another, and the profile's key went with it. The flag and environment paths never touch the config writer, so its guard did not cover this. The normalizer now refuses the same character set the writer does, which also keeps the invariant that nothing it blesses can be refused by the write that stores it. Comparing the parsed URL back against its input was the alternative and is wrong: the parser rewrites percent-encoding, case, internationalized hosts and default ports, so legitimate endpoints would be refused. The blank-query guard tested for exactly empty, so a whitespace-only value still reached the wire — as a real zero on a numeric filter, an explicit false on a boolean one, and as an encoded space the server then rejected. It now refuses any value that is blank once trimmed, while a body string keeps its meaning, an explicit zero still sends, and a value with content around its whitespace is passed through untouched rather than trimmed. A graph-id conflict reported 409 on the v2 route and fell through the older persistence wrapper as an unclassified 500. That wrapper now classifies orchestration failures through the cause chain, which also fixes a pre-existing case where a workflow archived between authorization and the locked read reported 500 rather than 404. Persisting a chat turn claimed its row by id alone, so a conversation soft-deleted mid-turn still received the messages and was bumped back up the list. It now requires a live row. A turn whose caller hung up after the model had already answered persisted nothing, though the work was done and billed; it now persists and still reports the connection as closed. An empty workspace id from the login response was read as no workspace at all. A published description still promised a language-tag standard the schema does not enforce. The test asserting that a turn is stored before the final event drained the whole response first, so it held whichever order the code used. It now reads the stream incrementally and fails if the write moves after the event.
8416 lines
299 KiB
JSON
8416 lines
299 KiB
JSON
{
|
||
"openapi": "3.1.0",
|
||
"info": {
|
||
"title": "Sim API v2 — Knowledge Bases",
|
||
"description": "Version 2 of the Sim REST API for knowledge bases, document ingestion, resumable uploads, folders, and semantic or tag-based search.",
|
||
"version": "2.0.0",
|
||
"contact": {
|
||
"name": "Sim Support",
|
||
"email": "help@sim.ai",
|
||
"url": "https://www.sim.ai"
|
||
},
|
||
"license": {
|
||
"name": "Apache 2.0",
|
||
"url": "https://www.apache.org/licenses/LICENSE-2.0.html"
|
||
}
|
||
},
|
||
"servers": [
|
||
{
|
||
"url": "https://www.sim.ai",
|
||
"description": "Production"
|
||
}
|
||
],
|
||
"tags": [
|
||
{
|
||
"name": "Knowledge Bases",
|
||
"description": "Create and organize knowledge bases, ingest documents, and search indexed content."
|
||
}
|
||
],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
}
|
||
],
|
||
"paths": {
|
||
"/api/v2/knowledge": {
|
||
"get": {
|
||
"operationId": "listKnowledgeBases",
|
||
"summary": "List Knowledge Bases",
|
||
"description": "List knowledge bases in a workspace with lifecycle scope, folder filtering, search, sorting, and opaque cursor pagination. `scope` defaults to `active`; pass `archived` to list knowledge bases a `DELETE` archived, each carrying the `deletedAt` instant it was archived, and recover one with `POST /api/v2/knowledge/{knowledgeBaseId}/restore`. 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": "scope",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Which lifecycle set to list: `active` (default) for live knowledge bases, `archived` for knowledge bases a `DELETE` archived and `POST /knowledge/{knowledgeBaseId}/restore` can bring back. `folderPath` resolves against active folders only, so pairing it with `scope=archived` returns an empty page when the containing folder was archived too.",
|
||
"schema": {
|
||
"default": "active",
|
||
"description": "Which lifecycle set to list: `active` (default) for live knowledge bases, `archived` for knowledge bases a `DELETE` archived and `POST /knowledge/{knowledgeBaseId}/restore` can bring back. `folderPath` resolves against active folders only, so pairing it with `scope=archived` returns an empty page when the containing folder was archived too.",
|
||
"type": "string",
|
||
"enum": ["active", "archived"]
|
||
}
|
||
},
|
||
{
|
||
"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"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}": {
|
||
"get": {
|
||
"operationId": "getKnowledgeBase",
|
||
"summary": "Get Knowledge Base",
|
||
"description": "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": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The requested knowledge base.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeBaseResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"patch": {
|
||
"operationId": "updateKnowledgeBase",
|
||
"summary": "Update Knowledge Base",
|
||
"description": "Update a knowledge base name, description, chunking configuration, or folder placement. A workspace folder tree over 10,000 folders is a `413`.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace scope and fields to update. At least one mutable field is required.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/UpdateKnowledgeBaseRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "The updated knowledge base.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeBaseResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"delete": {
|
||
"operationId": "deleteKnowledgeBase",
|
||
"summary": "Delete Knowledge Base",
|
||
"description": "Delete a knowledge base and its documents.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Knowledge base deletion acknowledgement.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeDeleteResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/connectors": {
|
||
"get": {
|
||
"operationId": "listKnowledgeConnectors",
|
||
"summary": "List Knowledge Connectors",
|
||
"description": "List external sources connected to a knowledge base with opaque cursor pagination. Stored API keys and encrypted secret material are never returned. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
},
|
||
{
|
||
"name": "sortBy",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Field used to sort the result.",
|
||
"schema": {
|
||
"default": "createdAt",
|
||
"description": "Field used to sort the result.",
|
||
"type": "string",
|
||
"enum": ["connectorType", "createdAt", "updatedAt"]
|
||
}
|
||
},
|
||
{
|
||
"name": "sortOrder",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Sort direction.",
|
||
"schema": {
|
||
"default": "desc",
|
||
"description": "Sort direction.",
|
||
"type": "string",
|
||
"enum": ["asc", "desc"]
|
||
}
|
||
},
|
||
{
|
||
"name": "limit",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Maximum connectors to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"schema": {
|
||
"default": 50,
|
||
"description": "Maximum connectors to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 100
|
||
}
|
||
},
|
||
{
|
||
"name": "cursor",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"schema": {
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "A page of knowledge connectors.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeConnectorListResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"post": {
|
||
"operationId": "createKnowledgeConnector",
|
||
"summary": "Create Knowledge Connector",
|
||
"description": "Validate and connect an external source, then queue its initial synchronization. The apiKey field is write-only and is never returned. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace, connector type, authentication reference, source configuration, and sync schedule.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateKnowledgeConnectorRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"201": {
|
||
"description": "The created connector without secret material.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeConnectorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/connectors/{connectorId}": {
|
||
"get": {
|
||
"operationId": "getKnowledgeConnector",
|
||
"summary": "Get Knowledge Connector",
|
||
"description": "Retrieve one connector and its ten most recent synchronization attempts. Stored API keys and encrypted secret material are never returned. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "connectorId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Connector selected for the operation.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Connector selected for the operation."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Knowledge base that owns the connector.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Knowledge base that owns the connector."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The connector and recent synchronization history.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeConnectorDetailResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"patch": {
|
||
"operationId": "updateKnowledgeConnector",
|
||
"summary": "Update Knowledge Connector",
|
||
"description": "Update connector source configuration, schedule, or active state. Replacing source configuration on a runnable connector queues an immediate synchronization; paused connectors retain the change without synchronizing until resumed. Source configuration cannot be replaced while synchronization is already in progress. Authentication material cannot be changed through this operation. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "connectorId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Connector selected for the operation.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Connector selected for the operation."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Knowledge base that owns the connector.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Knowledge base that owns the connector."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace scope and at least one mutable connector field.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/UpdateKnowledgeConnectorRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "The updated connector.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeConnectorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"delete": {
|
||
"operationId": "deleteKnowledgeConnector",
|
||
"summary": "Delete Knowledge Connector",
|
||
"description": "Delete a connector and optionally its synchronized documents. Documents are retained by default. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "connectorId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Connector selected for the operation.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Connector selected for the operation."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Knowledge base that owns the connector.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Knowledge base that owns the connector."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
},
|
||
{
|
||
"name": "deleteDocuments",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Also permanently delete documents produced by this connector.",
|
||
"schema": {
|
||
"description": "Also permanently delete documents produced by this connector.",
|
||
"type": "boolean"
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Connector deletion acknowledgement and document counts.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeConnectorDeleteResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/connectors/{connectorId}/sync": {
|
||
"post": {
|
||
"operationId": "syncKnowledgeConnector",
|
||
"summary": "Sync Knowledge Connector",
|
||
"description": "Queue a connector synchronization. Rehydration forces existing documents to be fetched and indexed again. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "connectorId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Connector selected for the operation.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Connector selected for the operation."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Knowledge base that owns the connector.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Knowledge base that owns the connector."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace scope and optional full rehydration control.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/SyncKnowledgeConnectorRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "Synchronization was queued.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeConnectorSyncResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/connectors/{connectorId}/documents": {
|
||
"get": {
|
||
"operationId": "listKnowledgeConnectorDocuments",
|
||
"summary": "List Knowledge Connector Documents",
|
||
"description": "List documents produced by one connector with opaque cursor pagination. Excluded documents are omitted unless explicitly requested. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "connectorId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Connector selected for the operation.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Connector selected for the operation."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Knowledge base that owns the connector.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Knowledge base that owns the connector."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
},
|
||
{
|
||
"name": "includeExcluded",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Include documents explicitly excluded by a user.",
|
||
"schema": {
|
||
"description": "Include documents explicitly excluded by a user.",
|
||
"type": "boolean"
|
||
}
|
||
},
|
||
{
|
||
"name": "limit",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Maximum connector documents to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"schema": {
|
||
"default": 50,
|
||
"description": "Maximum connector documents to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 100
|
||
}
|
||
},
|
||
{
|
||
"name": "cursor",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"schema": {
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "A page of connector documents.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeConnectorDocumentListResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"patch": {
|
||
"operationId": "updateKnowledgeConnectorDocuments",
|
||
"summary": "Update Knowledge Connector Documents",
|
||
"description": "Exclude connector documents from knowledge search or restore previously excluded documents. Only documents produced by the selected connector can change. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "connectorId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Connector selected for the operation.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Connector selected for the operation."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Knowledge base that owns the connector.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Knowledge base that owns the connector."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace, restore or exclude operation, and selected document identifiers.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/UpdateKnowledgeConnectorDocumentsRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "The selected connector documents were updated.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeConnectorDocumentsUpdateResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/search": {
|
||
"post": {
|
||
"operationId": "searchKnowledge",
|
||
"summary": "Search Knowledge",
|
||
"description": "Search one or more knowledge bases with semantic vector retrieval, optional hybrid full-text retrieval, and structured tag filters. Every result names the `knowledgeBaseId` it came from. A request body over 2 MiB is a `413`.",
|
||
"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"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/tags": {
|
||
"get": {
|
||
"operationId": "listKnowledgeTags",
|
||
"summary": "List Tags",
|
||
"description": "List the knowledge base's tag 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": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The knowledge base tag vocabulary.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeTagListResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"post": {
|
||
"operationId": "createKnowledgeTag",
|
||
"summary": "Create Tag",
|
||
"description": "Define one tag on a knowledge base; use `PUT` on this path to declare several at once. Define a tag here, write its `tagSlot` on a document with `PATCH /api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}`, then filter by its `displayName` on the document list or on search. Omit `tagSlot` to take the next free slot for the field type; a field type with no free slot left is a `400` naming it, since the remedy is a different type or a deleted definition rather than a retry. A `tagSlot` already taken, or a `displayName` already defined on this knowledge base, is a `409` naming which of the two to change. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace scope, display name, field type, and optional slot.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateKnowledgeTagRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"201": {
|
||
"description": "The created tag definition.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeTagResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"put": {
|
||
"operationId": "bulkSaveKnowledgeTagDefinitions",
|
||
"summary": "Bulk Save Tag Definitions",
|
||
"description": "Declare, in one request, several of the knowledge base's tag definitions. `POST` on this path defines exactly one tag; this is the same write over a list, and every slot the body names is written to the declaration it carries while slots it does not name are left alone. Updating an existing definition requires naming its current name in `originalDisplayName`; that is the only form that edits one in place. Without it the entry is a create, and a requested `tagSlot` another name already holds is refused in `errors` — it is neither overwritten nor relocated to a different slot, so an explicitly requested slot always means that slot or an error. A create whose `displayName` already exists is refused in `errors`. Per-definition failures are reported in `errors` and still answer `200`. This writes the vocabulary, not one document's tag values — set those with `PATCH /api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}`. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace scope and the tag definitions to create or update.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/BulkSaveKnowledgeTagDefinitionsRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "Definitions created and updated by the save.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2BulkSaveKnowledgeTagDefinitionsResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"delete": {
|
||
"operationId": "deleteKnowledgeTagDefinitions",
|
||
"summary": "Delete Tag Definitions",
|
||
"description": "Remove tag definitions from the knowledge base. `unused` defaults to `true`, which removes only the definitions no document still carries a value for — the recoverable half, since a definition with nothing behind it can simply be redefined. Pass `unused=false` to delete every definition on the knowledge base, which also clears its slot on every document and chunk and is not recoverable. Delete one definition at a time with `DELETE /api/v2/knowledge/{knowledgeBaseId}/tags/{tagId}`. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
},
|
||
{
|
||
"name": "unused",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Whether to remove only the tag definitions no document in the knowledge base still carries a value for. Defaults to true. Pass `unused=false` to delete every definition on the knowledge base, which also clears its slot on every document and chunk and is not recoverable.",
|
||
"schema": {
|
||
"description": "Whether to remove only the tag definitions no document in the knowledge base still carries a value for. Defaults to true. Pass `unused=false` to delete every definition on the knowledge base, which also clears its slot on every document and chunk and is not recoverable.",
|
||
"type": "boolean"
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Number of tag definitions removed.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2DeleteKnowledgeTagDefinitionsResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/documents": {
|
||
"get": {
|
||
"operationId": "listKnowledgeDocuments",
|
||
"summary": "List Documents",
|
||
"description": "List documents 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/{knowledgeBaseId}/tags`.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
},
|
||
{
|
||
"name": "limit",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Maximum documents to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"schema": {
|
||
"default": 50,
|
||
"description": "Maximum documents to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 100
|
||
}
|
||
},
|
||
{
|
||
"name": "search",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Case-insensitive substring match against the document filename.",
|
||
"schema": {
|
||
"description": "Case-insensitive substring match against the document filename.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 200
|
||
}
|
||
},
|
||
{
|
||
"name": "enabledFilter",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Filter by whether documents are enabled for search.",
|
||
"schema": {
|
||
"default": "all",
|
||
"description": "Filter by whether documents are enabled for search.",
|
||
"type": "string",
|
||
"enum": ["all", "enabled", "disabled"]
|
||
}
|
||
},
|
||
{
|
||
"name": "sortBy",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Field used to sort the result. 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/{knowledgeBaseId}/documents/{documentId}`. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Operation and the documents it applies to.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/BulkUpdateKnowledgeDocumentsRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "The number and identifiers of the documents that changed.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2BulkKnowledgeDocumentsResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"post": {
|
||
"operationId": "uploadKnowledgeDocument",
|
||
"summary": "Upload Document",
|
||
"description": "Upload one document as multipart form data. Processing continues asynchronously after the document is accepted.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Multipart form containing the document file.",
|
||
"content": {
|
||
"multipart/form-data": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/UploadKnowledgeDocumentForm"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"201": {
|
||
"description": "The accepted document queued for processing.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeDocumentSummaryResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"402": {
|
||
"$ref": "#/components/responses/UsageLimitExceeded"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/documents/uploads": {
|
||
"post": {
|
||
"operationId": "createKnowledgeDocumentUpload",
|
||
"summary": "Create Document Upload",
|
||
"description": "Create a resumable upload session and receive direct PUT or multipart transfer instructions.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Document metadata used to authorize and initialize the upload.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateKnowledgeDocumentUploadRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"201": {
|
||
"description": "The created upload session and transfer instructions.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2CreateKnowledgeDocumentUploadResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"402": {
|
||
"$ref": "#/components/responses/UsageLimitExceeded"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/documents/uploads/{uploadId}": {
|
||
"delete": {
|
||
"operationId": "abortKnowledgeDocumentUpload",
|
||
"summary": "Abort Document Upload",
|
||
"description": "Abort an incomplete upload and discard provider-side multipart state.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "uploadId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Upload session identifier returned when the upload was created.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Upload session identifier returned when the upload was created."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
},
|
||
{
|
||
"name": "upload-token",
|
||
"in": "header",
|
||
"required": true,
|
||
"description": "Signed upload control token returned when the upload session was created.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Signed upload control token returned when the upload session was created."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The aborted upload session.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeDocumentUploadResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/documents/uploads/{uploadId}/parts": {
|
||
"post": {
|
||
"operationId": "createKnowledgeDocumentUploadPartUrls",
|
||
"summary": "Create Document Upload Part URLs",
|
||
"description": "Issue short-lived signed PUT URLs for up to 100 multipart part numbers.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "uploadId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Upload session identifier returned when the upload was created.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Upload session identifier returned when the upload was created."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
},
|
||
{
|
||
"name": "upload-token",
|
||
"in": "header",
|
||
"required": true,
|
||
"description": "Signed upload control token returned when the upload session was created.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Signed upload control token returned when the upload session was created."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Multipart part numbers for which signed URLs should be created.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateKnowledgeDocumentUploadPartUrlsRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "Signed URLs for the requested upload parts.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeDocumentUploadPartUrlsResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/documents/uploads/{uploadId}/complete": {
|
||
"post": {
|
||
"operationId": "completeKnowledgeDocumentUpload",
|
||
"summary": "Complete Document Upload",
|
||
"description": "Verify a direct upload or assemble multipart parts, create the knowledge document, and queue asynchronous processing.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "uploadId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Upload session identifier returned when the upload was created.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Upload session identifier returned when the upload was created."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
},
|
||
{
|
||
"name": "upload-token",
|
||
"in": "header",
|
||
"required": true,
|
||
"description": "Signed upload control token returned when the upload session was created.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Signed upload control token returned when the upload session was created."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The completed upload and queued document.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeDocumentUploadResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}": {
|
||
"get": {
|
||
"operationId": "getKnowledgeDocument",
|
||
"summary": "Get Document",
|
||
"description": "Retrieve document detail, processing state, and connector provenance.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "documentId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge document identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge document identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The requested knowledge document.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeDocumentResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"patch": {
|
||
"operationId": "updateKnowledgeDocument",
|
||
"summary": "Update Document",
|
||
"description": "Rename a document, 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/{knowledgeBaseId}/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": "documentId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge document identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge document identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Filename, search state, tag slot values, or a processing retry.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/UpdateKnowledgeDocumentRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "The updated document, or the requeue acknowledgement.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2UpdateKnowledgeDocumentResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"delete": {
|
||
"operationId": "deleteKnowledgeDocument",
|
||
"summary": "Delete Document",
|
||
"description": "Remove 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": "documentId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge document identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge document identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Knowledge document deletion acknowledgement.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeDeleteResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/folders": {
|
||
"get": {
|
||
"operationId": "listKnowledgeFolders",
|
||
"summary": "List Folders",
|
||
"description": "List folders in the knowledge-base folder tree with filtering and sorting. 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"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"patch": {
|
||
"operationId": "relocateKnowledgeFolder",
|
||
"summary": "Rename or Move Folder",
|
||
"description": "Rename or move a folder and atomically rewrite descendant paths. 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"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"delete": {
|
||
"operationId": "deleteKnowledgeFolder",
|
||
"summary": "Delete Folder",
|
||
"description": "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"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/restore": {
|
||
"post": {
|
||
"operationId": "restoreKnowledgeBase",
|
||
"summary": "Restore Knowledge Base",
|
||
"description": "Un-archive a soft-deleted knowledge base along with its documents and connectors. Idempotent: a knowledge base that is already active is returned unchanged with no audit entry recorded. Restoring into an archived workspace is a `409`, and a knowledge base whose folder is still archived is returned to the workspace root. A workspace folder tree over 10,000 folders is a `413`.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace scope for the knowledge base.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/RestoreKnowledgeBaseRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "The restored knowledge base.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeBaseResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/documents/from-workspace-files": {
|
||
"post": {
|
||
"operationId": "addWorkspaceFilesToKnowledgeBase",
|
||
"summary": "Index Workspace Files",
|
||
"description": "Index files the workspace already stores, without re-uploading their bytes. Each reference is authorized against the file it names, so a reference the caller cannot read, one over the 100 MB document limit, or one whose type is not supported is reported in `failed` while the rest are queued — a partial outcome is a `200`, not a multi-status. A queued document starts in the `pending` processing state; the entries returned here carry only its identity, so read `GET /api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}` for its current state. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace scope and the workspace file references to index.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/AddWorkspaceFilesToKnowledgeBaseRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "Files queued for indexing, with any that could not be.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2AddWorkspaceFilesToKnowledgeBaseResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"402": {
|
||
"$ref": "#/components/responses/UsageLimitExceeded"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}/chunks": {
|
||
"get": {
|
||
"operationId": "listKnowledgeChunks",
|
||
"summary": "List Chunks",
|
||
"description": "List the passages a document was split into, with content search, enabled filtering, sorting, and opaque cursor pagination. Tag values are projected by slot; resolve slots to display names with `GET /api/v2/knowledge/{knowledgeBaseId}/tags`. A document that has not finished processing answers `409`; the message names the status it is in. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "documentId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge document identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge document identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
},
|
||
{
|
||
"name": "search",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Case-insensitive substring match against chunk content.",
|
||
"schema": {
|
||
"description": "Case-insensitive substring match against chunk content.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 200
|
||
}
|
||
},
|
||
{
|
||
"name": "enabled",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Restrict to enabled or disabled chunks. `all` returns both.",
|
||
"schema": {
|
||
"default": "all",
|
||
"description": "Restrict to enabled or disabled chunks. `all` returns both.",
|
||
"type": "string",
|
||
"enum": ["true", "false", "all"]
|
||
}
|
||
},
|
||
{
|
||
"name": "sortBy",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Field used to sort the result.",
|
||
"schema": {
|
||
"default": "chunkIndex",
|
||
"description": "Field used to sort the result.",
|
||
"type": "string",
|
||
"enum": ["chunkIndex", "tokenCount", "enabled"]
|
||
}
|
||
},
|
||
{
|
||
"name": "sortOrder",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Sort direction.",
|
||
"schema": {
|
||
"default": "asc",
|
||
"description": "Sort direction.",
|
||
"type": "string",
|
||
"enum": ["asc", "desc"]
|
||
}
|
||
},
|
||
{
|
||
"name": "limit",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Maximum chunks to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"schema": {
|
||
"default": 50,
|
||
"description": "Maximum chunks to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 100
|
||
}
|
||
},
|
||
{
|
||
"name": "cursor",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"schema": {
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "A page of document chunks.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeChunkListResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"post": {
|
||
"operationId": "createKnowledgeChunk",
|
||
"summary": "Create Chunk",
|
||
"description": "Append a chunk to a document. The text is embedded before the response returns, so the chunk is searchable immediately, and it inherits the document's tag values and the next `chunkIndex`. Chunks of a connector-synced document are read-only and a write answers `403` with `error.details.code: \"CONNECTOR_MANAGED_RESOURCE_READ_ONLY\"` — change the content at the source and re-sync, or exclude the document from the connector. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "documentId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge document identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge document identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace scope and the text to embed.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateKnowledgeChunkRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"201": {
|
||
"description": "The created chunk.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeChunkResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"patch": {
|
||
"operationId": "bulkUpdateKnowledgeChunks",
|
||
"summary": "Bulk Update Chunks",
|
||
"description": "Enable, disable, or delete many chunks of one document in a single request. Best-effort: an identifier naming no chunk in the document is reported in `errors` rather than failing the request. `processed` counts the chunks the operation matched, not the chunks it changed. Chunks of a connector-synced document are read-only and a write answers `403` with `error.details.code: \"CONNECTOR_MANAGED_RESOURCE_READ_ONLY\"` — change the content at the source and re-sync, or exclude the document from the connector. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "documentId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge document identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge document identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace scope, the operation to apply, and the chunks to apply it to.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/BulkUpdateKnowledgeChunksRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "Outcome of the bulk chunk operation.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2BulkKnowledgeChunksResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}/chunks/{chunkId}": {
|
||
"get": {
|
||
"operationId": "getKnowledgeChunk",
|
||
"summary": "Get Chunk",
|
||
"description": "Retrieve one chunk of a document, including the exact text that was embedded. A document that has not finished processing answers `409`; the message names the status it is in. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "documentId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge document identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge document identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "chunkId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique chunk identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique chunk identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The requested chunk.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeChunkResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"patch": {
|
||
"operationId": "updateKnowledgeChunk",
|
||
"summary": "Update Chunk",
|
||
"description": "Correct a chunk's text or take it out of search. Changing `content` re-embeds the chunk and re-derives the document's token and character counts, so the correction reaches search immediately; disabling keeps the chunk indexed. Chunks of a connector-synced document are read-only and a write answers `403` with `error.details.code: \"CONNECTOR_MANAGED_RESOURCE_READ_ONLY\"` — change the content at the source and re-sync, or exclude the document from the connector. A document that has not finished processing answers `409`; the message names the status it is in. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "documentId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge document identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge document identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "chunkId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique chunk identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique chunk identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace scope and the fields to update. At least one is required.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/UpdateKnowledgeChunkRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "The updated chunk.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeChunkResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"delete": {
|
||
"operationId": "deleteKnowledgeChunk",
|
||
"summary": "Delete Chunk",
|
||
"description": "Permanently remove one chunk and subtract it from the document's counts. Deleting does not renumber the remaining chunks, so `chunkIndex` values stay stable but become non-contiguous. Chunks of a connector-synced document are read-only and a write answers `403` with `error.details.code: \"CONNECTOR_MANAGED_RESOURCE_READ_ONLY\"` — change the content at the source and re-sync, or exclude the document from the connector. A document that has not finished processing answers `409`; the message names the status it is in. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "documentId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge document identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge document identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "chunkId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique chunk identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique chunk identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Chunk deletion acknowledgement.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeDeleteResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/tags/{tagId}": {
|
||
"patch": {
|
||
"operationId": "updateKnowledgeTag",
|
||
"summary": "Update Tag",
|
||
"description": "Rename a tag, or change the value type stored in its slot. Renaming changes the name filters and document reads use; the slot, and every value in it, is untouched. A tag's slot is fixed for its lifetime and each slot holds one kind of value, so `fieldType` can only change to another type valid for the slot the tag already occupies — anything else is a `400`, and the way to get a tag of that type is to create one. A name another tag on this knowledge base already holds is a `409`. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "tagId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique tag definition identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique tag definition identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace scope and the fields to update. At least one is required.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/UpdateKnowledgeTagRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "The updated tag definition.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeTagResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"delete": {
|
||
"operationId": "deleteKnowledgeTag",
|
||
"summary": "Delete Tag",
|
||
"description": "Remove a tag definition and clear its slot across every document and chunk in the knowledge base. Without a definition the slot has no meaning, so leaving the values would strand them under a raw slot name — this is not recoverable. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "tagId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique tag definition identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique tag definition identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Tag deletion acknowledgement.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2DeleteKnowledgeTagResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/tags/next-slot": {
|
||
"get": {
|
||
"operationId": "getNextKnowledgeTagSlot",
|
||
"summary": "Get Next Tag Slot",
|
||
"description": "Report which slot a create would take for a field type, and how many are left. Advisory rather than a claim: nothing is reserved, and `POST /api/v2/knowledge/{knowledgeBaseId}/tags` assigns the same slot when `tagSlot` is omitted. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
},
|
||
{
|
||
"name": "fieldType",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Value type stored in the slot; it decides which slots are usable and which filter operators apply. Slot capacity per type: text 7, number 5, date 2, boolean 3.",
|
||
"schema": {
|
||
"type": "string",
|
||
"enum": ["text", "number", "date", "boolean"],
|
||
"description": "Value type stored in the slot; it decides which slots are usable and which filter operators apply. Slot capacity per type: text 7, number 5, date 2, boolean 3.",
|
||
"examples": ["text"]
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Slot availability for the requested field type.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2NextKnowledgeTagSlotResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/knowledge/{knowledgeBaseId}/tags/usage": {
|
||
"get": {
|
||
"operationId": "listKnowledgeTagUsage",
|
||
"summary": "List Tag Usage",
|
||
"description": "Report how many documents and chunks carry a value for each defined tag, so a caller can tell a tag that is actually populated from one that was only declared. The bounded set is returned in one page; `nextCursor` is always null. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Knowledge Bases"],
|
||
"parameters": [
|
||
{
|
||
"name": "knowledgeBaseId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique knowledge base identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique knowledge base identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the knowledge base.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Usage counts for every defined tag.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2KnowledgeTagUsageListResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"components": {
|
||
"securitySchemes": {
|
||
"apiKey": {
|
||
"type": "apiKey",
|
||
"in": "header",
|
||
"name": "X-API-Key",
|
||
"description": "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- `ORGANIZATION_PLAN_REQUIRED` — The organization has no active organization subscription (Pro for Teams, Max for Teams, or Enterprise).\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.\n- `WORKSPACE_PLAN_CAPABILITY_REQUIRED` — The workspace's plan does not include a capability this request depends on. The message names the capability; upgrading the workspace's plan is the remedy.\n- `CHAT_AUTH_MODE_NOT_PERMITTED` — The workspace's permission group does not allow the chat authentication mode the request selected. A mode already saved on the deployment may still be re-saved; changing to a disallowed one cannot.\n- `CONNECTOR_MANAGED_RESOURCE_READ_ONLY` — This resource is managed by a knowledge base connector and cannot be edited directly. Change it at the source and re-sync, or exclude the document from the connector."
|
||
}
|
||
},
|
||
"required": ["code", "message"],
|
||
"additionalProperties": false,
|
||
"description": "Canonical error details."
|
||
}
|
||
},
|
||
"required": ["error"],
|
||
"additionalProperties": false,
|
||
"title": "v2 error response",
|
||
"description": "Canonical error envelope returned by the public v2 API.",
|
||
"examples": [
|
||
{
|
||
"error": {
|
||
"code": "BAD_REQUEST",
|
||
"message": "The request is invalid."
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"FolderPathInput": {
|
||
"title": "Folder path input",
|
||
"description": "Folder path. A missing leading slash is normalized before validation. Segments are percent-encoded, so a folder shown as \"New folder\" is `/New%20folder`: everything outside `A-Z a-z 0-9 - _ . ~` is escaped as uppercase hex, and only that exact encoding is accepted. A trailing slash, an empty segment, and a literal `.` or `..` segment are rejected. At most 64 segments and 4096 encoded bytes.",
|
||
"maxLength": 4096,
|
||
"type": "string"
|
||
},
|
||
"V2KnowledgeBase": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Unique knowledge base identifier.",
|
||
"examples": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"]
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"description": "Human-readable knowledge base name.",
|
||
"examples": ["Product Documentation"]
|
||
},
|
||
"description": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Knowledge base description, or null when none is set.",
|
||
"examples": ["All product documentation and guides"]
|
||
},
|
||
"tokenCount": {
|
||
"type": "number",
|
||
"description": "Total tokens across indexed documents.",
|
||
"examples": [48213]
|
||
},
|
||
"embeddingModel": {
|
||
"type": "string",
|
||
"description": "Embedding model used to index documents.",
|
||
"examples": ["text-embedding-3-small"]
|
||
},
|
||
"embeddingDimension": {
|
||
"type": "number",
|
||
"description": "Dimensionality of the embedding vectors.",
|
||
"examples": [1536]
|
||
},
|
||
"chunkingConfig": {
|
||
"$ref": "#/components/schemas/V2KnowledgeChunkingConfig"
|
||
},
|
||
"docCount": {
|
||
"description": "Number of documents in the knowledge base.",
|
||
"examples": [12],
|
||
"type": "number"
|
||
},
|
||
"connectorTypes": {
|
||
"description": "External connector types that have synced documents into the knowledge base.",
|
||
"examples": [["notion", "google_drive"]],
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
"createdAt": {
|
||
"type": "string",
|
||
"description": "ISO 8601 timestamp when the knowledge base was created.",
|
||
"format": "date-time",
|
||
"examples": ["2025-01-10T09:00:00Z"]
|
||
},
|
||
"updatedAt": {
|
||
"type": "string",
|
||
"description": "ISO 8601 timestamp when the knowledge base was last modified.",
|
||
"format": "date-time",
|
||
"examples": ["2025-06-18T16:45:00Z"]
|
||
},
|
||
"webUrl": {
|
||
"type": "string",
|
||
"format": "uri",
|
||
"description": "Canonical absolute URL for opening this resource in the Sim web application."
|
||
},
|
||
"ownerEmail": {
|
||
"type": "string",
|
||
"format": "email",
|
||
"pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
|
||
"description": "Current email address of the knowledge base owner.",
|
||
"examples": ["owner@example.com"]
|
||
},
|
||
"folderPath": {
|
||
"type": "string",
|
||
"title": "Folder path",
|
||
"description": "Canonical containing-folder path; `/` is the workspace root. Resolved against active folders only, so an archived knowledge base whose containing folder was archived with it reports `/`.",
|
||
"maxLength": 4096,
|
||
"examples": ["/Product"]
|
||
},
|
||
"deletedAt": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "ISO 8601 timestamp when the knowledge base was archived by `DELETE /knowledge/{knowledgeBaseId}`, or null while the knowledge base is active. Only `GET /knowledge?scope=archived` returns knowledge bases with a non-null value.",
|
||
"format": "date-time",
|
||
"examples": ["2026-01-16T09:00:00Z"]
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"name",
|
||
"description",
|
||
"tokenCount",
|
||
"embeddingModel",
|
||
"embeddingDimension",
|
||
"chunkingConfig",
|
||
"createdAt",
|
||
"updatedAt",
|
||
"webUrl",
|
||
"ownerEmail",
|
||
"folderPath",
|
||
"deletedAt"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge base",
|
||
"description": "A collection of documents indexed for vector and tag search."
|
||
},
|
||
"V2KnowledgeChunkingConfig": {
|
||
"type": "object",
|
||
"properties": {
|
||
"maxSize": {
|
||
"type": "number",
|
||
"description": "Maximum chunk size in tokens.",
|
||
"examples": [1024]
|
||
},
|
||
"minSize": {
|
||
"type": "number",
|
||
"description": "Minimum chunk size in characters.",
|
||
"examples": [100]
|
||
},
|
||
"overlap": {
|
||
"type": "number",
|
||
"description": "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
|
||
},
|
||
"strategy": {
|
||
"description": "Chunking strategy applied during document processing. `regex` additionally requires `strategyOptions.pattern`.",
|
||
"type": "string",
|
||
"enum": ["auto", "text", "regex", "recursive", "sentence", "token"]
|
||
},
|
||
"strategyOptions": {
|
||
"description": "Strategy-specific tuning options. `strictBoundaries` is accepted only with `strategy: \"regex\"`.",
|
||
"type": "object",
|
||
"properties": {
|
||
"pattern": {
|
||
"description": "Regular expression used by the regex chunking strategy.",
|
||
"type": "string",
|
||
"maxLength": 500
|
||
},
|
||
"separators": {
|
||
"description": "Ordered separators used to split content into chunks.",
|
||
"maxItems": 32,
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string",
|
||
"maxLength": 100
|
||
}
|
||
},
|
||
"recipe": {
|
||
"description": "Content-aware recipe used by the automatic chunking strategy.",
|
||
"type": "string",
|
||
"enum": ["plain", "markdown", "code"]
|
||
},
|
||
"strictBoundaries": {
|
||
"description": "Whether regex matches must form strict chunk boundaries.",
|
||
"type": "boolean"
|
||
}
|
||
},
|
||
"additionalProperties": false
|
||
}
|
||
},
|
||
"additionalProperties": false,
|
||
"title": "Knowledge chunking configuration input",
|
||
"description": "Chunking configuration applied when processing documents. On update this object is replaced wholesale rather than merged, so a caller preserving one key must read, modify, and write the whole object back."
|
||
},
|
||
"CreateKnowledgeBaseRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace in which to create the knowledge base."
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Human-readable knowledge base name.",
|
||
"examples": ["Product Documentation"]
|
||
},
|
||
"description": {
|
||
"description": "Optional knowledge base description.",
|
||
"examples": ["All product documentation and guides"],
|
||
"type": "string",
|
||
"maxLength": 10000
|
||
},
|
||
"chunkingConfig": {
|
||
"default": {
|
||
"maxSize": 1024,
|
||
"minSize": 100,
|
||
"overlap": 200
|
||
},
|
||
"description": "Chunking configuration; defaults are applied when omitted.",
|
||
"$ref": "#/components/schemas/V2KnowledgeChunkingConfigInput"
|
||
},
|
||
"folderPath": {
|
||
"description": "Containing folder path; omission creates the knowledge base at the root.",
|
||
"$ref": "#/components/schemas/FolderPathInput"
|
||
}
|
||
},
|
||
"required": ["workspaceId", "name"],
|
||
"additionalProperties": false,
|
||
"title": "Create knowledge base request",
|
||
"description": "Workspace, name, description, chunking configuration, and folder placement."
|
||
},
|
||
"UpdateKnowledgeBaseRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
},
|
||
"name": {
|
||
"description": "New knowledge base name.",
|
||
"examples": ["Updated Product Documentation"],
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255
|
||
},
|
||
"description": {
|
||
"description": "New knowledge base description.",
|
||
"examples": ["Refreshed product documentation and guides"],
|
||
"type": "string",
|
||
"maxLength": 10000
|
||
},
|
||
"chunkingConfig": {
|
||
"description": "New document chunking configuration.",
|
||
"$ref": "#/components/schemas/V2KnowledgeChunkingConfigInput"
|
||
},
|
||
"folderPath": {
|
||
"description": "New containing-folder path.",
|
||
"$ref": "#/components/schemas/FolderPathInput"
|
||
}
|
||
},
|
||
"required": ["workspaceId"],
|
||
"additionalProperties": false,
|
||
"title": "Update knowledge base request",
|
||
"description": "Workspace scope and fields to update. At least one mutable field is required."
|
||
},
|
||
"V2KnowledgeDeleteData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Identifier of the deleted resource.",
|
||
"examples": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"]
|
||
},
|
||
"deleted": {
|
||
"type": "boolean",
|
||
"const": true,
|
||
"description": "Confirms that the resource was deleted."
|
||
}
|
||
},
|
||
"required": ["id", "deleted"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge deletion data",
|
||
"description": "Acknowledgement for a deleted knowledge base or document."
|
||
},
|
||
"V2KnowledgeDeleteResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2KnowledgeDeleteData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge deletion response",
|
||
"description": "Deletion acknowledgement containing the removed resource identifier."
|
||
},
|
||
"V2KnowledgeConnector": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique connector identifier."
|
||
},
|
||
"knowledgeBaseId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Knowledge base synced by the connector."
|
||
},
|
||
"connectorType": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Registered external source type."
|
||
},
|
||
"credentialId": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "OAuth credential identifier, or null for API-key and unauthenticated sources."
|
||
},
|
||
"sourceConfig": {
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"description": "Connector-specific source configuration value."
|
||
},
|
||
"description": "Connector-specific source selection and filtering configuration."
|
||
},
|
||
"syncMode": {
|
||
"type": "string",
|
||
"description": "Synchronization mode used by the connector."
|
||
},
|
||
"syncIntervalMinutes": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Scheduled synchronization interval in minutes; zero disables scheduled syncs."
|
||
},
|
||
"status": {
|
||
"type": "string",
|
||
"enum": ["active", "paused", "pending", "syncing", "error", "disabled"],
|
||
"description": "Current connector state. `pending` means a sync is queued but not yet running."
|
||
},
|
||
"lastSyncAt": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Time of the most recent synchronization, or null before the first sync."
|
||
},
|
||
"lastSyncError": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Most recent synchronization error, or null when none is recorded."
|
||
},
|
||
"lastSyncDocCount": {
|
||
"anyOf": [
|
||
{
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Documents observed by the most recent synchronization."
|
||
},
|
||
"nextSyncAt": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Next scheduled synchronization time, or null when not scheduled."
|
||
},
|
||
"consecutiveFailures": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Number of consecutive synchronization failures."
|
||
},
|
||
"createdAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "Time the connector was created."
|
||
},
|
||
"updatedAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "Time the connector was last updated."
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"knowledgeBaseId",
|
||
"connectorType",
|
||
"credentialId",
|
||
"sourceConfig",
|
||
"syncMode",
|
||
"syncIntervalMinutes",
|
||
"status",
|
||
"lastSyncAt",
|
||
"lastSyncError",
|
||
"lastSyncDocCount",
|
||
"nextSyncAt",
|
||
"consecutiveFailures",
|
||
"createdAt",
|
||
"updatedAt"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector",
|
||
"description": "An external document source linked to a knowledge base, without secret material."
|
||
},
|
||
"V2KnowledgeConnectorListResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2KnowledgeConnector"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector list response",
|
||
"description": "A cursor-paginated page of connectors without secret material.",
|
||
"examples": [
|
||
{
|
||
"data": [
|
||
{
|
||
"id": "kc-9f8e7d6c",
|
||
"knowledgeBaseId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
|
||
"connectorType": "notion",
|
||
"credentialId": "cred-4b3a2c1d",
|
||
"sourceConfig": {
|
||
"pageIds": ["page-123"]
|
||
},
|
||
"syncMode": "full",
|
||
"syncIntervalMinutes": 1440,
|
||
"status": "active",
|
||
"lastSyncAt": "2026-06-20T14:02:11.000Z",
|
||
"lastSyncError": null,
|
||
"lastSyncDocCount": 42,
|
||
"nextSyncAt": "2026-06-21T14:02:11.000Z",
|
||
"consecutiveFailures": 0,
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z"
|
||
}
|
||
],
|
||
"nextCursor": null
|
||
}
|
||
]
|
||
},
|
||
"V2KnowledgeConnectorResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2KnowledgeConnector"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector response",
|
||
"description": "A single connector without secret material.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "kc-9f8e7d6c",
|
||
"knowledgeBaseId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
|
||
"connectorType": "notion",
|
||
"credentialId": "cred-4b3a2c1d",
|
||
"sourceConfig": {
|
||
"pageIds": ["page-123"]
|
||
},
|
||
"syncMode": "full",
|
||
"syncIntervalMinutes": 1440,
|
||
"status": "active",
|
||
"lastSyncAt": "2026-06-20T14:02:11.000Z",
|
||
"lastSyncError": null,
|
||
"lastSyncDocCount": 42,
|
||
"nextSyncAt": "2026-06-21T14:02:11.000Z",
|
||
"consecutiveFailures": 0,
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z"
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"CreateKnowledgeConnectorRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
},
|
||
"connectorType": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 100,
|
||
"description": "Registered connector type."
|
||
},
|
||
"credentialId": {
|
||
"description": "OAuth credential identifier for connectors that require OAuth.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255
|
||
},
|
||
"apiKey": {
|
||
"description": "Write-only API key for connectors that use API-key authentication.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 10000
|
||
},
|
||
"sourceConfig": {
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"description": "Connector-specific source configuration value."
|
||
},
|
||
"description": "Connector-specific source selection and filtering configuration."
|
||
},
|
||
"syncIntervalMinutes": {
|
||
"default": 1440,
|
||
"description": "Scheduled synchronization interval in minutes; zero disables scheduling.",
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 525600
|
||
}
|
||
},
|
||
"required": ["workspaceId", "connectorType", "sourceConfig"],
|
||
"additionalProperties": false,
|
||
"title": "Create knowledge connector request",
|
||
"description": "Workspace, connector type, authentication reference, source configuration, and sync schedule.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"connectorType": "notion",
|
||
"credentialId": "cred-4b3a2c1d",
|
||
"sourceConfig": {
|
||
"pageIds": ["page-123"]
|
||
},
|
||
"syncIntervalMinutes": 1440
|
||
}
|
||
]
|
||
},
|
||
"V2KnowledgeConnectorSyncLog": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique synchronization log identifier."
|
||
},
|
||
"connectorId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Connector that produced the log."
|
||
},
|
||
"status": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Synchronization outcome or current state."
|
||
},
|
||
"startedAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "Time synchronization started."
|
||
},
|
||
"completedAt": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Time synchronization completed, or null while it is running."
|
||
},
|
||
"docsAdded": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Documents added."
|
||
},
|
||
"docsUpdated": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Documents updated."
|
||
},
|
||
"docsDeleted": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Documents deleted."
|
||
},
|
||
"docsUnchanged": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Documents unchanged."
|
||
},
|
||
"docsSkipped": {
|
||
"default": 0,
|
||
"description": "Documents intentionally skipped because they could not be indexed safely.",
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991
|
||
},
|
||
"docsFailed": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Documents that failed to synchronize."
|
||
},
|
||
"errorMessage": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Synchronization error, or null."
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"connectorId",
|
||
"status",
|
||
"startedAt",
|
||
"completedAt",
|
||
"docsAdded",
|
||
"docsUpdated",
|
||
"docsDeleted",
|
||
"docsUnchanged",
|
||
"docsSkipped",
|
||
"docsFailed",
|
||
"errorMessage"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector sync log",
|
||
"description": "One synchronization attempt for a knowledge connector."
|
||
},
|
||
"V2KnowledgeConnectorDetail": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique connector identifier."
|
||
},
|
||
"knowledgeBaseId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Knowledge base synced by the connector."
|
||
},
|
||
"connectorType": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Registered external source type."
|
||
},
|
||
"credentialId": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "OAuth credential identifier, or null for API-key and unauthenticated sources."
|
||
},
|
||
"sourceConfig": {
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"description": "Connector-specific source configuration value."
|
||
},
|
||
"description": "Connector-specific source selection and filtering configuration."
|
||
},
|
||
"syncMode": {
|
||
"type": "string",
|
||
"description": "Synchronization mode used by the connector."
|
||
},
|
||
"syncIntervalMinutes": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Scheduled synchronization interval in minutes; zero disables scheduled syncs."
|
||
},
|
||
"status": {
|
||
"type": "string",
|
||
"enum": ["active", "paused", "pending", "syncing", "error", "disabled"],
|
||
"description": "Current connector state. `pending` means a sync is queued but not yet running."
|
||
},
|
||
"lastSyncAt": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Time of the most recent synchronization, or null before the first sync."
|
||
},
|
||
"lastSyncError": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Most recent synchronization error, or null when none is recorded."
|
||
},
|
||
"lastSyncDocCount": {
|
||
"anyOf": [
|
||
{
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Documents observed by the most recent synchronization."
|
||
},
|
||
"nextSyncAt": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Next scheduled synchronization time, or null when not scheduled."
|
||
},
|
||
"consecutiveFailures": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Number of consecutive synchronization failures."
|
||
},
|
||
"createdAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "Time the connector was created."
|
||
},
|
||
"updatedAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "Time the connector was last updated."
|
||
},
|
||
"syncLogs": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2KnowledgeConnectorSyncLog"
|
||
},
|
||
"description": "The ten most recent synchronization attempts."
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"knowledgeBaseId",
|
||
"connectorType",
|
||
"credentialId",
|
||
"sourceConfig",
|
||
"syncMode",
|
||
"syncIntervalMinutes",
|
||
"status",
|
||
"lastSyncAt",
|
||
"lastSyncError",
|
||
"lastSyncDocCount",
|
||
"nextSyncAt",
|
||
"consecutiveFailures",
|
||
"createdAt",
|
||
"updatedAt",
|
||
"syncLogs"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector detail",
|
||
"description": "A knowledge connector and its recent synchronization history."
|
||
},
|
||
"V2KnowledgeConnectorDetailResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2KnowledgeConnectorDetail"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector detail response",
|
||
"description": "A connector and recent synchronization history without secret material.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "kc-9f8e7d6c",
|
||
"knowledgeBaseId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
|
||
"connectorType": "notion",
|
||
"credentialId": "cred-4b3a2c1d",
|
||
"sourceConfig": {
|
||
"pageIds": ["page-123"]
|
||
},
|
||
"syncMode": "full",
|
||
"syncIntervalMinutes": 1440,
|
||
"status": "active",
|
||
"lastSyncAt": "2026-06-20T14:02:11.000Z",
|
||
"lastSyncError": null,
|
||
"lastSyncDocCount": 42,
|
||
"nextSyncAt": "2026-06-21T14:02:11.000Z",
|
||
"consecutiveFailures": 0,
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z",
|
||
"syncLogs": []
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"UpdateKnowledgeConnectorRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
},
|
||
"sourceConfig": {
|
||
"description": "Replacement source selection and filtering configuration. Updating a runnable connector queues synchronization; paused connectors remain paused.",
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"description": "Connector-specific source configuration value."
|
||
}
|
||
},
|
||
"syncIntervalMinutes": {
|
||
"description": "New scheduled synchronization interval in minutes.",
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 525600
|
||
},
|
||
"status": {
|
||
"description": "New connector state.",
|
||
"type": "string",
|
||
"enum": ["active", "paused"]
|
||
}
|
||
},
|
||
"required": ["workspaceId"],
|
||
"additionalProperties": false,
|
||
"title": "Update knowledge connector request",
|
||
"description": "Workspace scope and at least one mutable connector field.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"status": "paused"
|
||
}
|
||
]
|
||
},
|
||
"V2KnowledgeConnectorDeleteData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Deleted connector identifier."
|
||
},
|
||
"deleted": {
|
||
"type": "boolean",
|
||
"const": true,
|
||
"description": "Whether the connector was deleted."
|
||
},
|
||
"documentsDeleted": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Connector documents deleted."
|
||
},
|
||
"documentsKept": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Connector documents retained."
|
||
}
|
||
},
|
||
"required": ["id", "deleted", "documentsDeleted", "documentsKept"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector deletion data",
|
||
"description": "Connector deletion acknowledgement and affected document counts."
|
||
},
|
||
"V2KnowledgeConnectorDeleteResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2KnowledgeConnectorDeleteData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector delete response",
|
||
"description": "Deletion acknowledgement and affected document counts.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "kc-9f8e7d6c",
|
||
"deleted": true,
|
||
"documentsDeleted": 0,
|
||
"documentsKept": 42
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"V2KnowledgeConnectorSyncData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Connector queued for synchronization."
|
||
},
|
||
"syncTriggered": {
|
||
"type": "boolean",
|
||
"const": true,
|
||
"description": "Whether synchronization was queued."
|
||
}
|
||
},
|
||
"required": ["id", "syncTriggered"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector sync data",
|
||
"description": "Acknowledgement that connector synchronization was queued."
|
||
},
|
||
"V2KnowledgeConnectorSyncResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2KnowledgeConnectorSyncData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector sync response",
|
||
"description": "Acknowledgement that synchronization was queued.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "kc-9f8e7d6c",
|
||
"syncTriggered": true
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"SyncKnowledgeConnectorRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
},
|
||
"rehydrate": {
|
||
"default": false,
|
||
"description": "Re-fetch and re-index every existing connector document.",
|
||
"type": "boolean"
|
||
}
|
||
},
|
||
"required": ["workspaceId"],
|
||
"additionalProperties": false,
|
||
"title": "Sync knowledge connector request",
|
||
"description": "Workspace scope and optional full rehydration control.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"rehydrate": false
|
||
}
|
||
]
|
||
},
|
||
"V2KnowledgeConnectorDocument": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique document identifier."
|
||
},
|
||
"filename": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Document filename."
|
||
},
|
||
"externalId": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Identifier assigned by the external source."
|
||
},
|
||
"sourceUrl": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Original external source URL."
|
||
},
|
||
"enabled": {
|
||
"type": "boolean",
|
||
"description": "Whether the document is enabled for knowledge search."
|
||
},
|
||
"userExcluded": {
|
||
"type": "boolean",
|
||
"description": "Whether a user explicitly excluded the document from connector sync results."
|
||
},
|
||
"createdAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "Time the document was first synchronized."
|
||
},
|
||
"processingStatus": {
|
||
"type": "string",
|
||
"description": "Current document processing state."
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"filename",
|
||
"externalId",
|
||
"sourceUrl",
|
||
"enabled",
|
||
"userExcluded",
|
||
"createdAt",
|
||
"processingStatus"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector document",
|
||
"description": "A knowledge document produced by an external connector."
|
||
},
|
||
"V2KnowledgeConnectorDocumentListResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2KnowledgeConnectorDocument"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector document list response",
|
||
"description": "A cursor-paginated page of connector documents.",
|
||
"examples": [
|
||
{
|
||
"data": [
|
||
{
|
||
"id": "doc-8a7b6c5d",
|
||
"filename": "Product requirements",
|
||
"externalId": "page-123",
|
||
"sourceUrl": "https://www.notion.so/page-123",
|
||
"enabled": true,
|
||
"userExcluded": false,
|
||
"createdAt": "2026-06-01T09:15:00.000Z",
|
||
"processingStatus": "completed"
|
||
}
|
||
],
|
||
"nextCursor": null
|
||
}
|
||
]
|
||
},
|
||
"V2KnowledgeConnectorDocumentsUpdateData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"operation": {
|
||
"type": "string",
|
||
"enum": ["restore", "exclude"],
|
||
"description": "Operation that was applied."
|
||
},
|
||
"updatedCount": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Documents changed."
|
||
},
|
||
"documentIds": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "Identifiers of documents changed."
|
||
}
|
||
},
|
||
"required": ["operation", "updatedCount", "documentIds"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector documents update data",
|
||
"description": "Outcome of restoring or excluding connector documents."
|
||
},
|
||
"V2KnowledgeConnectorDocumentsUpdateResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2KnowledgeConnectorDocumentsUpdateData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge connector documents update response",
|
||
"description": "Operation result and identifiers actually changed.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"operation": "exclude",
|
||
"updatedCount": 1,
|
||
"documentIds": ["doc-8a7b6c5d"]
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"UpdateKnowledgeConnectorDocumentsRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
},
|
||
"operation": {
|
||
"type": "string",
|
||
"enum": ["restore", "exclude"],
|
||
"description": "Whether to restore or exclude the selected documents."
|
||
},
|
||
"documentIds": {
|
||
"minItems": 1,
|
||
"maxItems": 100,
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255
|
||
},
|
||
"description": "Connector document identifiers to update."
|
||
}
|
||
},
|
||
"required": ["workspaceId", "operation", "documentIds"],
|
||
"additionalProperties": false,
|
||
"title": "Update knowledge connector documents request",
|
||
"description": "Workspace, restore or exclude operation, and selected document identifiers.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"operation": "exclude",
|
||
"documentIds": ["doc-8a7b6c5d"]
|
||
}
|
||
]
|
||
},
|
||
"V2KnowledgeSearchResult": {
|
||
"type": "object",
|
||
"properties": {
|
||
"knowledgeBaseId": {
|
||
"type": "string",
|
||
"description": "Knowledge base the matching chunk came from; a search may span up to 20.",
|
||
"examples": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"]
|
||
},
|
||
"documentId": {
|
||
"type": "string",
|
||
"description": "Identifier of the document containing the matching chunk.",
|
||
"examples": ["b2d4f8a0-1c3e-4a5b-9d7c-2e6f0a8b4c12"]
|
||
},
|
||
"documentName": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Filename of the source document, or null when unavailable.",
|
||
"examples": ["getting-started.pdf"]
|
||
},
|
||
"sourceUrl": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Original source URL, or null for a directly uploaded document."
|
||
},
|
||
"content": {
|
||
"type": "string",
|
||
"description": "Text content of the matching chunk.",
|
||
"examples": ["To reset your password, open Settings and choose Security."]
|
||
},
|
||
"chunkIndex": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Zero-based chunk index within the document.",
|
||
"examples": [3]
|
||
},
|
||
"metadata": {
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"description": "User-defined string, number, boolean, or date tag value."
|
||
},
|
||
"description": "Document tag values keyed by tag display name.",
|
||
"examples": [
|
||
{
|
||
"category": "billing",
|
||
"priority": 2
|
||
}
|
||
]
|
||
},
|
||
"similarity": {
|
||
"type": "number",
|
||
"description": "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/{knowledgeBaseId}/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/{knowledgeBaseId}/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": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Tag definition identifier. Published because `PATCH` and `DELETE /knowledge/{knowledgeBaseId}/tags/{tagId}` address a definition by it; without it those operations are unreachable from a list read."
|
||
},
|
||
"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": ["id", "displayName", "tagSlot", "fieldType"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge tag",
|
||
"description": "A tag defined on a knowledge base, and the slot it is stored in."
|
||
},
|
||
"V2KnowledgeTagListResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2KnowledgeTag"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Always `null` — this list has no `cursor` or `limit` 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/{knowledgeBaseId}/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. The URL is signed and self-describing — construct it from this field only, never by hand.\n\n**Where this URL points depends on the deployment, and so does what answers you.** When Sim stores objects itself the URL is Sim's own data plane: success is `204` with an empty body, and 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. When object storage is configured — S3, Google Cloud Storage, or Azure Blob — the URL is that provider's own presigned URL, and the provider answers directly: treat **any `2xx` as success** (S3 and GCS answer `200`, Azure `201`), and on failure expect the provider's error document, typically XML, not the v2 envelope. Do not branch on `204` and do not parse a failure as JSON."
|
||
},
|
||
"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. One of: default, plain, markdown, code.",
|
||
"type": "string",
|
||
"enum": ["default", "plain", "markdown", "code"]
|
||
},
|
||
"lang": {
|
||
"description": "Optional document language: hyphen-separated letter and digit subtags such as `en`, `en-US`, or `zh-Hant-TW`. Only that shape is validated, not full BCP-47 conformance.",
|
||
"type": "string",
|
||
"maxLength": 35,
|
||
"pattern": "^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$"
|
||
}
|
||
},
|
||
"additionalProperties": false
|
||
}
|
||
},
|
||
"required": ["workspaceId", "name", "contentType", "size"],
|
||
"additionalProperties": false,
|
||
"title": "Create knowledge document upload request",
|
||
"description": "Document metadata used to authorize and initialize the upload.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"name": "getting-started.pdf",
|
||
"contentType": "application/pdf",
|
||
"size": 248913
|
||
}
|
||
]
|
||
},
|
||
"V2KnowledgeDocumentUploadResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2KnowledgeDocumentUpload"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge document upload response",
|
||
"description": "Current state of a knowledge document upload session."
|
||
},
|
||
"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. The URL is signed and self-describing — construct it from this field only, never by hand.\n\n**Where this URL points depends on the deployment, and so does what answers you.** When Sim stores objects itself the URL is Sim's own data plane: success is `204` with an empty body, and 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. When object storage is configured — S3, Google Cloud Storage, or Azure Blob — the URL is that provider's own presigned URL, and the provider answers directly: treat **any `2xx` as success** (S3 and GCS answer `200`, Azure `201`), and on failure expect the provider's error document, typically XML, not the v2 envelope. Do not branch on `204` and do not parse a failure as JSON.\n\nYou do not need to retain the `ETag` each part upload returns. Unlike a raw S3 multipart flow, completion takes no request body: Sim lists the uploaded parts from the provider itself and reads their entity tags there, so `POST .../complete` only has to happen after every part has been sent."
|
||
},
|
||
"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/{knowledgeBaseId}/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."
|
||
},
|
||
"RestoreKnowledgeBaseRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
}
|
||
},
|
||
"required": ["workspaceId"],
|
||
"additionalProperties": false,
|
||
"title": "Restore knowledge base request",
|
||
"description": "Workspace scope for the knowledge base.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64"
|
||
}
|
||
]
|
||
},
|
||
"V2AddedWorkspaceFileDocument": {
|
||
"type": "object",
|
||
"properties": {
|
||
"documentId": {
|
||
"type": "string",
|
||
"description": "Identifier of the queued knowledge document."
|
||
},
|
||
"filename": {
|
||
"type": "string",
|
||
"description": "Filename recorded on the knowledge document."
|
||
},
|
||
"mimeType": {
|
||
"type": "string",
|
||
"description": "MIME type of the source workspace file."
|
||
},
|
||
"fileSize": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "File size in bytes."
|
||
}
|
||
},
|
||
"required": ["documentId", "filename", "mimeType", "fileSize"],
|
||
"additionalProperties": false,
|
||
"title": "Indexed workspace file",
|
||
"description": "A workspace file that was queued for indexing into a knowledge base."
|
||
},
|
||
"V2AddWorkspaceFilesToKnowledgeBaseData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"knowledgeBaseId": {
|
||
"type": "string",
|
||
"description": "Knowledge base the files were added to."
|
||
},
|
||
"added": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2AddedWorkspaceFileDocument"
|
||
},
|
||
"description": "Files queued for indexing, in request order."
|
||
},
|
||
"failed": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "References that could not be indexed, echoed exactly as they were sent."
|
||
}
|
||
},
|
||
"required": ["knowledgeBaseId", "added", "failed"],
|
||
"additionalProperties": false,
|
||
"title": "Add workspace files data",
|
||
"description": "Outcome of indexing workspace files into a knowledge base."
|
||
},
|
||
"V2AddWorkspaceFilesToKnowledgeBaseResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2AddWorkspaceFilesToKnowledgeBaseData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Index workspace files response",
|
||
"description": "Documents queued for indexing and references that could not be."
|
||
},
|
||
"AddWorkspaceFilesToKnowledgeBaseRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns both the files and the base."
|
||
},
|
||
"fileReferences": {
|
||
"minItems": 1,
|
||
"maxItems": 100,
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
},
|
||
"description": "Workspace file identifiers or storage keys to index. Duplicates resolving to the same file are indexed once."
|
||
}
|
||
},
|
||
"required": ["workspaceId", "fileReferences"],
|
||
"additionalProperties": false,
|
||
"title": "Index workspace files request",
|
||
"description": "Workspace scope and the workspace file references to index.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"fileReferences": ["handbook.pdf"]
|
||
}
|
||
]
|
||
},
|
||
"V2KnowledgeChunk": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Unique chunk identifier.",
|
||
"examples": ["4c1f9e77-2b3a-4f8d-9e10-6a2c8d4b1e05"]
|
||
},
|
||
"chunkIndex": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Zero-based position of the chunk within its document.",
|
||
"examples": [3]
|
||
},
|
||
"content": {
|
||
"type": "string",
|
||
"description": "Text content of the chunk, exactly as it was embedded.",
|
||
"examples": ["To reset your password, open Settings and choose Security."]
|
||
},
|
||
"contentLength": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Character count of `content`.",
|
||
"examples": [58]
|
||
},
|
||
"tokenCount": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Tokens the chunk consumed when embedded.",
|
||
"examples": [14]
|
||
},
|
||
"enabled": {
|
||
"type": "boolean",
|
||
"description": "Whether the chunk participates in search. A disabled chunk stays indexed."
|
||
},
|
||
"startOffset": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Character offset of the chunk within the extracted document text."
|
||
},
|
||
"endOffset": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Character offset just past the end of the chunk."
|
||
},
|
||
"tag1": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Text tag value inherited from the document, or null when the slot is unset."
|
||
},
|
||
"tag2": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Text tag value inherited from the document, or null when the slot is unset."
|
||
},
|
||
"tag3": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Text tag value inherited from the document, or null when the slot is unset."
|
||
},
|
||
"tag4": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Text tag value inherited from the document, or null when the slot is unset."
|
||
},
|
||
"tag5": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Text tag value inherited from the document, or null when the slot is unset."
|
||
},
|
||
"tag6": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Text tag value inherited from the document, or null when the slot is unset."
|
||
},
|
||
"tag7": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Text tag value inherited from the document, or null when the slot is unset."
|
||
},
|
||
"createdAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "ISO 8601 timestamp when the chunk was created."
|
||
},
|
||
"updatedAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "ISO 8601 timestamp when the chunk was last modified."
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"chunkIndex",
|
||
"content",
|
||
"contentLength",
|
||
"tokenCount",
|
||
"enabled",
|
||
"startOffset",
|
||
"endOffset",
|
||
"tag1",
|
||
"tag2",
|
||
"tag3",
|
||
"tag4",
|
||
"tag5",
|
||
"tag6",
|
||
"tag7",
|
||
"createdAt",
|
||
"updatedAt"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge chunk",
|
||
"description": "One embedded passage of a knowledge document."
|
||
},
|
||
"V2KnowledgeChunkListResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2KnowledgeChunk"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge chunk list response",
|
||
"description": "A cursor-paginated page of document chunks."
|
||
},
|
||
"V2KnowledgeChunkResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2KnowledgeChunk"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge chunk response",
|
||
"description": "A single document chunk."
|
||
},
|
||
"CreateKnowledgeChunkRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
},
|
||
"content": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 10000,
|
||
"description": "Text to embed. It is embedded on write, so the chunk is searchable immediately."
|
||
},
|
||
"enabled": {
|
||
"default": true,
|
||
"description": "Whether the new chunk participates in search.",
|
||
"type": "boolean"
|
||
}
|
||
},
|
||
"required": ["workspaceId", "content"],
|
||
"additionalProperties": false,
|
||
"title": "Create knowledge chunk request",
|
||
"description": "Workspace scope and the text to embed.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"content": "To reset your password, open Settings and choose Security."
|
||
}
|
||
]
|
||
},
|
||
"V2BulkKnowledgeChunksData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"operation": {
|
||
"type": "string",
|
||
"enum": ["enable", "disable", "delete"],
|
||
"description": "Operation that was applied."
|
||
},
|
||
"processed": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Number of chunks in this document the operation matched. Chunks already in the requested state are counted too, so this is not a count of changes.",
|
||
"examples": [12]
|
||
},
|
||
"errors": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "Per-chunk failures, including any identifier that named no chunk in the document. A populated array still answers 200."
|
||
}
|
||
},
|
||
"required": ["operation", "processed", "errors"],
|
||
"additionalProperties": false,
|
||
"title": "Bulk knowledge chunk update data",
|
||
"description": "Outcome of a bulk enable, disable, or delete across knowledge chunks."
|
||
},
|
||
"V2BulkKnowledgeChunksResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2BulkKnowledgeChunksData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Bulk knowledge chunk response",
|
||
"description": "Counts and per-chunk failures from a bulk chunk operation."
|
||
},
|
||
"BulkUpdateKnowledgeChunksRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
},
|
||
"operation": {
|
||
"type": "string",
|
||
"enum": ["enable", "disable", "delete"],
|
||
"description": "What to do with the selected chunks."
|
||
},
|
||
"chunkIds": {
|
||
"minItems": 1,
|
||
"maxItems": 100,
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
},
|
||
"description": "Chunks to operate on, by identifier. An id naming no chunk in the document is reported in errors and does not fail the request."
|
||
}
|
||
},
|
||
"required": ["workspaceId", "operation", "chunkIds"],
|
||
"additionalProperties": false,
|
||
"title": "Bulk knowledge chunk request",
|
||
"description": "Workspace scope, the operation to apply, and the chunks to apply it to.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"operation": "disable",
|
||
"chunkIds": ["4c1f9e77-2b3a-4f8d-9e10-6a2c8d4b1e05"]
|
||
}
|
||
]
|
||
},
|
||
"UpdateKnowledgeChunkRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
},
|
||
"content": {
|
||
"description": "Replacement text. Changing it re-embeds the chunk and re-derives its token and character counts.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 10000
|
||
},
|
||
"enabled": {
|
||
"description": "Whether the chunk participates in search. Disabling keeps it indexed.",
|
||
"type": "boolean"
|
||
}
|
||
},
|
||
"required": ["workspaceId"],
|
||
"additionalProperties": false,
|
||
"title": "Update knowledge chunk request",
|
||
"description": "Workspace scope and the fields to update. At least one is required.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"enabled": false
|
||
}
|
||
]
|
||
},
|
||
"V2KnowledgeTagResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2KnowledgeTag"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge tag response",
|
||
"description": "A single tag definition."
|
||
},
|
||
"CreateKnowledgeTagRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
},
|
||
"displayName": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 100,
|
||
"description": "Name tag filters and document reads use for this tag.",
|
||
"examples": ["category"]
|
||
},
|
||
"fieldType": {
|
||
"default": "text",
|
||
"type": "string",
|
||
"enum": ["text", "number", "date", "boolean"],
|
||
"description": "Value type stored in the slot; it decides which slots are usable and which filter operators apply. Slot capacity per type: text 7, number 5, date 2, boolean 3.",
|
||
"examples": ["text"]
|
||
},
|
||
"tagSlot": {
|
||
"description": "Slot to store the tag in. Omit to take the next free slot for the field type; a slot that does not belong to the field type, or one already in use, is rejected.",
|
||
"type": "string",
|
||
"enum": [
|
||
"tag1",
|
||
"tag2",
|
||
"tag3",
|
||
"tag4",
|
||
"tag5",
|
||
"tag6",
|
||
"tag7",
|
||
"number1",
|
||
"number2",
|
||
"number3",
|
||
"number4",
|
||
"number5",
|
||
"date1",
|
||
"date2",
|
||
"boolean1",
|
||
"boolean2",
|
||
"boolean3"
|
||
],
|
||
"examples": ["tag1"]
|
||
}
|
||
},
|
||
"required": ["workspaceId", "displayName"],
|
||
"additionalProperties": false,
|
||
"title": "Create knowledge tag request",
|
||
"description": "Workspace scope, display name, field type, and optional slot.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"displayName": "category",
|
||
"fieldType": "text"
|
||
}
|
||
]
|
||
},
|
||
"UpdateKnowledgeTagRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
},
|
||
"displayName": {
|
||
"description": "New tag display name.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 100,
|
||
"examples": ["category"]
|
||
},
|
||
"fieldType": {
|
||
"description": "New value type for the tag.",
|
||
"type": "string",
|
||
"enum": ["text", "number", "date", "boolean"],
|
||
"examples": ["text"]
|
||
}
|
||
},
|
||
"required": ["workspaceId"],
|
||
"additionalProperties": false,
|
||
"title": "Update knowledge tag request",
|
||
"description": "Workspace scope and the fields to update. At least one is required.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"displayName": "topic"
|
||
}
|
||
]
|
||
},
|
||
"V2DeleteKnowledgeTagData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Identifier of the deleted tag definition."
|
||
},
|
||
"tagSlot": {
|
||
"type": "string",
|
||
"description": "Slot the deleted tag occupied; its values are now cleared."
|
||
},
|
||
"displayName": {
|
||
"type": "string",
|
||
"description": "Display name the deleted tag carried."
|
||
},
|
||
"deleted": {
|
||
"type": "boolean",
|
||
"const": true,
|
||
"description": "Confirms that the tag definition was deleted."
|
||
}
|
||
},
|
||
"required": ["id", "tagSlot", "displayName", "deleted"],
|
||
"additionalProperties": false,
|
||
"title": "Delete knowledge tag data",
|
||
"description": "Acknowledgement for a deleted tag definition."
|
||
},
|
||
"V2DeleteKnowledgeTagResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2DeleteKnowledgeTagData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Delete knowledge tag response",
|
||
"description": "Acknowledgement naming the deleted definition and the slot it freed."
|
||
},
|
||
"V2NextKnowledgeTagSlotData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"nextAvailableSlot": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "The free slot a create would take, or null when the field type is exhausted.",
|
||
"examples": ["tag3"]
|
||
},
|
||
"fieldType": {
|
||
"type": "string",
|
||
"description": "Field type the slots were counted for."
|
||
},
|
||
"usedSlots": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "Slots of this field type already holding a tag."
|
||
},
|
||
"totalSlots": {
|
||
"type": "integer",
|
||
"exclusiveMinimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Total slots this field type has: 7 for text, 5 for number, 2 for date, 3 for boolean."
|
||
},
|
||
"availableSlots": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Slots of this field type still free, or 0 when the field type is exhausted."
|
||
}
|
||
},
|
||
"required": ["nextAvailableSlot", "fieldType", "usedSlots", "totalSlots", "availableSlots"],
|
||
"additionalProperties": false,
|
||
"title": "Next knowledge tag slot",
|
||
"description": "Slot availability for one tag field type."
|
||
},
|
||
"V2NextKnowledgeTagSlotResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2NextKnowledgeTagSlotData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Next knowledge tag slot response",
|
||
"description": "Slot availability for one tag field type."
|
||
},
|
||
"V2KnowledgeTagUsage": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Tag definition identifier. Published for the same reason the vocabulary read publishes it: `PATCH` and `DELETE /knowledge/{knowledgeBaseId}/tags/{tagId}` address a definition by id, so without it a usage row cannot be acted on without a second read and a slot join.",
|
||
"examples": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"]
|
||
},
|
||
"tagSlot": {
|
||
"type": "string",
|
||
"description": "Slot the tag occupies.",
|
||
"examples": ["tag1"]
|
||
},
|
||
"displayName": {
|
||
"type": "string",
|
||
"description": "Tag display name.",
|
||
"examples": ["category"]
|
||
},
|
||
"fieldType": {
|
||
"type": "string",
|
||
"description": "Value type stored in the slot.",
|
||
"examples": ["text"]
|
||
},
|
||
"documentCount": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Documents in the knowledge base carrying a value in this slot."
|
||
},
|
||
"chunkCount": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Indexed chunks carrying a value in this slot."
|
||
}
|
||
},
|
||
"required": ["id", "tagSlot", "displayName", "fieldType", "documentCount", "chunkCount"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge tag usage",
|
||
"description": "How widely one tag is populated across a knowledge base."
|
||
},
|
||
"V2KnowledgeTagUsageListResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2KnowledgeTagUsage"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Always `null` — this list has no `cursor` or `limit` 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 usage response",
|
||
"description": "Usage counts for every tag defined on one knowledge base."
|
||
},
|
||
"V2BulkSaveKnowledgeTagDefinitionsData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"created": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2KnowledgeTag"
|
||
},
|
||
"description": "Definitions that did not previously exist."
|
||
},
|
||
"updated": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2KnowledgeTag"
|
||
},
|
||
"description": "Definitions whose slot was already defined."
|
||
},
|
||
"errors": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "Per-definition failures. A populated array still answers 200."
|
||
}
|
||
},
|
||
"required": ["created", "updated", "errors"],
|
||
"additionalProperties": false,
|
||
"title": "Bulk save knowledge tag definitions data",
|
||
"description": "Definitions created and updated by a bulk tag-definition save."
|
||
},
|
||
"V2BulkSaveKnowledgeTagDefinitionsResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2BulkSaveKnowledgeTagDefinitionsData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Bulk save tag definitions response",
|
||
"description": "Definitions created and updated, with any per-definition failures."
|
||
},
|
||
"V2BulkSaveKnowledgeTagDefinition": {
|
||
"type": "object",
|
||
"properties": {
|
||
"tagSlot": {
|
||
"type": "string",
|
||
"enum": [
|
||
"tag1",
|
||
"tag2",
|
||
"tag3",
|
||
"tag4",
|
||
"tag5",
|
||
"tag6",
|
||
"tag7",
|
||
"number1",
|
||
"number2",
|
||
"number3",
|
||
"number4",
|
||
"number5",
|
||
"date1",
|
||
"date2",
|
||
"boolean1",
|
||
"boolean2",
|
||
"boolean3"
|
||
],
|
||
"description": "Storage slot the tag occupies. It must belong to the tag’s `fieldType`.",
|
||
"examples": ["tag1"]
|
||
},
|
||
"displayName": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 100,
|
||
"description": "Name tag filters and document reads use for this tag.",
|
||
"examples": ["category"]
|
||
},
|
||
"fieldType": {
|
||
"type": "string",
|
||
"enum": ["text", "number", "date", "boolean"],
|
||
"description": "Value type stored in the slot; it decides which slots are usable and which filter operators apply. Slot capacity per type: text 7, number 5, date 2, boolean 3.",
|
||
"examples": ["text"]
|
||
},
|
||
"originalDisplayName": {
|
||
"description": "Previous display name, when this entry renames an existing definition.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 100,
|
||
"examples": ["category"]
|
||
}
|
||
},
|
||
"required": ["tagSlot", "displayName", "fieldType"],
|
||
"additionalProperties": false,
|
||
"title": "Knowledge tag definition input",
|
||
"description": "One tag definition declared in a bulk save."
|
||
},
|
||
"BulkSaveKnowledgeTagDefinitionsRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the knowledge base."
|
||
},
|
||
"definitions": {
|
||
"minItems": 1,
|
||
"maxItems": 17,
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2BulkSaveKnowledgeTagDefinition"
|
||
},
|
||
"description": "Tag definitions to create or update on the knowledge base."
|
||
}
|
||
},
|
||
"required": ["workspaceId", "definitions"],
|
||
"additionalProperties": false,
|
||
"title": "Bulk save tag definitions request",
|
||
"description": "Workspace scope and the tag definitions to create or update.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"definitions": [
|
||
{
|
||
"tagSlot": "tag1",
|
||
"displayName": "category",
|
||
"fieldType": "text"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
},
|
||
"V2DeleteKnowledgeTagDefinitionsData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"unused": {
|
||
"type": "boolean",
|
||
"description": "Whether the delete was restricted to definitions no document still uses."
|
||
},
|
||
"count": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Number of tag definitions removed."
|
||
}
|
||
},
|
||
"required": ["unused", "count"],
|
||
"additionalProperties": false,
|
||
"title": "Delete knowledge tag definitions data",
|
||
"description": "Outcome of a knowledge-base tag-definition delete."
|
||
},
|
||
"V2DeleteKnowledgeTagDefinitionsResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2DeleteKnowledgeTagDefinitionsData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Delete tag definitions response",
|
||
"description": "Number of tag definitions that were removed."
|
||
}
|
||
}
|
||
},
|
||
"x-generated-by": "scripts/generate-openapi.ts"
|
||
}
|