Designing Content APIs with Flux

Once you've modeled your content using Collections, the next step is delivering it to your applications. FoxNose Flux APIs provide a powerful solution for this by allowing you to create multiple, independent APIs from a single content source. This gives you precise control over what content is exposed, who can access it, and the resulting URL structure.

What is a Flux API?

A Flux API is a high-performance, read-only endpoint optimized for content delivery. It sits completely separate from the Management API, which is used to create and edit your content.

Key Features:

  • Purpose-Built for Delivery: Optimized for fast, scalable, and secure content retrieval for your applications, websites, and services.
  • Multiple APIs, One Source: Create any number of distinct APIs within a single environment (e.g., an API for your blog, one for your shop, and another for docs), all pulling from the same content repository.
  • Data Model as API: The API structure is not arbitrary; it's a direct reflection of your collection hierarchy, making your endpoints logical and predictable.
  • Flexible Access Control: Can be fully public, require an API key, and grants access on a per-collection, per-method (get_one/get_many/create/update) basis. Writes always require an authenticated key, even on public APIs.
  • Agent-Ready Surface: Every Flux API ships with a per-prefix MCP server at /{api_prefix}/_mcp, a route catalog at /{api_prefix}/_router, and per-collection schema introspection — discoverable at runtime by AI agents and SDKs. Toggleable per-API via mcp_enabled and router_introspection_enabled.

Controlling Your API Endpoints: Structure and URLs

Every Flux API you create is identified by a unique prefix. This prefix defines the primary segment of your API's URL structure for content delivery.

The general pattern for Flux API endpoints is:

URL Pattern

https://<ENVIRONMENT_KEY>.fxns.io/<API_PREFIX>/<FOLDER_PATH>/[<RESOURCE_KEY>]

Where:

  • <ENVIRONMENT_KEY>: Your unique environment identifier.
  • <API_PREFIX>: The unique identifier for this specific Flux API (e.g., ai-skills-v1, legal-kb).
  • <FOLDER_PATH>: The hierarchical path generated by your connected collections (e.g., tools/data-analysis, regulations/gdpr).
  • [<RESOURCE_KEY>]: The optional key for an individual content item within a collection.

Examples

AI Agent Skill Catalog API: Define an ai-skills-v1 API prefix.

https://<ENVIRONMENT_KEY>.fxns.io/ai-skills-v1/tools/                                # All tools
https://<ENVIRONMENT_KEY>.fxns.io/ai-skills-v1/tools/{tool_key}                       # A specific tool
https://<ENVIRONMENT_KEY>.fxns.io/ai-skills-v1/tools/data-analysis/actions/           # Actions for 'data-analysis' tool
https://<ENVIRONMENT_KEY>.fxns.io/ai-skills-v1/tools/data-analysis/actions/{action_key} # A specific action

Regulatory Knowledge Base API: Define a legal-kb prefix.

https://<ENVIRONMENT_KEY>.fxns.io/legal-kb/regulations/                               # All regulations
https://<ENVIRONMENT_KEY>.fxns.io/legal-kb/regulations/gdpr/articles/                 # Articles under GDPR regulation
https://<ENVIRONMENT_KEY>.fxns.io/legal-kb/regulations/gdpr/articles/{article_key}    # A specific article

Agent-Native by Default

In addition to the data routes (/{collection}, /{collection}/{key}, /{collection}/_search), every Flux API prefix automatically exposes three introspection endpoints designed for AI agents and runtime-adaptive clients:

EndpointPathPurpose
MCP ServerGET|POST|DELETE /{api_prefix}/_mcpA per-API Model Context Protocol server over Streamable HTTP. Publishes five read tools — discover_resources, describe_resource, get_record, query_records, search_records — plus two opt-in write tools (create_record, update_record) that any MCP-compatible client (Claude, autonomous agents, etc.) can consume directly without an SDK.
Router IntrospectionGET /{api_prefix}/_routerA flat route catalog listing every reachable REST endpoint with its method, path, action, scope, path params, query params, request body contract, and response shape. Useful for clients that build requests dynamically.
Schema IntrospectionGET /{api_prefix}/{collection_path}/_schemaLive JSON Schema and route metadata for any connected collection — including which fields are searchable and which locales are configured.

All three respect the same access model as the rest of the API: is_auth_required controls whether a key is required, and the per-collection allowed_methods controls which tools each agent gets (e.g., a collection connected with only get_many exposes query_records and search_records but not get_record). No second access-control surface to maintain.

Hiding the agent surface

If a specific API prefix should serve REST traffic but stay invisible to agents (legacy clients, partner-only feeds, internal tools), flip the per-API toggles via the Management API:

curl -X PATCH https://api.foxnose.net/v1/<ENVIRONMENT_KEY>/api/<API_KEY>/ \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{"mcp_enabled": false, "router_introspection_enabled": false}'

Both mcp_enabled and router_introspection_enabled default to true. Set them independently — you can keep router introspection enabled while disabling the MCP server, or vice versa. See Flux API Object for the field reference, and Connect Claude for a hands-on walkthrough.

For the full breakdown — when to use MCP vs. a hand-written integration, the client compatibility matrix, and how the permissions model maps to agent tools — see the Agent-Native Flux APIs concept page.

Exposing Content via Flux API

Once your Flux API is defined, the next step is to select which content it will serve. This is done by connecting collections to your API using the Management API. Only content from connected collections becomes accessible through that specific Flux API.

