> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

> Block IP addresses or CIDR ranges, IPv4 or IPv6, optionally with expires_in_hours. Applies to web widget traffic — email and WhatsApp carry no visitor IP.

# Block IP addresses



## OpenAPI

````yaml post /blocklist/ips
openapi: 3.1.0
info:
  title: OpenCX API
  description: >

    OpenCX is an AI-powered, all-in-one platform for customer support and
    outbound communications.


    Use this API to manage your OpenCX organization's AI agents, actions,
    conversations, contacts, and more.


    To get started, generate a new API key from the dashboard.


    ## Authentication

    All API endpoints require authentication using a Bearer token. You can
    generate an API key from your OpenCX dashboard.


    ## Rate Limiting

    API requests are rate limited to ensure fair usage. The current limits are:

    - 100 requests per minute for standard endpoints

    - 1000 requests per minute for streaming endpoints


    ## Error Handling

    The API uses standard HTTP status codes and returns detailed error messages
    in the response body.
  version: 1.0-beta
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: http://localhost:8080
    description: Development
  - url: https://api.open.cx
    description: Production
security:
  - bearerAuth: []
paths:
  /blocklist/ips:
    post:
      summary: Block IP addresses
      description: >-
        Block one or more IP addresses or CIDR ranges. Pass a comma-separated
        string for multiple values (e.g. "203.0.113.7, 198.51.100.0/24"). Both
        IPv4 and IPv6 are supported. Applies to web widget traffic: email and
        WhatsApp reach us through the provider’s servers and carry no visitor
        IP, so block those by domain or contact instead. A session first seen on
        the widget from a blocked address does stay blocked if it later
        continues on another channel.
      operationId: blockIps
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlockIpsInputDto'
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockIpsOutput'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
components:
  schemas:
    BlockIpsInputDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/BlockIpsInputDtoInput'
      type: object
      properties:
        ips:
          type: string
          minLength: 1
          description: >-
            IP(s) or CIDR range(s) to block — comma-separated for multiple (e.g.
            "203.0.113.7, 198.51.100.0/24")
        reason:
          description: Why these addresses are being blocked
          type: string
        expires_in_hours:
          description: >-
            Lift the block automatically after this many hours (max 8760). Omit
            for a permanent block. Automated callers should always set this: a
            shared or carrier-grade NAT address fronts many people, and a
            permanent block on one bans all of them.
          type: integer
          exclusiveMinimum: 0
          maximum: 8760
      required:
        - ips
    BlockIpsOutput:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/BlockIpsOutput'
      type: object
      properties:
        blocked:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Block record ID
              ip_address:
                type: string
                description: >-
                  The blocked address — a single IP (203.0.113.7) or a CIDR
                  range (203.0.113.0/24)
              reason:
                anyOf:
                  - type: string
                  - type: 'null'
                description: Why the address was blocked
              created_at:
                type: string
                format: date-time
              expires_at:
                anyOf:
                  - type: string
                    format: date-time
                  - type: 'null'
                description: When the block lifts automatically. Null means it never does.
            required:
              - id
              - ip_address
              - reason
              - created_at
              - expires_at
            additionalProperties: false
          description: Addresses that were successfully blocked
        skipped:
          type: array
          items:
            type: string
          description: >-
            Addresses that needed no action — already blocked, or not a valid
            IP/CIDR
        failed:
          type: array
          items:
            type: object
            properties:
              ip:
                type: string
              error:
                type: string
            required:
              - ip
              - error
            additionalProperties: false
          description: Addresses that could NOT be blocked — these are still unblocked
        summary:
          type: object
          properties:
            total:
              type: number
            blocked:
              type: number
            skipped:
              type: number
            failed:
              type: number
          required:
            - total
            - blocked
            - skipped
            - failed
          additionalProperties: false
      required:
        - blocked
        - skipped
        - failed
        - summary
      additionalProperties: false
    ErrorDto:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        error:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````