Sorting

By default the engine chooses the order: relevance when there is a query to be relevant to, a quality ranking when there is not. sort replaces that with an explicit ordering of up to three clauses, strongest key first:

{
  "query": "payment companies",
  "category": "company",
  "sort": [
    { "field": "employee_count", "direction": "desc" },
    { "field": "founded_year", "direction": "asc" }
  ]
}

Three rules, each a 422 if broken:

• sort needs an explicit category. Auto-classification picks the category, so there would be nothing to validate the fields against.
• A field may appear only once.
• The field has to be one this category accepts.

Ask GET /v1/sorts/{category} for that list, with labels and default directions, rather than hard-coding one. Note the applies_to split: a person-axis field on a company search is refused.

Two fields don't sort the way their values read:

• seniority (people) orders by the seniority ladder, most senior first by default, not alphabetically.
• global_presence (companies) orders by the number of countries a company employs people in, most countries first by default.

resolved_search.sort echoes the sort that was applied: yours, or one the engine inferred from the question when you didn't send sort (for example, "top fintechs by revenue"). It is [] when the engine chose the order itself.