Getting Started with Flux API

Flux API is FoxNose’s delivery layer. Management API creates and structures content; Flux exposes it to your web apps, stores, or integrations with fast read-only endpoints.

How Flux APIs Are Organized

• Environment scoped – Each environment (e.g., production, preview) has its own Flux base domain: https://{environment_key}.fxns.io.
• Multiple APIs per environment – Create custom prefixes (e.g., /blog, /storefront) via Build Flux APIs and map folders to each prefix.
• Folder routing – Connected folders define the URL paths available under a prefix. If a folder is not connected, Flux returns route_not_found.
• Authentication optional – APIs can be public or require Flux API keys. Secure mode uses signed requests; Simple mode is for development only.

Core Endpoints

Resource delivery endpoints (list, get, search) use the _sys + data structure. Introspection endpoints return contract/schema metadata.

URL Pattern

https://{environment_key}.fxns.io/{api_prefix}/{folder_path}/[resource_key]

Example:

# List articles
GET https://7c9h4pwu.fxns.io/blog/articles

# Fetch a specific article
GET https://7c9h4pwu.fxns.io/blog/articles/dw2qC5qRwxuZ

# Run a search
POST https://7c9h4pwu.fxns.io/blog/articles/_search

Making Your First Call

curl "https://7c9h4pwu.fxns.io/blog/articles?limit=5" \
  -H "Authorization: Secure <access_key>:<signature>"

Flux responses always include pagination keys (limit, next, previous) even for simple list calls.

Feature Highlights

Authentication Options

• Secure (recommended) – Signed headers with Authorization: Secure <access_key>:<signature> plus Date. Prevents replay attacks and is mandatory for production APIs.
• Simple – Authorization: Simple <public_key>:<private_key>. Use only for local testing or temporary public APIs.

More details: Flux Authentication.

Pagination

• Cursor-based, stateless pagination with next/previous URLs.
• limit accepts 1–100 results.
• Both list and search endpoints share the same format.
• Learn more: Pagination guide.

Population

Pass populate=fieldA,fieldA.nested to replace reference IDs with the full resource (up to 3 levels deep). Works across list and search.

Localization

Use search_locale (sorting), return_locales (which locales appear in data), and fallback_locales=true to reuse your environment’s fallback chain. Details in Localization.

Search vs List

• List Resources – Use simple filters (where__field__operator), no request body, ideal for most pages.
• Search – Use when you need complex where logic, joins, text/vector search, or custom sort orders via POST.

Vector Search

Flux can run semantic queries (search_mode="vector" or boosted/hybrid modes). If you plan to use vectors, enable vectorizable fields first and see the Vector Search guide.

Error Handling

Flux returns structured JSON errors:

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

Refer to Flux Errors for the full list (authentication_required, access_denied, action_not_allowed, max_response_size_exceeded, etc.).

Next Steps

1. Secure your APIs – Authentication explains Secure and Simple modes.
2. List vs Search – Start with List Resources and graduate to Search for advanced scenarios.
3. Single Resource Patterns – Use Get Resource for detail views or lookups.
4. API Discovery – Add Router Introspection and Schema Introspection when building MCP/agent integrations.
5. Semantics & Ranking – Explore Vector Search to add semantic relevance.
6. Manage Flux APIs – Learn how to configure prefixes, authentication, and folder mapping via Build Flux APIs.

Flux API is read-only, fast, and stateless. With these building blocks you can compose custom content feeds, search experiences, and storefronts while keeping authoring inside Management API.