How it Works:

  1. Choose a Flux API: Decide which of your Flux APIs (identified by its prefix) will expose the content.
  2. Select Collections: Pick the collections that contain the content you want to deliver.
  3. Define Permissions: For each connected collection, you specify exactly what operations are allowed (e.g., list resources, get single resource).
  4. Instant Delivery: Once connected, the content becomes immediately available through your Flux API endpoints, respecting the collection's hierarchy.

See the detailed guide here

The Role of Your Collection Hierarchy

The API structure automatically mirrors your collection hierarchy. Endpoint paths are generated using the alias property of connected collections, ensuring meaningful and consistent URL paths. For a deeper understanding of how collection hierarchies translate into API URLs, including the power of strict_reference, refer to the Collections guide.

Controlling Access: Permissions and allowed_methods

A key aspect of designing your Flux APIs is controlling exactly what content is accessible and how. When connecting collections, you define permissions using allowed_methods to control the available operations. This ensures that your APIs expose only what's intended.

Available Methods:

  • get_many: Allows listing resources and using the Search API or List Resources API for the connected collection.
  • get_one: Allows retrieving individual resources by their key using the Get Resource API.
  • create: Allows creating published resources via POST or the MCP create_record tool. Off by default; requires a matching create grant on the caller's key role.
  • update: Allows replacing resources via PUT or the MCP update_record tool. Off by default; requires a matching update grant on the key role.

Granular Control with allowed_methods

By combining these methods, you gain fine-grained control:

  • "allowed_methods": ["get_many", "get_one"] → Full Access: Allows both listing/searching and retrieving individual resources.
  • "allowed_methods": ["get_many"] → Discoverability Only: Allows listing/searching resources. By default, only _sys metadata (keys, timestamps) is returned, making content discoverable without revealing full data. This is ideal for scenarios where you want to expose a catalog of items without showing their full details until explicitly requested via get_one.
  • "allowed_methods": ["get_one"] → Direct Access Only: Allows retrieving individual resources by key, but not listing or searching.
  • "allowed_methods": [] → URL Structure Only: The collection path is part of the API's URL structure, but no content can be accessed through it. Useful for building hierarchical URLs without exposing data from intermediate collections.

Collection Hierarchy and strict_reference

The way your collections are nested is crucial, especially when using the strict_reference setting. This powerful feature automatically constructs logical, hierarchical URLs for your API endpoints.

For a detailed explanation of collection hierarchy and the strict_reference feature, including examples of how it ensures data integrity and simplifies API design, please refer to the Collections guide.

Common Flux API Delivery Patterns

Flux APIs are highly flexible and can be configured to support various content delivery patterns, ranging from simple lists to complex, hierarchical knowledge bases.

Pattern 1: AI Agent Tool Catalog

Use Case: Exposing a flat list of tools or actions for an AI agent.

📁 Tools (connected with ["get_many", "get_one"])

Endpoints:

  • GET /ai-tools/tools/ - List all tools
  • POST /ai-tools/tools/_search - Search tools
  • GET /ai-tools/tools/{tool_key}/ - Get specific tool

Pattern 2: Categorized Knowledge Base

Use Case: Organizing knowledge by category (e.g., product features, FAQs, regulatory topics).

📁 Categories (connected with ["get_many"])
└── 📁 Articles (connected with ["get_many", "get_one"])

Endpoints:

  • GET /knowledge-base/categories/ - List all categories (identifiers only)
  • GET /knowledge-base/categories/:category_key/articles/ - List articles in a specific category
  • GET /knowledge-base/categories/:category_key/articles/{article_key}/ - Get a specific article

Pattern 3: Multi-level Hierarchical Data

Use Case: Delivering deeply nested, context-dependent information (e.g., a legal code, scientific classifications).

📁 Regulations (connected with ["get_many"])
└── 📁 Chapters (connected with ["get_many"])
    └── 📁 Sections (connected with ["get_many", "get_one"])

Endpoints:

  • GET /legal-code/regulations/ - List regulations
  • GET /legal-code/regulations/:reg_key/chapters/ - List chapters in a regulation
  • GET /legal-code/regulations/:reg_key/chapters/:chapter_key/sections/ - List sections in a chapter
  • GET /legal-code/regulations/:reg_key/chapters/:chapter_key/sections/{section_key}/ - Get a specific section

Best Practices for Flux API Design

Designing powerful and secure Flux APIs requires thoughtful planning. Here are some key recommendations:

API Design Strategies

  • Meaningful Prefixes: Choose descriptive API prefixes (e.g., ai-skills-v1, legal-kb) that clearly indicate the API's purpose.
  • Collection Structure First: Design your collection hierarchy to directly reflect your desired API structure. Your data model is your API.
  • Consistent Aliases: Use clear, consistent, and often plural aliases for collections (articles, tools, regulations) as they form your API endpoint segments.
  • Leverage strict_reference: For truly dependent data (e.g., comments for a post), use strict_reference in nested collections to enforce data integrity and create clean, hierarchical API paths.
  • Principle of Least Privilege: Grant only the necessary allowed_methods for each connected collection. If an application only needs to read single items, don't grant get_many.

Your Next Steps

Ready to bring your content to life with Flux APIs? Here's how to continue:

You've got the blueprint; now it's time to build!

Was this page helpful?