Causerie Chatbots API

openapi: 3.2.0
info:
  title: Causerie public Chatbots API
  version: 2026-09
  summary: Read the chatbots, contacts (leads) and conversations of a Causerie account.
  description: 'Read-only REST API of Causerie (French SaaS: AI chatbots for websites).


    Authentication: `Authorization: Bearer csb_live_…`, an API key created in Settings › API keys. The key identifies an account and gives read access to everything the endpoints below return for that account; keys have no scopes.


    Pagination (lists of contacts and conversations): oldest first. Follow `next_cursor` (pass it back as `cursor`) until it is `null`. Use `since` to fetch only what is new since the last synchronisation.


    Errors are JSON: `{ "error": "…", "code": "…", "hint": "…" }`. `error` is a human-readable message in French, `code` is stable, `hint` says what to do. An unknown path under /api/public answers 404 `not_found`; a method other than GET answers 405 `method_not_allowed`.


    Call it from a server, not from a web page: a key in a browser is a published key.'
  contact:
    name: Causerie
    email: contact@causeriebot.com
    url: https://causeriebot.com
  termsOfService: https://dashboard.causeriebot.com/terms
servers:
- url: https://dashboard.causeriebot.com/api/public
security:
- apiKey: []
tags:
- name: Chatbots
paths:
  /chatbots:
    get:
      operationId: listChatbots
      tags:
      - Chatbots
      summary: List the account's chatbots
      description: The chatbots owned by the account of the key (not those shared with it), most recent first. Not paginated. Available on every plan.
      responses:
        '200':
          description: The chatbots.
          content:
            application/json:
              schema:
                type: object
                required:
                - chatbots
                properties:
                  chatbots:
                    type: array
                    items:
                      $ref: '#/components/schemas/Chatbot'
        '401':
          description: Missing, malformed, invalid or revoked API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_api_key:
                  summary: missing_api_key
                  value:
                    error: 'Clé API manquante. En-tête attendu : Authorization: Bearer csb_live_…'
                    code: missing_api_key
                    hint: 'Ajoutez l''en-tête Authorization: Bearer csb_live_… (clé créée dans Paramètres › Clés API : https://dashboard.causeriebot.com/settings?tab=api).'
                invalid_api_key_format:
                  summary: invalid_api_key_format
                  value:
                    error: Format de clé invalide
                    code: invalid_api_key_format
                    hint: Une clé API Causerie commence par csb_live_.
                invalid_api_key:
                  summary: invalid_api_key
                  value:
                    error: Clé API invalide ou révoquée
                    code: invalid_api_key
                    hint: 'Vérifiez la clé, ou créez-en une dans Paramètres › Clés API : https://dashboard.causeriebot.com/settings?tab=api.'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                internal_error:
                  summary: internal_error
                  value:
                    error: Erreur interne
                    code: internal_error
                    hint: 'Réessayez dans un instant. Si l''erreur persiste : contact@causeriebot.com.'
components:
  schemas:
    Chatbot:
      type: object
      required:
      - id
      - name
      - is_active
      - theme_color
      - welcome_message
      - position
      - language
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        is_active:
          type:
          - boolean
          - 'null'
        theme_color:
          type:
          - string
          - 'null'
          description: Main color of the widget.
        welcome_message:
          type:
          - string
          - 'null'
        position:
          type:
          - string
          - 'null'
          description: 'Position of the widget: bottom-right or bottom-left.'
        language:
          type:
          - string
          - 'null'
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable message, in French.
        code:
          type: string
          enum:
          - missing_api_key
          - invalid_api_key_format
          - invalid_api_key
          - plan_required
          - invalid_since
          - invalid_cursor
          - invalid_limit
          - chatbot_not_found
          - conversation_not_found
          - not_found
          - method_not_allowed
          - read_failed
          - internal_error
          description: Stable error code.
        hint:
          type: string
          description: What to do about it.
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: csb_live_…
      description: 'API key of the account (Settings › API keys), sent as `Authorization: Bearer csb_live_…`. No scopes: the key reads everything the endpoints return for its account. OAuth access tokens are not accepted here (they are for the MCP server, /api/mcp/account).'
externalDocs:
  description: Full documentation (REST API, webhooks, MCP server)
  url: https://dashboard.causeriebot.com/llms-full.txt