Knowledge bases and documents¶

Use an API key or REST OAuth access token. Scopes and your current workspace permissions apply together. All examples are illustrative.

Check knowledge-base deletion¶

GET /api/external/v1/knowledge-bases/{id}/deletion-checklist

Scope: knowledge-bases:write

Parameters

Name	Location	Type	Required	Description
`id`	Path	`string` (uuid)	Yes	Resource identifier in the bound workspace.

Response 200

Success.

Header	Type	Description
`Cache-Control`	`string`	The response must not be cached. Example: `no-store`
`ETag`	`string`	Deletion-check revision. Send unchanged as If-Match when deleting the knowledge base. Example: `"revision-from-get"`

application/json

FieldsExample

Field	Type	Description
`assessmentToken`	`string`	Deletion-check token. Use the response ETag for the delete request.
`canDelete`	`boolean`	Whether the knowledge base can currently be deleted.
`blockingReferences`	`integer` (int64)	Assignments or dependencies that prevent deletion.

{
  "assessmentToken": "string",
  "canDelete": true,
  "blockingReferences": 0
}

Error responses

Status	Meaning
`400`	Invalid input, unsupported selection or time range.
`401`	Missing, expired or invalid credential. The body may be empty.
`403`	Required scope or current user permission missing. The body may be empty.
`404`	Resource is unavailable in the bound workspace.
`429`	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
`503`	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
`status`	`integer`	HTTP status code.
`error`	`string`	Description of the error.
`details`	`any`	Additional error details, when available. Rules: `null` allowed
`code`	`string`	Machine-readable error code.
`params`	`object`	Additional values associated with the error code.
`fieldErrors`	`object`	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

Create knowledge base¶

POST /api/external/v1/knowledge-bases

Scope: knowledge-bases:write

Saves configuration directly; no call, tool test or message delivery is executed.

Request body · application/json

FieldsExample

Field	Type	Required	Description
`title`	`string`	Yes	Display name of the resource. Rules: up to 255 characters

{
  "title": "NuvoCar service"
}

Response 201

Created.

Header	Type	Description
`Cache-Control`	`string`	The response must not be cached. Example: `no-store`
`Location`	`string`	Path of the created resource.
`ETag`	`string`	Current revision. Send unchanged, including quotes, as If-Match when required. Example: `"revision-from-get"`

application/json

FieldsExample

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`title`	`string`	Display name of the resource.
`version`	`integer` (int64)	Current resource version. Use the response ETag when updating or deleting.

{
  "id": "00000000-0000-0000-0000-000000000001",
  "title": "NuvoCar service",
  "version": 1
}

Error responses

Status	Meaning
`400`	Invalid input, unsupported selection or time range.
`401`	Missing, expired or invalid credential. The body may be empty.
`403`	Required scope or current user permission missing. The body may be empty.
`409`	Missing/stale revision or dependency/routing conflict. Read again before retrying.
`429`	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
`503`	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
`status`	`integer`	HTTP status code.
`error`	`string`	Description of the error.
`details`	`any`	Additional error details, when available. Rules: `null` allowed
`code`	`string`	Machine-readable error code.
`params`	`object`	Additional values associated with the error code.
`fieldErrors`	`object`	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

List knowledge bases¶

GET /api/external/v1/knowledge-bases

Scope: knowledge-bases:read

Parameters

Name	Location	Type	Required	Description
`page`	Query	`integer` (int32)	No	Page index, starting at 0. Rules: `0–100000` Default: `0`
`size`	Query	`integer` (int32)	No	Results per page. Rules: `1–100` Default: `25`

Response 200

Success.

Header	Type	Description
`Cache-Control`	`string`	The response must not be cached. Example: `no-store`

application/json

FieldsExample

Field	Type	Description
`items`	List of `object`	Results on this page.
`page`	`integer` (int32)	Current page index, starting at 0.
`size`	`integer` (int32)	Number of results requested per page.
`totalElements`	`integer` (int64)	Total number of matching results.
`totalPages`	`integer` (int32)	Total number of result pages.

items — fields

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`title`	`string`	Display name of the resource.
`version`	`integer` (int64)	Current resource version. Use the response ETag when updating or deleting.

