Skip to main content

External Project API

Interaktiv testen: https://ki-toolbox.reflactportal.com/swagger.

GET /api/external/projectapi/bots​

List all bots of the project (scope bots:read)

Auth: APIKeyHeaderProject

StatusBeschreibung
200Array of bots belonging to the project

POST /api/external/projectapi/bots​

Create a new bot in the project (scope bots:write)

Auth: APIKeyHeaderProject

Request-Body (application/json): name: string, customJs: string, customCss: string, customChatCss: string, customVoiceCss: string, customAvatarCss: string, customDidAvatarCss: string, botInstruction: string, summarizePrompt: string, helpUrls: string, documentationUrl: string, temperature: number, model: string, modelSource: "openai" | "vllm", reasoningEffort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh", textVerbosity: "low" | "medium" | "high", isPublic: boolean, isPwProtected: boolean, botPassword: string, websearch: boolean, allowUserFileUpload: boolean, memoryEnabled: boolean, voiceAutoPlay: boolean, tagList: string[], stopWords: string[], chatMsgSourceOption: "hidden" | "visible" | "linking", wordReplacements: object[], complianceText: object, storageaccessText: object, loadingMessages: string, postMessageTargetOrigin: string, speechRecognitionMode: "locale" | "auto", enableMessageFeedback: boolean, enableInstantAccess: boolean, createEmptyThreadOnVisit: boolean, secondsToWaitForThreadDeleting: integer, deleteGuestsAfterDays: integer, supervisorEnabled: boolean, messageCopyChatActive: boolean, messageDeleteChatActive: boolean, cancelBotThinkingChatActive: boolean, cancelBotThinkingVoiceActive: boolean, cancelBotThinkingAvatarActive: boolean, promptbarChatActive: boolean, promptbarAudioActive: boolean, promptbarAvatarActive: boolean, voiceInputChatActive: boolean, voiceInputVoiceActive: boolean, voiceInputAvatarActive: boolean, voiceOutputChatActive: boolean, switchToChatFromVoice: boolean, switchToChatFromAvatar: boolean, switchToVoiceFromChat: boolean, switchToVoiceFromAvatar: boolean, switchToAvatarFromChat: boolean, switchToAvatarFromVoice: boolean, activeDocSearch: boolean, activeDocSearchCount: integer, activeDocSearchMinScore: integer, activeDocSearchType: "vector" | "text" | "combined", userDocumentsEnabled: boolean, userDocumentsMaxCount: integer, userDocumentsMaxMb: integer & object

StatusBeschreibung
200The newly created bot (API keys are masked)
404Project not found
422Invalid or unknown fields in request body

GET /api/external/projectapi/bots/{botId}​

Get a single bot of the project (scope bots:read)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string
StatusBeschreibung
200The bot (API keys are masked)
404Bot not found

PUT /api/external/projectapi/bots/{botId}​

Partially update a bot of the project (scope bots:write)

Only the fields present in the request body are updated (like a PATCH) - any allow-listed field can be omitted. Unknown fields are rejected. Use this to edit e.g. customJs without resending the whole bot config.

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string

Request-Body (application/json): name: string, customJs: string, customCss: string, customChatCss: string, customVoiceCss: string, customAvatarCss: string, customDidAvatarCss: string, botInstruction: string, summarizePrompt: string, helpUrls: string, documentationUrl: string, temperature: number, model: string, modelSource: "openai" | "vllm", reasoningEffort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh", textVerbosity: "low" | "medium" | "high", isPublic: boolean, isPwProtected: boolean, botPassword: string, websearch: boolean, allowUserFileUpload: boolean, memoryEnabled: boolean, voiceAutoPlay: boolean, tagList: string[], stopWords: string[], chatMsgSourceOption: "hidden" | "visible" | "linking", wordReplacements: object[], complianceText: object, storageaccessText: object, loadingMessages: string, postMessageTargetOrigin: string, speechRecognitionMode: "locale" | "auto", enableMessageFeedback: boolean, enableInstantAccess: boolean, createEmptyThreadOnVisit: boolean, secondsToWaitForThreadDeleting: integer, deleteGuestsAfterDays: integer, supervisorEnabled: boolean, messageCopyChatActive: boolean, messageDeleteChatActive: boolean, cancelBotThinkingChatActive: boolean, cancelBotThinkingVoiceActive: boolean, cancelBotThinkingAvatarActive: boolean, promptbarChatActive: boolean, promptbarAudioActive: boolean, promptbarAvatarActive: boolean, voiceInputChatActive: boolean, voiceInputVoiceActive: boolean, voiceInputAvatarActive: boolean, voiceOutputChatActive: boolean, switchToChatFromVoice: boolean, switchToChatFromAvatar: boolean, switchToVoiceFromChat: boolean, switchToVoiceFromAvatar: boolean, switchToAvatarFromChat: boolean, switchToAvatarFromVoice: boolean, activeDocSearch: boolean, activeDocSearchCount: integer, activeDocSearchMinScore: integer, activeDocSearchType: "vector" | "text" | "combined", userDocumentsEnabled: boolean, userDocumentsMaxCount: integer, userDocumentsMaxMb: integer

