Search

Method: POST /{api_prefix}/{folder_path}/_search Auth: Flux API Key

_search is the most flexible Flux endpoint. Use it when you need structured filters, joins across folders, population, localization, full-text search, or semantic vector search in a single request.

URL Pattern

POST https://{environment_key}.fxns.io/{api_prefix}/{folder_path}/_search

Example: POST https://7c9h4pwu.fxns.io/blog/articles/_search

Make sure the folder path is connected to your Flux API through Connect Folder to API.

Query Parameters

These parameters live in the query string alongside the POST body.

Request Body

Filtering with where

Use where to combine AND/OR logic:

{
  "where": {
    "$": {
      "all_of": [
        {"status__eq": "published"},
        {
          "any_of": [
            {"category__in": ["tech", "science"]},
            {"tags__includes": "ml"}
          ]
        }
      ]
    }
  }
}

Supported operators:

Prefix any operator with not_ to negate it (e.g., {"status__not_in": ["archived", "deleted"]}).

Per-Field Locale Override

By default, filters on localized fields use the search_locale parameter. You can override the locale for a specific field by appending [locale] to the field name:

{
  "where": {
    "$": {
      "all_of": [
        {"title[fr]__eq": "Bonjour"},
        {"description[de]__icontains": "hallo"}
      ]
    }
  }
}

This is useful when you need to filter on multiple locales in the same query or when the filter locale differs from the search/sort locale.

Text & Phrase Search

find_text

"find_text": {
  "query": "machine learning",
  "fields": ["title", "summary"],
  "threshold": 0.85
}

• query is required (1–1000 characters).
• fields is optional; omit it to search all text-searchable fields.
• threshold ranges from 0 to 1 (defaults to 1.0). Lower values behave like typo tolerance.

find_phrase

"find_phrase": {
  "query": "artificial intelligence",
  "fields": ["title"]
}

Phrase search looks for exact matches. Do not include find_text in the same request.

Vector Search Modes

Set search_mode to unlock semantic search:

vector_search

"vector_search": {
  "query": "modern living room inspiration",
  "fields": ["body"],
  "top_k": 50,
  "similarity_threshold": 0.5
}

query is required (min length 3). top_k ≤ 100 (default 10). fields and similarity_threshold are optional (default 0.4).

Boost & Hybrid Settings

• vector_boost_config: { "boost_factor": 1.2, "similarity_threshold": 0.8, "max_boost_results": 20 }
• hybrid_config: { "vector_weight": 0.6, "text_weight": 0.4, "rerank_results": true }

Flux calculates embeddings behind the scenes and includes metadata in the response when vector modes are active. For a full walkthrough (prerequisites, examples, best practices), see the Vector Search guide.

vector_field_search

If you manage your own embeddings, use vector_field_search instead of vector_search to query a vector field directly:

"vector_field_search": {
  "field": "custom_embedding",
  "query_vector": [0.012, -0.034, 0.056, ...],
  "top_k": 20,
  "similarity_threshold": 0.6
}

This sends your own embedding vector and compares it against stored vectors using cosine similarity. Cannot be combined with vector_search or search_mode="hybrid". See Vector Field Search for details.

Sorting

Provide an array of fields or a comma-separated string.

"sort": ["-_sys.created_at", "title"]

Sorting respects search_locale for localized strings.

Joins

join lets you enrich the primary folder (the collection in your _search URL) with up to three additional collections. Think of it as instructing Flux how to look up related records during the SQL query.

"join": {
  "as": {
    "articles": "blog.articles",
    "authors": "people.authors",
    "companies": "orgs.companies"
  },
  "relations": [
    {
      "source": "articles",
      "target": "authors",
      "relation_type": "inner",
      "source_field": "author"
    },
    {
      "source": "authors",
      "target": "companies",
      "relation_type": "left",
      "source_field": "company"
    }
  ]
}

1. Map folder aliases

• Add every collection you want to use inside join.as.
• The primary folder (the one you’re querying) is implicitly $; you do not add it to join.as.

2. Describe relationships

3. Filter joined folders

You can add alias-specific filters inside where. Use the alias name (with or without $) as a key at the top level:

"where": {
  "$": {
    "all_of": [{"status__eq": "published"}]
  },
  "authors": {
    "all_of": [{"country__eq": "FR"}]
  }
}