{
  "items": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "title": "NuvoCar service",
      "version": 1
    }
  ],
  "page": 0,
  "size": 25,
  "totalElements": 1,
  "totalPages": 1
}

Error responses

Status	Meaning
`400`	Invalid input, unsupported selection or time range.
`401`	Missing, expired or invalid credential. The body may be empty.
`403`	Required scope or current user permission missing. The body may be empty.
`429`	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
`503`	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
`status`	`integer`	HTTP status code.
`error`	`string`	Description of the error.
`details`	`any`	Additional error details, when available. Rules: `null` allowed
`code`	`string`	Machine-readable error code.
`params`	`object`	Additional values associated with the error code.
`fieldErrors`	`object`	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

Delete knowledge base¶

DELETE /api/external/v1/knowledge-bases/{id}

Scope: knowledge-bases:write

Use the ETag from the fresh deletion checklist, not the normal knowledge-base version. Resolve blocking assignments first.

Parameters

Name	Location	Type	Required	Description
`id`	Path	`string` (uuid)	Yes	Resource identifier in the bound workspace.
`If-Match`	Header	`string`	Yes	ETag from a fresh deletion-checklist response, including quotes. Example: `"revision-from-get"`

Response 204

Deleted; no response body.

Header	Type	Description
`Cache-Control`	`string`	The response must not be cached. Example: `no-store`

Error responses

Status	Meaning
`400`	Invalid input, unsupported selection or time range.
`401`	Missing, expired or invalid credential. The body may be empty.
`403`	Required scope or current user permission missing. The body may be empty.
`404`	Resource is unavailable in the bound workspace.
`409`	Missing/stale revision or dependency/routing conflict. Read again before retrying.
`429`	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
`503`	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
`status`	`integer`	HTTP status code.
`error`	`string`	Description of the error.
`details`	`any`	Additional error details, when available. Rules: `null` allowed
`code`	`string`	Machine-readable error code.
`params`	`object`	Additional values associated with the error code.
`fieldErrors`	`object`	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

Read knowledge base¶

GET /api/external/v1/knowledge-bases/{id}

Scope: knowledge-bases:read

Parameters

Name	Location	Type	Required	Description
`id`	Path	`string` (uuid)	Yes	Resource identifier in the bound workspace.

Response 200

Success.

Header	Type	Description
`Cache-Control`	`string`	The response must not be cached. Example: `no-store`
`ETag`	`string`	Current revision. Send unchanged, including quotes, as If-Match when required. Example: `"revision-from-get"`

application/json

FieldsExample

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`title`	`string`	Display name of the resource.
`version`	`integer` (int64)	Current resource version. Use the response ETag when updating or deleting.

{
  "id": "00000000-0000-0000-0000-000000000001",
  "title": "NuvoCar service",
  "version": 1
}

Error responses

Status	Meaning
`400`	Invalid input, unsupported selection or time range.
`401`	Missing, expired or invalid credential. The body may be empty.
`403`	Required scope or current user permission missing. The body may be empty.
`404`	Resource is unavailable in the bound workspace.
`429`	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
`503`	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
`status`	`integer`	HTTP status code.
`error`	`string`	Description of the error.
`details`	`any`	Additional error details, when available. Rules: `null` allowed
`code`	`string`	Machine-readable error code.
`params`	`object`	Additional values associated with the error code.
`fieldErrors`	`object`	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

Update knowledge base¶

PUT /api/external/v1/knowledge-bases/{id}

Scope: knowledge-bases:write

Saves configuration directly; no call, tool test or message delivery is executed. Read the resource first. Send its current ETag, including quotes, in If-Match. Send the full editable configuration. Omitted settings can be reset.

Parameters

Name	Location	Type	Required	Description
`id`	Path	`string` (uuid)	Yes	Resource identifier in the bound workspace.
`If-Match`	Header	`string`	Yes	ETag from the preceding read, including quotes. Example: `"revision-from-get"`

Request body · application/json

FieldsExample

Field	Type	Required	Description
`title`	`string`	Yes	Display name of the resource. Rules: up to 255 characters

