Find Record records semantically similar to a text query, scoped to one space.

​

Returns the top-N records from a single space whose embedded text fields are * closest to the query (cosine similarity, descending). Pre-filtering via filter or * segment_id runs BEFORE vector ranking so the candidate base is the same as an * equivalent GET /record?filter=... listing.

Query Parameters
  • space_id
    Type: integer
    min:  
    1
    required

    Tenant scope. Rows from other spaces are excluded. The acting user must have read access. The custom module the records belong to is derived from space.custom_module_id — the caller does not pass it.

  • query
    Type: string
    min length:  
    1
    max length:  
    4000
    required

    Free-text query to embed and rank against. Max 4000 characters to keep the URL within Apache/NGINX default 8 KB limits.

  • limit
    Type: integer
    min:  
    1

    Maximum records to return. Defaults to 20. No hard upper cap at the API layer.

  • filter
    Type: string

    Filter expression in the same syntax as GET /record?filter=.... Resolves to a candidate-record set via FilterManager before vector ranking. Mutually exclusive with segment_id.

  • segment_id
    Type: integer
    min:  
    1

    ID of a saved segment whose filter to apply. Mutually exclusive with filter. Segment must belong to module custom-module-item.

  • min_similarity
    Type: number Format: float
    min:  
    0
    max:  
    1

    Cosine similarity floor in [0, 1]. Records whose best embedding is below this similarity are dropped at SQL level (HAVING).

Responses
  • application/json
  • 400

    Validation error (missing required param, segment/filter mutual exclusion, invalid threshold range, space/module mismatch, …).

  • 401

    Not authenticated.

  • 403

    User lacks read access to the requested space.

  • 405

    Method not GET.

  • 502

    Embedding provider call failed (logged; client may retry).

Request Example for get/record/vector/similar
curl 'https://test.boost.space/api/record/vector/similar?space_id=123&query=software%20company%20focused%20on%20automation' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "results": [
    {
      "recordId": 12345,
      "similarity": 0.94,
      "record": {
        "id": 42,
        "created": "2026-01-15T09:30:00Z",
        "createdUserId": 42,
        "statusSystemId": 42,
        "statusId": 42,
        "spaceId": 42,
        "featuredImageId": 42,
        "files": [
          1
        ],
        "labels": [
          1
        ],
        "boostId": "string",
        "customFieldsValues": [
          {
            "id": 42,
            "created": "2026-01-15T09:30:00Z",
            "valueWysiwyg": "string",
            "valueInt": 1,
            "valueFloat": 1.5,
            "valueDatetime": "2026-01-15T09:30:00Z",
            "valueModule": "string",
            "value": "string",
            "fileId": 42,
            "customFieldInputId": 42,
            "module": "activities",
            "table": "string",
            "entityId": 42,
            "customFieldInputName": "Sample customFieldInputName",
            "selected": true,
            "ipAddress": "string",
            "translatable": true,
            "translations": {
              "en": {
                "field1": "translation1",
                "field2": "translation2"
              },
              "it": {
                "field1": "translation1",
                "field2": "translation2"
              },
              "cs": {
                "field1": "translation1",
                "field2": "translation2"
              }
            }
          }
        ]
      }
    }
  ],
  "totalCandidates": 8000,
  "queryTimeMs": 38
}

Ranked records.