Search

Authentication: API Key

Search in Flux API is a powerful tool for executing complex queries with filtering, full-text search, joining data across folders, and populating related resources. The search method is available through the _search endpoint and supports a wide range of operations to get exactly the data you need.

URL Structure

Search is performed via POST request to the special _search endpoint:

URL Pattern

POST https://<ENVIRONMENT_KEY>.fxns.io/<API_PREFIX>/<PATH>/_search

Examples:

POST https://7c9h4pwu.fxns.io/blog/articles/_search
POST https://7c9h4pwu.fxns.io/ecommerce/products/DPX5noSHSDku/reviews/_search
POST https://7c9h4pwu.fxns.io/content/pages/_search

API Structure Setup

The URL structure corresponds to your folder hierarchy and API configuration:

Create folders using the Folder API to organize your content
Connect folders to your Flux API using the Connection method to make them accessible

The <PATH> in the URL directly maps to your folder structure. For example:

Folder path blog/articles → Endpoint /blog/articles/_search
Nested folder ecommerce/products/reviews → Endpoint /ecommerce/products/reviews/_search

Request Parameters

All search parameters are passed in the POST request body in JSON format, except for pagination and some specific parameters that go in the query string.

Query Parameters

Name
component
Type
string
Description
Component key (required for composite folders when using field-based filters)
Name
fallback_locales
Type
boolean
Default
default:false
Description
Whether to use fallback locales when translation is missing
Name
search_locale
Type
string
Default
default:null
Description
Locale for performing search and sorting. If not specified, uses the default locale configured in the environment.
Name
return_locales
Type
string
Default
default:null
Description
Comma-separated list of locales to return in response (e.g., "en,fr,es"). If not specified, returns all locales configured in the environment.
Name
populate
Type
string
Default
default:null
Description
Comma-separated list of field paths for automatic population of related resources (e.g., "author,category" or "author.company,category.parent"). Use dot notation for nested population.
Name
limit
Type
integer
Default
default:50
Description
Maximum number of results (maximum 50)
Name
next
Type
string
Description
Cursor for getting next page results
Name
previous
Type
string
Description
Cursor for getting previous page results

Body Parameters

Name
where
Type
object
Default
default:{}
Description
Filter conditions with logical operators all_of and any_of
Name
find_text
Type
object
Default
default:null
Description
Full-text search with field specification and typo tolerance
Name
find_phrase
Type
object
Default
default:null
Description
Exact phrase search in specified fields
Name
sort
Type
array
Default
default:null
Description
Array of fields for sorting (supports - for descending order)
Name
join
Type
object
Default
default:{}
Description
Object for joining data from different folders
Name
ignore_unknown_fields
Type
boolean
Default
default:false
Description
Whether to ignore unknown fields in where conditions. If set to false and unknown field is passed, returns error unknown_field (422 status code).

Filtering with WHERE

The where parameter allows creating complex filter conditions using logical operators.

Logical Operators

Name
all_of
Type
array
Description
All conditions must be met (logical AND)
Name
any_of
Type
array
Description
Any of the conditions must be met (logical OR)

Comparison Operators

Operator	Description	Example
`eq`	Equal to	`{"title__eq": "Hello"}`
`ieq`	Equal to (case-insensitive)	`{"title__ieq": "hello"}`
`gt`	Greater than	`{"price__gt": 100}`
`gte`	Greater than or equal	`{"rating__gte": 4.5}`
`lt`	Less than	`{"created_at__lt": "2024-01-01"}`
`lte`	Less than or equal	`{"expires_at__lte": "2024-12-31"}`
`in`	Value in list	`{"category__in": ["tech", "news"]}`
`iin`	Value in list (case-insensitive)	`{"status__iin": ["Active", "PENDING"]}`
`null`	Value is null	`{"description__null": true}`
`exists`	Field exists	`{"description__exists": true}`
`contains`	Contains substring	`{"title__contains": "API"}`
`icontains`	Contains substring (case-insensitive)	`{"title__icontains": "api"}`
`startswith`	Starts with	`{"name__startswith": "John"}`
`istartswith`	Starts with (case-insensitive)	`{"name__istartswith": "john"}`
`endswith`	Ends with	`{"email__endswith": "@gmail.com"}`
`iendswith`	Ends with (case-insensitive)	`{"email__iendswith": "@GMAIL.COM"}`
`between`	Between values	`{"price__between": [50, 200]}`
`includes`	Includes value	`{"tags__includes": "ai"}`
`iincludes`	Includes value (case-insensitive)	`{"tags__iincludes": "AI"}`