{
  "title": "NuvoCar service"
}

Response 200

Success.

Header	Type	Description
`Cache-Control`	`string`	The response must not be cached. Example: `no-store`
`ETag`	`string`	Current revision. Send unchanged, including quotes, as If-Match when required. Example: `"revision-from-get"`

application/json

FieldsExample

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`title`	`string`	Display name of the resource.
`version`	`integer` (int64)	Current resource version. Use the response ETag when updating or deleting.

{
  "id": "00000000-0000-0000-0000-000000000001",
  "title": "NuvoCar service",
  "version": 1
}

Error responses

Status	Meaning
`400`	Invalid input, unsupported selection or time range.
`401`	Missing, expired or invalid credential. The body may be empty.
`403`	Required scope or current user permission missing. The body may be empty.
`404`	Resource is unavailable in the bound workspace.
`409`	Missing/stale revision or dependency/routing conflict. Read again before retrying.
`429`	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
`503`	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
`status`	`integer`	HTTP status code.
`error`	`string`	Description of the error.
`details`	`any`	Additional error details, when available. Rules: `null` allowed
`code`	`string`	Machine-readable error code.
`params`	`object`	Additional values associated with the error code.
`fieldErrors`	`object`	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

Delete a knowledge document¶

DELETE /api/external/v1/knowledge-bases/{id}/documents/{documentId}

Scope: documents:write

Read the resource first. Send its current ETag, including quotes, in If-Match.

Parameters

Name	Location	Type	Required	Description
`id`	Path	`string` (uuid)	Yes	Resource identifier in the bound workspace.
`documentId`	Path	`string` (uuid)	Yes	Resource identifier in the bound workspace.
`If-Match`	Header	`string`	Yes	ETag from the preceding read, including quotes. Example: `"revision-from-get"`

Response 204

Deleted; no response body.

Header	Type	Description
`Cache-Control`	`string`	The response must not be cached. Example: `no-store`

Error responses

Status	Meaning
`400`	Invalid input, unsupported selection or time range.
`401`	Missing, expired or invalid credential. The body may be empty.
`403`	Required scope or current user permission missing. The body may be empty.
`404`	Resource is unavailable in the bound workspace.
`409`	Missing/stale revision or dependency/routing conflict. Read again before retrying.
`429`	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
`503`	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
`status`	`integer`	HTTP status code.
`error`	`string`	Description of the error.
`details`	`any`	Additional error details, when available. Rules: `null` allowed
`code`	`string`	Machine-readable error code.
`params`	`object`	Additional values associated with the error code.
`fieldErrors`	`object`	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

Read document metadata¶

GET /api/external/v1/knowledge-bases/{id}/documents/{documentId}

Scope: documents:read

Parameters

Name	Location	Type	Required	Description
`id`	Path	`string` (uuid)	Yes	Resource identifier in the bound workspace.
`documentId`	Path	`string` (uuid)	Yes	Resource identifier in the bound workspace.

Response 200

Success.

Header	Type	Description
`Cache-Control`	`string`	The response must not be cached. Example: `no-store`
`ETag`	`string`	Current revision. Send unchanged, including quotes, as If-Match when required. Example: `"revision-from-get"`

application/json

FieldsExample

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`title`	`string`	Display name of the resource.
`documentType`	`string`	Type of the uploaded document. Values: `PDF`, `TEXT`, `XML`, `MARKDOWN`, `HTML`, `DOCX`
`version`	`integer` (int64)	Current resource version. Use the response ETag when updating or deleting.

{
  "id": "00000000-0000-0000-0000-000000000001",
  "title": "NuvoCar service",
  "documentType": "PDF",
  "version": 1
}

Error responses

Status	Meaning
`400`	Invalid input, unsupported selection or time range.
`401`	Missing, expired or invalid credential. The body may be empty.
`403`	Required scope or current user permission missing. The body may be empty.
`404`	Resource is unavailable in the bound workspace.
`429`	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
`503`	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
`status`	`integer`	HTTP status code.
`error`	`string`	Description of the error.
`details`	`any`	Additional error details, when available. Rules: `null` allowed
`code`	`string`	Machine-readable error code.
`params`	`object`	Additional values associated with the error code.
`fieldErrors`	`object`	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

