API basics

This page covers what applies to every route of the XICBOT API: base address and version, access zones, how requests and errors are structured, HTTPS, response headers, CORS, pagination and how repeated requests behave. Individual routes are documented on the pages for authentication, integration and the other areas.

Base address and version

The API is served under https://app.xicbot.de/api/. Every functional route carries the version v1 in its path, so the base address for your own calls is https://app.xicbot.de/api/v1/. The web app and the clients in the tool kit call the same routes.

To check whether the API is working, call GET /api/v1/public/status; no sign-in is needed. It reports only whether each part is working and gives no further detail. See availability and monitoring.

The simplest way to test a connection is the integration status route. It is the only integration route that needs no scope, and it reads no data:

curl https://app.xicbot.de/api/v1/integration/status \
  -H 'Accept: application/json' \
  -H 'X-Api-Key: xbot_…'

The response names the account, the scopes and the per-minute cap of the key. Its fields are covered in Integration endpoints, the caps in API limits.

Access zones

Routes under /api/v1/ are grouped into zones, each with its own form of authentication. Within a zone, individual routes may additionally require a role, a plan feature or a key scope.

Requests

• Send request bodies as JSON with Content-Type: application/json and ask for JSON with Accept: application/json. The web app does the same.
• Files, for example for a knowledge source of type file, are sent as multipart/form-data. Let your HTTP client set the Content-Type header including the boundary; a header set by hand without the boundary makes the body unreadable.
• Under /api/, errors come back as JSON even without an Accept header, not as an HTML page.
• App routes authenticate with Authorization: Bearer <token>, the integration with the X-Api-Key header. If a key appears in the URL (?api_key= or ?key=), the integration rejects the request with 400 and key_in_url. See authentication for details.
• Timestamps are returned as ISO 8601 strings, for example in the created field.
• Assistant replies, for example to POST integration/chat, arrive as a stream with Content-Type: text/event-stream. Errors detected before the stream starts come back as JSON with a matching status. Once the stream is running, an error arrives as an event in the stream and the status no longer changes. The Python client in the tool kit requests these responses with Accept: text/event-stream.
• The web server aborts a request if the application sends no data for 300 seconds. Set your client timeout accordingly if you expect long responses.

Error format

Errors are returned as JSON with a matching HTTP status. Depending on where the error originates, the body takes one of five forms:

For an unexpected error with status 500 or above, the API replaces the text in message with Serverfehler and removes the fields exception, file, line and trace. A response without message does not get one. Messages with a status from 400 to 499 are passed through unchanged, including field errors.

Status codes and error codes

Unknown routes and wrong methods

A call for which no route exists is answered by a catch-all branch with JSON instead of an HTML error page. It covers GET, HEAD, POST, PUT, PATCH and DELETE under /api/, including paths outside /api/v1/: /api/ itself and any made-up address return 404 with route_unknown.

If the path exists but not for the method used, the API responds with 405 and method_not_allowed. The allowed field lists the permitted methods in alphabetical order, without HEAD. The catch-all branch does not answer OPTIONS, so preflight requests from other origins stay with the CORS layer.

curl -s https://app.xicbot.de/api/v1/login -H 'Accept: application/json'
{"error":"method_not_allowed","allowed":["POST"]}

curl -s https://app.xicbot.de/api/v1/beispiel -H 'Accept: application/json'
{"error":"route_unknown"}

HTTPS and HSTS

The API runs over HTTPS. The web server redirects http requests under /api/ to the https address with 301, whatever the method. If an unencrypted request does reach the application, it redirects only GET and HEAD with 301 and rejects every other method with 403 and https_required. The application builds the redirect target from its own address, not from the Host header of the request.

Responses over https carry Strict-Transport-Security: max-age=31536000; includeSubDomains, which tells browsers to use https only for this address for one year. preload is deliberately not set.

Response headers

CORS

The API sends CORS headers only on the public section /api/v1/public/*, for example for the status page, the changelog and the widget branch, and only for the approved origins listed in the table. The integration and all authenticated routes send no CORS headers. Call the integration from your server, not from JavaScript in the browser.

GET cart/pickup/{token} follows its own rule. The route is meant for server-to-server calls. In a browser, only the origin of the stored handover address may read the response. Responses carry Cache-Control: no-store and Vary: Origin.

Because only Content-Type and Accept are allowed, a preflight from another origin permits neither X-Api-Key nor Authorization. The routes for the chat window are covered in widget endpoints, the remaining public routes in public endpoints.

Pagination

Lists are paginated with the query parameter page, starting at 1. Page size, permitted ranges and response fields differ by route. Where a route checks a range, values outside it return 422; the integration treats values below 1 as 1.

Repeated requests

The API prevents duplicates through IDs in the request body or through the state of the record, not through a dedicated header. Whether a request can be safely repeated after a timeout depends on the route:

Frequent questions