/api/v1/suggest

Auto-suggest / autocomplete. Given the user's current input, returns candidate completions either as token frequencies (tokens) or as per-field value matches (fields), plus optionally the full linked-object descriptors for picker UIs (linked_objects). Backed by the search index — the same language settings apply.

Read-only: the request runs in a read transaction; nothing is written. Requires an authenticated user. Suggestions are limited to what that user may see: fields and linked_objects come only from records the user may read, tokens only from the mask and pool combinations of the user's best-mask filter.

GET /suggest — Auto-suggest with the request encoded in the URL.

Auto-suggest with the request encoded in the URL.

get

Identical semantics to POST /suggest; the JSON request is passed verbatim as the BODY query parameter. Useful for front ends that prefer not to send a GET body.

The query parameter name is BODY (uppercase) — the handler reads r.URL.Query().Get("BODY") case-sensitively, so a lowercase body=... is not picked up; an absent or empty BODY then fails JSON parsing and returns a 400.

Authorizations

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Query parameters

BODYstring · jsonRequired

JSON-encoded SuggestRequest. See the request schema on POST /suggest for the field set.

Responses

200

Suggestion envelope.

application/json

Auto-suggest response — returned by GET /api/v1/suggest and POST /api/v1/suggest. Carries diagnostic timing info plus a suggestions envelope with the three optional result sets the request opted into.

es_timeinteger · int64Optional

Time the search index spent on the request, in milliseconds. Excludes fylr-side serialisation overhead.

timed_outbooleanOptional

True if the request reached the per-request timeout. Partial results may still be present in suggestions.

400

Malformed request — invalid JSON in BODY, an objecttype in objecttypes or linked_objecttypes that does not exist, an unresolvable entry in fields, or an unknown tokens_mode (the latter only rejects when token suggestions run, i.e. unless tokens is false). All return ServerGeneric / 400.

application/json

401

No authenticated user. The request must carry a valid access token.

application/json

{
  "suggestions": {
    "tokens": [
      {
        "suggest": "<b>fahr</b>bar",
        "tokens": [
          "fahrbar"
        ],
        "count": 1
      },
      {
        "suggest": "<b>fahr</b>rad",
        "tokens": [
          "fahrrad"
        ],
        "count": 1
      }
    ],
    "fields": [
      {
        "field": "fahrrad",
        "suggest": "<b>fahrrad</b>",
        "count": 1,
        "_system_object_id": [
          100
        ]
      },
      {
        "field": "fahrbar",
        "suggest": "<b>fahrbar</b>",
        "count": 1,
        "_system_object_id": [
          101
        ]
      }
    ],
    "linked_objects": [
      {
        "_standard": {
          "1": {
            "text": {
              "de-DE": "henk 18"
            }
          }
        }
      }
    ]
  }
}

POST /suggest — Auto-suggest with the request as a JSON body.

Auto-suggest with the request as a JSON body.

post

Authorizations

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Body

Auto-suggest request — accepted as the JSON request body of POST /api/v1/suggest, and as the value of the BODY query parameter on GET /api/v1/suggest. Drives token and / or field completion through the search index.

Each result kind is opted into independently: token suggestions (tokens, on by default unless tokens is false), per-field value matches (fields_suggest: true, which also needs a non-empty fields), and linked-object descriptors (a non-null linked_objecttypes).

querystringOptional

The user's current input. Optional; defaults to the empty string. Tokenised (whitespace-split) unless tokens_dont_split_query is set. The last token is treated as the partial term to complete.

tokens_dont_split_querybooleanOptional

If true, the query is sent verbatim — the engine does not split it on whitespace. Useful when the input is a multi-word phrase that should match as a single token.

Default: false

tokensboolean · nullableOptional

If true, null, or omitted, return token completions in suggestions.tokens. Set to false to suppress them. Independent of fields_suggest.

fieldsstring[]Optional