List document metadata¶

GET /api/external/v1/knowledge-bases/{id}/documents

Scope: documents:read

Parameters

Name	Location	Type	Required	Description
`id`	Path	`string` (uuid)	Yes	Resource identifier in the bound workspace.
`page`	Query	`integer` (int32)	No	Page index, starting at 0. Rules: `0–100000` Default: `0`
`size`	Query	`integer` (int32)	No	Results per page. Rules: `1–100` Default: `25`

Response 200

Success.

Header	Type	Description
`Cache-Control`	`string`	The response must not be cached. Example: `no-store`

application/json

FieldsExample

Field	Type	Description
`items`	List of `object`	Results on this page.
`page`	`integer` (int32)	Current page index, starting at 0.
`size`	`integer` (int32)	Number of results requested per page.
`totalElements`	`integer` (int64)	Total number of matching results.
`totalPages`	`integer` (int32)	Total number of result pages.

items — fields

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`title`	`string`	Display name of the resource.
`documentType`	`string`	Type of the uploaded document. Values: `PDF`, `TEXT`, `XML`, `MARKDOWN`, `HTML`, `DOCX`
`version`	`integer` (int64)	Current resource version. Use the response ETag when updating or deleting.

{
  "items": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "title": "NuvoCar service",
      "documentType": "PDF",
      "version": 1
    }
  ],
  "page": 0,
  "size": 25,
  "totalElements": 1,
  "totalPages": 1
}

Error responses

Status	Meaning
`400`	Invalid input, unsupported selection or time range.
`401`	Missing, expired or invalid credential. The body may be empty.
`403`	Required scope or current user permission missing. The body may be empty.
`404`	Resource is unavailable in the bound workspace.
`429`	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
`503`	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
`status`	`integer`	HTTP status code.
`error`	`string`	Description of the error.
`details`	`any`	Additional error details, when available. Rules: `null` allowed
`code`	`string`	Machine-readable error code.
`params`	`object`	Additional values associated with the error code.
`fieldErrors`	`object`	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

Upload a knowledge document¶

POST /api/external/v1/knowledge-bases/{id}/documents

Scope: documents:write

Uploads a document and waits for processing to finish. Returns document metadata, not the file contents.

Parameters

Name	Location	Type	Required	Description
`id`	Path	`string` (uuid)	Yes	Resource identifier in the bound workspace.

Request body · multipart/form-data

Field	Type	Required	Description
`title`	`string`	Yes	Nonblank document title, up to 255 characters. Rules: 1–255 characters
`file`	`string` (binary)	Yes	Nonempty knowledge document. Accepted formats and size limits are described in the Knowledge Base guide.

Response 201

Created.

Header	Type	Description
`Cache-Control`	`string`	The response must not be cached. Example: `no-store`
`Location`	`string`	Path of the created resource.
`ETag`	`string`	Current revision. Send unchanged, including quotes, as If-Match when required. Example: `"revision-from-get"`

application/json

FieldsExample

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`title`	`string`	Display name of the resource.
`documentType`	`string`	Type of the uploaded document. Values: `PDF`, `TEXT`, `XML`, `MARKDOWN`, `HTML`, `DOCX`
`version`	`integer` (int64)	Current resource version. Use the response ETag when updating or deleting.

{
  "id": "00000000-0000-0000-0000-000000000001",
  "title": "NuvoCar service",
  "documentType": "PDF",
  "version": 1
}

Error responses

Status	Meaning
`400`	Invalid input, unsupported selection or time range.
`401`	Missing, expired or invalid credential. The body may be empty.
`403`	Required scope or current user permission missing. The body may be empty.
`404`	Resource is unavailable in the bound workspace.
`409`	Missing/stale revision or dependency/routing conflict. Read again before retrying.
`429`	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
`503`	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
`status`	`integer`	HTTP status code.
`error`	`string`	Description of the error.
`details`	`any`	Additional error details, when available. Rules: `null` allowed
`code`	`string`	Machine-readable error code.
`params`	`object`	Additional values associated with the error code.
`fieldErrors`	`object`	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.