Negation with NOT Operators

All operators support negation by prefixing them with not_. This creates the logical NOT condition for any operator.

Operator	Negation	Description
`not_eq`	`{"title__not_eq": "Hello"}`	Not equal to
`not_ieq`	`{"title__not_ieq": "hello"}`	Not equal to (case-insensitive)
`not_gt`	`{"price__not_gt": 100}`	Not greater than (less than or equal)
`not_gte`	`{"rating__not_gte": 4.5}`	Not greater than or equal (less than)
`not_lt`	`{"created_at__not_lt": "2024-01-01"}`	Not less than (greater than or equal)
`not_lte`	`{"expires_at__not_lte": "2024-12-31"}`	Not less than or equal (greater than)
`not_in`	`{"category__not_in": ["tech", "news"]}`	Value not in list
`not_iin`	`{"status__not_iin": ["Active", "PENDING"]}`	Value not in list (case-insensitive)
`not_null`	`{"description__not_null": true}`	Value is not null
`not_exists`	`{"description__not_exists": true}`	Field does not exist
`not_contains`	`{"title__not_contains": "API"}`	Does not contain substring
`not_icontains`	`{"title__not_icontains": "api"}`	Does not contain substring (case-insensitive)
`not_startswith`	`{"name__not_startswith": "John"}`	Does not start with
`not_istartswith`	`{"name__not_istartswith": "john"}`	Does not start with (case-insensitive)
`not_endswith`	`{"email__not_endswith": "@gmail.com"}`	Does not end with
`not_iendswith`	`{"email__not_iendswith": "@GMAIL.COM"}`	Does not end with (case-insensitive)
`not_between`	`{"price__not_between": [50, 200]}`	Not between values
`not_includes`	`{"tags__not_includes": "ai"}`	Does not include value
`not_iincludes`	`{"tags__not_iincludes": "AI"}`	Does not include value (case-insensitive)

Simple Conditions

Filtering by a single condition.

Body

{
  "where": {
    "$": {
      "all_of": [
        {"status__eq": "published"}
      ]
    }
  }
}

Complex Conditions

Combining multiple conditions with logical operators.

Body

{
  "where": {
    "$": {
      "all_of": [
        {"status__eq": "published"},
        {
          "any_of": [
            {"category__eq": "technology"},
            {"featured__eq": true}
          ]
        },
        {"rating__gte": 4.0}
      ]
    }
  }
}

Case-Insensitive Search

Using case-insensitive operators for flexible matching.

Body

{
  "where": {
    "$": {
      "all_of": [
        {"title__icontains": "api"},
        {"status__iin": ["Published", "ACTIVE"]},
        {"author__istartswith": "john"}
      ]
    }
  }
}

Negation (NOT) Conditions

Using NOT operators to exclude certain values or conditions.

Body

{
  "where": {
    "$": {
      "all_of": [
        {"status__not_eq": "draft"},
        {"category__not_in": ["spam", "deleted"]},
        {"description__not_null": true},
        {"title__not_contains": "outdated"}
      ]
    }
  }
}

System Fields Filtering

You can filter by system fields using the _sys object. This allows filtering by resource metadata like key, creation date, update date, etc.

Body

{
  "where": {
    "$": {
      "all_of": [
        {"_sys.key__eq": "dw2qC5qRwxuZ"},
        {"_sys.created_at__gte": "2024-01-01T00:00:00Z"},
        {"_sys.updated_at__lt": "2024-12-31T23:59:59Z"}
      ]
    }
  }
}

Full-Text Search

