definitions:
  gorm.DeletedAt:
    properties:
      time:
        type: string
      valid:
        description: Valid is true if Time is not NULL
        type: boolean
    type: object
  model.Account:
    properties:
      active:
        type: boolean
      auto_resolve_duration:
        description: days
        type: integer
      created_at:
        type: string
      deleted_at:
        $ref: '#/definitions/gorm.DeletedAt'
      domain:
        type: string
      feature_flags:
        description: JSON-encoded feature flags
        type: string
      id:
        type: integer
      locale:
        type: string
      name:
        type: string
      status:
        type: string
      timezone:
        type: string
      updated_at:
        type: string
    type: object
  model.Contact:
    properties:
      account_id:
        type: integer
      additional_attributes:
        items:
          type: integer
        type: array
      avatar_url:
        type: string
      blocked:
        type: boolean
      company_id:
        type: integer
      contact_type:
        type: string
      country_code:
        type: string
      created_at:
        type: string
      custom_attributes:
        items:
          type: integer
        type: array
      deleted_at:
        $ref: '#/definitions/gorm.DeletedAt'
      email:
        type: string
      id:
        type: integer
      identifier:
        type: string
      last_activity_at:
        type: integer
      last_name:
        type: string
      location:
        type: string
      middle_name:
        type: string
      name:
        type: string
      phone_number:
        type: string
      source_id:
        type: string
      updated_at:
        type: string
    type: object
  model.Conversation:
    properties:
      account_id:
        type: integer
      additional_attributes:
        items:
          type: integer
        type: array
      agent_last_seen_at:
        type: integer
      assignee_id:
        type: integer
      assignee_last_seen_at:
        type: integer
      campaign_id:
        type: integer
      channel:
        description: channel identifier for routing
        type: string
      channel_type:
        type: string
      contact_id:
        type: integer
      contact_inbox_id:
        type: integer
      contact_last_seen_at:
        type: integer
      created_at:
        type: string
      custom_attributes:
        items:
          type: integer
        type: array
      deleted_at:
        $ref: '#/definitions/gorm.DeletedAt'
      display_id:
        description: account-level auto-increment number
        type: integer
      first_reply_created_at:
        type: integer
      id:
        type: integer
      inbox_id:
        type: integer
      labels:
        description: comma-separated or JSON label list
        type: string
      last_activity_at:
        type: integer
      last_message_at:
        type: integer
      last_non_system_message_at:
        type: integer
      muted:
        type: boolean
      priority:
        description: none, low, medium, high, urgent
        type: string
      resolved_at:
        description: 'Chatwoot: timestamp when conversation was resolved'
        type: string
      resumed_at:
        description: 'Chatwoot: timestamp when conversation was reopened'
        type: string
      sla_policy_id:
        type: integer
      snoozed_until:
        description: timestamp for snoozed conversations
        type: integer
      status:
        description: open, resolved, pending, snoozed
        type: string
      team_id:
        type: integer
      updated_at:
        type: string
      uuid:
        description: auto-generated global unique identifier
        type: string
      waiting_since:
        type: integer
    type: object
  model.ErrorResponse:
    properties:
      error:
        example: not_found
        type: string
      message:
        example: Resource not found
        type: string
    type: object
  model.Inbox:
    properties:
      account_id:
        type: integer
      allow_messages_after_resolved:
        type: boolean
      auto_assignment_limit:
        type: integer
      avatar_url:
        description: URL to inbox avatar image
        type: string
      business_name:
        type: string
      channel_config:
        description: JSON-encoded per-inbox channel configuration
        type: string
      channel_id:
        type: integer
      channel_type:
        description: web_widget, facebook, twitter, whatsapp, telegram, email, api,
          etc
        type: string
      created_at:
        type: string
      csat_config:
        description: JSON-encoded CSAT survey configuration
        type: string
      csat_survey_enabled:
        type: boolean
      deleted_at:
        $ref: '#/definitions/gorm.DeletedAt'
      enable_auto_assignment:
        type: boolean
      enable_email_collect:
        type: boolean
      enabled:
        type: boolean
      greeting_enabled:
        description: Chatwoot inbox settings (from permitted_params)
        type: boolean
      greeting_message:
        type: string
      id:
        type: integer
      lock_to_single_conversation:
        type: boolean
      name:
        type: string
      out_of_office_message:
        type: string
      portal_id:
        description: FK to help-center portal (nullable)
        type: integer
      secret:
        description: HMAC secret for API inbox webhook verification
        type: string
      sender_name_type:
        description: friendly_name, business_name, random
        type: string
      timezone:
        description: e.g. "Asia/Kolkata"
        type: string
      updated_at:
        type: string
      webhook_url:
        description: API inbox specific fields
        type: string
      working_hours_enabled:
        type: boolean
    type: object
  model.JSONMap:
    additionalProperties: true
    type: object
  model.Message:
    properties:
      account_id:
        type: integer
      additional_attributes:
        items:
          type: integer
        type: array
      content:
        type: string
      content_attributes:
        description: attachments, mentions, etc
        items:
          type: integer
        type: array
      content_type:
        description: text, input, input_csat, file, image, etc
        type: string
      conversation_id:
        type: integer
      created_at:
        type: string
      deleted_at:
        $ref: '#/definitions/gorm.DeletedAt'
      external:
        type: boolean
      external_source_ids:
        description: external platform IDs
        items:
          type: integer
        type: array
      id:
        type: integer
      inbox_id:
        type: integer
      message_type:
        description: incoming, outgoing, activity, template
        type: string
      private:
        type: boolean
      sender_id:
        type: integer
      sender_type:
        description: contact, agent, bot
        type: string
      source_id:
        type: string
      status:
        description: sent, delivered, read, failed
        type: string
      updated_at:
        type: string
    type: object
  search.SearchResponse:
    properties:
      by_type:
        additionalProperties:
          format: int64
          type: integer
        description: 'count per type: {"conversation":5,"message":12,...}'
        type: object
      page:
        type: integer
      per_page:
        type: integer
      query:
        type: string
      results:
        items:
          $ref: '#/definitions/search.SearchResult'
        type: array
      total_count:
        description: total hits across all types
        type: integer
    type: object
  search.SearchResult:
    properties:
      account_id:
        type: integer
      data:
        description: full entity payload (Conversation, Message, Contact)
      id:
        type: integer
      score:
        description: relevance score (higher = more relevant)
        type: number
      snippet:
        description: short excerpt for display
        type: string
      type:
        $ref: '#/definitions/search.SearchResultType'
    type: object
  search.SearchResultType:
    enum:
    - conversation
    - message
    - contact
    - article
    type: string
    x-enum-varnames:
    - ResultTypeConversation
    - ResultTypeMessage
    - ResultTypeContact
    - ResultTypeArticle
  service.AssignAgentRequest:
    properties:
      assignee_id:
        type: integer
    required:
    - assignee_id
    type: object
  service.CreateAccountRequest:
    properties:
      domain:
        minLength: 3
        type: string
      locale:
        type: string
      name:
        minLength: 2
        type: string
    required:
    - name
    type: object
  service.CreateContactRequest:
    properties:
      additional_attributes:
        $ref: '#/definitions/model.JSONMap'
      avatar_url:
        type: string
      company_id:
        type: integer
      contact_type:
        type: string
      country_code:
        type: string
      custom_attributes:
        $ref: '#/definitions/model.JSONMap'
      email:
        type: string
      identifier:
        type: string
      inbox_id:
        type: integer
      last_name:
        type: string
      location:
        type: string
      middle_name:
        type: string
      name:
        minLength: 1
        type: string
      phone:
        type: string
      source_id:
        type: string
    required:
    - name
    type: object
  service.CreateInboxRequest:
    properties:
      channel_type:
        enum:
        - web_widget
        - telegram
        - facebook
        - instagram
        - whatsapp
        - email
        - api
        - tiktok
        - line
        - twilio_sms
        type: string
      enable_auto_assignment:
        type: boolean
      enabled:
        type: boolean
      name:
        minLength: 2
        type: string
    required:
    - channel_type
    - name
    type: object
  service.CreateMessageRequest:
    properties:
      content:
        minLength: 1
        type: string
      content_type:
        enum:
        - text
        - input_text
        - input_email
        - input_phone
        - select
        - card
        - private_note
        type: string
      conversation_id:
        type: integer
      message_type:
        enum:
        - outgoing
        - incoming
        - activity
        - template
        - private_note
        type: string
      private:
        type: boolean
      source_id:
        description: 'Chatwoot: source_id for message origin (user/agent/bot)'
        type: string
    required:
    - content
    - conversation_id
    - message_type
    type: object
  service.ToggleStatusRequest:
    properties:
      assignee_id:
        description: 'Chatwoot: auto-assign on reopen'
        type: integer
      is_bot:
        description: 'Chatwoot: pending_to_open_by_bot — agent bot triggers handoff'
        type: boolean
      snoozed_until:
        description: 'Chatwoot: snooze with wake-up time (unix timestamp)'
        type: integer
      status:
        enum:
        - open
        - resolved
        - pending
        - snoozed
        type: string
      user_id:
        description: 'Chatwoot: should_assign_conversation — auto-assign to agent
          who opens'
        type: integer
    required:
    - status
    type: object
  service.UpdateAccountRequest:
    properties:
      auto_resolve_duration:
        minimum: 0
        type: integer
      domain:
        minLength: 3
        type: string
      feature_flags:
        type: string
      locale:
        type: string
      name:
        minLength: 2
        type: string
      status:
        enum:
        - active
        - inactive
        type: string
    type: object
  service.UpdateContactRequest:
    properties:
      additional_attributes:
        $ref: '#/definitions/model.JSONMap'
      avatar_url:
        type: string
      company_id:
        type: integer
      contact_type:
        type: string
      country_code:
        type: string
      custom_attributes:
        $ref: '#/definitions/model.JSONMap'
      email:
        type: string
      identifier:
        type: string
      last_name:
        type: string
      location:
        type: string
      middle_name:
        type: string
      name:
        minLength: 1
        type: string
      phone:
        type: string
    type: object
  service.UpdateInboxRequest:
    properties:
      enable_auto_assignment:
        type: boolean
      enabled:
        type: boolean
      name:
        minLength: 2
        type: string
    type: object
