openapi: 3.1.0
info:
  title: 'ONOXIA API'
  description: 'RESTful API zur programmatischen Verwaltung Ihrer ONOXIA-Chatbots.'
  version: 1.0.0
servers:
  -
    url: 'https://onoxia.nz'
tags:
  -
    name: Webhooks
    description: ''
  -
    name: Chat
    description: ''
  -
    name: Leads
    description: ''
  -
    name: Analytics
    description: ''
  -
    name: Import
    description: ''
  -
    name: 'Raw LLM'
    description: ''
  -
    name: Conversations
    description: ''
  -
    name: 'RAG Sources'
    description: ''
  -
    name: Schedules
    description: ''
  -
    name: 'Site (Bot Config)'
    description: ''
  -
    name: 'Support Agents'
    description: ''
components:
  securitySchemes:
    default:
      type: http
      scheme: bearer
      description: 'Create your API token at <a href="https://onoxia.nz/app/api-tokens"><b>Administration → API Tokens</b></a>.'
security:
  -
    default: []
paths:
  /api/v1/bot/webhooks:
    get:
      summary: 'List webhooks'
      operationId: listWebhooks
      description: "Returns all registered webhooks (bot tools) for this chatbot. Webhooks enable the bot to\ncall external systems during conversations — e.g. capturing leads to a CRM, creating support\ntickets, or triggering custom workflows. Each webhook has a name, URL, event triggers, and\nan optional HMAC secret for signature verification.\n\nRequires: `webhooks:read` permission."
      parameters: []
      responses:
        401:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Unauthenticated.
                examples:
                  -
                    message: Unauthenticated.
      tags:
        - Webhooks
    post:
      summary: 'Create a webhook'
      operationId: createAWebhook
      description: "Registers a new webhook (bot tool). The bot will call this URL when the configured\nevents or triggers match during a conversation. Payloads are signed with HMAC-SHA256\nusing the optional `secret` field.\n\nThe `trigger_config` object defines when the bot should use this tool — provide a\n`tool_name` and `tool_description` that the LLM uses to decide when to invoke it.\n\nAfter creation, the bot is re-provisioned to include the new tool in its capabilities.\n\nRequires: `webhooks:write` permission."
      parameters: []
      responses: {  }
      tags:
        - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: ':Attribute darf maximal 255 Zeichen haben.'
                  examples:
                    - b
                url:
                  type: string
                  description: 'Must be a valid URL. :Attribute darf maximal 2000 Zeichen haben.'
                  examples:
                    - 'http://bailey.com/'
                secret:
                  type:
                    - string
                    - 'null'
                  description: ':Attribute darf maximal 64 Zeichen haben.'
                  examples:
                    - m
                events:
                  type:
                    - object
                    - 'null'
                  description: ''
                  properties: {  }
                  examples:
                    - null
                trigger_config:
                  type:
                    - object
                    - 'null'
                  description: ''
                  properties: {  }
                  examples:
                    - null
                description:
                  type:
                    - string
                    - 'null'
                  description: ':Attribute darf maximal 1000 Zeichen haben.'
                  examples:
                    - 'Et fugiat sunt nihil accusantium.'
                is_active:
                  type: boolean
                  description: ''
                  examples:
                    - true
              required:
                - name
                - url
  '/api/v1/bot/webhooks/{id}':
    put:
      summary: 'Update a webhook'
      operationId: updateAWebhook
      description: "Updates an existing webhook by ID. Only send the fields you want to change.\nThe bot is re-provisioned after update to reflect changes in tool capabilities.\n\nRequires: `webhooks:write` permission."
      parameters: []
      responses: {  }
      tags:
        - Webhooks
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: ':Attribute darf maximal 255 Zeichen haben.'
                  examples:
                    - b
                url:
                  type: string
                  description: 'Must be a valid URL. :Attribute darf maximal 2000 Zeichen haben.'
                  examples:
                    - 'http://bailey.com/'
                secret:
                  type:
                    - string
                    - 'null'
                  description: ':Attribute darf maximal 64 Zeichen haben.'
                  examples:
                    - m
                events:
                  type:
                    - object
                    - 'null'
                  description: ''
                  properties: {  }
                  examples:
                    - null
                trigger_config:
                  type:
                    - object
                    - 'null'
                  description: ''
                  properties: {  }
                  examples:
                    - null
                description:
                  type:
                    - string
                    - 'null'
                  description: ':Attribute darf maximal 1000 Zeichen haben.'
                  examples:
                    - 'Et fugiat sunt nihil accusantium.'
                is_active:
                  type: boolean
                  description: ''
                  examples:
                    - true
    delete:
      summary: 'Delete a webhook'
      operationId: deleteAWebhook
      description: "Permanently removes a webhook. The bot will no longer have access to this tool.\nThe bot is re-provisioned after deletion.\n\nRequires: `webhooks:write` permission."
      parameters: []
      responses: {  }
      tags:
        - Webhooks
    parameters:
      -
        in: path
        name: id
        description: 'The ID of the webhook.'
        required: true
        schema:
          type: string
          examples:
            - architecto
  /api/v1/bot/chat:
    post:
      summary: 'Chat with the bot'
      operationId: chatWithTheBot
      description: "Send a message to the bot and receive an AI-generated response. This endpoint uses the same\nflow as the chat widget: RAG knowledge retrieval, tool execution, token budget deduction.\n\nPass a `conversation_id` to continue an existing conversation, or omit it to start a new one.\nThe response includes the conversation ID for subsequent messages.\n\nThe `locale` parameter hints the bot about the visitor's language. With auto-detection enabled,\nthe bot will respond in whatever language the user writes in regardless of this parameter.\n\nToken usage is deducted from your monthly budget. Returns 429 if budget is exhausted.\n\nRequires: `chat:write` permission."
      parameters: []
      responses: {  }
      tags:
        - Chat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  description: ':Attribute darf maximal 2000 Zeichen haben.'
                  examples:
                    - b
                conversation_id:
                  type:
                    - string
                    - 'null'
                  description: ':Attribute muss ein UUID sein.'
                  examples:
                    - a4855dc5-0acb-33c3-b921-f4291f719ca0
                visitor_id:
                  type:
                    - string
                    - 'null'
                  description: ':Attribute darf maximal 64 Zeichen haben.'
                  examples:
                    - z
                locale:
                  type:
                    - string
                    - 'null'
                  description: ':Attribute darf maximal 5 Zeichen haben.'
                  examples:
                    - en_CA
                context:
                  type:
                    - object
                    - 'null'
                  description: ''
                  properties: {  }
                  examples:
                    - null
              required:
                - message
  /api/v1/bot/leads/export.csv:
    get:
      summary: 'Export leads as CSV'
      operationId: exportLeadsAsCSV
      description: "Downloads all leads for this chatbot as a CSV file. Includes name, email, phone, company,\nsource, and creation date. Useful for importing into CRM systems or spreadsheets.\n\nRequires: `leads:read` permission."
      parameters: []
      responses:
        401:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Unauthenticated.
                examples:
                  -
                    message: Unauthenticated.
      tags:
        - Leads
  /api/v1/bot/leads:
    get:
      summary: 'List leads'
      operationId: listLeads
      description: "Returns a paginated list of captured leads. Leads are created when visitors provide their\ncontact information through the pre-chat form or during bot conversations.\n\nFilters: `?since=2026-01-01`, `?source=prechat` (or `bot`, `manual`).\nPagination: `?per_page=50` (max 100).\n\nRequires: `leads:read` permission."
      parameters: []
      responses:
        401:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Unauthenticated.
                examples:
                  -
                    message: Unauthenticated.
      tags:
        - Leads
  /api/v1/bot/analytics/tokens:
    get:
      summary: 'Token usage analytics'
      operationId: tokenUsageAnalytics
      description: "Returns your current token budget (monthly limit, used, remaining) and daily usage\nbreakdown for this chatbot. Filter by date range with `?from=2026-03-01&to=2026-03-31`.\n\nEach day shows input tokens, output tokens, and total. Use this to monitor consumption,\ndetect usage spikes, and plan token package purchases.\n\nRequires: `analytics:read` permission."
      parameters: []
      responses:
        401:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Unauthenticated.
                examples:
                  -
                    message: Unauthenticated.
      tags:
        - Analytics
  /api/v1/bot/analytics/conversations:
    get:
      summary: 'Conversation statistics'
      operationId: conversationStatistics
      description: "Returns aggregate statistics: total conversations, rated conversations, average CSAT rating,\nand a breakdown by channel (widget, email, api). Use this for dashboard widgets or\nreporting integrations.\n\nRequires: `analytics:read` permission."
      parameters: []
      responses:
        401:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Unauthenticated.
                examples:
                  -
                    message: Unauthenticated.
      tags:
        - Analytics
  /api/v1/bot/ingest/llms-txt:
    post:
      summary: 'Import llms.txt'
      operationId: importLlmstxt
      description: "Imports a website's `llms.txt` file as RAG knowledge. This is a standardized format\n(llms-txt.org) that describes a website's content for AI consumption.\n\nProvide either a `url` (the system fetches it) or raw `content` (inline import).\nThe content is parsed, split into chunks, and embedded as RAG sources.\nProcessing happens asynchronously — check back via the RAG list endpoint.\n\nRequires: `rag:write` permission."
      parameters: []
      responses: {  }
      tags:
        - Import
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type:
                    - string
                    - 'null'
                  description: 'This field is required when <code>content</code> is not present. Must be a valid URL. :Attribute darf maximal 2000 Zeichen haben.'
                  examples:
                    - 'http://www.bailey.biz/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html'
                content:
                  type:
                    - string
                    - 'null'
                  description: 'This field is required when <code>url</code> is not present.'
                  examples:
                    - architecto
  /api/v1/bot/ingest/sitemap:
    post:
      summary: 'Import sitemap'
      operationId: importSitemap
      description: "Imports a website's XML sitemap and creates RAG sources from the linked pages.\nThe system fetches each page, extracts text content, and creates knowledge entries.\n\nUse `max_pages` to limit the number of pages processed (default: all, max: 500).\nUse `exclude_patterns` to skip certain URL patterns (e.g. `[\"/admin/*\", \"/tag/*\"]`).\n\nProcessing happens asynchronously. Monitor progress via the RAG list endpoint.\n\nRequires: `rag:write` permission."
      parameters: []
      responses: {  }
      tags:
        - Import
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  description: 'Must be a valid URL. :Attribute darf maximal 2000 Zeichen haben.'
                  examples:
                    - 'http://www.bailey.biz/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html'
                max_pages:
                  type:
                    - integer
                    - 'null'
                  description: ':Attribute muss mindestens 1 sein. :Attribute darf maximal 500 sein.'
                  examples:
                    - 5
                exclude_patterns:
                  type:
                    - object
                    - 'null'
                  description: ''
                  properties: {  }
                  examples:
                    - null
              required:
                - url
  /api/v1/bot/ingest/url:
    post:
      summary: 'Import single URL'
      operationId: importSingleURL
      description: "Fetches a single web page, extracts its text content, and creates a RAG source from it.\nUseful for importing specific pages (e.g. a pricing page, product page, or help article)\nwithout processing an entire sitemap.\n\nOptional: Set a custom `name`, `context_tags`, or `url_patterns` for the created source.\n\nRequires: `rag:write` permission."
      parameters: []
      responses: {  }
      tags:
        - Import
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  description: 'Must be a valid URL. :Attribute darf maximal 2000 Zeichen haben.'
                  examples:
                    - 'http://www.bailey.biz/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html'
                name:
                  type:
                    - string
                    - 'null'
                  description: ':Attribute darf maximal 255 Zeichen haben.'
                  examples:
                    - i
                context_tags:
                  type:
                    - object
                    - 'null'
                  description: ''
                  properties: {  }
                  examples:
                    - null
                url_patterns:
                  type:
                    - object
                    - 'null'
                  description: ''
                  properties: {  }
                  examples:
                    - null
              required:
                - url
  /api/v1/bot/llm/chat:
    post:
      summary: 'Raw LLM Proxy'
      operationId: rawLLMProxy
      description: "Direct access to the underlying LLM without RAG, tools, or conversation context.\nSend your own message array and get a raw AI response. Tokens are deducted from your budget.\n\nOptionally specify a `model` (e.g. `mistral-medium`, `qwen-3.5-plus`, `gemini-2.5-flash`).\nIf omitted, the system auto-selects the best model for the bot's configured language.\n\nUse cases: content generation, translation, summarization, classification — anything\nthat needs AI but doesn't require your knowledge base.\n\nNote: Different models have different token multipliers. Gemini Flash (0.5x) is the\ncheapest option, Mistral Medium (1.0x) is the default.\n\nRequires: `llm:write` permission."
      parameters: []
      responses: {  }
      tags:
        - 'Raw LLM'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                messages:
                  type: array
                  description: ':Attribute muss mindestens 1 Elemente haben.'
                  items:
                    type: object
                    properties:
                      role:
                        type: string
                        description: ''
                        enum:
                          - system
                          - user
                          - assistant
                        examples:
                          - assistant
                      content:
                        type: string
                        description: ''
                        examples:
                          - architecto
                    required:
                      - role
                      - content
                  examples:
                    -
                      - []
                model:
                  type:
                    - string
                    - 'null'
                  description: ':Attribute darf maximal 50 Zeichen haben.'
                  examples:
                    - b
                temperature:
                  type:
                    - number
                    - 'null'
                  description: ':Attribute muss mindestens 0 sein. :Attribute darf maximal 2 sein.'
                  examples:
                    - 2
                max_tokens:
                  type:
                    - integer
                    - 'null'
                  description: ':Attribute muss mindestens 1 sein. :Attribute darf maximal 4096 sein.'
                  examples:
                    - 7
              required:
                - messages
  /api/v1/bot/conversations:
    get:
      summary: 'List conversations'
      operationId: listConversations
      description: "Returns a paginated list of conversations for this chatbot. Each conversation includes\nmetadata like visitor ID, channel (widget/email), status (bot/agent/closed), locale,\nmessage count, and CSAT rating.\n\nFilters: `?status=bot`, `?channel=widget`, `?since=2026-01-01`, `?rated=true`.\nPagination: `?per_page=50` (max 100).\n\nRequires: `conversations:read` permission."
      parameters: []
      responses:
        401:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Unauthenticated.
                examples:
                  -
                    message: Unauthenticated.
      tags:
        - Conversations
  '/api/v1/bot/conversations/{uuid}':
    get:
      summary: 'Get conversation details'
      operationId: getConversationDetails
      description: "Returns a single conversation with its full message history. Messages are ordered\nchronologically and include role (user/assistant/agent), content, token count,\nand timestamp. Useful for auditing, analytics, or building custom conversation UIs.\n\nRequires: `conversations:read` permission."
      parameters: []
      responses:
        401:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Unauthenticated.
                examples:
                  -
                    message: Unauthenticated.
      tags:
        - Conversations
    parameters:
      -
        in: path
        name: uuid
        description: ''
        required: true
        schema:
          type: string
          examples:
            - 6ff8f7f6-1eb3-3525-be4a-3932c805afed
  /api/v1/bot/rag:
    get:
      summary: 'List RAG sources'
      operationId: listRAGSources
      description: "Returns all knowledge sources (RAG) for this chatbot. Each source has a type (faq, text, document),\na processing status, and optional context filters (tags, URL patterns).\nFilter by `?status=ready` to see only processed sources, or `?status=pending` for queued ones.\n\nRequires: `rag:read` permission."
      parameters: []
      responses:
        401:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Unauthenticated.
                examples:
                  -
                    message: Unauthenticated.
      tags:
        - 'RAG Sources'
    post:
      summary: 'Create a RAG source'
      operationId: createARAGSource
      description: "Creates a new knowledge source for the bot. Supported types: `faq` (question + answer pair)\nand `text` (free-form text/markdown). After creation, the source is automatically queued for\nprocessing — vector embeddings are generated and stored in Qdrant.\n\nOptional: Add `context_tags` or `url_patterns` to restrict when this source is used.\nFor example, a product FAQ with `url_patterns: [\"/products/*\"]` will only be searched\nwhen visitors are on product pages.\n\nRequires: `rag:write` permission."
      parameters: []
      responses: {  }
      tags:
        - 'RAG Sources'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: ''
                  enum:
                    - faq
                    - text
                  examples:
                    - text
                name:
                  type: string
                  description: ':Attribute darf maximal 255 Zeichen haben.'
                  examples:
                    - b
                question:
                  type:
                    - string
                    - 'null'
                  description: 'This field is required when <code>type</code> is <code>faq</code>.'
                  examples:
                    - architecto
                answer:
                  type: string
                  description: ''
                  examples:
                    - architecto
                context_tags:
                  type:
                    - object
                    - 'null'
                  description: ''
                  properties: {  }
                  examples:
                    - null
                url_patterns:
                  type:
                    - object
                    - 'null'
                  description: ''
                  properties: {  }
                  examples:
                    - null
              required:
                - type
                - name
                - answer
  /api/v1/bot/rag/sync:
    post:
      summary: 'Bulk sync RAG sources'
      operationId: bulkSyncRAGSources
      description: "Upsert + delete in a single request. Ideal for CMS plugins that sync page content automatically.\nSources are matched by `name` — existing sources with the same name are updated, new names are created.\n\nWith `delete_missing: true`, any API-created sources (`source: \"api\"`) whose names are NOT in the\nrequest body will be deleted. Manually created sources (via dashboard) are never deleted by sync.\n\nReturns a summary: `{ created, updated, deleted, unchanged }`.\n\nRequires: `rag:write` permission."
      parameters: []
      responses: {  }
      tags:
        - 'RAG Sources'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sources:
                  type: array
                  description: ':Attribute muss mindestens 1 Elemente haben.'
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        description: ':Attribute darf maximal 255 Zeichen haben.'
                        examples:
                          - b
                      type:
                        type: string
                        description: ''
                        enum:
                          - faq
                          - text
                        examples:
                          - text
                      answer:
                        type: string
                        description: ''
                        examples:
                          - architecto
                      question:
                        type:
                          - string
                          - 'null'
                        description: ''
                        examples:
                          - architecto
                      context_tags:
                        type:
                          - object
                          - 'null'
                        description: ''
                        properties: {  }
                        examples:
                          - null
                      url_patterns:
                        type:
                          - object
                          - 'null'
                        description: ''
                        properties: {  }
                        examples:
                          - null
                    required:
                      - name
                      - type
                      - answer
                  examples:
                    -
                      - []
                delete_missing:
                  type: boolean
                  description: ''
                  examples:
                    - true
              required:
                - sources
  '/api/v1/bot/rag/{id}':
    put:
      summary: 'Update a RAG source'
      operationId: updateARAGSource
      description: "Updates an existing knowledge source by ID. The source is automatically re-processed after update\n(new embeddings are generated). Only send the fields you want to change.\n\nNote: Changing the `answer` or `question` triggers re-embedding, which may take a few seconds.\n\nRequires: `rag:write` permission."
      parameters: []
      responses: {  }
      tags:
        - 'RAG Sources'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: ':Attribute darf maximal 255 Zeichen haben.'
                  examples:
                    - b
                question:
                  type:
                    - string
                    - 'null'
                  description: ''
                  examples:
                    - architecto
                answer:
                  type: string
                  description: ''
                  examples:
                    - architecto
                context_tags:
                  type:
                    - object
                    - 'null'
                  description: ''
                  properties: {  }
                  examples:
                    - null
                url_patterns:
                  type:
                    - object
                    - 'null'
                  description: ''
                  properties: {  }
                  examples:
                    - null
    delete:
      summary: 'Delete a RAG source'
      operationId: deleteARAGSource
      description: "Permanently deletes a knowledge source and all its vector chunks. The bot will no longer\nreference this content. The Qdrant collection is automatically re-provisioned.\n\nRequires: `rag:write` permission."
      parameters: []
      responses: {  }
      tags:
        - 'RAG Sources'
    parameters:
      -
        in: path
        name: id
        description: 'The ID of the rag.'
        required: true
        schema:
          type: string
          examples:
            - architecto
  /api/v1/bot/schedules:
    get:
      summary: 'List schedules'
      operationId: listSchedules
      description: "Returns all schedule rules for this chatbot. Schedules control when the bot is active,\ninactive, or displays a custom message. Use them to implement business hours, holiday\nmessages, or time-based bot behavior.\n\nEach schedule has an action (`on`, `off`, `message`), time range, optional weekday filter,\ndate range, timezone, and priority (higher number = higher priority).\n\nRequires: `schedules:read` permission."
      parameters: []
      responses:
        401:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Unauthenticated.
                examples:
                  -
                    message: Unauthenticated.
      tags:
        - Schedules
    post:
      summary: 'Create a schedule'
      operationId: createASchedule
      description: "Creates a new schedule rule. Actions: `on` (activate bot), `off` (deactivate bot),\n`message` (show custom text instead of bot response).\n\nWeekdays are optional — empty array means the schedule applies every day.\nUse `0` for Sunday through `6` for Saturday.\n\nThe `use_browser_timezone` flag makes the schedule use the visitor's local time\n(detected from the browser). Otherwise, the `timezone` field is used.\n\nRequires: `schedules:write` permission."
      parameters: []
      responses: {  }
      tags:
        - Schedules
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: ':Attribute darf maximal 255 Zeichen haben.'
                  examples:
                    - b
                action:
                  type: string
                  description: ''
                  enum:
                    - 'on'
                    - 'off'
                    - message
                  examples:
                    - message
                message:
                  type:
                    - string
                    - 'null'
                  description: 'This field is required when <code>action</code> is <code>message</code>.'
                  examples:
                    - architecto
                weekdays:
                  type:
                    - object
                    - 'null'
                  description: ''
                  properties: {  }
                  examples:
                    - null
                time_from:
                  type: string
                  description: 'Must be a valid date in the format <code>H:i</code>.'
                  examples:
                    - '13:57'
                time_to:
                  type: string
                  description: 'Must be a valid date in the format <code>H:i</code>.'
                  examples:
                    - '13:57'
                date_from:
                  type:
                    - string
                    - 'null'
                  description: ':Attribute muss ein gültiges Datum sein.'
                  examples:
                    - '2026-07-28T13:57:36'
                date_to:
                  type:
                    - string
                    - 'null'
                  description: ':Attribute muss ein gültiges Datum sein.'
                  examples:
                    - '2026-07-28T13:57:36'
                timezone:
                  type:
                    - string
                    - 'null'
                  description: ':Attribute darf maximal 64 Zeichen haben.'
                  examples:
                    - Asia/Ulaanbaatar
                use_browser_timezone:
                  type:
                    - boolean
                    - 'null'
                  description: ''
                  examples:
                    - false
                priority:
                  type:
                    - integer
                    - 'null'
                  description: ':Attribute muss mindestens 0 sein.'
                  examples:
                    - 84
                is_active:
                  type:
                    - boolean
                    - 'null'
                  description: ''
                  examples:
                    - false
              required:
                - name
                - action
                - time_from
                - time_to
  '/api/v1/bot/schedules/{id}':
    put:
      summary: 'Update a schedule'
      operationId: updateASchedule
      description: "Updates an existing schedule rule by ID. Only send the fields you want to change.\n\nRequires: `schedules:write` permission."
      parameters: []
      responses: {  }
      tags:
        - Schedules
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: ':Attribute darf maximal 255 Zeichen haben.'
                  examples:
                    - b
                action:
                  type: string
                  description: ''
                  enum:
                    - 'on'
                    - 'off'
                    - message
                  examples:
                    - message
                message:
                  type:
                    - string
                    - 'null'
                  description: ''
                  examples:
                    - architecto
                weekdays:
                  type:
                    - object
                    - 'null'
                  description: ''
                  properties: {  }
                  examples:
                    - null
                time_from:
                  type: string
                  description: 'Must be a valid date in the format <code>H:i</code>.'
                  examples:
                    - '13:57'
                time_to:
                  type: string
                  description: 'Must be a valid date in the format <code>H:i</code>.'
                  examples:
                    - '13:57'
                date_from:
                  type:
                    - string
                    - 'null'
                  description: ':Attribute muss ein gültiges Datum sein.'
                  examples:
                    - '2026-07-28T13:57:36'
                date_to:
                  type:
                    - string
                    - 'null'
                  description: ':Attribute muss ein gültiges Datum sein.'
                  examples:
                    - '2026-07-28T13:57:36'
                timezone:
                  type:
                    - string
                    - 'null'
                  description: ':Attribute darf maximal 64 Zeichen haben.'
                  examples:
                    - Asia/Ulaanbaatar
                use_browser_timezone:
                  type:
                    - boolean
                    - 'null'
                  description: ''
                  examples:
                    - true
                priority:
                  type:
                    - integer
                    - 'null'
                  description: ':Attribute muss mindestens 0 sein.'
                  examples:
                    - 84
                is_active:
                  type:
                    - boolean
                    - 'null'
                  description: ''
                  examples:
                    - false
    delete:
      summary: 'Delete a schedule'
      operationId: deleteASchedule
      description: "Permanently deletes a schedule rule by ID.\n\nRequires: `schedules:write` permission."
      parameters: []
      responses: {  }
      tags:
        - Schedules
    parameters:
      -
        in: path
        name: id
        description: 'The ID of the schedule.'
        required: true
        schema:
          type: string
          examples:
            - architecto
  /api/v1/bot/site:
    get:
      summary: 'Read bot configuration'
      operationId: readBotConfiguration
      description: "Returns the full configuration of the chatbot bound to this API token, including widget settings,\nsystem prompt, bot rules, languages, and usage counters (RAG sources, conversations, webhooks, leads).\nUse this to verify your token is working and to inspect the current bot setup.\n\nRequires: `site:read` permission."
      parameters: []
      responses:
        401:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Unauthenticated.
                examples:
                  -
                    message: Unauthenticated.
      tags:
        - 'Site (Bot Config)'
    patch:
      summary: 'Update bot settings'
      operationId: updateBotSettings
      description: "Partially updates the chatbot configuration. Only send the fields you want to change.\nJSON fields (`widget_config`, `bot_rules`, `handover_config`) are **merged** with existing values,\nnot replaced — so you can update individual keys without losing others.\n\nIf you change the `system_prompt` or `bot_rules`, the bot is automatically re-provisioned\n(RAG embeddings are rebuilt). This may take a few seconds.\n\nRequires: `site:write` permission."
      parameters: []
      responses: {  }
      tags:
        - 'Site (Bot Config)'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: ':Attribute darf maximal 255 Zeichen haben.'
                  examples:
                    - b
                system_prompt:
                  type:
                    - string
                    - 'null'
                  description: ':Attribute darf maximal 10000 Zeichen haben.'
                  examples:
                    - 'n'
                response_length:
                  type: string
                  description: ''
                  enum:
                    - short
                    - medium
                    - detailed
                  examples:
                    - medium
                is_active:
                  type: boolean
                  description: ''
                  examples:
                    - false
                allowed_domains:
                  type: object
                  description: ''
                  properties: {  }
                  examples:
                    - null
                bot_languages:
                  type: object
                  description: ''
                  properties: {  }
                  examples:
                    - null
                widget_config:
                  type: object
                  description: ''
                  properties: {  }
                  examples:
                    - null
                bot_rules:
                  type: object
                  description: ''
                  properties: {  }
                  examples:
                    - null
                handover_config:
                  type: object
                  description: ''
                  properties: {  }
                  examples:
                    - null
                privacy_text:
                  type:
                    - string
                    - 'null'
                  description: ''
                  examples:
                    - architecto
                privacy_url:
                  type:
                    - string
                    - 'null'
                  description: 'Must be a valid URL. :Attribute darf maximal 500 Zeichen haben.'
                  examples:
                    - 'http://bailey.com/'
  /api/v1/bot/agents:
    get:
      summary: 'List support agents'
      operationId: listSupportAgents
      description: "Returns all support agents for your account with their assigned sites and online status.\nSupport agents are used for the Live Chat / Handover feature — they can take over bot\nconversations and chat directly with visitors.\n\nRequires: `agents:read` permission."
      parameters: []
      responses:
        401:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Unauthenticated.
                examples:
                  -
                    message: Unauthenticated.
      tags:
        - 'Support Agents'
    post:
      summary: 'Create a support agent'
      operationId: createASupportAgent
      description: "Creates a new support agent who can log in at `/support` and handle live chat handovers.\nAgents must be assigned to at least one site via `site_ids` (array of site UUIDs).\nThe agent receives their own login credentials (email + password) separate from the tenant account.\n\nRequires: `agents:write` permission."
      parameters: []
      responses: {  }
      tags:
        - 'Support Agents'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: ':Attribute darf maximal 255 Zeichen haben.'
                  examples:
                    - b
                email:
                  type: string
                  description: ':Attribute muss eine gültige E-Mail-Adresse sein. :Attribute darf maximal 255 Zeichen haben.'
                  examples:
                    - zbailey@example.net
                password:
                  type: string
                  description: ':Attribute muss mindestens 8 Zeichen lang sein.'
                  examples:
                    - '-0pBNvYgxw'
                locale:
                  type:
                    - string
                    - 'null'
                  description: ''
                  enum:
                    - de
                    - en
                  examples:
                    - de
                site_ids:
                  type:
                    - object
                    - 'null'
                  description: ''
                  properties: {  }
                  examples:
                    - null
              required:
                - name
                - email
                - password
  '/api/v1/bot/agents/{uuid}':
    put:
      summary: 'Update a support agent'
      operationId: updateASupportAgent
      description: "Updates an existing support agent by UUID. You can change name, email, password, locale,\nactive status, and site assignments. Only send the fields you want to change.\n\nRequires: `agents:write` permission."
      parameters: []
      responses: {  }
      tags:
        - 'Support Agents'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: ':Attribute darf maximal 255 Zeichen haben.'
                  examples:
                    - b
                email:
                  type: string
                  description: ':Attribute muss eine gültige E-Mail-Adresse sein. :Attribute darf maximal 255 Zeichen haben.'
                  examples:
                    - zbailey@example.net
                password:
                  type: string
                  description: ':Attribute muss mindestens 8 Zeichen lang sein.'
                  examples:
                    - '-0pBNvYgxw'
                locale:
                  type: string
                  description: ''
                  enum:
                    - de
                    - en
                  examples:
                    - en
                is_active:
                  type: boolean
                  description: ''
                  examples:
                    - true
                site_ids:
                  type:
                    - object
                    - 'null'
                  description: ''
                  properties: {  }
                  examples:
                    - null
    delete:
      summary: 'Delete a support agent'
      operationId: deleteASupportAgent
      description: "Permanently deletes a support agent. The agent will no longer be able to log in or handle\nconversations. Active conversations assigned to this agent are returned to the bot.\n\nRequires: `agents:write` permission."
      parameters: []
      responses: {  }
      tags:
        - 'Support Agents'
    parameters:
      -
        in: path
        name: uuid
        description: ''
        required: true
        schema:
          type: string
          examples:
            - 6ff8f7f6-1eb3-3525-be4a-3932c805afed