Flux API supports two types of full-text search: find_text and find_phrase.

You can specify particular fields to search in, or leave the fields array empty to search across all text-searchable fields in your content.

Important: You cannot use find_text and find_phrase simultaneously in the same request.

Text Search

Search with typo tolerance in titles and content.

Body

{
  "find_text": {
    "query": "artificial intelligence",
    "fields": ["title", "content", "description"],
    "max_typos": 2
  }
}

Phrase Search

Search for exact phrase in specified fields.

Body

{
  "find_phrase": {
    "query": "machine learning algorithms",
    "fields": ["title", "content"]
  }
}

Joins Between Folders

One of the most powerful features of Flux API is performing joins between data from different folders. Joins allow you to combine data from multiple folders in a single query, similar to SQL JOIN operations.

Understanding Joins

Joins in Flux API work by connecting related data across different folders through reference fields. When you perform a join, you're essentially telling the API: "Get me data from folder A, but also include related data from folder B where field X in folder A matches field Y in folder B."

Key Concepts:

Main Folder ($): The primary folder you're searching in, represented by the $ symbol
Joined Folders: Additional folders that contain related data you want to include
Aliases: Short names you assign to folders to reference them in the query (defined in the as object)
Relations: The connections between folders, specifying how they relate to each other
Join Types:
- inner - Only returns records that have matching data in both folders
- left - Returns all records from the main folder, with related data when available

Join Structure

Every join query requires two main components:

as object: Maps aliases to actual folder names
- Must always include $ for the main folder
- Must contain at least one additional folder besides $
- Folder paths: Use dot notation to specify folder paths, same as in URL structure
  - Example: "authors": "catalog.authors.writers" refers to folder accessible at /catalog/authors/writers
  - The API prefix is omitted, only the folder path after the API prefix is specified
relations array: Defines how folders connect to each other
- Each relation specifies source, target, join type, and the connecting field

Filtering in Joins

When using joins, you can apply filters to any of the joined folders. In the where clause, use the folder aliases (not the actual folder names) to specify which folder the filter applies to.

Join Limitations:

Joins are only available for "collection" type folders
Cannot perform joins on "composite" type folders
All folders participating in join must be connected to the API
The as object must contain at least one folder besides "$"
All relations must reference folders defined in the as object
See API Limits for maximum number of folders and other constraints

Step-by-Step Join Example

Let's break down a simple join between articles and their authors:

Scenario: Get all published articles along with their author information, but only include authors who are currently active.

Step 1: Define folder aliases in as

$ represents the main folder (articles)
authors is an alias for the catalog.authors folder (used only for convenience in the query)

Step 2: Define the relationship

Source: $ (articles folder)
Target: authors (authors folder alias)
Connection: author field in articles references authors
Join type: left (include articles even if author is missing)

Step 3: Apply filters

Filter articles: status = "published"
Filter authors: status = "active" (using the alias authors in where conditions)

Step 4: Response structure

Joined data appears as author (using the actual field name, not the alias)

Body

{
  "join": {
    "as": {
      "authors": "catalog.authors"
    },
    "relations": [
      {
        "source": "$",
        "target": "authors",
        "relation_type": "left",
        "source_field": "author"
      }
    ]
  },
  "where": {
    "$": {
      "all_of": [
        {"status__eq": "published"}
      ]
    },
    "authors": {
      "all_of": [
        {"status__eq": "active"}
      ]
    }
  }
}

Response Structure

{
  "limit": 50,
  "next": null,
  "previous": null,
  "results": [
    {
      "_sys": {
        "key": "dw2qC5qRwxuZ",
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z",
        "folder": "aooxoscltikj",
        "relevance": 2.0
      },
      "data": {
        "title": "Introduction to AI",
        "status": "published",
        "content": "This article explores artificial intelligence...",
        "author": {
          "_sys": {
            "key": "mK8pL2nRvXwQ",
            "created_at": "2024-01-10T08:00:00Z",
            "updated_at": "2024-01-10T08:00:00Z",
            "folder": "bppxptdmujlk",
            "relevance": 1.0
          },
          "data": {
            "name": "John Smith",
            "status": "active",
            "email": "john@example.com"
          }
        }
      }
    }
  ]
}