StatusBeschreibung
200The updated bot (API keys are masked)
404Bot not found
422Invalid or unknown fields, or no fields provided

DELETE /api/external/projectapi/bots/{botId}​

Delete, archive or trash a bot of the project (scope bots:write)

Default mode is "delete" (irreversible - uploaded files, docsearch documents, scrapes, history, threads, blockly blocks, trunks, D-ID agent, ... - same teardown as the internal admin delete). "archive" and "trash" instead just flag the bot (archived/thisIsTrash) - after that it's excluded from this API's bot lookups (same as demo/template bots), so further calls on it will 404.

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string

Request-Body (application/json): mode: "delete" | "archive" | "trash"

StatusBeschreibung
200Bot deleted, archived or trashed
404Bot not found

GET /api/external/projectapi/bots/{botId}/changelog​

Read the change history of a bot of the project (scope changelog:read)

Returns up to the last 5000 changelog entries, newest first.

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string
StatusBeschreibung
200Array of changelog entries
404Bot not found

POST /api/external/projectapi/bots/{botId}/doc/assign​

Attach one or more already uploaded project-level documents to a bot of the project (scopes projectdoc:write and bots:write)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string

Request-Body (application/json): docIds: string[]

StatusBeschreibung
200Documents assigned to the bot (already assigned documents are returned as-is)
404Bot or document not found
422No document IDs were provided

POST /api/external/projectapi/bots/{botId}/doc/unassign​

Detach one or more documents from a bot of the project (scopes projectdoc:write and bots:write)

Removes the bot-level copy of each document. The project-level document (botId == null) and any copies attached to other bots are not affected. Documents that are not currently assigned to the bot are silently skipped.

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string

Request-Body (application/json): docIds: string[]

StatusBeschreibung
200Documents detached from the bot (not-assigned documents are skipped)
404Bot or document not found
422No document IDs were provided

POST /api/external/projectapi/bots/{botId}/doc/upload​

Upload a new document and attach it to a bot of the project (scope projectdoc:write)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string

Request-Body (multipart/form-data): file: string

StatusBeschreibung
200Uploaded document, attached to both project and bot
404Bot or project not found
422No file was uploaded
500Upload failed

POST /api/external/projectapi/bots/{botId}/duplicate​

Duplicate a bot of the project (scope bots:write)

Creates a full copy of the bot (config, documents, skills, stages, fusion views, ...) in the same project.

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string

Request-Body (application/json): name: string

StatusBeschreibung
200The newly created bot (API keys are masked)
404Bot not found

GET /api/external/projectapi/bots/{botId}/embedding​

List all website-crawls of a bot of the project (scope embedding:read)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string
StatusBeschreibung
200Array of website-crawls
404Bot not found

POST /api/external/projectapi/bots/{botId}/embedding​

Start a new website-crawl for a bot of the project (scope embedding:write)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string

Request-Body (application/json): url: string, depth: integer, skillId: string, description: string, name: string

StatusBeschreibung
200The created (or already-running) crawl
404Bot not found
422Invalid or missing fields

GET /api/external/projectapi/bots/{botId}/embedding/{scrapeId}​

Get a single website-crawl of a bot of the project (scope embedding:read)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string
scrapeIdpath✔string
StatusBeschreibung
200The website-crawl, including its scraped pages
404Bot or website-crawl not found

