Hellou AI Knowledge Base API

openapi: 3.2.0
info:
  title: HellouOne Knowledge Base API
  version: 1.0.0
  description: 'The HellouOne REST API: everything the dashboard does, available to your

    own systems — CRMs, bots, BI tools and back-office automation.'
  termsOfService: https://hellou.ai/en/legal/terms/
  contact:
    name: HellouOne support
    email: support@hellou.ai
servers:
- url: https://one.hellou.ai
  description: HellouOne cloud
security:
- userApiKey: []
tags:
- name: Knowledge Base
paths:
  /api/v1/accounts/{account_id}/kb_setting:
    parameters:
    - $ref: '#/components/parameters/account_id'
    get:
      tags:
      - Knowledge Base
      operationId: getKbSetting
      summary: Get the knowledge-base setting
      description: 'Returns the account''s knowledge-base setting: the database and table that ingested

        documents are written to. Answers 404 until one has been created.


        **Administrators only.**


        **Requires feature:** any of `agent_bots`, `native_bots`'
      x-required-feature: agent_bots
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/kb_setting'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
    post:
      tags:
      - Knowledge Base
      operationId: createKbSetting
      summary: Create the knowledge-base setting
      description: 'Turns on the account''s knowledge base. The server picks the database and table

        (one table per account in the shared knowledge-base database) and creates the

        table; neither can be chosen through the API. An account has at most one

        setting; creating a second answers 422. The embedding model is fixed to

        `text-embedding-3-small`.


        **Administrators only.**


        **Requires feature:** any of `agent_bots`, `native_bots`'
      x-required-feature: agent_bots
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/kb_setting'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '422':
          $ref: '#/components/responses/unprocessable'
    delete:
      tags:
      - Knowledge Base
      operationId: deleteKbSetting
      summary: Delete the knowledge-base setting
      description: 'Removes the setting. The knowledge-base database and its contents are left untouched.


        **Administrators only.**


        **Requires feature:** any of `agent_bots`, `native_bots`'
      x-required-feature: agent_bots
      responses:
        '200':
          description: Deleted. The response has no body.
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
  /api/v1/accounts/{account_id}/kb_documents:
    parameters:
    - $ref: '#/components/parameters/account_id'
    get:
      tags:
      - Knowledge Base
      operationId: listKbDocuments
      summary: List knowledge-base documents
      description: 'Lists every knowledge-base document in the account, most recently updated first.

        The text `content` is left out; fetch a single document to read it.


        **Administrators only.**


        **Requires feature:** any of `agent_bots`, `native_bots`'
      x-required-feature: agent_bots
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/kb_document'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
    post:
      tags:
      - Knowledge Base
      operationId: createKbDocument
      summary: Add a knowledge-base document
      description: 'Adds a document and queues it for ingestion; it starts as `pending`. Poll the

        document until `status` is `ready` or `failed`.


        - **Manual text** (`source_type: manual`): send `content` as JSON.

        - **Web page** (`source_type: url`): send `source_url` as JSON; the page is fetched during ingestion.

        - **File** (`source_type: file_upload`): send `multipart/form-data` with a `file`

        part (PDF, DOCX, plain text or Markdown, up to 10 MB).


        **Administrators only.**


        **Requires feature:** any of `agent_bots`, `native_bots`'
      x-required-feature: agent_bots
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/kb_document_create_payload'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/kb_document_upload_payload'
      responses:
        '200':
          description: Created and queued for ingestion
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/kb_document'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '422':
          $ref: '#/components/responses/unprocessable'
  /api/v1/accounts/{account_id}/kb_documents/{id}:
    parameters:
    - $ref: '#/components/parameters/account_id'
    - name: id
      in: path
      required: true
      description: ID of the document
      schema:
        type: integer
    get:
      tags:
      - Knowledge Base
      operationId: getKbDocument
      summary: Get a knowledge-base document
      description: 'Returns one document, including its text `content`.


        **Administrators only.**


        **Requires feature:** any of `agent_bots`, `native_bots`'
      x-required-feature: agent_bots
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/kb_document_detail'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
    patch:
      tags:
      - Knowledge Base
      operationId: updateKbDocument
      summary: Update a knowledge-base document
      description: 'Changes a document. Changing its title, text, category, URL or file queues it

        for ingestion again. Send `multipart/form-data` to replace the file.


        **Administrators only.**


        **Requires feature:** any of `agent_bots`, `native_bots`'
      x-required-feature: agent_bots
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/kb_document_update_payload'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/kb_document_update_payload'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/kb_document'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '422':
          $ref: '#/components/responses/unprocessable'
    delete:
      tags:
      - Knowledge Base
      operationId: deleteKbDocument
      summary: Delete a knowledge-base document
      description: 'Deletes the document and, in the background, removes its chunks from the

        knowledge base so your bot stops finding it.


        **Administrators only.**


        **Requires feature:** any of `agent_bots`, `native_bots`'
      x-required-feature: agent_bots
      responses:
        '200':
          description: Deleted. The response has no body.
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
  /api/v1/accounts/{account_id}/kb_documents/{id}/reingest:
    parameters:
    - $ref: '#/components/parameters/account_id'
    - name: id
      in: path
      required: true
      description: ID of the document
      schema:
        type: integer
    post:
      tags:
      - Knowledge Base
      operationId: reingestKbDocument
      summary: Re-ingest a knowledge-base document
      description: 'Queues the document for ingestion again (for example after a `failed` attempt,

        or to re-fetch a web page). The document returns to `pending`. Answers 422 while

        the document is `processing`.


        **Administrators only.**


        **Requires feature:** any of `agent_bots`, `native_bots`'
      x-required-feature: agent_bots
      responses:
        '200':
          description: Queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/kb_document'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '422':
          description: The document is already being processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