Folder Path Examples

Understanding Folder Paths in Joins

Folder paths in the as object use dot notation that mirrors the URL structure of your API endpoints.

Examples of folder path mapping:

"users" → /users endpoint
"catalog.products" → /catalog/products endpoint
"content.blog.posts" → /content/blog/posts endpoint
"ecommerce.inventory.items" → /ecommerce/inventory/items endpoint

The API prefix (like https://7c9h4pwu.fxns.io/api/v1) is automatically handled - you only specify the folder path portion.

Body

{
  "join": {
    "as": {
      "authors": "users.authors",
      "categories": "content.categories",
      "tags": "content.blog.tags"
    },
    "relations": [
      {
        "source": "$",
        "target": "authors",
        "relation_type": "inner",
        "source_field": "author"
      },
      {
        "source": "$",
        "target": "categories",
        "relation_type": "left",
        "source_field": "category"
      }
    ]
  },
  "where": {
    "$": {
      "all_of": [
        {"status__eq": "published"}
      ]
    },
    "categories": {
      "all_of": [
        {"active__eq": true}
      ]
    }
  }
}

Aliases vs Response Fields

Important distinction: Aliases are used only for convenience in queries, but response fields use actual schema field names.

Scenario:

Schema has field writer that references catalog.users.authors
Schema has field category that references content.categories
We use short aliases in the query for convenience

Query uses aliases, Response uses actual field names

Body

{
  "join": {
    "as": {
      "author_info": "catalog.users.authors",
      "cat_info": "content.categories"
    },
    "relations": [
      {
        "source": "$",
        "target": "author_info",
        "relation_type": "left",
        "source_field": "writer"
      },
      {
        "source": "$",
        "target": "cat_info",
        "relation_type": "left",
        "source_field": "category"
      }
    ]
  },
  "where": {
    "author_info": {
      "all_of": [
        {"verified__eq": true}
      ]
    }
  }
}

Response Structure

{
  "limit": 50,
  "next": null,
  "previous": null,
  "results": [
    {
      "_sys": { "key": "post123", "..." },
      "data": {
        "title": "My Blog Post",
        "writer": "author456",
        "category": "cat789"
      },
      "writer": {
        "_sys": { "key": "author456", "..." },
        "data": { "name": "John Doe", "verified": true }
      },
      "category": {
        "_sys": { "key": "cat789", "..." },
        "data": { "name": "Technology" }
      }
    }
  ]
}

Multi-Folder Join

Scenario: Get products with their category and manufacturer information.

This example demonstrates:

Inner join with categories (only products that have a category)
Left join with manufacturers (include products even without manufacturer)
Multiple filters applied to different joined folders

Key Points:

inner join means products without a category won't appear in results
left join means products without a manufacturer will still appear
Each folder can have its own where conditions
Aliases (categories, manufacturers) are used only in the query for convenience
Response will contain category and manufacturer

Body

{
  "join": {
    "as": {
      "categories": "categories",
      "manufacturers": "manufacturers"
    },
    "relations": [
      {
        "source": "$",
        "target": "categories",
        "relation_type": "inner",
        "source_field": "category"
      },
      {
        "source": "$",
        "target": "manufacturers",
        "relation_type": "left",
        "source_field": "manufacturer"
      }
    ]
  },
  "where": {
    "$": {
      "all_of": [
        {"price__gte": 100},
        {"in_stock__eq": true}
      ]
    },
    "categories": {
      "all_of": [
        {"active__eq": true},
        {"name__not_eq": "deprecated"}
      ]
    },
    "manufacturers": {
      "all_of": [
        {"country__eq": "Germany"},
        {"verified__eq": true}
      ]
    }
  }
}

Chain Joins

Advanced Scenario: Join articles → authors → companies

This demonstrates chaining joins where:

Articles are joined with authors
Authors are then joined with their companies

Important: When chaining joins, the source field references the previous join result using the alias.

Body

{
  "join": {
    "as": {
      "authors": "authors",
      "companies": "companies"
    },
    "relations": [
      {
        "source": "$",
        "target": "authors",
        "relation_type": "inner",
        "source_field": "author"
      },
      {
        "source": "authors",
        "target": "companies",
        "relation_type": "left",
        "source_field": "company"
      }
    ]
  },
  "where": {
    "$": {
      "all_of": [
        {"status__eq": "published"}
      ]
    },
    "companies": {
      "all_of": [
        {"type__eq": "technology"},
        {"employees__gte": 100}
      ]
    }
  }
}

Join Best Practices

1. Choose the Right Join Type

Use inner when you only want records that have matching data in both folders
Use left when you want all records from the main folder, regardless of matches

2. Optimize Performance

Apply filters to reduce the dataset size before joining
Use specific field filters rather than broad text searches when possible
Consider the order of joins - start with the most restrictive filters

3. Folder Path Specification

Use dot notation for nested folder paths: "catalog.products.electronics"
Path corresponds directly to URL structure: catalog.products.electronics → /catalog/products/electronics
API prefix is automatically handled - only specify the folder path portion
Ensure all referenced folders are accessible through the same Flux API instance

Population

Population automatically loads related resources, replacing references with full objects. The populate parameter is passed as a query parameter.

Population paths can use dot notation (e.g., "company.employees")
Only populates by reference fields
Multiple fields are comma-separated in query string (e.g., "author,category.books")
See API Limits for maximum population depth and other constraints

Basic Population

Automatic loading of related data using query parameters.

Request

curl -X POST "https://7c9h4pwu.fxns.io/articles/_search?populate=author,category" \
  -H "Authorization: Simple <public_key>:<private_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "where": {
      "$": {
        "all_of": [
          {"status__eq": "published"}
        ]
      }
    }
  }'

