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

# Search similar object embeddings by text

> Search for similar objects by text



## OpenAPI

````yaml https://api2.rhombussystems.com/api/openapi/public.json post /api/search/searchSimilarObjectEmbeddingsByText
openapi: 3.0.1
info:
  contact:
    email: developer@rhombussystems.com
  description: >-
    This API is for use by Rhombus customers and partners.


    ## Authentication


    All requests require two headers:

    - `x-auth-scheme` — The authentication scheme identifier. Use `api-token`
    for standard API key auth, or `partner-api-token` for partner API auth.

    - `x-auth-apikey` — Your Rhombus API key.


    Example:

    ```

    POST /api/camera/getMinimalCameraStateList

    x-auth-scheme: api-token

    x-auth-apikey: YOUR_API_KEY

    Content-Type: application/json

    ```
  title: Rhombus API
  version: '1.0'
servers:
  - description: Production Server
    url: https://api2.rhombussystems.com
security:
  - ApiKeyAuth: []
paths:
  /api/search/searchSimilarObjectEmbeddingsByText:
    post:
      tags:
        - Search Webservice
      summary: Search similar object embeddings by text
      description: Search for similar objects by text
      operationId: searchSimilarObjectEmbeddingsByText
      parameters:
        - description: >-
            Authentication scheme identifier. Use `api-token` for standard API
            key authentication, `partner-api-token` for partner API key
            authentication. Must be paired with the `x-auth-apikey` header
            containing your API key.
          example: api-token
          in: header
          name: x-auth-scheme
          required: true
          schema:
            type: string
            default: api-token
            enum:
              - api-token
              - api
              - partner-api-token
              - partner-api
      requestBody:
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/Search_SearchSimilarObjectEmbeddingsByTextWSRequest
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/Search_SearchSimilarObjectEmbeddingsWSResponse
          description: OK
components:
  schemas:
    Search_SearchSimilarObjectEmbeddingsByTextWSRequest:
      type: object
      description: Request object for searching similar object embeddings by text.
      properties:
        includeVector:
          type: boolean
          default: false
          description: Whether to include the embedding vector in the response.
          nullable: true
        maxNumResults:
          type: integer
          format: int32
          description: >-
            Optional number of results to return. Setting to larger numbers will
            increase latency.
          nullable: true
        model:
          $ref: '#/components/schemas/ObjectSearchModelEnum'
        objectTypeFilter:
          type: array
          description: >-
            Optional object type filter. Provide explicit type values to narrow
            results, or omit to search all object types. Pass the single value
            "AUTO" to have the server infer the object type (humans or vehicles)
            from the search text.
          items:
            type: string
            enum:
              - MOTION_HUMAN
              - MOTION_CAR
              - AUTO
            nullable: true
          nullable: true
        queryDeviceUuids:
          type: array
          description: Optional list of device uuids to filter result set on.
          items:
            type: string
            format: DeviceFacetUuid
            description: RUUID with optional appended facet information
            example: AAAAAAAAAAAAAAAAAAAAAA.v0
            nullable: true
          nullable: true
        queryEndTimeMs:
          type: integer
          format: int64
          description: >-
            End time in epoch milliseconds. Results returned will have occurred
            before this time.
          nullable: true
        queryStartTimeMs:
          type: integer
          format: int64
          description: >-
            Start time in epoch milliseconds. Results returned will have
            occurred after this time.
          nullable: true
        regionFilter:
          type: array
          description: >-
            Optional region filter to return results only if they overlap with
            the supplied region. This is a list of perymyriad points defining a
            polygon. The first and last elements must be the same to make a
            connected polygon. For example, a triangle should have 4 points
            defined in this list.
          items:
            type: array
            description: Permyriad point [x, y]
            items:
              type: integer
              format: int32
              description: Permyriad point [x, y]
              nullable: true
            nullable: true
          nullable: true
        searchText:
          type: string
          description: >-
            The search text to find similar objects to. Phrases like "red
            sedan", "person in yellow shirt", etc.
          nullable: true
        similarityThreshold:
          type: number
          format: float
          description: >-
            Optional threshold applied to filter returned results, set as a
            float in [0.0, 1.0].
          nullable: true
      required:
        - model
        - queryEndTimeMs
        - queryStartTimeMs
        - searchText
    Search_SearchSimilarObjectEmbeddingsWSResponse:
      type: object
      description: Response object for searching similar object embeddings.
      properties:
        error:
          type: boolean
          nullable: true
        errorMsg:
          type: string
          nullable: true
        moderationReason:
          type: string
          description: Reason for moderation if query is not allowed
          nullable: true
        queryAllowed:
          type: boolean
          description: Whether the query is allowed
          nullable: true
        similarEmbeddings:
          type: array
          description: List of similar object embedding matches
          items:
            $ref: '#/components/schemas/GenericObjectEmbeddingMatch'
          nullable: true
        warningMsg:
          type: string
          nullable: true
    ObjectSearchModelEnum:
      type: string
      description: Object search model to use for embeddings
      enum:
        - CLIP_512
        - UNKNOWN
        - REIDENTIFICATION_NET
        - PERSON_VIT
        - PERSON_VITS
        - CLIP_REID
        - DINOV3
        - SWIN_BASE
        - SWIN_SMALL
        - PERSON_VIT_SHADOW
        - CHARON
    GenericObjectEmbeddingMatch:
      type: object
      description: List of similar object embedding matches
      properties:
        distance:
          type: number
          format: float
          nullable: true
        embedding:
          $ref: '#/components/schemas/GenericObjectEmbedding'
        matchedEmbeddingId:
          type: string
          format: RUUID
          description: base 64 (url-safe) uuid string
          example: AAAAAAAAAAAAAAAAAAAAAA
          nullable: true
    GenericObjectEmbedding:
      type: object
      properties:
        b:
          type: integer
          format: int32
          description: bounding box - bottom permyriad
          nullable: true
        deviceUuid:
          type: string
          format: DeviceFacetUuid
          description: RUUID with optional appended facet information
          example: AAAAAAAAAAAAAAAAAAAAAA.v0
          nullable: true
        embedding:
          type: array
          items:
            type: number
            format: float
            nullable: true
          nullable: true
        embeddingId:
          type: string
          nullable: true
        l:
          type: integer
          format: int32
          description: bounding box - left permyriad
          nullable: true
        locationUuid:
          type: string
          format: RUUID
          description: base 64 (url-safe) uuid string
          example: AAAAAAAAAAAAAAAAAAAAAA
          nullable: true
        model:
          $ref: '#/components/schemas/ObjectSearchModelEnum'
        objectId:
          type: integer
          format: int32
          nullable: true
        objectType:
          type: string
          nullable: true
        orgUuid:
          type: string
          format: RUUID
          description: base 64 (url-safe) uuid string
          example: AAAAAAAAAAAAAAAAAAAAAA
          nullable: true
        r:
          type: integer
          format: int32
          description: bounding box - right permyriad
          nullable: true
        stableTrackId:
          type: integer
          format: int32
          nullable: true
        t:
          type: integer
          format: int32
          description: bounding box - top permyriad
          nullable: true
        thumbnailLocation:
          type: string
          nullable: true
        thumbnailUri:
          type: string
          nullable: true
        timestamp:
          type: integer
          format: int64
          nullable: true
  securitySchemes:
    ApiKeyAuth:
      description: >-
        Your Rhombus API key. Must be accompanied by the `x-auth-scheme` header
        set to `api-token` (or `partner-api-token` for partner endpoints).
      in: header
      name: x-auth-apikey
      type: apiKey

````