PUT /api/external/projectapi/bots/{botId}/embedding/{scrapeId}​

Update a website-crawl of a bot of the project (scope embedding:write)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string
scrapeIdpath✔string

Request-Body (application/json): description: string, active: boolean, skillId: string, name: string

StatusBeschreibung
200The updated website-crawl
404Bot or website-crawl not found
422Invalid or missing fields

DELETE /api/external/projectapi/bots/{botId}/embedding/{scrapeId}​

Delete a website-crawl of a bot of the project (scope embedding:write)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string
scrapeIdpath✔string
StatusBeschreibung
200Website-crawl deleted
404Bot or website-crawl not found

GET /api/external/projectapi/bots/{botId}/feedback​

Read message feedback of a bot of the project (scope stats:read)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string
StatusBeschreibung
200Array of message feedback entries
404Bot not found

GET /api/external/projectapi/bots/{botId}/fusion​

List all Fusion-Views of a bot of the project (scope fusion:read)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string
StatusBeschreibung
200Array of Fusion-Views
404Bot not found

POST /api/external/projectapi/bots/{botId}/fusion​

Create a new Fusion-View for a bot of the project (scope fusion:write)

For rise/storyline/captivate/lxt/knowledgeworker this only creates the metadata entry - upload the ZIP afterwards via the /upload endpoint.

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string

Request-Body (application/json): type: string, title: string

StatusBeschreibung
200The newly created Fusion-View
404Bot not found
422Invalid fields (e.g. missing type/title, or a reserved field was set)

GET /api/external/projectapi/bots/{botId}/fusion/{fusionId}​

Get a single Fusion-View of a bot of the project (scope fusion:read)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string
fusionIdpath✔string
StatusBeschreibung
200The Fusion-View
404Bot or Fusion-View not found

PUT /api/external/projectapi/bots/{botId}/fusion/{fusionId}​

Partially update a Fusion-View's metadata of a bot of the project (scope fusion:write)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string
fusionIdpath✔string

Request-Body (application/json): object

StatusBeschreibung
200The updated Fusion-View
404Bot or Fusion-View not found
422Invalid fields (e.g. type/_id/botId was set, or no fields provided)

DELETE /api/external/projectapi/bots/{botId}/fusion/{fusionId}​

Delete a Fusion-View of a bot of the project (scope fusion:write)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string
fusionIdpath✔string
StatusBeschreibung
200Fusion-View deleted
404Bot or Fusion-View not found

POST /api/external/projectapi/bots/{botId}/fusion/{fusionId}/upload​

Upload the ZIP content for a rise/storyline/captivate/lxt/knowledgeworker Fusion-View of a bot of the project (scope fusion:write)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string
fusionIdpath✔string

Request-Body (multipart/form-data): file: string

StatusBeschreibung
200The updated Fusion-View file entry
404Bot or Fusion-View not found
415Upload not supported for this Fusion-View type, or unsupported mimetype

GET /api/external/projectapi/bots/{botId}/skills​

List all Wenn-Dann rules of a bot of the project (scope skills:read)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string
StatusBeschreibung
200Array of skills
404Bot not found

POST /api/external/projectapi/bots/{botId}/skills​

Create a new Wenn-Dann rule for a bot of the project (scope skills:write)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string

Request-Body (application/json): name: string, skillId: string, description: string, enabled: boolean, content: string, params: object[], toolCallAnswer: string[], answerMode: "sequence" | "sequenceloop" | "random" & object

StatusBeschreibung
200The newly created skill
404Bot not found
409name or skillId already used by another Wenn-Dann rule of this bot
422Invalid or unknown fields

GET /api/external/projectapi/bots/{botId}/skills/{skillId}​

Get a single Wenn-Dann rule of a bot of the project (scope skills:read)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string
skillIdpath✔string
StatusBeschreibung
200The skill
404Bot or skill not found

PUT /api/external/projectapi/bots/{botId}/skills/{skillId}​

Partially update a Wenn-Dann rule of a bot of the project (scope skills:write)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string
skillIdpath✔string

Request-Body (application/json): name: string, skillId: string, description: string, enabled: boolean, content: string, params: object[], toolCallAnswer: string[], answerMode: "sequence" | "sequenceloop" | "random"