Response with Population

{
  "limit": 50,
  "next": null,
  "previous": null,
  "results": [
    {
      "_sys": {
        "key": "dw2qC5qRwxuZ",
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z",
        "folder": "aooxoscltikj",
        "relevance": 2.0
      },
      "data": {
        "title": "Introduction to AI",
        "content": "This comprehensive guide covers...",
        "status": "published",
        "author": {
          "_sys": {
            "key": "mK8pL2nRvXwQ",
            "created_at": "2024-01-10T08:00:00Z",
            "updated_at": "2024-01-10T08:00:00Z",
            "folder": "bppxptdmujlk"
          },
          "data": {
            "name": "John Smith",
            "email": "john@example.com",
            "bio": "AI researcher and writer"
          }
        },
        "category": {
          "_sys": {
            "key": "fR9sT5kPqBmN",
            "created_at": "2024-01-05T12:00:00Z",
            "updated_at": "2024-01-05T12:00:00Z",
            "folder": "cqqxrsdnvjml"
          },
          "data": {
            "name": "Technology",
            "description": "Technology articles",
            "slug": "technology"
          }
        }
      }
    }
  ]
}

Deep Population

Population with multiple nesting levels using dot notation.

Request

curl -X POST "https://7c9h4pwu.fxns.io/articles/_search?populate=author.company,category.parent_category" \
  -H "Authorization: Simple <public_key>:<private_key>" \
  -H "Content-Type: application/json" \
  -d '{}'

Sorting

Sort results by one or multiple fields.

Sorting Examples

Sort by one or multiple fields with ascending or descending order.

Use - prefix for descending sort order.

Body

{
  "sort": ["-_sys.created_at"]
}

Localization

Flux API supports multilingual content with a flexible localization system. All localization parameters are passed as query parameters.

Name
search_locale
Type
string
Default
default:null
Description
Query Parameter: Locale for performing search and sorting. If not specified, uses the default locale configured in the environment.
Name
return_locales
Type
string
Default
default:null
Description
Query Parameter: Comma-separated list of locales to return in response (e.g., "en,fr,es"). If not specified, returns all locales configured in the environment.
Name
fallback_locales
Type
boolean
Default
default:false
Description
Query Parameter: Whether to use fallback locale when translation is missing

