List Resources

Authentication: API Key

The List Resources endpoint allows you to retrieve multiple resources from a folder using GET requests with query parameters. This method supports filtering, full-text search, sorting, population, and pagination for efficient data retrieval.

URL Structure

List resources via GET request to the folder endpoint:

URL Pattern

GET https://<ENVIRONMENT_KEY>.fxns.io/<API_PREFIX>/<PATH>

Examples:

GET https://7c9h4pwu.fxns.io/blog/articles
GET https://7c9h4pwu.fxns.io/catalog/kM8pL2nRvXwQ/items
GET https://7c9h4pwu.fxns.io/public/catalogs/DPX5noSHSDku/items

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
Nested folder ecommerce/products → Endpoint /ecommerce/products

Query Parameters

All parameters are passed as query parameters in the URL.

Pagination Parameters

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

Localization Parameters

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
fallback_locales
Type
boolean
Default
default:false
Description
Whether to use fallback locales when translation is missing

Data Enhancement Parameters

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
sort
Type
string
Default
default:null
Description
Comma-separated list of fields for sorting (supports - for descending order, e.g., "-_sys.created_at,title")

Filtering Parameters

Name
where__<field>__<operator>
Type
string
Description
Field-based filtering using comparison operators (e.g., where__status__eq=published)
Name
find_text__query
Type
string
Description
Full-text search query (1-1000 characters)
Name
find_text__fields
Type
string
Description
Comma-separated list of fields to search in for text search
Name
find_text__max_typos
Type
integer
Default
default:0
Description
Maximum number of typos allowed in text search (0-2)
Name
find_phrase__query
Type
string
Description
Exact phrase search query (1-1000 characters)
Name
find_phrase__fields
Type
string
Description
Comma-separated list of fields to search in for phrase search

Advanced Parameters

Name
component
Type
string
Description
Component key (required for composite folders when using field-based filters)
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).

Basic Listing

Simple Resource Listing

Get all resources from a folder with default settings.

Request

curl -X GET "https://7c9h4pwu.fxns.io/public/articles" \
  -H "Authorization: Simple <public_key>:<private_key>"

Response

{
  "limit": 50,
  "next": "eyJjcmVhdGVkX2F0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoiLCJfa2V5IjoiYXJ0aWNsZV8xMCJ9",
  "previous": null,
  "results": [
    {
      "_sys": {
        "key": "dw2qC5qRwxuZ",
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z",
        "folder": "aooxoscltikj"
      },
      "data": {
        "title": "First Article",
        "status": "published",
        "content": "Article content..."
      }
    }
  ]
}

Filtering Resources

Filter resources using the where__<field>__<operator> parameter format.

Comparison Operators

Operator	Description	Example
`eq`	Equal to	`where__title__eq=Hello`
`ieq`	Equal to (case-insensitive)	`where__title__ieq=hello`
`gt`	Greater than	`where__price__gt=100`
`gte`	Greater than or equal	`where__rating__gte=4.5`
`lt`	Less than	`where__created_at__lt=2024-01-01`
`lte`	Less than or equal	`where__expires_at__lte=2024-12-31`
`in`	Value in list	`where__category__in=tech,news`
`iin`	Value in list (case-insensitive)	`where__status__iin=Active,PENDING`
`null`	Value is null	`where__description__null=true`
`exists`	Field exists	`where__description__exists=true`
`contains`	Contains substring	`where__title__contains=API`
`icontains`	Contains substring (case-insensitive)	`where__title__icontains=api`
`startswith`	Starts with	`where__name__startswith=John`
`istartswith`	Starts with (case-insensitive)	`where__name__istartswith=john`
`endswith`	Ends with	`where__email__endswith=@gmail.com`
`iendswith`	Ends with (case-insensitive)	`where__email__iendswith=@GMAIL.COM`
`between`	Between values	`where__price__between=50,200`
`includes`	Includes value	`where__tags__includes=ai`
`iincludes`	Includes value (case-insensitive)	`where__tags__iincludes=AI`

Negation with NOT Operators

All operators support negation by prefixing them with not_:

Operator	Example	Description
`not_eq`	`where__title__not_eq=Hello`	Not equal to
`not_ieq`	`where__title__not_ieq=hello`	Not equal to (case-insensitive)
`not_gt`	`where__price__not_gt=100`	Not greater than (less than or equal)
`not_gte`	`where__rating__not_gte=4.5`	Not greater than or equal (less than)
`not_lt`	`where__created_at__not_lt=2024-01-01`	Not less than (greater than or equal)
`not_lte`	`where__expires_at__not_lte=2024-12-31`	Not less than or equal (greater than)
`not_in`	`where__category__not_in=spam,deleted`	Value not in list
`not_iin`	`where__status__not_iin=Active,PENDING`	Value not in list (case-insensitive)
`not_null`	`where__description__not_null=true`	Value is not null
`not_exists`	`where__description__not_exists=true`	Field does not exist
`not_contains`	`where__title__not_contains=API`	Does not contain substring
`not_icontains`	`where__title__not_icontains=api`	Does not contain substring (case-insensitive)
`not_startswith`	`where__name__not_startswith=John`	Does not start with
`not_istartswith`	`where__name__not_istartswith=john`	Does not start with (case-insensitive)
`not_endswith`	`where__email__not_endswith=@gmail.com`	Does not end with
`not_iendswith`	`where__email__not_iendswith=@GMAIL.COM`	Does not end with (case-insensitive)
`not_between`	`where__price__not_between=50,200`	Not between values
`not_includes`	`where__tags__not_includes=ai`	Does not include value
`not_iincludes`	`where__tags__not_iincludes=AI`	Does not include value (case-insensitive)