StatusBeschreibung
200The updated skill
404Bot or skill not found
409name or skillId already used by another Wenn-Dann rule of this bot
422Invalid or unknown fields, or no fields provided

DELETE /api/external/projectapi/bots/{botId}/skills/{skillId}​

Delete a Wenn-Dann rule of a bot of the project (scope skills:write)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string
skillIdpath✔string
StatusBeschreibung
200Skill deleted
404Bot or skill not found

GET /api/external/projectapi/bots/{botId}/stages​

List all stages of a bot of the project (scope stages:read)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string
StatusBeschreibung
200Array of stages
404Bot not found

POST /api/external/projectapi/bots/{botId}/stages​

Create a new stage for a bot of the project (scope stages:write)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string

Request-Body (application/json): title: string, name: string, hidden: boolean, footer: boolean, forceSkills: boolean, skills: string[], enterJS: string, exitJS: string, preConditionJS: string & object

StatusBeschreibung
200The newly created stage
404Bot not found
422Invalid or unknown fields

GET /api/external/projectapi/bots/{botId}/stages/{stageId}​

Get a single stage of a bot of the project (scope stages:read)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string
stageIdpath✔string
StatusBeschreibung
200The stage
404Bot or stage not found

PUT /api/external/projectapi/bots/{botId}/stages/{stageId}​

Partially update a stage of a bot of the project (scope stages:write)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string
stageIdpath✔string

Request-Body (application/json): title: string, name: string, hidden: boolean, footer: boolean, forceSkills: boolean, skills: string[], enterJS: string, exitJS: string, preConditionJS: string

StatusBeschreibung
200The updated stage
404Bot or stage not found
422Invalid or unknown fields, or no fields provided

DELETE /api/external/projectapi/bots/{botId}/stages/{stageId}​

Delete a stage of a bot of the project (scope stages:write)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string
stageIdpath✔string
StatusBeschreibung
200Stage deleted
404Bot or stage not found

GET /api/external/projectapi/bots/{botId}/usage​

Read usage/token statistics of a bot of the project (scope stats:read)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
botIdpath✔string
StatusBeschreibung
200Array of usage stats (chat completions, TTS, HeyGen)
404Bot not found

GET /api/external/projectapi/checkauth​

Verify external project API token

Auth: APIKeyHeaderProject

StatusBeschreibung
200Validated token data

POST /api/external/projectapi/doc/extract/{docId}​

Trigger chunking/extraction for a project document (scope projectdoc:chunk)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
docIdpath✔string

Request-Body (application/json): maxChars: integer, maxOverlap: integer, chunking_strategy: "text" | "markdown" | "yaml", imagesEnabled: boolean, ocrEnabled: boolean, ocrLanguage: string

StatusBeschreibung
200Extraction triggered/finished
404Document or project not found
500Extraction failed

GET /api/external/projectapi/doc/files​

List all project-level documents (scope projectdoc:read)

Auth: APIKeyHeaderProject

StatusBeschreibung
200Array of project documents

GET /api/external/projectapi/doc/files/{docId}​

Get metadata of a single project document (scope projectdoc:read)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
docIdpath✔string
StatusBeschreibung
200Document metadata
404Document not found

DELETE /api/external/projectapi/doc/files/{docId}​

Delete a project document (scope projectdoc:write). Also removes the document from every bot of the project it was attached to.

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
docIdpath✔string
StatusBeschreibung
200Document deleted
404Document not found

GET /api/external/projectapi/doc/files/{docId}/chunks​

Get the extracted chunks of a project document (scope projectdoc:read)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
docIdpath✔string
StatusBeschreibung
200Array of document chunks
404Document not found

GET /api/external/projectapi/doc/files/{docId}/download​

Download the file content of a project document (scope projectdoc:read)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
docIdpath✔string
StatusBeschreibung
200Binary file stream
404Document not found

PUT /api/external/projectapi/doc/replace/{docId}​

Replace/overwrite an existing project document (scope projectdoc:write)

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
docIdpath✔string

Request-Body (multipart/form-data): file: string, extract: boolean & maxChars: integer, maxOverlap: integer, chunking_strategy: "text" | "markdown" | "yaml", imagesEnabled: boolean, ocrEnabled: boolean, ocrLanguage: string