Localized Search

Search in French with multiple locale return using query parameters.

Request

curl -X POST "https://7c9h4pwu.fxns.io/articles/_search?search_locale=fr&return_locales=fr,en&fallback_locales=true" \
  -H "Authorization: Simple <public_key>:<private_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "find_text": {
      "query": "intelligence artificielle",
      "fields": ["title", "content"]
    }
  }'

Localized Response

{
  "results": [
    {
      "key": "bH7mN3kRpQwT",
      "title": {
        "fr": "Introduction à l'IA",
        "en": "Introduction to AI"
      },
      "content": {
        "fr": "Article sur l'intelligence artificielle...",
        "en": "Article about artificial intelligence..."
      }
    }
  ]
}

Composite Folders

When working with composite folders, additional considerations apply.

Component Requirement

For composite folders, you must specify a component when using field-based filters.

Body

{
  "where": {
    "$": {
      "all_of": [
        {"status__eq": "published"}
      ]
    }
  }
}

Query String: ?component=d7nfrzhi7xtw

Response Format

All search requests return a standardized response with pagination and structured data.

Name
limit
Type
integer
Description
Maximum number of results per page
Name
next
Type
string|null
Description
Cursor for getting next page
Name
previous
Type
string|null
Description
Cursor for getting previous page
Name
results
Type
array
Description
Array of found resources, each containing sys and data objects

Result Object Structure

Each result in the results array has the following structure:

Name
_sys
Type
object
Description
System information about the resource
Name
data
Type
object
Description
The actual content data of the resource (your custom fields). When joins are used, reference fields are replaced with full joined objects containing their own _sys and data structure.

Example Response

Basic search response showing the standard structure.

Search Response

{
  "limit": 3,
  "next": "eyJjcmVhdGVkX2F0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoiLCJfa2V5IjoiYXJ0aWNsZV8xMjMifQ==",
  "previous": null,
  "results": [
    {
      "_sys": {
        "key": "0zvrciuyec2k",
        "created_at": "2024-06-16T20:34:48.952000",
        "updated_at": "2024-06-16T20:34:48.952000",
        "folder": "aooxoscltikj",
        "relevance": 2.0
      },
      "data": {
        "title": "Getting Started with AI",
        "status": "published",
        "author": "john_doe"
      }
    },
    {
      "_sys": {
        "key": "kxRZYFMnukau",
        "created_at": "2024-06-16T20:57:35.322000",
        "updated_at": "2024-06-16T20:57:35.322000",
        "folder": "aooxoscltikj",
        "relevance": 1.8
      },
      "data": {
        "title": "Advanced Machine Learning",
        "status": "published",
        "author": "jane_smith"
      }
    },
    {
      "_sys": {
        "key": "YRZSdMR2JJyM",
        "created_at": "2024-06-17T13:00:39.757000",
        "updated_at": "2024-06-17T13:00:39.757000",
        "folder": "aooxoscltikj",
        "relevance": 1.5
      },
      "data": {
        "title": "Data Science Fundamentals",
        "status": "published",
        "author": "bob_wilson",
        "tags": ["data", "science", "analytics"]
      }
    }
  ]
}

Error Handling

Common Errors

Name
400 Bad Request
Description
Invalid request parameters
- invalid_json - incorrect JSON in request body
- validation_error - parameter validation error
Name
401 Unauthorized
Description
Authentication issues
- authentication_failed - invalid or missing credentials
Name
403 Forbidden
Description
Insufficient permissions
- permission_denied - insufficient permissions to perform operation
Name
404 Not Found
Description
Resource not found
- folder_not_found - specified folder does not exist
- route_not_found - invalid endpoint URL or path not found in API routing
Name
405 Method Not Allowed
Description
Operation not allowed for this folder
- action_not_allowed - the folder does not have permission for the requested operation (search requires get_many permission)
Name
422 Unprocessable Entity
Description
Business logic errors
- failed_join - error executing join
- unknown_locale - specified locale not supported
- missed_component - component not specified for composite folder
- component_not_found - specified component does not exist
- unknown_field - unknown field in where conditions (when ignore_unknown_fields is false)
- too_many_join_folders - more than 3 folders specified in join operation
Name
429 Too Many Requests
Description
Rate limiting
- rate_limit_exceeded - too many requests sent in a given time period
Name
500 Internal Server Error
Description
Server errors
- internal_server_error - an unexpected error occurred on the server