components:
  schemas:
    kb_document_detail:
      description: A knowledge-base document including its text content.
      allOf:
      - $ref: '#/components/schemas/kb_document'
      - type: object
        properties:
          content:
            type:
            - string
            - 'null'
            description: The document text, for a `manual` document.
        required:
        - content
    kb_document:
      type: object
      description: A knowledge-base document and the state of its ingestion.
      properties:
        id:
          type: integer
          description: ID of the document.
        title:
          type: string
        category:
          type: string
          enum:
          - faq
          - document
          - policy
          - other
        source_type:
          type: string
          enum:
          - manual
          - file_upload
          - url
          description: '`manual`: text typed into `content`. `file_upload`: an attached PDF, DOCX,

            plain-text or Markdown file. `url`: a web page fetched from `source_url`.

            '
        status:
          type: string
          enum:
          - pending
          - processing
          - ready
          - failed
          description: 'Ingestion state. A document is `pending` when created or changed, `processing`

            while it is being split and embedded, then `ready` or `failed`

            (see `error_message`).

            '
        error_message:
          type:
          - string
          - 'null'
          description: Why the last ingestion failed, when it did.
        chunk_count:
          type: integer
          description: Number of searchable chunks the document was split into.
        source_url:
          type:
          - string
          - 'null'
          description: The page fetched for a `url` document.
        last_synced_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the document was last ingested successfully.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        file:
          description: The attached file, for a `file_upload` document; otherwise `null`.
          oneOf:
          - type: 'null'
          - type: object
            properties:
              filename:
                type: string
              byte_size:
                type: integer
              content_type:
                type:
                - string
                - 'null'
            required:
            - filename
            - byte_size
            - content_type
      required:
      - id
      - title
      - category
      - source_type
      - status
      - error_message
      - chunk_count
      - source_url
      - last_synced_at
      - created_at
      - updated_at
      - file
    kb_document_create_payload:
      type: object
      description: 'Which fields are required depends on `source_type`: `content` for `manual`,

        `source_url` for `url`, and `file` for `file_upload` (send that one as

        `multipart/form-data`).

        '
      properties:
        title:
          type: string
          description: Display title of the document.
        category:
          type: string
          enum:
          - faq
          - document
          - policy
          - other
          default: faq
        source_type:
          type: string
          enum:
          - manual
          - file_upload
          - url
          default: manual
        content:
          type: string
          maxLength: 200000
          description: 'Document text. Required when `source_type` is `manual`. At most 200,000

            characters; longer text gets `422`. Text read from a file or a web page

            has the same limit: over it, ingestion ends `failed`.

            '
        source_url:
          type: string
          format: uri
          description: An `http` or `https` URL to fetch. Required when `source_type` is `url`.
      required:
      - title
    kb_document_upload_payload:
      description: 'Same fields as the JSON body, plus the file. Required for a `file_upload`

        document.

        '
      allOf:
      - $ref: '#/components/schemas/kb_document_create_payload'
      - type: object
        properties:
          file:
            type: string
            format: binary
            description: 'PDF, DOCX, plain text or Markdown (`application/pdf`,

              `application/vnd.openxmlformats-officedocument.wordprocessingml.document`,

              `text/plain`, `text/markdown`), up to 10 MB.

              '
    kb_document_update_payload:
      type: object
      description: 'Send only the fields to change. Changing `title`, `content`, `category`,

        `source_url` or the file queues the document for ingestion again. To replace the

        file, send the request as `multipart/form-data` with a `file` part.

        '
      properties:
        title:
          type: string
        category:
          type: string
          enum:
          - faq
          - document
          - policy
          - other
        source_type:
          type: string
          enum:
          - manual
          - file_upload
          - url
        content:
          type: string
          maxLength: 200000
          description: Document text. At most 200,000 characters; longer text gets `422`.
        source_url:
          type: string
          format: uri
        file:
          type: string
          format: binary
          description: Replacement file (multipart only). Same types and size limit as on create.
    error_message:
      type: object
      description: An error with a human-readable message.
      properties:
        error:
          type: string
          description: What went wrong.
        reason:
          type: string
          description: Machine-readable cause, when there is one (for example `feature_disabled`).
      required:
      - error
    kb_setting:
      type: object
      description: 'Where this account''s knowledge base lives: the vector database and table that

        ingested documents are written to and that your bot searches.

        '
      properties:
        id:
          type: integer
          description: ID of the setting.
        database_name:
          type: string
          description: Name of the knowledge-base database.
          example: hellouchat_kb
        table_name:
          type: string
          description: Name of the vector table inside that database.
          example: acct_1_kb_vectors
        embedding_model:
          type: string
          enum:
          - text-embedding-3-small
          description: Embedding model used for ingestion. Fixed; it cannot be changed through the API.
      required:
      - id
      - database_name
      - table_name
      - embedding_model
    validation_error:
      type: object
      description: Validation failure for a record.
      properties:
        message:
          type: string
          description: Every validation message, joined with commas.
        attributes:
          type: array
          description: The attributes that failed validation.
          items:
            type: string
      required:
      - message
  responses:
    unauthorized:
      description: Missing or invalid `api_access_token`, or a bot token on an endpoint bots cannot use.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_message'
    forbidden:
      description: 'Not allowed: the user''s role does not permit it, the feature is not enabled

        for the account (`reason: feature_disabled`), or the account is read-only.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_message'
    not_found:
      description: The resource does not exist in this account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_message'
    unprocessable:
      description: The request was understood but the data is invalid.
      content:
        application/json:
          schema:
            anyOf:
            - $ref: '#/components/schemas/validation_error'
            - $ref: '#/components/schemas/error_message'
  parameters:
    account_id:
      in: path
      name: account_id
      required: true
      description: The numeric ID of the account
      schema:
        type: integer
  securitySchemes:
    userApiKey:
      type: apiKey
      in: header
      name: api_access_token
      description: 'A user''s access token, from **Profile settings → Access token** in the dashboard.

        Requests act with that user''s role: administrators reach everything in their

        account, agents only what their role and visibility settings allow.

        '
    agentBotApiKey:
      type: apiKey
      in: header
      name: api_access_token
      description: 'An agent bot''s access token, shown to administrators on the bot''s settings page.

        Bot tokens reach a limited set of conversation and message endpoints.

        '
    platformAppApiKey:
      type: apiKey
      in: header
      name: api_access_token
      description: 'A platform app token, issued by the installation operator. Used to provision

        accounts, users, account memberships and agent bots.

        '
    connectorInvokeToken:
      type: http
      scheme: bearer
      description: 'A connector''s invoke token (`hci_…`), sent as `Authorization: Bearer <token>`.

        Each connector install has its own; it is rotated whenever the connector is

        reconnected or disconnected, so a stale copy stops working.

        '