info:
  contact: {}
paths:
  /api/v1/accounts:
    get:
      consumes:
      - application/json
      description: Returns all accounts the authenticated user has access to, with
        pagination support
      parameters:
      - default: 1
        description: Page number
        in: query
        name: page
        type: integer
      - default: 25
        description: Items per page
        in: query
        name: page_size
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              $ref: '#/definitions/model.Account'
            type: array
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: List accounts accessible by the current user
      tags:
      - Accounts
    post:
      consumes:
      - application/json
      description: Creates a new account and assigns the creator as administrator
      parameters:
      - description: Account creation payload
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/service.CreateAccountRequest'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            $ref: '#/definitions/model.Account'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Create a new account
      tags:
      - Accounts
  /api/v1/accounts/{account_id}/conversations:
    get:
      consumes:
      - application/json
      description: Retrieves all conversations for an account with pagination, optionally
        filtered by status query param
      parameters:
      - description: Account ID
        in: path
        name: account_id
        required: true
        type: integer
      - description: Filter by conversation status (open/pending/resolved/snoozed)
        in: query
        name: status
        type: string
      - default: 1
        description: Page number
        in: query
        name: page
        type: integer
      - default: 25
        description: Items per page
        in: query
        name: page_size
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              $ref: '#/definitions/model.Conversation'
            type: array
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: List conversations for an account
      tags:
      - Conversations
  /api/v1/accounts/{account_id}/conversations/{conversation_id}/messages:
    get:
      consumes:
      - application/json
      description: Retrieves all messages for a conversation with pagination
      parameters:
      - description: Account ID
        in: path
        name: account_id
        required: true
        type: integer
      - description: Conversation ID
        in: path
        name: conversation_id
        required: true
        type: integer
      - default: 1
        description: Page number
        in: query
        name: page
        type: integer
      - default: 25
        description: Items per page
        in: query
        name: page_size
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              $ref: '#/definitions/model.Message'
            type: array
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: List messages in a conversation
      tags:
      - Messages
    post:
      consumes:
      - application/json
      description: Creates a new message in an existing conversation
      parameters:
      - description: Account ID
        in: path
        name: account_id
        required: true
        type: integer
      - description: Conversation ID
        in: path
        name: conversation_id
        required: true
        type: integer
      - description: Message creation payload
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/service.CreateMessageRequest'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            $ref: '#/definitions/model.Message'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Create a message in a conversation
      tags:
      - Messages
  /api/v1/accounts/{account_id}/conversations/{conversation_id}/messages/{id}:
    delete:
      consumes:
      - application/json
      description: Soft-deletes a message from a conversation
      parameters:
      - description: Account ID
        in: path
        name: account_id
        required: true
        type: integer
      - description: Conversation ID
        in: path
        name: conversation_id
        required: true
        type: integer
      - description: Message ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "204":
          description: No Content
          schema:
            type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Delete a message
      tags:
      - Messages
    get:
      consumes:
      - application/json
      description: Retrieves detailed information about a specific message
      parameters:
      - description: Account ID
        in: path
        name: account_id
        required: true
        type: integer
      - description: Conversation ID
        in: path
        name: conversation_id
        required: true
        type: integer
      - description: Message ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/model.Message'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Get a single message
      tags:
      - Messages
  /api/v1/accounts/{account_id}/conversations/{id}:
    get:
      consumes:
      - application/json
      description: Retrieves detailed information about a specific conversation within
        an account
      parameters:
      - description: Account ID
        in: path
        name: account_id
        required: true
        type: integer
      - description: Conversation ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/model.Conversation'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Get a single conversation
      tags:
      - Conversations
  /api/v1/accounts/{account_id}/conversations/{id}/assign:
    post:
      consumes:
      - application/json
      description: Assigns a specific agent to a conversation by providing the assignee
        ID
      parameters:
      - description: Account ID
        in: path
        name: account_id
        required: true
        type: integer
      - description: Conversation ID
        in: path
        name: id
        required: true
        type: integer
      - description: Agent assignment payload
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/service.AssignAgentRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/model.Conversation'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Assign an agent to a conversation
      tags:
      - Conversations
  /api/v1/accounts/{account_id}/conversations/{id}/assignments:
    post:
      consumes:
      - application/json
      description: Assigns a team (and optionally an agent) to a conversation
      parameters:
      - description: Account ID
        in: path
        name: account_id
        required: true
        type: integer
      - description: Conversation ID
        in: path
        name: id
        required: true
        type: integer
      - description: Team assignment payload
        in: body
        name: body
        required: true
        schema:
          type: object
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/model.Conversation'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Assign a team to a conversation
      tags:
      - Conversations
  /api/v1/accounts/{account_id}/conversations/{id}/mute:
    post:
      consumes:
      - application/json
      description: Mutes a conversation to suppress notifications
      parameters:
      - description: Account ID
        in: path
        name: account_id
        required: true
        type: integer
      - description: Conversation ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/model.Conversation'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Mute a conversation
      tags:
      - Conversations
  /api/v1/accounts/{account_id}/conversations/{id}/toggle_status:
    post:
      consumes:
      - application/json
      description: Toggles the status of a conversation between open, pending, resolved,
        or snoozed
      parameters:
      - description: Account ID
        in: path
        name: account_id
        required: true
        type: integer
      - description: Conversation ID
        in: path
        name: id
        required: true
        type: integer
      - description: Status toggle payload
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/service.ToggleStatusRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/model.Conversation'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Toggle conversation status
      tags:
      - Conversations
  /api/v1/accounts/{account_id}/conversations/{id}/unmute:
    post:
      consumes:
      - application/json
      description: Unmutes a conversation to restore notifications
      parameters:
      - description: Account ID
        in: path
        name: account_id
        required: true
        type: integer
      - description: Conversation ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/model.Conversation'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Unmute a conversation
      tags:
      - Conversations
  /api/v1/accounts/{account_id}/conversations/search:
    get:
      consumes:
      - application/json
      description: Searches conversations by query string with pagination and search
        mode support
      parameters:
      - description: Account ID
        in: path
        name: account_id
        required: true
        type: integer
      - description: Search query
        in: query
        name: q
        required: true
        type: string
      - default: prefix
        description: Search mode (prefix/semantic/fulltext)
        in: query
        name: search_mode
        type: string
      - default: 1
        description: Page number
        in: query
        name: page
        type: integer
      - default: 25
        description: Items per page
        in: query
        name: page_size
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              $ref: '#/definitions/model.Conversation'
            type: array
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Search conversations
      tags:
      - Conversations
  /api/v1/accounts/{account_id}/search:
    get:
      consumes:
      - application/json
      description: Searches across conversations, messages, contacts, and articles
        with advanced filtering and pagination
      parameters:
      - description: Account ID
        in: path
        name: account_id
        required: true
        type: integer
      - description: Search query string
        in: query
        name: q
        type: string
      - default: conversation,message,contact,article
        description: Entity types to search (conversation,message,contact,article)
        in: query
        name: types
        type: string
      - default: ilike
        description: 'Search mode: ilike (substring) or trigram (fuzzy)'
        in: query
        name: search_mode
        type: string
      - description: Conversation status filter (open,resolved,pending,snoozed)
        in: query
        name: status
        type: string
      - description: Conversation priority filter (none,low,medium,high,urgent)
        in: query
        name: priority
        type: string
      - description: Assignee agent ID filter
        in: query
        name: assignee_id
        type: integer
      - description: Team ID filter
        in: query
        name: team_id
        type: integer
      - description: Inbox ID filter
        in: query
        name: inbox_id
        type: integer
      - description: Label filter (comma-separated)
        in: query
        name: labels
        type: string
      - description: Contact source filter (email,phone,website,api)
        in: query
        name: contact_source
        type: string
      - description: Message type filter (incoming,outgoing,activity)
        in: query
        name: message_type
        type: string
      - description: Sender type filter
        in: query
        name: sender_type
        type: string
      - description: Content type filter (text,input_email,card)
        in: query
        name: content_type
        type: string
      - description: Private message filter
        in: query
        name: private
        type: boolean
      - description: Date range start (ISO 8601)
        in: query
        name: date_from
        type: string
      - description: Date range end (ISO 8601)
        in: query
        name: date_to
        type: string
      - description: Portal ID filter (for article search)
        in: query
        name: portal_id
        type: integer
      - description: Article status filter (draft,published,archived)
        in: query
        name: article_status
        type: string
      - description: Article locale filter
        in: query
        name: article_locale
        type: string
      - default: created_at
        description: Sort field (created_at,last_activity_at,updated_at)
        in: query
        name: sort_by
        type: string
      - default: desc
        description: Sort order (asc,desc)
        in: query
        name: sort_order
        type: string
      - default: 1
        description: Page number
        in: query
        name: page
        type: integer
      - default: 25
        description: Items per page
        in: query
        name: per_page
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/search.SearchResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Global search across all entity types
      tags:
      - Search
  /api/v1/accounts/{account_id}/search/articles:
    get:
      consumes:
      - application/json
      description: Searches knowledge base articles by query string (title, description,
        content) with portal, status, and locale filters
      parameters:
      - description: Account ID
        in: path
        name: account_id
        required: true
        type: integer
      - description: Search query string
        in: query
        name: q
        required: true
        type: string
      - default: ilike
        description: 'Search mode: ilike (substring) or trigram (fuzzy)'
        in: query
        name: search_mode
        type: string
      - description: Portal ID filter
        in: query
        name: portal_id
        type: integer
      - description: Article status filter (draft,published,archived)
        in: query
        name: article_status
        type: string
      - description: Article locale filter (en,es,fr,de,pt,etc)
        in: query
        name: article_locale
        type: string
      - description: Author ID filter
        in: query
        name: author_id
        type: integer
      - default: created_at
        description: Sort field (created_at,updated_at)
        in: query
        name: sort_by
        type: string
      - default: desc
        description: Sort order (asc,desc)
        in: query
        name: sort_order
        type: string
      - default: 1
        description: Page number
        in: query
        name: page
        type: integer
      - default: 25
        description: Items per page
        in: query
        name: per_page
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Search knowledge base articles
      tags:
      - Search
  /api/v1/accounts/{account_id}/search/contacts:
    get:
      consumes:
      - application/json
      description: Searches contacts by query string (name, email, phone, identifier)
        with advanced filtering
      parameters:
      - description: Account ID
        in: path
        name: account_id
        required: true
        type: integer
      - description: Search query string
        in: query
        name: q
        required: true
        type: string
      - default: ilike
        description: 'Search mode: ilike (substring) or trigram (fuzzy)'
        in: query
        name: search_mode
        type: string
      - description: Contact source filter (email,phone,website,api)
        in: query
        name: contact_source
        type: string
      - default: created_at
        description: Sort field (created_at,updated_at,name)
        in: query
        name: sort_by
        type: string
      - default: desc
        description: Sort order (asc,desc)
        in: query
        name: sort_order
        type: string
      - default: 1
        description: Page number
        in: query
        name: page
        type: integer
      - default: 25
        description: Items per page
        in: query
        name: per_page
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Search contacts
      tags:
      - Search
  /api/v1/accounts/{account_id}/search/conversations:
    get:
      consumes:
      - application/json
      description: Searches conversations by query string with advanced filtering
        (status, assignee, labels, date range)
      parameters:
      - description: Account ID
        in: path
        name: account_id
        required: true
        type: integer
      - description: Search query string
        in: query
        name: q
        required: true
        type: string
      - default: ilike
        description: 'Search mode: ilike (substring) or trigram (fuzzy)'
        in: query
        name: search_mode
        type: string
      - description: Conversation status filter (open,resolved,pending,snoozed)
        in: query
        name: status
        type: string
      - description: Conversation priority filter (none,low,medium,high,urgent)
        in: query
        name: priority
        type: string
      - description: Assignee agent ID filter
        in: query
        name: assignee_id
        type: integer
      - description: Team ID filter
        in: query
        name: team_id
        type: integer
      - description: Inbox ID filter
        in: query
        name: inbox_id
        type: integer
      - description: Label filter (comma-separated)
        in: query
        name: labels
        type: string
      - description: Date range start (ISO 8601)
        in: query
        name: date_from
        type: string
      - description: Date range end (ISO 8601)
        in: query
        name: date_to
        type: string
      - default: created_at
        description: Sort field (created_at,last_activity_at,updated_at)
        in: query
        name: sort_by
        type: string
      - default: desc
        description: Sort order (asc,desc)
        in: query
        name: sort_order
        type: string
      - default: 1
        description: Page number
        in: query
        name: page
        type: integer
      - default: 25
        description: Items per page
        in: query
        name: per_page
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Search conversations
      tags:
      - Search
  /api/v1/accounts/{account_id}/search/messages:
    get:
      consumes:
      - application/json
      description: Searches messages by query string with advanced filtering (message
        type, sender type, content type, private)
      parameters:
      - description: Account ID
        in: path
        name: account_id
        required: true
        type: integer
      - description: Search query string
        in: query
        name: q
        required: true
        type: string
      - default: ilike
        description: 'Search mode: ilike (substring) or trigram (fuzzy)'
        in: query
        name: search_mode
        type: string
      - description: Message type filter (incoming,outgoing,activity)
        in: query
        name: message_type
        type: string
      - description: Sender type filter
        in: query
        name: sender_type
        type: string
      - description: Content type filter (text,input_email,card)
        in: query
        name: content_type
        type: string
      - description: Private message filter
        in: query
        name: private
        type: boolean
      - description: Inbox ID filter
        in: query
        name: inbox_id
        type: integer
      - description: Date range start (ISO 8601)
        in: query
        name: date_from
        type: string
      - description: Date range end (ISO 8601)
        in: query
        name: date_to
        type: string
      - default: created_at
        description: Sort field (created_at,updated_at)
        in: query
        name: sort_by
        type: string
      - default: desc
        description: Sort order (asc,desc)
        in: query
        name: sort_order
        type: string
      - default: 1
        description: Page number
        in: query
        name: page
        type: integer
      - default: 25
        description: Items per page
        in: query
        name: per_page
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Search messages
      tags:
      - Search
  /api/v1/accounts/{id}:
    delete:
      consumes:
      - application/json
      description: Soft-deletes an account by ID
      parameters:
      - description: Account ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "204":
          description: No Content
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Delete an account
      tags:
      - Accounts
    get:
      consumes:
      - application/json
      description: Retrieves detailed information about a specific account
      parameters:
      - description: Account ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/model.Account'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Get a single account by ID
      tags:
      - Accounts
    put:
      consumes:
      - application/json
      description: Modifies account details such as name and settings
      parameters:
      - description: Account ID
        in: path
        name: id
        required: true
        type: integer
      - description: Account update payload
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/service.UpdateAccountRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/model.Account'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Update an existing account
      tags:
      - Accounts
  /api/v1/accounts/{id}/contacts:
    get:
      consumes:
      - application/json
      description: Retrieves all contacts for an account with pagination and optional
        sort
      parameters:
      - description: Account ID
        in: path
        name: id
        required: true
        type: integer
      - default: name
        description: Sort field
        in: query
        name: sort
        type: string
      - default: 1
        description: Page number
        in: query
        name: page
        type: integer
      - default: 25
        description: Items per page
        in: query
        name: page_size
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              $ref: '#/definitions/model.Contact'
            type: array
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: List contacts for an account
      tags:
      - Contacts
    post:
      consumes:
      - application/json
      description: Creates a new contact, optionally auto-creating a ContactInbox
        when inbox_id is provided
      parameters:
      - description: Account ID
        in: path
        name: id
        required: true
        type: integer
      - description: Contact creation payload
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/service.CreateContactRequest'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            $ref: '#/definitions/model.Contact'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Create a new contact
      tags:
      - Contacts
  /api/v1/accounts/{id}/contacts/{contact_id}:
    delete:
      consumes:
      - application/json
      description: Soft-deletes a contact from an account
      parameters:
      - description: Account ID
        in: path
        name: id
        required: true
        type: integer
      - description: Contact ID
        in: path
        name: contact_id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Delete a contact
      tags:
      - Contacts
    get:
      consumes:
      - application/json
      description: Retrieves detailed information about a specific contact within
        an account
      parameters:
      - description: Account ID
        in: path
        name: id
        required: true
        type: integer
      - description: Contact ID
        in: path
        name: contact_id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/model.Contact'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Get a single contact
      tags:
      - Contacts
    put:
      consumes:
      - application/json
      description: Modifies an existing contact's details
      parameters:
      - description: Account ID
        in: path
        name: id
        required: true
        type: integer
      - description: Contact ID
        in: path
        name: contact_id
        required: true
        type: integer
      - description: Contact update payload
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/service.UpdateContactRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/model.Contact'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Update a contact
      tags:
      - Contacts
  /api/v1/accounts/{id}/contacts/search:
    get:
      consumes:
      - application/json
      description: Searches contacts by query string with pagination, sort, and search
        mode support
      parameters:
      - description: Account ID
        in: path
        name: id
        required: true
        type: integer
      - description: Search query
        in: query
        name: q
        required: true
        type: string
      - description: Sort field
        in: query
        name: sort
        type: string
      - default: prefix
        description: Search mode (prefix/semantic/fulltext)
        in: query
        name: search_mode
        type: string
      - default: 1
        description: Page number
        in: query
        name: page
        type: integer
      - default: 25
        description: Items per page
        in: query
        name: page_size
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              $ref: '#/definitions/model.Contact'
            type: array
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Search contacts
      tags:
      - Contacts
  /api/v1/accounts/{id}/inboxes:
    get:
      consumes:
      - application/json
      description: Retrieves all inboxes for an account with pagination
      parameters:
      - description: Account ID
        in: path
        name: id
        required: true
        type: integer
      - default: 1
        description: Page number
        in: query
        name: page
        type: integer
      - default: 25
        description: Items per page
        in: query
        name: page_size
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              $ref: '#/definitions/model.Inbox'
            type: array
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: List inboxes for an account
      tags:
      - Inboxes
    post:
      consumes:
      - application/json
      description: Creates a new inbox for an account
      parameters:
      - description: Account ID
        in: path
        name: id
        required: true
        type: integer
      - description: Inbox creation payload
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/service.CreateInboxRequest'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            $ref: '#/definitions/model.Inbox'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Create a new inbox
      tags:
      - Inboxes
  /api/v1/accounts/{id}/inboxes/{inbox_id}:
    delete:
      consumes:
      - application/json
      description: Deletes an inbox from an account
      parameters:
      - description: Account ID
        in: path
        name: id
        required: true
        type: integer
      - description: Inbox ID
        in: path
        name: inbox_id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Delete an inbox
      tags:
      - Inboxes
    get:
      consumes:
      - application/json
      description: Retrieves detailed information about a specific inbox within an
        account
      parameters:
      - description: Account ID
        in: path
        name: id
        required: true
        type: integer
      - description: Inbox ID
        in: path
        name: inbox_id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/model.Inbox'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Get a single inbox
      tags:
      - Inboxes
    put:
      consumes:
      - application/json
      description: Updates an existing inbox's configuration
      parameters:
      - description: Account ID
        in: path
        name: id
        required: true
        type: integer
      - description: Inbox ID
        in: path
        name: inbox_id
        required: true
        type: integer
      - description: Inbox update payload
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/service.UpdateInboxRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/model.Inbox'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/model.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Update an inbox
      tags:
      - Inboxes
swagger: "2.0"