Error Examples

Method Not Allowed (405)

{
  "message": "Action not allowed",
  "error_code": "action_not_allowed",
  "detail": null
}

Route Not Found (404)

{
  "message": "Route not found",
  "error_code": "route_not_found",
  "detail": null
}

Validation Error (422)

{
  "message": "Invalid data was provided",
  "error_code": "validation_error",
  "detail": [
    {
      "field": "where.$.all_of.0.status__eq",
      "message": "Invalid type",
      "details": "This field is required"
    }
  ]
}

Too Many Join Folders (422)

{
  "message": "Too many folders in join",
  "error_code": "too_many_join_folders",
  "detail": null
}

Complete Example

Comprehensive Search Query

Example request demonstrating all major search capabilities with proper parameter placement.

Request

curl -X POST "https://7c9h4pwu.fxns.io/articles/_search?search_locale=en&return_locales=en,fr&fallback_locales=true&populate=author,category&limit=20" \
  -H "Authorization: Simple <public_key>:<private_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "where": {
      "$": {
        "all_of": [
          {"status__eq": "published"},
          {"rating__gte": 4.0},
          {"title__icontains": "machine"},
          {"category__not_in": ["spam", "outdated"]},
          {"description__not_null": true}
        ]
      },
      "authors": {
        "all_of": [
          {"verified__eq": true},
          {"name__istartswith": "dr"},
          {"status__not_eq": "suspended"}
        ]
      }
    },
    "find_text": {
      "query": "machine learning",
      "fields": ["title", "content", "tags"],
      "max_typos": 1
    },
    "join": {
      "as": {
        "authors": "authors",
        "categories": "categories"
      },
      "relations": [
        {
          "source": "$",
          "target": "authors",
          "relation_type": "inner",
          "source_field": "author"
        },
        {
          "source": "$",
          "target": "categories",
          "relation_type": "left",
          "source_field": "category"
        }
      ]
    },
    "sort": ["-published_at", "title"]
  }'

Response

{
  "limit": 20,
  "next": "eyJjcmVhdGVkX2F0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoiLCJfa2V5IjoiYXJ0aWNsZV8xMjMifQ==",
  "previous": null,
  "results": [
    {
      "_sys": {
        "key": "hG9tL4nRmXwP",
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z",
        "folder": "articles",
        "relevance": 2.0
      },
      "data": {
        "title": "Advanced Machine Learning Techniques",
        "status": "published",
        "content": "This article explores...",
        "rating": 4.8,
        "published_at": "2024-01-15T10:30:00Z",
        "author": {
          "_sys": {
            "key": "kM8pL2nRvXwQ",
            "created_at": "2024-01-10T08:00:00Z",
            "updated_at": "2024-01-10T08:00:00Z",
            "folder": "authors",
            "relevance": 1.0
          },
          "data": {
            "name": "Dr. John Smith",
            "verified": true
          }
        },
        "category": {
          "_sys": {
            "key": "fR9sT5kPqBmN",
            "created_at": "2024-01-15T10:30:00Z",
            "updated_at": "2024-01-15T10:30:00Z",
            "folder": "categories",
            "relevance": 1.0
          },
          "data": {
            "name": "Technology",
            "description": "Technology articles"
          }
        }
      }
    }
  ]
}

Performance Tips

Query Optimization

Use exact filters - prefer eq, in over contains where possible
Limit populate fields - only load necessary related data
Set reasonable limits - don't request more data than needed
Use pagination - use next/previous cursors for large datasets
Minimize joins - each join operation increases response time
Limit population depth - each population level adds processing time

For detailed information about API limits and constraints, see the Limits guide.