x-tagGroups:
- name: Guides
  tags:
  - Introduction
  - Authentication
  - Errors
  - Pagination
  - Rate limits
  - Webhook events
- name: Webhook payloads
  tags:
  - Event payloads
- name: Platform
  tags:
  - Accounts
  - Account Users
  - AgentBots
  - Users
- name: Application
  tags:
  - Account AgentBots
  - Agents
  - Automation Rule
  - Campaigns
  - Canned Responses
  - Contacts
  - Contact Labels
  - Conversation Assignment
  - Conversation Labels
  - Conversations
  - Custom Attributes
  - Custom Filters
  - Help Center
  - Inboxes
  - Integrations
  - Macros
  - Messages
  - Profile
  - Reports
  - Security Settings
  - Teams
  - Webhooks
- name: Business tools
  tags:
  - AI Classifications
  - Assignment Settings
  - Calls
  - AI Phone Lines
  - Connectors
  - ElevenLabs Integration
  - Facebook Marketing
  - HellouAI Integration
  - Knowledge Base
  - Marketing Consent
  - Plan Upgrades
  - Voice Campaigns
  - WhatsApp Campaigns
  - WhatsApp Flows
  - WhatsApp Templates
- name: Client
  tags:
  - Inbox API
  - Contacts API
  - Conversations API
  - Messages API
- name: Others
  tags:
  - CSAT Survey Page