Kairon Inbox API

openapi: 3.2.0
info:
  title: Kairon Inbox API
  description: B2B agentic go-to-market platform
  version: 0.0.0
  contact: {}
servers: []
security:
- api-key: []
tags:
- name: inbox
paths:
  /api/inbox/seats:
    get:
      operationId: InboxController_seats
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - inbox
      summary: Inbox controller seats
      x-summary-source: derived
  /api/inbox/mailboxes:
    get:
      operationId: InboxController_mailboxes
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - inbox
      summary: Inbox controller mailboxes
      x-summary-source: derived
  /api/inbox/owed-count:
    get:
      operationId: InboxController_owedCount
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - inbox
      summary: Inbox controller owed count
      x-summary-source: derived
  /api/inbox/chats/{chatId}/set-aside:
    post:
      operationId: InboxController_setAside
      parameters:
      - name: chatId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetAsideChatDto'
      responses:
        '204':
          description: ''
      tags:
      - inbox
      summary: Inbox controller set aside
      x-summary-source: derived
  /api/inbox/needs-human-count:
    get:
      operationId: InboxController_needsHumanCount
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - inbox
      summary: Inbox controller needs human count
      x-summary-source: derived
  /api/inbox/interested-unanswered-count:
    get:
      operationId: InboxController_interestedUnansweredCount
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - inbox
      summary: Inbox controller interested unanswered count
      x-summary-source: derived
  /api/inbox/resolve-chat:
    get:
      operationId: InboxController_resolveChat
      parameters:
      - name: providerChatId
        required: true
        in: query
        schema:
          type: string
      - name: seatId
        required: true
        in: query
        schema:
          type: string
      responses:
        '200':
          description: ''
      tags:
      - inbox
      summary: Inbox controller resolve chat
      x-summary-source: derived
  /api/inbox/sync:
    post:
      operationId: InboxController_syncNow
      parameters: []
      responses:
        '202':
          description: ''
      tags:
      - inbox
      summary: Inbox controller sync now
      x-summary-source: derived
  /api/inbox/chats:
    get:
      operationId: InboxController_listChats
      parameters:
      - name: seatId
        required: false
        in: query
        schema:
          maxLength: 64
          type: string
      - name: channel
        required: false
        in: query
        schema:
          type: string
          enum:
          - linkedin
          - email
          - whatsapp
      - name: mailbox
        required: false
        in: query
        schema:
          maxLength: 320
          type: string
      - name: leadId
        required: false
        in: query
        schema:
          maxLength: 64
          type: string
      - name: campaignId
        required: false
        in: query
        schema:
          maxLength: 64
          type: string
      - name: unread
        required: false
        in: query
        description: True returns only chats with unread messages.
        x-nestjs_zod-empty-type: true
        schema:
          anyOf:
          - type: boolean
          - type: string
            enum:
            - '0'
            - '1'
            - 'true'
            - 'false'
      - name: answered
        required: false
        in: query
        description: '''no'' returns chats waiting on a reply from you: they spoke last, and nobody on your team closed the chat or set it for later since (a chat comes back when they write again, or when its later date passes). ''yes'' returns the ones you already answered. Chats whose history has not been loaded yet match neither.'
        schema:
          type: string
          enum:
          - 'yes'
          - 'no'
      - name: leadsOnly
        required: false
        in: query
        x-nestjs_zod-empty-type: true
        schema:
          anyOf:
          - type: boolean
          - type: string
            enum:
            - '0'
            - '1'
            - 'true'
            - 'false'
      - name: needsHuman
        required: false
        in: query
        description: True returns only chats where Kairon stepped back and is waiting on you.
        x-nestjs_zod-empty-type: true
        schema:
          anyOf:
          - type: boolean
          - type: string
            enum:
            - '0'
            - '1'
            - 'true'
            - 'false'
      - name: classification
        required: false
        in: query
        description: 'What their last inbound message meant: interested, objection, neutral, or not_interested. Combine with answered=no for the pile you have not replied to.'
        schema:
          type: string
          enum:
          - interested
          - objection
          - neutral
          - not_interested
      - name: seen
        required: false
        in: query
        description: 'True returns LinkedIn chats where they saw your last message and have not replied. Checks LinkedIn live for up to 50 chats first, so the first call can take up to a minute; calling again works through the rest. On normal (non-Sales Navigator) chats many people hide read receipts, so a chat missing here may still have been read. It already means your message is the last one: do not combine it with answered.'
        x-nestjs_zod-empty-type: true
        schema:
          anyOf:
          - type: boolean
          - type: string
            enum:
            - '0'
            - '1'
            - 'true'
            - 'false'
      - name: pendingBy
        required: false
        in: query
        description: 'What you have to answer by a day: `today` (in your own timezone) or YYYY-MM-DD. Returns chats where they wrote last and nobody answered, plus chats about a person you have an open task on due that day or earlier. Each row says why in `pending`: reply, task or both. It means unanswered, not unread. Combines with the other filters, but not `answered`: it narrows both halves.'
        schema:
          type: string
      - name: q
        required: false
        in: query
        schema:
          maxLength: 200
          type: string
      - name: cursor
        required: false
        in: query
        schema:
          maxLength: 65536
          type: string
      - name: limit
        required: false
        in: query
        schema:
          minimum: 1
          maximum: 100
          default: 30
          type: integer
      responses:
        '200':
          description: ''
      tags:
      - inbox
      summary: Inbox controller list chats
      x-summary-source: derived
    post:
      operationId: InboxController_start
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboxStartChatDto'
      responses:
        '200':
          description: ''
      tags:
      - inbox
      summary: Inbox controller start
      x-summary-source: derived
  /api/inbox/chats/{chatId}:
    get:
      operationId: InboxController_getChat
      parameters:
      - name: chatId
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
      tags:
      - inbox
      summary: Inbox controller get chat
      x-summary-source: derived
  /api/inbox/chats/{chatId}/template-vars:
    get:
      operationId: InboxController_getTemplateVars
      parameters:
      - name: chatId
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
      tags:
      - inbox
      summary: Inbox controller get template vars
      x-summary-source: derived
  /api/inbox/chats/{chatId}/messages:
    get:
      operationId: InboxController_getThread
      parameters:
      - name: chatId
        required: true
        in: path
        schema:
          type: string
      - name: cursor
        required: false
        in: query
        schema:
          maxLength: 65536
          type: string
      - name: limit
        required: false
        in: query
        schema:
          minimum: 1
          maximum: 100
          default: 30
          type: integer
      responses:
        '200':
          description: ''
      tags:
      - inbox
      summary: Inbox controller get thread
      x-summary-source: derived
    post:
      operationId: InboxController_reply
      parameters:
      - name: chatId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboxReplyDto'
      responses:
        '201':
          description: ''
      tags:
      - inbox
      summary: Inbox controller reply
      x-summary-source: derived
  /api/inbox/chats/{chatId}/messages/{messageId}/attachments/{index}:
    get:
      operationId: InboxController_attachment
      parameters:
      - name: chatId
        required: true
        in: path
        schema:
          type: string
      - name: messageId
        required: true
        in: path
        schema:
          type: string
      - name: index
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
      tags:
      - inbox
      summary: Inbox controller attachment
      x-summary-source: derived
  /api/inbox/first-message:
    get:
      operationId: InboxController_firstMessage
      parameters:
      - name: leadId
        required: true
        in: query
        schema:
          type: string
      responses:
        '200':
          description: ''
      tags:
      - inbox
      summary: Inbox controller first message
      x-summary-source: derived
  /api/inbox/chats/{chatId}/messages/suggest:
    post:
      operationId: InboxController_suggest
      parameters:
      - name: chatId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboxSuggestDto'
      responses:
        '201':
          description: ''
      tags:
      - inbox
      summary: Inbox controller suggest
      x-summary-source: derived
  /api/inbox/chats/{chatId}/messages/{messageId}:
    patch:
      operationId: InboxController_editMessage
      parameters:
      - name: chatId
        required: true
        in: path
        schema:
          type: string
      - name: messageId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboxEditDto'
      responses:
        '200':
          description: ''
      tags:
      - inbox
      summary: Inbox controller edit message
      x-summary-source: derived
    delete:
      operationId: InboxController_deleteMessage
      parameters:
      - name: chatId
        required: true
        in: path
        schema:
          type: string
      - name: messageId
        required: true
        in: path
        schema:
          type: string
      responses:
        '204':
          description: ''
      tags:
      - inbox
      summary: Inbox controller delete message
      x-summary-source: derived
  /api/inbox/chats/{chatId}/read:
    post:
      operationId: InboxController_markRead
      parameters:
      - name: chatId
        required: true
        in: path
        schema:
          type: string
      responses:
        '204':
          description: ''
      tags:
      - inbox
      summary: Inbox controller mark read
      x-summary-source: derived
  /api/inbox/chats/{chatId}/unread:
    post:
      operationId: InboxController_markUnread
      parameters:
      - name: chatId
        required: true
        in: path
        schema:
          type: string
      responses:
        '204':
          description: ''
      tags:
      - inbox
      summary: Inbox controller mark unread
      x-summary-source: derived
  /api/inbox/chats/{chatId}/lead:
    post:
      operationId: InboxController_addAsLead
      parameters:
      - name: chatId
        required: true
        in: path
        schema:
          type: string
      responses:
        '201':
          description: ''
      tags:
      - inbox
      summary: Inbox controller add as lead
      x-summary-source: derived
components:
  schemas:
    InboxEditDto:
      type: object
      properties:
        text:
          type: string
          minLength: 1
          maxLength: 8000
      required:
      - text
    SetAsideChatDto:
      type: object
      properties:
        until:
          anyOf:
          - type: string
            format: date-time
            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
          - type: 'null'
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-empty-type: true
        shownLastMessageAt:
          type: string
          format: date-time
          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
          x-nestjs_zod-uses-3-point-1-syntax: true
      required:
      - until
    InboxSuggestDto:
      type: object
      properties:
        feedback:
          type: string
          maxLength: 4000
    InboxStartChatDto:
      type: object
      properties:
        target:
          oneOf:
          - type: object
            properties:
              type:
                type: string
                const: url
                description: Which form `value` takes. Exactly one form per call — pick the one you actually have rather than reshaping it.
              value:
                type: string
                minLength: 1
                maxLength: 512
                description: A LinkedIn profile or company URL.
              kind:
                description: What `value` names, when already known — set for you on targets read off a list row. Leave unset when addressing something by hand; `linkedin_fetch`'s own `kind` overrides it. Ignored on a URL, which already says what it points at.
                type: string
                enum:
                - profile
                - company
            required:
            - type
            - value
          - type: object
            properties:
              type:
                type: string
                const: public_identifier
                description: Which form `value` takes. Exactly one form per call — pick the one you actually have rather than reshaping it.
              value:
                type: string
                minLength: 1
                maxLength: 512
                description: The vanity slug (e.g. "jane-doe") or company universal name.
              kind:
                description: What `value` names, when already known — set for you on targets read off a list row. Leave unset when addressing something by hand; `linkedin_fetch`'s own `kind` overrides it. Ignored on a URL, which already says what it points at.
                type: string
                enum:
                - profile
                - company
            required:
            - type
            - value
          - type: object
            properties:
              type:
                type: string
                const: provider_id
                description: Which form `value` takes. Exactly one form per call — pick the one you actually have rather than reshaping it.
              value:
                type: string
                minLength: 1
                maxLength: 512
                description: Unipile/LinkedIn internal id (e.g. "ACoAAB…" or the Sales-Nav "ACwAAB…").
              kind:
                description: What `value` names, when already known — set for you on targets read off a list row. Leave unset when addressing something by hand; `linkedin_fetch`'s own `kind` overrides it. Ignored on a URL, which already says what it points at.
                type: string
                enum:
                - profile
                - company
            required:
            - type
            - value
          description: Who this acts on — one LinkedIn person or company, named by URL, vanity slug, or provider id.
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-empty-type: true
        text:
          type: string
          minLength: 1
          maxLength: 8000
          description: 'The message body, exactly as it will be sent. Nothing rewrites it — and nothing splits it either: a line of `---` goes out as those characters, not as a bubble break. Bubbles are a CAMPAIGN message step; this tool sends one message.'
          x-nestjs_zod-uses-3-point-1-syntax: true
        attachments:
          maxItems: 5
          type: array
          items:
            anyOf:
            - type: object
              properties:
                fileName:
                  type: string
                  minLength: 1
                  maxLength: 255
                  description: The file name, with its extension — what the recipient sees.
                mimeType:
                  type: string
                  minLength: 1
                  maxLength: 255
                  description: The file's MIME type, e.g. `image/png` or `application/pdf`.
                dataBase64:
                  type: string
                  minLength: 1
                  maxLength: 4194304
                  description: The file itself, base64-encoded. Use this OR `url`, never both.
              required:
              - fileName
              - mimeType
              - dataBase64
              additionalProperties: false
            - type: object
              properties:
                fileName:
                  type: string
                  minLength: 1
                  maxLength: 255
                  description: The file name, with its extension — what the recipient sees.
                mimeType:
                  type: string
                  minLength: 1
                  maxLength: 255
                  description: The file's MIME type, e.g. `image/png` or `application/pdf`.
                url:
                  type: string
                  minLength: 1
                  maxLength: 2048
                  format: uri
                  description: An https address we fetch server-side. Use this OR `dataBase64`, never both. Reach for it when you cannot produce base64.
              required:
              - fileName
              - mimeType
              - url
              additionalProperties: false
          x-nestjs_zod-uses-3-point-1-syntax: true
        seatId:
          type: string
          x-nestjs_zod-uses-3-point-1-syntax: true
      required:
      - target
      - text
    InboxReplyDto:
      type: object
      properties:
        text:
          type: string
          maxLength: 8000
        clientToken:
          description: Your own idempotency key. Send the SAME token when retrying after a lost response and the message is not sent twice.
          type: string
          minLength: 1
          maxLength: 128
        isRetry:
          type: boolean
        cc:
          description: 'EMAIL conversations only: up to 5 addresses to copy on the reply, e.g. your main address so the conversation continues there. Refused on a LinkedIn conversation.'
          maxItems: 5
          type: array
          items:
            type: string
            maxLength: 320
            format: email
            pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
      required:
      - text
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: x-api-key
      description: 'A Kairon API key (Settings → Integrations → API access), sent as `x-api-key`. NOT an `Authorization: Bearer` token — that header belongs to the separate /mcp door and is ignored here.'
    session:
      type: apiKey
      in: cookie
      name: better-auth.session_token