Search

The Search endpoint provides full-text search across all entities in the tenant using PostgreSQL Full-Text Search (FTS). Results are ranked by relevance score and include highlighted matches, making it suitable for building search-as-you-type interfaces and global search features.

The search index is a read-side projection maintained by background workers (search:run). Newly created or updated entities may take a moment to appear in search results.

The search result model

Each search result represents an entity that matched the query, enriched with relevance scoring and highlighted excerpts.

Properties

Name
id
Type
string
Description
Unique identifier of the matched entity (UUID).
Name
family_code
Type
string
Description
The entity family code, such as contact, company, deal, or task.
Name
fields
Type
object
Description
Key-value map of the entity's indexed fields. Contains the field values as stored in the search index, such as { "first_name": "John", "last_name": "Doe", "email": "john@acme.com" }.
Name
score
Type
number
Description
Relevance score computed by PostgreSQL FTS. Higher values indicate a stronger match. Scores are relative and should only be used for ordering, not as absolute values.
Name
highlights
Type
object
Description
Key-value map of fields that matched the query, with the matching portion wrapped in highlights. For example, { "first_name": "John", "email": "john@acme.com" }. Only fields that contributed to the match are included.

GET/core/api/v1/search

Search entities

Perform a full-text search across all indexed entities in the current tenant. Supports filtering by entity family and offset-based pagination. Results are ordered by relevance score (highest first).

The search engine supports:

Full-text matching -- queries are parsed into lexemes and matched against indexed fields using PostgreSQL tsquery.
Family filtering -- restrict results to a single entity family.
Field-specific search -- use field:value syntax in the query to target specific fields, such as email:john@acme.com.
Partial matching -- prefix queries are supported, so joh will match John.

Query parameters

Name
q
Type
string
Description
The search query string. Supports full-text syntax, prefix matching, and field-specific queries (field:value).
Name
family
Type
string
Description
Filter results by entity family code, such as contact, company, deal, or task. When omitted, searches across all families.
Name
page
Type
integer
Description
Page number for offset-based pagination. Defaults to 1.
Name
per_page
Type
integer
Description
Number of results per page. Defaults to 20, maximum 100.

Request

GET

/core/api/v1/search

curl -G https://your-sphere.example.com/core/api/v1/search \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -d q=john \
  -d family=contact \
  -d page=1 \
  -d per_page=20

Response

{
  "data": [
    {
      "id": "c4d5e6f7-a8b9-0123-cdef-456789abcdef",
      "family_code": "contact",
      "fields": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@acme.com",
        "phone": "+33612345678",
        "company": "Acme Corp"
      },
      "score": 0.8721,
      "highlights": {
        "first_name": "John",
        "email": "john.doe@acme.com"
      }
    },
    {
      "id": "d5e6f7a8-b9c0-1234-defa-56789abcdef0",
      "family_code": "contact",
      "fields": {
        "first_name": "Johnny",
        "last_name": "Walker",
        "email": "johnny.walker@beta.com",
        "phone": "+33698765432",
        "company": "Beta Inc"
      },
      "score": 0.6543,
      "highlights": {
        "first_name": "Johnny"
      }
    },
    {
      "id": "e6f7a8b9-c0d1-2345-efab-6789abcdef01",
      "family_code": "contact",
      "fields": {
        "first_name": "Sarah",
        "last_name": "Johnson",
        "email": "s.johnson@gamma.io",
        "phone": "+33611223344",
        "company": "Gamma Ltd"
      },
      "score": 0.4210,
      "highlights": {
        "last_name": "Johnson"
      }
    }
  ],
  "meta": {
    "total": 3,
    "page": 1,
    "per_page": 20
  }
}

GET/core/api/v1/search

Search across all families

When the family parameter is omitted, search runs across all entity families in the tenant. Results from different families are interleaved by relevance score, allowing you to build a unified global search experience.

The family_code field on each result tells you which family the entity belongs to, so you can render results differently based on type.

Request

GET

/core/api/v1/search

curl -G https://your-sphere.example.com/core/api/v1/search \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -d q=acme \
  -d per_page=10

Response

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "family_code": "company",
      "fields": {
        "name": "Acme Corp",
        "industry": "Technology",
        "website": "https://acme.com"
      },
      "score": 0.9512,
      "highlights": {
        "name": "Acme Corp"
      }
    },
    {
      "id": "c4d5e6f7-a8b9-0123-cdef-456789abcdef",
      "family_code": "contact",
      "fields": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@acme.com",
        "company": "Acme Corp"
      },
      "score": 0.7234,
      "highlights": {
        "email": "john.doe@acme.com",
        "company": "Acme Corp"
      }
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "family_code": "deal",
      "fields": {
        "title": "Acme Enterprise License",
        "value": 45000,
        "stage": "negotiation"
      },
      "score": 0.6891,
      "highlights": {
        "title": "Acme Enterprise License"
      }
    }
  ],
  "meta": {
    "total": 3,
    "page": 1,
    "per_page": 10
  }
}

GET/core/api/v1/search

Field-specific search

Use the field:value syntax in the q parameter to restrict the search to a specific field. This is useful when you know which attribute you are looking for, such as searching by email address or phone number.

Multiple field queries can be combined in a single search string, for example email:john company:acme.

Request

GET

/core/api/v1/search

curl -G https://your-sphere.example.com/core/api/v1/search \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  --data-urlencode 'q=email:john@acme.com' \
  -d family=contact

Response

{
  "data": [
    {
      "id": "c4d5e6f7-a8b9-0123-cdef-456789abcdef",
      "family_code": "contact",
      "fields": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@acme.com",
        "phone": "+33612345678",
        "company": "Acme Corp"
      },
      "score": 0.9876,
      "highlights": {
        "email": "john.doe@acme.com"
      }
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 20
  }
}