Field paths whose values should be considered as completion candidates. Each entry is a fully-qualified field name (e.g. picture.title, _tags.tag.name). Must be non-empty to get any per-field suggestions: combining fields_suggest: true with an empty fields yields no suggestions.fields (it is a silent no-op, not an error).

fields_suggestbooleanOptional

If true, also return per-field completions in suggestions.fields — one entry per matching value, with the list of system-object ids that hold it.

Default: false

objecttypesstring[]Optional

Restrict suggestions to objects of these objecttypes. Empty / omitted means no restriction.

pool_idsinteger · int64[]Optional

Restrict suggestions to objects in exactly these pools — there is no automatic sub-pool inclusion. Empty / omitted means no restriction.

languagesstring[]Optional

Restrict token / field matching to these language-tagged sub-fields (e.g. de-DE, en-US). Empty means consider all languages enabled on the instance.

linked_objecttypesstring[] · nullableOptional

If set, the engine also returns linked_objects — full ObjectApi entries of the named objecttypes that match the query. By default every match is returned, referenced or not; set linked_objects_referenced_by_objecttypes to keep only the ones actually in use. Useful for autocomplete pickers that need to show the target object inline.

linked_objects_referenced_by_objecttypesstring[] · nullableOptional

Opt-in filter for linked_objects. When set, a linked-object suggestion is kept only if at least one record of these objecttypes links to it (directly, nested or reverse — the _linked.<ot>._id closure the "in" filter queries when a suggestion is clicked), so selecting the suggestion as a search filter over these objecttypes always yields results. Absent / empty returns every match. Pass the objecttypes the caller will actually filter on click — kept separate from objecttypes on purpose, since objecttypes may be widened with the linked objecttypes so token matches inside linked objects are found.

analyze_wildcardsbooleanOptional

If true, the query string is interpreted as a wildcard pattern (* and ?) rather than a prefix. Applies to token suggestions only; the field and linked-object searches ignore it.

Default: false

tokens_modestring · enumOptional

Token-matching mode. One of:

• `` (empty) / ngram — substring match (default).
• edgengram — prefix match.
• exact — exact-term match.

Any other value is rejected with a 400.

Possible values:

timeoutintegerOptional

Per-request timeout in milliseconds passed through to the search index. Zero / omitted uses the indexer's default.

limitintegerOptional

Maximum number of suggestions to return (per kind). Defaults to 10 when unset or zero.

Default: 10

Responses

200

Suggestion envelope.

application/json

Auto-suggest response — returned by GET /api/v1/suggest and POST /api/v1/suggest. Carries diagnostic timing info plus a suggestions envelope with the three optional result sets the request opted into.

es_timeinteger · int64Optional

Time the search index spent on the request, in milliseconds. Excludes fylr-side serialisation overhead.

timed_outbooleanOptional

True if the request reached the per-request timeout. Partial results may still be present in suggestions.

400

Malformed request — invalid JSON in the request body, an objecttype in objecttypes or linked_objecttypes that does not exist, an unresolvable entry in fields, or an unknown tokens_mode (the latter only rejects when token suggestions run, i.e. unless tokens is false). All return ServerGeneric / 400.

application/json

401

No authenticated user. The request must carry a valid access token.

application/json

{
  "suggestions": {
    "tokens": [
      {
        "suggest": "<b>fahr</b>bar",
        "tokens": [
          "fahrbar"
        ],
        "count": 1
      },
      {
        "suggest": "<b>fahr</b>rad",
        "tokens": [
          "fahrrad"
        ],
        "count": 1
      }
    ],
    "fields": [
      {
        "field": "fahrrad",
        "suggest": "<b>fahrrad</b>",
        "count": 1,
        "_system_object_id": [
          100
        ]
      },
      {
        "field": "fahrbar",
        "suggest": "<b>fahrbar</b>",
        "count": 1,
        "_system_object_id": [
          101
        ]
      }
    ],
    "linked_objects": [
      {
        "_standard": {
          "1": {
            "text": {
              "de-DE": "henk 18"
            }
          }
        }
      }
    ]
  }
}