Flux applies the root filters to the primary folder and the alias filters to the joined folder before assembling the result set.

Constraints & validation

• Maximum joined folders (excluding the primary folder): 3. Exceeding this returns too_many_join_folders.
• Joined folders must be collections; composite folders are not supported in joins.
• Every alias referenced in relations or alias-specific filters must be declared in join.as.
• If a folder path cannot be resolved, Flux returns failed_join (check the detail.route value).
• Joined data follows the same localization and population rules as the primary folder (e.g., populated references still count toward the response-size limit).

Population & Localization

Population

• Pass populate=field1,field2.nested in the query string to replace reference/relation IDs with their full documents.
• Use dot notation to walk nested references (e.g., author.company).
• Flux follows references up to three levels deep. Exceeding this depth silently stops population for deeper paths.
• Population increases response size; heavy use may trigger max_response_size_exceeded.

Example:

POST https://7c9h4pwu.fxns.io/blog/articles/_search?populate=author.company,category.parent

{
  "_sys": {...},
  "data": {
    "title": "Introduction to AI",
    "author": {
      "_sys": {...},
      "data": {
        "name": "John Smith",
        "company": {
          "_sys": {...},
          "data": {"name": "Tech Corp"}
        }
      }
    }
  }
}

Localization

• search_locale controls which locale Flux uses for sorting, text search, and case-insensitive comparisons. If omitted, Flux uses the environment default.
• return_locales limits the locales returned in data. Provide a comma-separated list (return_locales=en,fr).
• fallback_locales=true tells Flux to pull translations from the fallback chain when a requested locale is missing. If no fallback exists, the field is returned as null.
• These parameters apply to both the root resources and any populated documents.

Example:

POST https://7c9h4pwu.fxns.io/blog/articles/_search?return_locales=en,fr&fallback_locales=true

{
  "_sys": {...},
  "data": {
    "title": {
      "en": "Introduction to AI",
      "fr": "Introduction à l'IA"
    },
    "summary": {
      "en": "Guide to AI...",
      "fr": "Guide de l'IA..."
    }
  }
}

Pagination

Flux uses cursor-based pagination for _search. Each response returns fully qualified next/previous URLs that already include the cursor token and any query parameters you supplied (e.g., populate, return_locales).

{
  "limit": 50,
  "next": "https://7c9h4pwu.fxns.io/blog/articles/_search?limit=50&next=eyJjcmVh...NDJ9",
  "previous": null,
  "results": [...]
}

Usage tips:

1. First page – Omit next/previous.
2. Next page – Call the next URL as-is with the same headers/body.
3. Previous page – Call the previous URL if it’s not null.
4. Cursor exclusivity – Only one of next or previous can be provided per request; violating this returns 422 invalid_request.
5. Limit overrides – Body limit overrides the query limit. Both are clamped to 100.

For code samples in multiple languages, see the dedicated Pagination guide.

Response Schema

Errors

For additional error payloads, see Flux Errors.

Complete Example

POST https://7c9h4pwu.fxns.io/blog/articles/_search?populate=author&return_locales=en,fr&fallback_locales=true
Authorization: Secure <access_key>:<signature>
Content-Type: application/json

{
  "where": {
    "$": {
      "all_of": [
        {"status__eq": "published"},
        {"published_at__gte": "2024-01-01"}
      ]
    }
  },
  "find_text": {
    "query": "machine learning",
    "fields": ["title", "summary"],
    "threshold": 0.85
  },
  "sort": ["-_sys.created_at"],
  "limit": 25,
  "ignore_unknown_fields": false
}

{
  "limit": 25,
  "next": "https://7c9h4pwu.fxns.io/blog/articles/_search?limit=25&next=eyJjcmVh...MjV9",
  "previous": null,
  "results": [
    {
      "_sys": {
        "key": "hG9tL4nRmXwP",
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z",
        "folder": "blog_articles"
      },
      "data": {
        "title": {
          "en": "Advanced Machine Learning Techniques",
          "fr": "Techniques avancées d'apprentissage automatique"
        },
        "status": "published",
        "author": {
          "_sys": {...},
          "data": {"name": "Dr. John Smith"}
        }
      }
    }
  ],
  "metadata": {
    "search_mode": "text",
    "limit": 25,
    "text_threshold": 0.85
  }
}