Causerie Conversations API

openapi: 3.2.0
info:
  title: Causerie public Conversations 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: Conversations
  description: Conversations between visitors and the chatbots. Pro and Business plans.
paths:
  /conversations:
    get:
      operationId: listConversations
      tags:
      - Conversations
      summary: List conversations (without messages)
      description: Conversations of the chatbots the account can access (its own and those shared with it), sorted by `started_at`, oldest first, without their messages (see GET /conversations/{id}). `since` and `cursor` apply to `started_at`, also returned as `created_at`.
      parameters:
      - $ref: '#/components/parameters/chatbot_id'
      - $ref: '#/components/parameters/since'
      - $ref: '#/components/parameters/cursor'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: A page of conversations.
          headers:
            X-Causerie-Version:
              description: API version.
              schema:
                type: string
                example: 2026-09
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationPage'
        '400':
          description: Invalid `since`, `cursor` or `limit`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_since:
                  summary: invalid_since
                  value:
                    error: '`since` doit être une date ISO 8601'
                    code: invalid_since
                    hint: Une date ISO 8601, par exemple since=2026-09-01T00:00:00Z.
                invalid_cursor:
                  summary: invalid_cursor
                  value:
                    error: '`cursor` invalide'
                    code: invalid_cursor
                    hint: Reprenez telle quelle la valeur next_cursor de la page précédente.
                invalid_limit:
                  summary: invalid_limit
                  value:
                    error: '`limit` doit être un entier positif'
                    code: invalid_limit
                    hint: Un entier à partir de 1 ; au-delà de 200, 200 sont renvoyés. 50 par défaut.
        '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.'
        '403':
          description: The account's plan does not include the API for contacts and conversations (Pro and Business only).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                plan_required:
                  summary: plan_required
                  value:
                    error: L'API des contacts et des conversations est disponible à partir du plan Pro.
                    code: plan_required
                    hint: 'Passez au plan Pro ou Business : https://dashboard.causeriebot.com/settings?tab=abonnement.'
        '404':
          description: '`chatbot_id` is not one of the chatbots the key can access.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                chatbot_not_found:
                  summary: chatbot_not_found
                  value:
                    error: Chatbot inconnu pour cette clé
                    code: chatbot_not_found
                    hint: Utilisez l'identifiant d'un chatbot du compte (GET /api/public/chatbots), ou retirez chatbot_id.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                read_failed:
                  summary: read_failed
                  value:
                    error: Lecture impossible
                    code: read_failed
                    hint: 'Réessayez dans un instant. Si l''erreur persiste : contact@causeriebot.com.'
                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.'
  /conversations/{id}:
    get:
      operationId: getConversation
      tags:
      - Conversations
      summary: Get a conversation with its messages
      description: One conversation with the visitor's and the assistant's messages (oldest first, at most 500; internal system messages are left out) and the first contact collected in it, if any.
      parameters:
      - name: id
        in: path
        required: true
        description: Conversation id.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The conversation.
          headers:
            X-Causerie-Version:
              description: API version.
              schema:
                type: string
                example: 2026-09
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '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.'
        '403':
          description: The account's plan does not include the API for contacts and conversations (Pro and Business only).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                plan_required:
                  summary: plan_required
                  value:
                    error: L'API des contacts et des conversations est disponible à partir du plan Pro.
                    code: plan_required
                    hint: 'Passez au plan Pro ou Business : https://dashboard.causeriebot.com/settings?tab=abonnement.'
        '404':
          description: No conversation with this id among the chatbots the key can access (or the id is not a UUID).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                conversation_not_found:
                  summary: conversation_not_found
                  value:
                    error: Conversation introuvable
                    code: conversation_not_found
                    hint: Utilisez un identifiant renvoyé par GET /api/public/conversations.
        '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:
  parameters:
    chatbot_id:
      name: chatbot_id
      in: query
      required: false
      description: 'Only this chatbot. It must be one the key can access, otherwise 404 `chatbot_not_found`. Without it: all of them.'
      schema:
        type: string
        format: uuid
    limit:
      name: limit
      in: query
      required: false
      description: Page size. Values above 200 are treated as 200.
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
    cursor:
      name: cursor
      in: query
      required: false
      description: 'The `next_cursor` of the previous page: items strictly after it.'
      schema:
        type: string
        format: date-time
    since:
      name: since
      in: query
      required: false
      description: 'ISO 8601 date: only items from this date on (inclusive).'
      schema:
        type: string
        format: date-time
      example: '2026-09-01T00:00:00Z'
  schemas:
    ConversationLead:
      type: object
      required:
      - id
      - name
      - email
      - phone
      - company
      - source
      - created_at
      properties:
        id:
          type: string
          format: uuid
        name:
          type:
          - string
          - 'null'
        email:
          type:
          - string
          - 'null'
        phone:
          type:
          - string
          - 'null'
        company:
          type:
          - string
          - 'null'
        source:
          type:
          - string
          - 'null'
        created_at:
          type: string
          format: date-time
    ConversationPage:
      type: object
      required:
      - data
      - next_cursor
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ConversationSummary'
        next_cursor:
          type:
          - string
          - 'null'
          format: date-time
          description: '`started_at` of the last item when there is a next page, otherwise null.'
    ConversationSummary:
      type: object
      required:
      - id
      - chatbot
      - source
      - status
      - is_lead
      - message_count
      - started_at
      - last_message_at
      - created_at
      properties:
        id:
          type: string
          format: uuid
        chatbot:
          $ref: '#/components/schemas/ChatbotRef'
        source:
          type:
          - string
          - 'null'
        status:
          type:
          - string
          - 'null'
        is_lead:
          type: boolean
        message_count:
          type: integer
        started_at:
          type: string
          format: date-time
        last_message_at:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
          description: Same value as `started_at`.
    ChatbotRef:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
          format: uuid
        name:
          type:
          - string
          - 'null'
    Conversation:
      type: object
      required:
      - id
      - chatbot
      - source
      - status
      - is_lead
      - started_at
      - last_message_at
      - lead
      - messages
      properties:
        id:
          type: string
          format: uuid
        chatbot:
          $ref: '#/components/schemas/ChatbotRef'
        source:
          type:
          - string
          - 'null'
        status:
          type:
          - string
          - 'null'
        is_lead:
          type: boolean
        started_at:
          type: string
          format: date-time
        last_message_at:
          type:
          - string
          - 'null'
          format: date-time
        lead:
          oneOf:
          - $ref: '#/components/schemas/ConversationLead'
          - type: 'null'
        messages:
          type: array
          maxItems: 500
          items:
            $ref: '#/components/schemas/Message'
    Message:
      type: object
      required:
      - id
      - role
      - content
      - created_at
      properties:
        id:
          type: string
          format: uuid
        role:
          type: string
          enum:
          - visitor
          - assistant
        content:
          type: string
        created_at:
          type: string
          format: date-time
    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