Knowledge and assistant endpoints
App API endpoints for knowledge sources, search, probe sets, setup, assistants, acceptance checks and tools, with fields, roles and errors.
In plain language
These endpoints let the app manage knowledge and assistants. You create knowledge sources. You keep pairs of question and answer. You check how well the search finds things. You set up an assistant from your website. You manage assistants, their versions and the code to embed them. For each endpoint you must be signed in to the app.
All documentation topics
This page covers the app API endpoints for managing knowledge sources, question-and-answer pairs, the search probe set, setup from your own website, assistants with their versions and embed code, acceptance checks and tools. Every endpoint sits under /api/v1/ and requires you to be signed in to the app. Connections that use an API key are described under Integration.
Access, roles and throttles
Every endpoint on this page requires a valid sign-in as described under Authentication, an active account and a confirmed email address. Any role may read; search and the test question are open to every role as well, since they write nothing. Any change to your data needs at least the Edit role. Deleting an assistant and replacing its public key are reserved for the Administration role.
| Role in the app | Identifier | Rank |
|---|---|---|
| Read | viewer | 10 |
| Edit | editor | 20 |
| Administration | admin | 30 |
| Owner | owner | 40 |
How roles are assigned is explained under Team and roles.
Throttles
Some endpoints carry a named throttle. It counts per signed-in user and minute; above it you receive 429. The general rules are under Limits.
| Throttle | Requests per minute | Endpoints |
|---|---|---|
knowledge-sources | 20 | create source, re-read, restore version, rebuild vectors, start setup |
knowledge-search | 60 | POST /knowledge/search |
knowledge-ask | 30 | POST /knowledge/ask |
knowledge-probes | 6 | POST /knowledge/probes/run |
knowledge-tune | 2 | POST /knowledge/probes/tune |
assistants | 30 | create and change assistants, versions, replace key, start acceptance run, create or change check questions, create and change tools |
Common errors
| Status | Identifier | Meaning |
|---|---|---|
| 403 | email_unverified | The email address has not been confirmed yet. |
| 403 | no_tenant, tenant_… | No account, or the account is not active; the suffix states its status. |
| 403 | role_too_low | Your role is not sufficient; required names the role needed. |
| 402 | plan_limit_reached | The plan limit has been reached; allowed, used and plan_name give the limit, current use and plan. |
| 503 | plan_limit_unmeasured | Usage could not be measured just now; the request was not carried out. |
| 404 | not_found | The entry does not belong to your account or does not exist. |
| 422 | field errors | A value breaks the rules in the tables below. |
| 429 | – | The throttle is used up. |
| 500 | not_logged | The audit entry could not be written, so the change was not carried out. |
How many sources, documents, chunks and assistants your plan allows is listed under Plans and quotas and on the pricing page.
Knowledge sources
In the app, sources live under Knowledge (app.xicbot.de/wissen). What a source is and how answers are built from it is explained under Knowledge and Knowledge and answers.
GET /api/v1/knowledge/sources
Lists the account’s sources, newest first, up to 200. The response also carries the vector status (vectors), the enrichment status with keywords and questions (enrichment) and the limits of the input fields (limits).
- Authentication
- Signed in, confirmed email address, any role
- Rate limit
- none
Field in limits | Value | Meaning |
|---|---|---|
chunk_default_chars | 800 | default Chunk size in characters |
chunk_overlap_default_chars | 120 | default Overlap in characters |
chunk_defaults_by_type | target, overlap per type | default per source type; files start at 1400 and 200 |
chunk_min_chars, chunk_max_chars | 200, 4000 | smallest and largest chunk size you can set |
exclude_max_patterns | 50 | maximum number of Excluded paths per source |
exclude_max_length | 300 | maximum length of one pattern in characters |
crawl_max_pages | 25 | maximum pages one pass over a website reads |
refresh_min_days, refresh_max_days | 1, 365 | allowed range for refresh_days |
refresh_default_days | number | default used when refresh_days is left empty |
Field in vectors and enrichment | Meaning |
|---|---|
chunks | total number of chunks |
embedded | chunks with a finished vector (vectors only) |
enriched | enriched chunks (enrichment only) |
pending | chunks still outstanding |
model | identifier of the method that builds the vectors (vectors) or enriches the chunks (enrichment) |
Each source appears in the list with these fields:
| Field | Meaning |
|---|---|
id, type, title, created | identifier, type, Label, creation time |
origin | for websites the Start address, for files the original file name |
status, error | ingestion status and the error, if any, see States |
documents, chunks | number of documents and chunks |
version, versions_kept | number of the version currently answering and how many versions are kept (5) |
refresh_days | the interval entered on the source; null means nothing was entered |
last_checked, last_failed | time of the last confirmation (Last confirmed) and the last failure (Failed on) |
fresh, fresh_measured, fresh_reason | measured for websites only: Current or Stale; otherwise fresh_measured is false with reason not_applicable, and never_checked for websites never confirmed |
crawl_truncated, crawl_pending, crawl_measured, crawl_reason | whether the last pass stopped at the page cap and how many links were left; reason not_applicable for other types, never_crawled before the first pass |
chunk_target, chunk_overlap, exclude_patterns | the source’s own settings |
pairs | number of question-and-answer pairs in a source of type faq |
pairs_matchable | of these, the active pairs with an answer, i.e. those that can answer a question; like pairs, counted only in this list |
Source states
status | In the app | Meaning |
|---|---|---|
new | new | created, ingestion not started yet |
running | processing | the website is being read |
ready | indexed | content is available |
failed | not indexed | ingestion failed, error gives the reason |
stale | outdated | a website has been marked as outdated |
GET /api/v1/knowledge/sources/{id}
Returns one source (source) with its documents (documents), sorted by title, up to 200. Each document carries id, title, url, characters, is_draft, published_at and published. Drafts and documents not yet published are included here. documents_total states how many documents the source has, documents_limit the cap of the list (200); if documents_total is larger, the list is cut off.
- Authentication
- Signed in, confirmed email address, any role
- Rate limit
- none
POST /api/v1/knowledge/sources
Creates a source. Text and file sources are ingested straight away and return 201, even if ingestion fails: the source then exists with status failed and an error. A website is read in the background; the response is 202 with the source and the job (job with id, status, task). A source of type faq is ready at once and stays empty until you add pairs. There is one per account: if one already exists, the response is 422 with faq_exists and source_id, the ID of the collection new pairs go into. Text, file and website sources are followed by a job that builds the vectors. In the app: New source, then Add source.
- Authentication
- Signed in, confirmed email address, Edit role or higher; plan limits for sources, documents and chunks
- Rate limit
- Throttle
knowledge-sources: 20 requests per minute per user, see Limits
| Field | Required | Rule |
|---|---|---|
type | yes | text, file, website or faq (Type of source) |
title | yes | up to 200 characters (Label) |
text | for text | up to 1,000,000 characters (Content) |
url | for website | valid URL, up to 500 characters (Start address) |
file | for file | uploaded file (Choose file), sent as multipart/form-data |
refresh_days | no | website only; integer from 1 to 365 |
exclude_patterns | no | website only; list of up to 50 patterns, each up to 300 characters (Excluded paths) |
chunk_target | no | integer from 200 to 4000 (Chunk size) |
chunk_overlap | no | integer from 0 (Overlap); at most half the chunk size takes effect |
draft | no | text and file only; true or false |
published_at | no | text and file only; publication date |
A website address is checked before the source is created. If it cannot be parsed, uses a scheme that is not allowed, has a name that does not resolve or points to a target that is not allowed, you get 422 with url_unreadable, scheme_not_allowed, name_unresolvable or target_not_allowed.
PUT /api/v1/knowledge/sources/{id}
Changes a source’s settings; PATCH works the same way. All fields are optional: title (up to 200 characters), refresh_days, exclude_patterns, chunk_target, chunk_overlap, with the rules used when creating; null resets refresh_days and exclude_patterns to the default, and for websites also chunk_target and chunk_overlap; title does not accept null. Nothing is ingested: new chunk sizes take effect on the next pass. On a source that is not a website, the following return 422 website_only, with field naming the field concerned, or the first of several in the order refresh_days, exclude_patterns, chunk_target, chunk_overlap: a value for refresh_days, a non-empty list in exclude_patterns that differs from the stored one, and a value for chunk_target or chunk_overlap that differs from the stored one, including null. Still accepted there are null for refresh_days, null or an empty list for exclude_patterns, and the stored list and the stored chunk sizes. Without an audit entry the source stays unchanged; the response is then 500 with not_logged. Response: source.
- Authentication
- Signed in, confirmed email address, Edit role or higher
- Rate limit
- none
DELETE /api/v1/knowledge/sources/{id}
Deletes a source; the audit entry records how many documents and chunks it had. The audit entry is written first, in the same step as the deletion; if it fails, the source stays and the response is 500 with not_logged. Response: {"deleted": true}.
- Authentication
- Signed in, confirmed email address, Edit role or higher
- Rate limit
- none
POST /api/v1/knowledge/sources/{id}/refresh
Re-reads a website (Re-read). With "rebuild": true, unchanged pages are split into chunks again as well (Rebuild completely); you need this after changing the chunk size. If an ingestion or re-read job for this source is already open, waiting or running, it is reused and already_open is true; task then names its kind, source.ingest or source.refresh. A waiting job still picks up a requested rebuild; if the job is already running without one, you get 409 refresh_running. The API also queues the vector build for the source. Source types other than websites return 422 website_only. Response: 202 with job (id, status, task) and already_open.
- Authentication
- Signed in, confirmed email address, Edit role or higher; plan limits for documents and chunks
- Rate limit
- Throttle
knowledge-sources: 20 requests per minute per user, see Limits
GET /api/v1/knowledge/jobs/{id}
Shows the status of a job from this account: id, task, status, attempts, error, result and finished_at. Use it to follow ingestion, re-reading and vector building. How jobs are processed is described under Background jobs.
- Authentication
- Signed in, confirmed email address, any role
- Rate limit
- none
Source versions
GET /api/v1/knowledge/sources/{id}/versions
Lists the versions kept for a source (Versions). current is the version currently answering (answering), kept the number of versions kept (5), and versions the list.
- Authentication
- Signed in, confirmed email address, any role
- Rate limit
- none
POST /api/v1/knowledge/sources/{id}/versions/{number}/restore
Brings back an earlier version (Restore). Versions above the one named are discarded. A number that is not before the current one returns 422 not_a_previous_version; one that is no longer kept returns 422 version_not_kept; an open ingestion or re-read job for this source, waiting or running, returns 409 refresh_running. Response: restored, source, current, kept (how many versions are kept at most), discarded (number of discarded versions) and versions (list of versions).
- Authentication
- Signed in, confirmed email address, Edit role or higher
- Rate limit
- Throttle
knowledge-sources: 20 requests per minute per user, see Limits
POST /api/v1/knowledge/embed
Starts building the missing vectors, for the whole account or, with source_id, for one source. If such a job is already waiting, it is reused. Response: 202 with job, already_open, vectors and enrichment.
- Authentication
- Signed in, confirmed email address, Edit role or higher
- Rate limit
- Throttle
knowledge-sources: 20 requests per minute per user, see Limits
Search and test question
POST /api/v1/knowledge/search
Searches for chunks matching a question without writing an answer. This shows you what an assistant finds for a question.
- Authentication
- Signed in, confirmed email address, any role
- Rate limit
- Throttle
knowledge-search: 60 requests per minute per user, see Limits
| Field | Required | Rule |
|---|---|---|
question | yes | up to 2000 characters |
source_id | no | identifier of a source to limit the search to |
count | no | 1 to 20 hits, default 6 |
context | no | true or false, default true: also returns the chunk’s surroundings in the document |
language | no | language code, up to 5 characters |
| Hit field | Meaning |
|---|---|
chunk_id, source_id | identifier of the chunk and its source |
document, heading | document title and chunk heading |
excerpt | the first 400 characters of the chunk |
keywords, questions | keywords and questions from enrichment; null means not enriched yet, an empty list means none found |
context | surroundings in the document when context is true |
value | hit score, rounded to five places |
paths | which search paths found the chunk |
Fields without a value are left out of the hit.
POST /api/v1/knowledge/ask
Asks the knowledge base a test question and returns an answer with citations, as the app shows under Check an answer. If the question matches an active question and answer pair, that pair's answer comes word for word without a model call. Otherwise the answer draws on up to five chunks found by search and, once their coverage is sufficient, up to twelve further chunks from text blocks. The answer is written in the language of the question if that can be identified as German or English. How an answer is produced is explained under Knowledge and answers.
- Authentication
- Signed in, confirmed email address, any role
- Rate limit
- Throttle
knowledge-ask: 30 requests per minute per user, see Limits
| Field | Required | Rule |
|---|---|---|
question | yes | up to 2000 characters (Your question) |
language | no | de or en; applies only if the question cannot be reliably identified as German or English, then with the default de |
source_id | no | identifier of a source |
| Response field | Meaning |
|---|---|
answered | whether an answer was produced |
text | answer text or the refusal |
citations | citations with number, chunk_id, document, heading, excerpt |
path | model for a written answer, qa_pair for an answer taken from a question-and-answer pair, none for a refusal |
reason | reason for the refusal, otherwise null |
blocks | number of chunks from text blocks supplied in addition to the hits, see Text blocks; null for a refusal and for an answer from a question-and-answer pair |
model | identifier of the method used |
A refusal comes with these reasons and texts:
reason | Text |
|---|---|
empty_question | “Please ask a question.” |
nothing_found, not_covered, model_declined, without_citation | “The stored knowledge base does not cover this.” |
no_model | “An answer is not possible right now. Please try again later.” |
Question-and-answer pairs
Without source_id, a new pair goes into the oldest source of type faq; if there is none, one is created. Its title follows the locale of the signed-in person (Account and profile): “Questions and answers” for en, otherwise “Fragen und Antworten”. That new source counts against the plan limit for sources; if the limit is reached, no pair is created and the response is the same as when creating a source. With source_id you name the source yourself.
GET /api/v1/knowledge/qa-pairs
Lists the pairs, ordered by position, creation time and identifier, up to 500; with source_id, only those of one source. Each pair carries id, source_id, question, answer, variants, position, is_active and created. It also returns matching: limit states how many active pairs with an answer the answer search compares at most (300, in the order of this list), active how many such pairs exist. If active is greater than limit, the rest never match. variants states the limits for the variants of a pair: max (20) and length (500 characters per variant).
- Authentication
- Signed in, confirmed email address, any role
- Rate limit
- none
POST /api/v1/knowledge/qa-pairs
Creates a pair. A pair without an answer is stored as inactive. Duplicate variants are dropped. Without an audit entry no pair is created; the response is then 500 with not_logged. Response: 201 with pair.
- Authentication
- Signed in, confirmed email address, Edit role or higher
- Rate limit
- none
| Field | Required | Rule |
|---|---|---|
question | yes | up to 500 characters |
answer | no | up to 5000 characters |
variants | no | up to 20 alternative phrasings, each up to 500 characters |
position | no | 0 to 9999 |
is_active | no | default true; false without an answer |
source_id | no | identifier of a source in your account; an unknown one returns 404 not_found |
PUT /api/v1/knowledge/qa-pairs/{id}
Changes a pair; all fields optional, same rules as for creating. If the answer ends up empty, the pair becomes inactive. variants replaces the list of variants, dropping duplicates; without variants it stays as it is. Without an audit entry the pair stays unchanged; the response is then 500 with not_logged. Response: pair.
- Authentication
- Signed in, confirmed email address, Edit role or higher
- Rate limit
- none
DELETE /api/v1/knowledge/qa-pairs/{id}
Deletes a pair. Without an audit entry it stays; the response is then 500 with not_logged. Response: {"deleted": true}.
- Authentication
- Signed in, confirmed email address, Edit role or higher
- Rate limit
- none
Probe set and weighting
The Probe set measures whether search finds the expected document for a question. A probe line consists of a Question and the Expected document. A run only queries your own search, with no model and no outside network, so it runs directly within the request. Each account can hold 100 probe lines; search looks down to position 10.
GET /api/v1/knowledge/documents
Lists the documents you choose an expected document from: id, title, source_title; up to 500, limit states the number.
- Authentication
- Signed in, confirmed email address, any role
- Rate limit
- none
GET /api/v1/knowledge/probes
Returns the probe lines (probes), the limit (limit, 100), the search depth (depth, 10), the weighting (weights) and the last run (run with probes, hits, mrr, ran_at, or null).
- Authentication
- Signed in, confirmed email address, any role
- Rate limit
- none
| Probe line field | Meaning |
|---|---|
id, question, language | identifier, question, language |
expected_document_id, expected_title | expected document and its title |
last_rank | position in the last run (Position {n}); 0 means measured but not found; null means never measured |
last_run_at | time of the last run |
POST /api/v1/knowledge/probes
Creates a probe line (Add probe line): question (required, up to 500 characters), expected_document_id (required, a document identifier), language (de or en, optional). If 100 lines already exist, you get 422 probe_limit; an unknown document returns 404. Without an audit entry no probe line is created; the response is then 500 with not_logged. Response: 201 with probe.
- Authentication
- Signed in, confirmed email address, Edit role or higher
- Rate limit
- none
DELETE /api/v1/knowledge/probes/{id}
Deletes a probe line. Without an audit entry it stays; the response is then 500 with not_logged. Response: {"deleted": true}.
- Authentication
- Signed in, confirmed email address, Edit role or higher
- Rate limit
- none
POST /api/v1/knowledge/probes/run
Measures all probe lines (Measure) and returns run with probes, hits (Found), mrr and ran_at, plus the updated lines. mrr is the Retrieval quality: the mean of one divided by the expected document’s position, rounded to three decimal places; a document that is not found counts as 0. Without probe lines you get 422 no_probe.
- Authentication
- Signed in, confirmed email address, Edit role or higher
- Rate limit
- Throttle
knowledge-probes: 6 requests per minute per user, see Limits
Weighting
Two settings determine how search ranks hits: the Title factor (title_factor, 1.0 to 5.0, default 1.8) boosts hits in the document title, and the Keyword weight (keyword_tf, 0 to 10, default 3) boosts hits in the enriched keywords. weights contains title_factor and keyword_tf (in effect), set (your own entries), default and bounds.
PUT /api/v1/knowledge/weights
Saves the weighting (Save weighting). Both fields are optional; null resets to the default. title_factor is rounded to two places. Without an audit entry the weighting stays unchanged; the response is then 500 with not_logged. Response: weights.
- Authentication
- Signed in, confirmed email address, Edit role or higher
- Rate limit
- none
POST /api/v1/knowledge/probes/tune
On the oldest up to 20 lines of the probe set, tries first each title factor (1.0, 1.4, 1.8, 2.2, 2.6, 3.0) at the current keyword weight, then each keyword weight (0, 1, 2, 3, 5, 8) at the best title factor (Tune). Without apply, it only measures. With "apply": true (Apply best value), the best candidate is adopted, but only if it genuinely beats the current setting; on a tie nothing changes (No candidate beats the current setting.). If the audit entry for adopting it cannot be written, the current weighting stays; the response is then 500 with not_logged. Response: tuning with rows_used, rows_total, current, best, candidates, plus applied and weights.
- Authentication
- Signed in, confirmed email address, Edit role or higher
- Rate limit
- Throttle
knowledge-tune: 2 requests per minute per user, see Limits
Setup from your website
Setup reads your website, proposes an assistant from it and creates that assistant based on your choices. In the app this is Setup (app.xicbot.de/einrichtung); the workflow is described under Setup. Starting a run counts against the same limits as a knowledge source, because it creates one.
status | Meaning |
|---|---|
liest | the website is being read |
schlaegt_vor | the proposal is being written (The proposal is being written.) |
entscheidung | the Proposal is ready and waits for your choices |
uebernommen | the assistant has been created (The assistant has been created.) |
fehler | the run failed; hinweis gives the reason (The run failed) |
leer | no content came out of the website; hinweis gives the reason (No proposal) |
GET /api/v1/setup/runs
Lists the last 20 runs, newest first (Earlier runs). Response: runs.
- Authentication
- Signed in, confirmed email address, any role
- Rate limit
- none
| Run field | Meaning |
|---|---|
id, website, status | identifier, address read, status |
language | de or en: the proposal and first version are written in this language; de if none is stored |
vorschlag | the proposal with zweck and rolle (each with text and fundstelle), name, tonfall, erster_satz, fragen (each with frage, antwort, fundstelle), schweigethemen, luecken and removed: what was removed from the proposal (Removed from the proposal), each entry with kind promise and the word in word, no_source and the field in field, or question_no_source and the question in question |
angenommen | the selection you accepted |
hinweis | for fehler and leer, the reason as a code: website_unreadable (for leer possibly followed by the ingestion reason after a colon), no_text, too_little_text: with the number of characters read, model_unavailable, budget_exhausted, model_failed, reply_unreadable or run_aborted; otherwise null. The app shows a sentence for it in the interface language. |
assistent_id | the assistant created |
erstellt, beendet | start and end |
dismissed_at | time the run was dismissed, otherwise null; the app no longer shows a dismissed run by itself when opened |
taboo_limit | how many schweigethemen accepting takes (the cap of the never-discuss list) |
POST /api/v1/setup/runs
Starts a run with website (required, an http or https address, up to 255 characters; Address of your website, button Read website) and optionally language (de or en, Language of the assistant; if omitted, the locale of your account; any other value gives 422). The website is created as a knowledge source; that source stays yours even if you do not accept the proposal. If a run is already in progress (status liest or schlaegt_vor), you get 409 run_in_progress with that run in run. An open run whose processing is no longer active and that has not changed for more than a minute is ended as fehler with the note run_aborted before a start and before the list of runs; it then no longer blocks a new start. Response: 201 with run.
- Authentication
- Signed in, confirmed email address, Edit role or higher; plan limits for sources, documents and chunks
- Rate limit
- Throttle
knowledge-sources: 20 requests per minute per user, see Limits
GET /api/v1/setup/runs/{id}
Returns one run (run). Poll it until it reaches entscheidung, fehler or leer.
- Authentication
- Signed in, confirmed email address, any role
- Rate limit
- none
POST /api/v1/setup/runs/{id}/accept
Adopts your selection from the proposal and creates an assistant as a Draft (Create assistant). Only possible in the entscheidung state, otherwise 409 not_ready with the current status; a dismissed run can be accepted, which clears dismissed_at. If a source of type faq has to be created for the questions first and the plan limit for sources has been reached, the adoption ends without an assistant, with the same response as creating a source (402 plan_limit_reached, or 503 plan_limit_unmeasured if usage cannot be measured). Without an audit entry for the assistant or the new source, the whole adoption is not carried out; the response is then 500 with not_logged. Response: 201 with the run (run) and assistant (id, name, slug, status).
- Authentication
- Signed in, confirmed email address, Edit role or higher; plan limit for assistants
- Rate limit
- none
| Field | Rule | In the app | Becomes |
|---|---|---|---|
name | required, up to 80 characters | Name of the assistant | name |
zweck | up to 600 characters | What your business does | Topic boundary of the first version |
rolle | up to 200 characters | Who the assistant represents | Role of the first version |
tone | neutral, friendly, concise or detailed | How it speaks with factual, friendly, brief and detailed, preselected factual; the tone sentence from the proposal is shown below only as a hint | Tone of the first version, factual if omitted; the tonfall sentence from the proposal is not adopted |
erster_satz | up to 300 characters | Its opening line | Greeting |
fragen | up to 50, each with required frage (500) and antwort (4000) | Questions and answers | pairs in the oldest source of type faq, otherwise in a new source of type faq whose title follows the locale of the person adopting (“Questions and answers” for en, otherwise “Fragen und Antworten”); questions already in your account (ignoring upper and lower case) are skipped, and duplicate questions in the selection count once |
schweigethemen | at most as many as taboo_limit (8), each up to 120 characters; more or longer gives 422 | Topics it stays silent on | taboo topics of the first version, duplicates removed |
POST /api/v1/setup/runs/{id}/discard
Dismisses a run (Dismiss): dismissed_at is set, and dismissing again keeps the first time. Nothing is deleted; the run stays in the list and a dismissed proposal can still be accepted. Only in the entscheidung, leer and fehler states, otherwise 409 not_discardable with the current status; unknown ID 404 not_found. Response: 200 with run.
- Authentication
- Signed in, confirmed email address, Edit role or higher
- Rate limit
- none
The first version of an assistant created this way answers only from the knowledge base and has the language of the run (language); the handover rule and fallback answer come from the base template of that language, as do the role, topic boundary and greeting where your selection leaves them empty.
Assistants
In the app, assistants live under Assistants (app.xicbot.de/assistenten). What each building block does is explained under Assistants. An assistant has header data (name, status, fallback answer, widget settings) and versions holding the Answer building blocks. You change header data directly; a change to the building blocks creates a new version and leaves the old one untouched.
GET /api/v1/assistants/templates
Lists the templates (Template), grouped into Industries and Tasks. With ?language=en you get the English texts; the default is de. Response: templates.
- Authentication
- Signed in, confirmed email address, any role
- Rate limit
- none
GET /api/v1/assistants
Lists the assistants by name, up to 200, each with its active version. Response: assistants.
- Authentication
- Signed in, confirmed email address, any role
- Rate limit
- none
GET /api/v1/assistants/{id}
Returns one assistant (assistant) and its versions (versions), newest first, up to 50.
- Authentication
- Signed in, confirmed email address, any role
- Rate limit
- none
Field of assistant | Meaning |
|---|---|
id, name, slug, template | identifier, name, short name, template |
status | draft (Draft), active (active) or paused (paused) |
fallback_reply | Fallback answer |
version | the active version |
widget | widget settings: is_active, title, color, position, vertical, offset_x, offset_y, width, height, scale, radius, avatar, outreach_rules, domains, consent, consent_text, attachments, base_url and key, the Public key |
POST /api/v1/assistants
Creates an assistant as a Draft (New assistant, Create assistant), together with version 1. Fields: name (required, up to 120 characters), template (template identifier, up to 40 characters; omitted means no template), language (de or en). The short name is derived from the name, up to 50 characters; if it is already taken in your account, -2, -3 and so on is appended. The first version answers only from the knowledge base. An unknown template returns 422 unknown_template. Without an audit entry neither the assistant nor the version is created; the response is then 500 with not_logged. Response: 201 with assistant.
- Authentication
- Signed in, confirmed email address, Edit role or higher; plan limit for assistants
- Rate limit
- Throttle
assistants: 30 requests per minute per user, see Limits
PUT /api/v1/assistants/{id}
Changes the header data; all fields are optional. The widget fields are described in detail under Widget settings. Response: assistant.
- Authentication
- Signed in, confirmed email address, Edit role or higher
- Rate limit
- Throttle
assistants: 30 requests per minute per user, see Limits
| Field | Rule |
|---|---|
name | up to 120 characters |
status | draft, active or paused (Status) |
fallback_reply | 5 to 500 characters (Fallback answer) |
widget_enabled | true or false |
widget_title | up to 80 characters |
widget_color | colour as #rrggbb |
widget_position, widget_vertical | right or left; bottom or top |
widget_offset_x, widget_offset_y | 0 to 400 |
widget_width, widget_height | 280 to 720; 320 to 1200 |
widget_scale, widget_radius | 80 to 150; 0 to 40 |
widget_avatar | PNG, JPEG or WebP image in a data: URL; errors widget_avatar_format, widget_avatar_too_large, widget_avatar_not_an_image |
widget_domains | up to 500 characters |
widget_consent, widget_consent_text | true or false; up to 500 characters |
widget_outreach_rules, widget_attachments | see Outreach rules and Widget settings |
widget_base_url | up to 200 characters, absolute http or https address without a query part or fragment; a trailing slash is removed; errors widget_base_url_not_absolute, widget_base_url_scheme, widget_base_url_has_query |
Versions
POST /api/v1/assistants/{id}/version
Publishes a new version (Publish new version). It gets the next number and becomes active straight away. Send the required fields from the table every time. taboos, facts, master_data, escalation_topics, escalation_threshold, escalation_words and handoff_email are carried over from the active version if you do not send them; knowledge_only is true if omitted. Without an audit entry no new version is created and the previously active one stays active; the response is then 500 with not_logged. Response: 201 with version.
- Authentication
- Signed in, confirmed email address, Edit role or higher
- Rate limit
- Throttle
assistants: 30 requests per minute per user, see Limits
| Field | Required | Rule | In the app |
|---|---|---|---|
persona | yes | up to 200 characters | Role |
tone | yes | neutral, friendly, concise or detailed | Tone: factual, friendly, brief, detailed |
topic_scope | yes | up to 600 characters | Topic boundary |
handoff_rule | yes | up to 400 characters | Handover rule |
greeting | yes | up to 500 characters | Greeting |
language | yes | de or en | – |
knowledge_only | no | true or false, default true | Answer only from the knowledge base |
taboos | no | up to 8 entries of up to 120 characters | taboo topics |
facts | no | up to 12 entries of up to 200 characters | fixed facts |
master_data | no | see Business details | business details |
escalation_topics | no | identifiers of known topics; unknown ones return 422 unknown_topic with topics | handover topics |
escalation_threshold | no | 1 to 20, default 3 | handover threshold |
escalation_words | no | per topic up to 20 words of 3 to 40 characters | signal words |
handoff_email | no | email address, up to 190 characters; only the Owner may change it | handover address |
Anyone who changes the handover address without being the Owner receives 403 role_too_low with required owner and field handoff_email. Sending the existing address unchanged is not a change and is not rejected.
Business details
Part of master_data | Rule |
|---|---|
opening_hours | up to 14 entries with day (mon to sun), from, to (time HH:MM) |
locations | up to 5 with name (required), street, postal_code, city |
service_area | up to 20 entries of up to 80 characters |
contacts | up to 5 with role (required), name, email, phone |
price_ranges | up to 10 with item, from_cents (required, from 0), to_cents, unit, currency (three letters) |
Any other field in master_data returns 422 unknown_master_field with fields.
A version in a response (version) carries, besides these fields, id, number, restored_from, published_at and the limits the app needs for its form, such as taboo_limit, fact_limit, master_data_limits, escalation_threshold_min and escalation_threshold_max.
POST /api/v1/assistants/{id}/versions/{number}/restore
Brings back an earlier version by creating a new version with its content; restored_from names the source. The versions in between are kept. An unknown number returns 404 version_not_found, the version already active 422 already_active. If the old version carries a different handover address, the owner rule above applies. Without an audit entry no new version is created and the previously active one stays active; the response is then 500 with not_logged. Response: 201 with restored, from and version.
- Authentication
- Signed in, confirmed email address, Edit role or higher
- Rate limit
- Throttle
assistants: 30 requests per minute per user, see Limits
Deletion, embed code and key
DELETE /api/v1/assistants/{id}
Deletes an assistant with its versions and all of its conversations. The audit entry is written first; if that fails, everything stays and the response is 500 with not_logged. Response: {"deleted": true}.
- Authentication
- Signed in, confirmed email address, Administration role or higher
- Rate limit
- none
GET /api/v1/assistants/{id}/embed
Returns the embed code and its parts. How to place it on your site is described under Embed the widget and Script attributes.
- Authentication
- Signed in, confirmed email address, any role
- Rate limit
- none
| Response field | Meaning |
|---|---|
snippet | the embed code |
url, api, key | address of the embed file, API address, public key |
base, snippet_first_party | your own base address and the embed code for it, when widget_base_url is set |
sri, reason | checksum of the delivered embed file or, if missing, the reason (file_missing, file_unreadable); neither goes into the embed code |
seen_at, seen_host | when and on which site the embed was last reported |
Source code html
<script src="{url}/einbetten.js" data-xicbot="{key}" data-api="{api}" defer></script>If consent is switched on for the assistant, the embed code also carries data-einwilligung="erforderlich".
POST /api/v1/assistants/{id}/key
Replaces the public key (Generate a new key). After that, no existing embed loads any more; the app reports: *The new key is active. Please replace the embed code everywhere.* The audit entry is written first; if that fails, the previous key stays valid and the response is 500 with not_logged. An unknown assistant gives 404 not_found. Response: key, the new key of 32 hexadecimal characters.
- Authentication
- Signed in, confirmed email address, Administration role or higher
- Rate limit
- Throttle
assistants: 30 requests per minute per user, see Limits
GET /api/v1/usage
Shows the quota for the current month (Quota this month). From 80 percent use, level is warning; once the quota is used up, exhausted; otherwise ok. Without an account you get 403 no_tenant. Plan quotas are listed under Plans and quotas.
- Authentication
- Signed in, confirmed email address, any role
- Rate limit
- none
Field in usage | Meaning |
|---|---|
month | month |
used, budget, remaining | used, available, left |
messages | number of messages |
share | share used |
warn_at | warning threshold |
warning, throttled, exhausted | warning, throttled, used up |
reply_tokens, tool_rounds | caps per answer, lower from the warning threshold |
level | ok, warning or exhausted |
Acceptance checks
An acceptance run puts fixed check questions to an assistant’s active version and compares the answers with a Model answer. The workflow in the app is described under Test and acceptance. Each assistant can hold 50 check questions.
GET /api/v1/assistants/{id}/checks
Lists the check questions (checks), each with last_result and last_run_at, plus limit (50), terms_limit (10 terms per list) and the last run (last_run).
- Authentication
- Signed in, confirmed email address, any role
- Rate limit
- none
POST /api/v1/assistants/{id}/checks
Creates a check question (Add check question); it is appended at the end. If 50 already exist, you get 422 limit_reached. Response: 201 with check.
- Authentication
- Signed in, confirmed email address, Edit role or higher
- Rate limit
- Throttle
assistants: 30 requests per minute per user, see Limits
| Field | Required on create | Rule | In the app |
|---|---|---|---|
question | yes | 3 to 500 characters | Question |
expected | yes | 3 to 4000 characters | Model answer |
must_contain | no | up to 10 terms of up to 80 characters | Must contain |
must_not_contain | no | up to 10 terms of up to 80 characters | Must not contain |
min_overlap | no | 0 to 1, default 0.5 | Minimum coverage |
language | no | de or en | – |
position | no | 0 to 9999 | – |
is_active | no | true or false | Runs along |
PUT /api/v1/assistants/{id}/checks/{check}
Changes a check question; all fields are optional. Response: check.
- Authentication
- Signed in, confirmed email address, Edit role or higher
- Rate limit
- Throttle
assistants: 30 requests per minute per user, see Limits
DELETE /api/v1/assistants/{id}/checks/{check}
Deletes a check question. Response: {"deleted": true}.
- Authentication
- Signed in, confirmed email address, Edit role or higher
- Rate limit
- none
POST /api/v1/assistants/{id}/checks/run
Starts an acceptance run (Start acceptance run) with every check question set to run along. The run works in the background; if one is already waiting or running, it is reused. Without an active version you get 422 no_version, without a check question that runs along 422 no_check, and with the quota used up 422 quota_exhausted. Response: 202 with run.
- Authentication
- Signed in, confirmed email address, Edit role or higher
- Rate limit
- Throttle
assistants: 30 requests per minute per user, see Limits
GET /api/v1/assistants/{id}/check-runs
Lists the last 30 runs, newest first. Response: runs.
- Authentication
- Signed in, confirmed email address, any role
- Rate limit
- none
GET /api/v1/assistants/{id}/check-runs/{run}
Returns one run (run) with the result for each check question (results).
- Authentication
- Signed in, confirmed email address, any role
- Rate limit
- none
| Field | Meaning |
|---|---|
status | pending (queued), running (running), done (finished), failed (stopped) |
checks, passed, failed, errored | number of check questions, Passed, Failed, Not measurable |
rate | Rate: passed divided by passed plus failed, to three places; null while nothing has been scored |
version_id | the version checked |
started_at, finished_at, duration_ms, reason, created_at | times, duration and reason for stopping |
A result (result) is pass (passed), fail (failed) or error (not measurable). An answer passes when every term from Must contain appears, none from Must not contain does, and its coverage of the model answer reaches the Minimum coverage; if the minimum is 0 or coverage cannot be measured, that last part is skipped. Upper and lower case do not matter. Each result gives answer, missing, forbidden, overlap, reason, conversation_id and duration_ms.
Tools
Tools give an assistant actions, such as taking a request or searching a catalogue. What each type does is explained under Tools and Tool kit. Creating, changing and deleting needs the Edit role; Interface address, Access token and Minimum role additionally need the Administration role.
Type (type) | Kind | Default Approval |
|---|---|---|
lead | write | confirm |
appointment | write | confirm |
handoff | write | confirm |
product_search | read | automatic |
cart | irreversible | confirm |
http | read | confirm |
form_fill | write | confirm |
The types from the Tool kit come on top; each brings its own kind and default approval. Only read tools may be set to automatic; for all others the API sets confirm, whatever you send.
GET /api/v1/assistants/{assistant}/tools
Lists an assistant’s tools.
- Authentication
- Signed in, confirmed email address, any role
- Rate limit
- none
| Tool field | Meaning |
|---|---|
id, key, title, description | identifier, Key, Label, When should the assistant use it? |
adapter, kind | type and kind |
approval, min_role | Approval, Minimum role |
required_fields, required_effective | entered and actually applied Required fields |
schema | Input fields |
settings | settings; a stored Access token appears as __set__ |
is_active | Active |
timezone_valid | for type appointment, whether the time zone in settings is valid (true or false), judged the same way as when saving; null for all other types |
POST /api/v1/assistants/{assistant}/tools
Creates a tool (Add tool). Response: 201 with tool.
- Authentication
- Signed in, confirmed email address, Edit role or higher
- Rate limit
- Throttle
assistants: 30 requests per minute per user, see Limits
| Field | Required | Rule |
|---|---|---|
type | yes | one of the types above or from the tool kit (Type) |
key | yes | lower-case letter first, then lower-case letters, digits or _, 3 to 64 characters; unique per assistant |
title | yes | up to 120 characters |
description | yes | up to 600 characters |
approval | no | automatic or confirm |
min_role | no | public, member, admin or owner; default public |
required_fields | no | up to 20 names of up to 40 characters |
settings | no | type-specific settings, for http with address and access token |
schema | no | custom input fields, see below |
is_active | no | true or false |
| Status | Identifier | Meaning |
|---|---|---|
| 422 | key_taken | This key already exists for this assistant. |
| 422 | shape_unknown | unknown type |
| 422 | url_required | type http without an address |
| 422 | url_unreadable, scheme_not_allowed, name_unresolvable, target_not_allowed | the address fails the address check |
| 422 | settings check codes, for example appointment_timezone_invalid | the settings of type appointment, cart or form_fill fail the check; appointment_timezone_invalid means an unknown time zone in settings, an empty value counts as the default |
| 403 | role_too_low with field min_role | the chosen minimum role is above your own (You can choose levels up to your own role.) |
| 403 | role_too_low with required admin and field | address, access token or minimum role changed without the Administration role |
| 402 | plan_feature_missing | the type is not part of the plan; feature, plan, plan_name and available_in name the feature, plan and the plans that include it |
Custom input fields
For the http type you define under Input fields which values the assistant passes on. schema is a list of fields with Field name, Type, Description and Required. These rules apply: at most 20 fields; a name starts with a lower-case letter followed by up to 39 lower-case letters, digits or _; the names tenant_id, mandant, mandant_id and konto_id are blocked; types are string, integer, number and boolean, and any other type becomes string; the description is cut to 200 characters and defaults to the field name. The service refuses a schema that breaks these rules with 422: schema_field_name_invalid or schema_field_name_reserved with the field name under field, schema_fields_too_many with max, schema_required_unknown for a required name without a field. Nothing is saved in that case.
PUT /api/v1/tools/{id}
Changes a tool. The type stays as it is; title and description are required again, the other fields optional. If you send __set__ as the access token, the stored one is kept. Response: tool.
- Authentication
- Signed in, confirmed email address, Edit role or higher
- Rate limit
- Throttle
assistants: 30 requests per minute per user, see Limits
DELETE /api/v1/tools/{id}
Deletes a tool. If the audit entry fails, the tool stays and the response is 500 with not_logged. Response: {"deleted": true}.
- Authentication
- Signed in, confirmed email address, Edit role or higher
- Rate limit
- none
Frequent questions
Why does creating a website source return 202 instead of 201?
A website is read in the background. The response contains the job; check its status with GET /api/v1/knowledge/jobs/{id} and the source’s status with GET /api/v1/knowledge/sources/{id}.
How do I check whether search finds the right document?
Create probe lines with a question and the expected document and measure with POST /api/v1/knowledge/probes/run. POST /api/v1/knowledge/probes/tune then tries other weightings and, with "apply": true, adopts only a genuine improvement.
Do I lose newer versions when I restore?
For a knowledge source, yes: versions above the restored one are discarded. For an assistant, no: restoring creates a new version with the old content.
Why do I get 403 when changing the handover address?
Only the account owner may change the handover address. The response states required owner and field handoff_email.
What happens to embedding pages when I replace the key?
They stop loading the widget until the new embed code is in place. Fetch it with GET /api/v1/assistants/{id}/embed.
Ask it yourself, Assistant of this website
Automated assistant