StatusBeschreibung
200Replaced document (no projectDoc — use GET /files/{docId} to fetch the updated metadata)
404Document or project not found
422No file was uploaded
500Replace failed

POST /api/external/projectapi/doc/upload​

Upload a new document to the project (scope projectdoc:write)

Auth: APIKeyHeaderProject

Request-Body (multipart/form-data): file: string, extract: boolean, skillId: string, functionName: string & maxChars: integer, maxOverlap: integer, chunking_strategy: "text" | "markdown" | "yaml", imagesEnabled: boolean, ocrEnabled: boolean, ocrLanguage: string

StatusBeschreibung
200Uploaded document
404Project not found
422No file was uploaded
500Upload failed

GET /api/external/projectapi/keyval​

List all key-value entries for this project

Returns all ProjectKeyVal entries belonging to the token's project. Filter by userId, key, keyPrefix, and/or type.

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
userIdquery–string
typequery–string
keyquery–stringExact key match (mutually exclusive with keyPrefix)
keyPrefixquery–stringKey starts-with filter (mutually exclusive with key)
StatusBeschreibung
200Array of ProjectKeyVal entries

GET /api/external/projectapi/keyval/{userId}​

List all project key-value entries for a specific user

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
userIdpath✔string
typequery–string
keyPrefixquery–string
StatusBeschreibung
200Array of ProjectKeyVal entries

DELETE /api/external/projectapi/keyval/{userId}​

Delete all project key-value entries for a specific user

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
userIdpath✔string
typequery–string
keyPrefixquery–string
keepPermanentquery–boolean
StatusBeschreibung
200Number of deleted entries

GET /api/external/projectapi/keyval/{userId}/{type}/{key}​

Get a single project key-value entry

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
userIdpath✔string
typepath✔string
keypath✔string
StatusBeschreibung
200ProjectKeyVal entry
404Entry not found

PUT /api/external/projectapi/keyval/{userId}/{type}/{key}​

Create or update a project key-value entry (upsert)

Permanent entries (key starts with "!") cannot be written and return 403.

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
userIdpath✔string
typepath✔string
keypath✔string

Request-Body (application/json): value: unknown

StatusBeschreibung
200Updated or created entry
403Key is read-only (starts with "!")

DELETE /api/external/projectapi/keyval/{userId}/{type}/{key}​

Delete a single project key-value entry

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
userIdpath✔string
typepath✔string
keypath✔string
StatusBeschreibung
200Entry deleted
404Entry not found

POST /api/external/projectapi/keyval/bulk-delete​

Bulk-delete project key-value entries

Deletes all project entries matching the given filter. Permanent entries ("!"-prefixed keys) are protected by default.

Auth: APIKeyHeaderProject

Request-Body (application/json): userId: string, type: string, keyPrefix: string, keepPermanent: boolean

StatusBeschreibung
200Number of deleted entries

GET /api/external/projectapi/keyval/maxage​

List all MaxAge rules for this project

Auth: APIKeyHeaderProject

StatusBeschreibung
200Array of MaxAge rules

POST /api/external/projectapi/keyval/maxage​

Create a new MaxAge rule

Entries whose key matches keyPattern and that have not been accessed or updated within maxAgeSeconds seconds will be automatically deleted by the cleanup job.

Auth: APIKeyHeaderProject

Request-Body (application/json): keyPattern: string, maxAgeSeconds: number

StatusBeschreibung
200Created MaxAge rule
422Missing or invalid request body

PUT /api/external/projectapi/keyval/maxage/{ruleId}​

Update a MaxAge rule

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
ruleIdpath✔string

Request-Body (application/json): keyPattern: string, maxAgeSeconds: number

StatusBeschreibung
200Updated MaxAge rule
404Rule not found
422Invalid ruleId format

DELETE /api/external/projectapi/keyval/maxage/{ruleId}​

Delete a MaxAge rule

Auth: APIKeyHeaderProject

ParameterInPflichtTypBeschreibung
ruleIdpath✔string
StatusBeschreibung
200Rule deleted
422Invalid ruleId format

Fehlt etwas auf dieser Seite?

Änderungswunsch einreichen