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

# Search cases

> Search support cases using AI-powered recommendation. You can provide a search query, a conversationId to load ticket content, or both.
At least one of query or conversationId must be provided. When both are provided, the ticket content is combined with the query for a richer search.




## OpenAPI

````yaml /api-reference/openapi.json post /v1/search/cases
openapi: 3.0.3
info:
  title: IrisAgent's API Reference
  description: >
    IrisAgent service can be used as an API to power intelligent conversations
    and search, index, and connect with your internal and external knowledge
    articles, tickets, community forums, product documentation,

    and other informational content.
  version: 1.2.0
servers:
  - url: https://api1.irisagent.com
security:
  - bearerAuth: []
paths:
  /v1/search/cases:
    post:
      summary: Search cases
      description: >
        Search support cases using AI-powered recommendation. You can provide a
        search query, a conversationId to load ticket content, or both.

        At least one of query or conversationId must be provided. When both are
        provided, the ticket content is combined with the query for a richer
        search.
      operationId: searchCases
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CasesSearchRequest'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CasesSearchResponse'
        '400':
          description: Bad request - invalid input
        '401':
          description: Unauthorized - invalid credentials
        '403':
          description: Forbidden - insufficient permissions
        '404':
          description: Conversation not found - the specified conversationId does not exist
components:
  schemas:
    CasesSearchRequest:
      type: object
      properties:
        query:
          description: |
            The search query string. Optional if conversationId is provided.
          type: string
        conversationId:
          description: >
            Unique ticket or case ID to load the full ticket content (subject,
            description, and comments) for searching.

            Optional if query is provided. The ticket content will be loaded
            from the database and used as the search query.

            Note: The case with this conversationId will be excluded from the
            search results.
          type: string
        productId:
          description: >
            Product ID to filter cases. To filter across multiple products, pass
            a

            comma-separated list (e.g. "prod-a,prod-b"); results are searched
            per

            product and merged. Whitespace around commas is trimmed.
          type: string
        formId:
          description: The form ID to filter cases.
          type: string
        sourceBrandId:
          description: The source brand ID to filter cases.
          type: string
        filterUrls:
          description: >
            Array of case URLs to exclude from the search results. Cases with
            URLs matching any of these URLs will be filtered out.
          type: array
          items:
            type: string
            format: uri
        numResults:
          description: >
            (Legacy) Maximum number of results to return. Defaults to 4 if not
            specified.

            Prefer using offset and limit parameters for pagination.
          type: integer
          default: 4
          maximum: 100
          minimum: 1
        offset:
          description: >
            Number of results to skip for pagination. Used with limit parameter.

            If offset or limit is provided, pagination mode is used and
            numResults is ignored.
          type: integer
          format: uint
          default: 0
          minimum: 0
        limit:
          description: >
            Maximum number of results to return per page. Defaults to 25 in
            pagination mode.

            If offset or limit is provided, pagination mode is used and
            numResults is ignored.

            Note: offset + limit cannot exceed 200 due to external API
            constraints.
          type: integer
          format: uint
          default: 25
          maximum: 100
          minimum: 1
    CasesSearchResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/SearchCase'
      required:
        - results
    SearchCase:
      type: object
      properties:
        id:
          description: Unique identifier for the case
          type: string
        subject:
          description: Subject of the case
          type: string
        url:
          description: Public link to the case
          type: string
          format: uri
        timeOfCreation:
          description: Unix timestamp epoch in milli-seconds as string
          type: integer
          format: int64
          example: 17437722600
        productId:
          description: Product ID associated with the case, if applicable
          type: string
        score:
          description: >-
            Similarity score for the case, computed using Manhattan distance. A
            lower score indicates greater similarity.
          type: number
          format: float
      required:
        - id
        - subject
        - url
        - timeOfCreation
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        The `Authorization` header is required to authenticate API requests.
        It should contain a bearer token obtained through the IrisAgent portal.

````