> ## Documentation index > Fetch the complete documentation index at: https://developer.rhombus.com/llms.txt > Use it to discover all available pages before exploring further. # Search similar object embeddings by text > Search for similar objects by text ```http POST https://api2.rhombussystems.com/api/search/searchSimilarObjectEmbeddingsByText ``` EU organizations send the same request to `https://api2.eu.rhombussystems.com`. ## Authentication and parameters - `x-auth-apikey` (header, required): Your Rhombus API key. Must be accompanied by the `x-auth-scheme` header set to `api-token` (or `partner-api-token` for partner endpoints). - `Authorization` (header): instead of an API key, an OAuth access token (`Bearer `) with the `read` scope. - `x-auth-scheme` (header, string, default: `api-token`): Authentication scheme identifier. Use `api-token` or `partner-api-token` with the `x-auth-apikey` header, `api` or `partner-api` with `x-auth-apikey` plus a client certificate, `api-oauth-token` or `partner-api-oauth-token` with `x-auth-access-token`, and `federated-token` with `x-auth-ft`. A request with `Authorization: Bearer ` and no `x-auth-scheme` is treated as OAuth, and `federated-token` may also be sent as the `x-auth-scheme` and `x-auth-ft` query parameters. One of: `api-token`, `api`, `api-oauth-token`, `federated-token`, `partner-api-token`, `partner-api`, `partner-api-oauth-token`. - `x-auth-org` (header, string): Client organization UUID (22-character RUUID), for partner credentials only. With it the call runs in that client organization with the partner support authority's role. Without it a partner credential runs as the partner organization, which outside the partner endpoints is deprecated (responses carry `Deprecation` and `Sunset: Tue, 05 Jan 2027 00:00:00 GMT`). A malformed value returns 400 `INVALID_AUTH_ORG`; a client organization the partner cannot access returns 403 `PARTNER_CLIENT_ACCESS_DENIED`. ## Request body Content type: `application/json`. Request object for searching similar object embeddings by text. - `includeVector` (boolean | null): Whether to include the embedding vector in the response. - `maxNumResults` (integer | null): Optional number of results to return. Setting to larger numbers will increase latency. - `model` (string, required): Model used for embeddings. The streaming variant of this search accepts only "CHARON". One of: `CLIP_512`, `CHARON`. - `objectTypeFilter` (array | null): 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. - `onlyMatches` (boolean | null): Only applies to models that classify results as matches: when true (default) return only actual matches; when false return all results within the similarity threshold. - `queryDeviceUuids` (array | null> | null): Optional list of device uuids to filter result set on. - `queryEndTimeMs` (integer | null, required): End time in epoch milliseconds. Results returned will have occurred before this time. - `queryStartTimeMs` (integer | null, required): Start time in epoch milliseconds. Results returned will have occurred after this time. - `regionFilter` (array | null> | null> | null): 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. - `searchText` (string | null, required): The search text to find similar objects to. Phrases like "red sedan", "person in yellow shirt", etc. - `similarityThreshold` (number | null): Optional threshold applied to filter returned results, set as a float in [0.0, 1.0]. ## Response 200 OK. Content type: `application/json` - `error` (boolean | null) - `errorCode` (string | null): Stable, machine-readable code for the failure (one of the ApiErrorCode catalog) when error is true. Branch on this, not on errorMsg. - `errorMsg` (string | null) - `moderationReason` (string | null): Reason for moderation if query is not allowed - `queryAllowed` (boolean | null): Whether the query is allowed - `similarEmbeddings` (array | null): List of similar object embedding matches - `warningMsg` (string | null) ## Errors Also 400, 401, 403, 429, 500, 503 with the standard error body (`errorCode`, `errorMsg`): https://developer.rhombus.com/errors ## OpenAPI ````yaml openapi: 3.0.1 info: title: Rhombus API version: "1.0" servers: - description: Production Server url: https://api2.rhombussystems.com security: - ApiKeyAuth: [] paths: /api/search/searchSimilarObjectEmbeddingsByText: post: description: Search for similar objects by text operationId: searchSimilarObjectEmbeddingsByText parameters: - description: "Authentication scheme identifier. Use `api-token` or `partner-api-token` with the `x-auth-apikey` header, `api` or `partner-api` with `x-auth-apikey` plus a client certificate, `api-oauth-token` or `partner-api-oauth-token` with `x-auth-access-token`, and `federated-token` with `x-auth-ft`. A request with `Authorization: Bearer ` and no `x-auth-scheme` is treated as OAuth, and `federated-token` may also be sent as the `x-auth-scheme` and `x-auth-ft` query parameters." example: api-token in: header name: x-auth-scheme required: false schema: default: api-token enum: - api-token - api - api-oauth-token - federated-token - partner-api-token - partner-api - partner-api-oauth-token type: string - description: "Client organization UUID (22-character RUUID), for partner credentials only. With it the call runs in that client organization with the partner support authority's role. Without it a partner credential runs as the partner organization, which outside the partner endpoints is deprecated (responses carry `Deprecation` and `Sunset: Tue, 05 Jan 2027 00:00:00 GMT`). A malformed value returns 400 `INVALID_AUTH_ORG`; a client organization the partner cannot access returns 403 `PARTNER_CLIENT_ACCESS_DENIED`." in: header name: x-auth-org required: false schema: format: RUUID maxLength: 22 minLength: 22 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/Search_SearchSimilarObjectEmbeddingsByTextWSRequest" responses: "200": content: application/json: schema: $ref: "#/components/schemas/Search_SearchSimilarObjectEmbeddingsWSResponse" description: OK "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "429": $ref: "#/components/responses/TooManyRequests" "500": $ref: "#/components/responses/InternalServerError" "503": $ref: "#/components/responses/ServiceUnavailable" security: - ApiKeyAuth: [] - oauth2: - read summary: Search similar object embeddings by text tags: - Search Webservice components: schemas: Search_SearchSimilarObjectEmbeddingsByTextWSRequest: description: Request object for searching similar object embeddings by text. properties: includeVector: default: false description: Whether to include the embedding vector in the response. nullable: true type: boolean maxNumResults: description: Optional number of results to return. Setting to larger numbers will increase latency. format: int32 nullable: true type: integer model: $ref: "#/components/schemas/ObjectSearchModelEnum" objectTypeFilter: 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: enum: - MOTION_HUMAN - MOTION_CAR - AUTO nullable: true type: string nullable: true type: array onlyMatches: description: "Only applies to models that classify results as matches: when true (default) return only actual matches; when false return all results within the similarity threshold." nullable: true type: boolean queryDeviceUuids: description: Optional list of device uuids to filter result set on. items: description: RUUID with optional appended facet information example: AAAAAAAAAAAAAAAAAAAAAA.v0 format: DeviceFacetUuid nullable: true type: string nullable: true type: array queryEndTimeMs: description: End time in epoch milliseconds. Results returned will have occurred before this time. format: int64 nullable: true type: integer queryStartTimeMs: description: Start time in epoch milliseconds. Results returned will have occurred after this time. format: int64 nullable: true type: integer regionFilter: 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: description: Permyriad point [x, y] items: description: Permyriad point [x, y] format: int32 nullable: true type: integer nullable: true type: array nullable: true type: array searchText: description: The search text to find similar objects to. Phrases like "red sedan", "person in yellow shirt", etc. nullable: true type: string similarityThreshold: description: Optional threshold applied to filter returned results, set as a float in [0.0, 1.0]. format: float nullable: true type: number required: - model - queryEndTimeMs - queryStartTimeMs - searchText type: object ObjectSearchModelEnum: description: Model used for embeddings. The streaming variant of this search accepts only "CHARON". enum: - CLIP_512 - CHARON type: string Search_SearchSimilarObjectEmbeddingsWSResponse: description: Response object for searching similar object embeddings. properties: error: nullable: true type: boolean errorCode: description: Stable, machine-readable code for the failure (one of the ApiErrorCode catalog) when error is true. Branch on this, not on errorMsg. nullable: true type: string errorMsg: nullable: true type: string moderationReason: description: Reason for moderation if query is not allowed nullable: true type: string queryAllowed: description: Whether the query is allowed nullable: true type: boolean similarEmbeddings: description: List of similar object embedding matches items: $ref: "#/components/schemas/GenericObjectEmbeddingMatch" nullable: true type: array warningMsg: nullable: true type: string type: object GenericObjectEmbeddingMatch: description: List of similar object embedding matches properties: distance: format: float nullable: true type: number embedding: $ref: "#/components/schemas/GenericObjectEmbedding" matchedEmbeddingId: description: base 64 (url-safe) uuid string example: AAAAAAAAAAAAAAAAAAAAAA format: RUUID nullable: true type: string type: object GenericObjectEmbedding: properties: b: description: bounding box - bottom permyriad format: int32 nullable: true type: integer clipEndMs: format: int64 nullable: true type: integer deviceUuid: description: RUUID with optional appended facet information example: AAAAAAAAAAAAAAAAAAAAAA.v0 format: DeviceFacetUuid nullable: true type: string embedding: items: format: float nullable: true type: number nullable: true type: array embeddingId: nullable: true type: string isMatch: description: 'Match confidence for the query: "YES", "MAYBE", or "NO". Set on CHARON model results; null for CLIP.' nullable: true type: string l: description: bounding box - left permyriad format: int32 nullable: true type: integer locationUuid: description: base 64 (url-safe) uuid string example: AAAAAAAAAAAAAAAAAAAAAA format: RUUID nullable: true type: string model: $ref: "#/components/schemas/ObjectSearchModelEnum" objectId: format: int32 nullable: true type: integer objectType: nullable: true type: string orgUuid: description: base 64 (url-safe) uuid string example: AAAAAAAAAAAAAAAAAAAAAA format: RUUID nullable: true type: string r: description: bounding box - right permyriad format: int32 nullable: true type: integer stableTrackId: format: int32 nullable: true type: integer t: description: bounding box - top permyriad format: int32 nullable: true type: integer thumbnailLocation: nullable: true type: string thumbnailUri: nullable: true type: string timestamp: format: int64 nullable: true type: integer type: object 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 oauth2: description: 'OAuth 2.0 authorization code flow with PKCE (`S256`). Send the access token as `Authorization: Bearer `. Each operation lists the scopes it requires; a token without them is refused 403 with `WWW-Authenticate: Bearer error="insufficient_scope"`.' flows: authorizationCode: authorizationUrl: https://console.rhombus.com/oauth/authorize refreshUrl: https://auth-web.rhombussystems.com/oauth/token scopes: physical: Unlock doors and elevators, lockdown, alarms, speakers and robots read: View cameras, footage and settings write: Change settings and data tokenUrl: https://auth-web.rhombussystems.com/oauth/token type: oauth2 ````