Simple Filtering

Filter resources by a single condition.

Request

GET https://7c9h4pwu.fxns.io/public/articles?where__status__eq=published

Multiple Filters

Combine multiple filter conditions. Multiple values for the same field create OR conditions, while different fields create AND conditions.

Request

GET https://7c9h4pwu.fxns.io/public/articles?where__status__eq=published&where__category__in=tech,science&where__rating__gte=4.0

Full-Text Search

Search within text content using the find_text_* or find_phrase_* parameters.

Parameter Combination: To perform full-text search, you need to combine:

Query parameter: find_text__query or find_phrase__query (required)
Fields parameter: find_text__fields or find_phrase__fields (optional)
Typo tolerance: find_text__max_typos (optional, only for text search)

Important: You cannot use find_text_* and find_phrase_* simultaneously in the same request.

Text Search

Search across specified fields with optional typo tolerance. The find_text__fields parameter is optional - if not provided or empty, searches across all text-searchable fields.

Request

GET https://7c9h4pwu.fxns.io/articles?find_text__query=artificial%20intelligence&find_text__fields=title,content

Phrase Search

Search for exact phrases in specified fields. The find_phrase__fields parameter is optional - if not provided or empty, searches across all text-searchable fields.

Request

GET https://7c9h4pwu.fxns.io/articles?find_phrase__query=machine%20learning%20algorithms&find_phrase__fields=title,content

Parameter Requirements

Name
find_text__query
Type
string
Required
required
Description
Text search query (1-1000 characters). Required for text search.
Name
find_text__fields
Type
string
Description
Comma-separated list of fields to search in. Optional - if empty or not provided, searches all text-searchable fields.
Name
find_text__max_typos
Type
integer
Default
default:0
Description
Maximum number of typos allowed (0-2). Optional - only available for text search, not phrase search.
Name
find_phrase__query
Type
string
Required
required
Description
Exact phrase search query (1-1000 characters). Required for phrase search.
Name
find_phrase__fields
Type
string
Description
Comma-separated list of fields to search in. Optional - if empty or not provided, searches all text-searchable fields.

Sorting Resources

Sort results using the sort parameter with comma-separated field names.

Sorting Examples

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

Use - prefix for descending sort order.

Request

curl -X GET "https://7c9h4pwu.fxns.io/public/articles?sort=-_sys.created_at" \
  -H "Authorization: Simple <public_key>:<private_key>"

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 GET "https://7c9h4pwu.fxns.io/public/articles?populate=author,category" \
  -H "Authorization: Simple <public_key>:<private_key>"

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"
      },
      "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"
          }
        }
      }
    }
  ]
}

Localization

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

Localized Listing

List resources in French with multiple locale return using query parameters.

Request

curl -X GET "https://7c9h4pwu.fxns.io/public/articles?search_locale=fr&return_locales=fr,en&fallback_locales=true" \
  -H "Authorization: Simple <public_key>:<private_key>"

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..."
      }
    }
  ]
}

Pagination

List Resources uses the same cursor-based pagination as the Search API. See the Pagination guide for detailed information.

Pagination Example

Navigate through pages using cursor-based pagination.

Request

curl -X GET "https://7c9h4pwu.fxns.io/public/articles?limit=10" \
  -H "Authorization: Simple <public_key>:<private_key>"

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.

Request

curl -X GET "https://7c9h4pwu.fxns.io/public/composite-folder?component=d7nfrzhi7xtw&where__status__eq=published" \
  -H "Authorization: Simple <public_key>:<private_key>"

Response Format

All list requests return the same standardized response format as the Search API.

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

Error Handling

List Resources uses the same error handling as the Search API. See the Search API Error Handling for detailed information about common errors.

Common Errors Specific to List Resources

Name
405 Method Not Allowed
Description
Operation not allowed for this folder
- action_not_allowed - the folder does not have permission for the get_many operation

Complete Example

Comprehensive Listing Query

Example request demonstrating multiple query parameters.

Request

curl -X GET "https://7c9h4pwu.fxns.io/articles?where__status__eq=published&where__rating__gte=4.0&where__category__in=tech,science&find_text__query=machine%20learning&find_text__fields=title,content&find_text__max_typos=1&sort=-_sys.created_at,title&populate=author,category&search_locale=en&return_locales=en,fr&fallback_locales=true&limit=20" \
  -H "Authorization: Simple <public_key>:<private_key>"

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"
      },
      "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"
          },
          "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"
          },
          "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

URL Length Considerations

Complex queries - For very complex filtering, consider using the Search API with POST requests
URL encoding - Ensure proper URL encoding for special characters
Browser limits - Be aware of URL length limits in browsers (typically 2048 characters)

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