Flux APIs Management

Authentication: JWT | API Key

Flux APIs enable public access to content through the Flux API. Create APIs to expose folders as public endpoints with configurable access methods. Each API generates a unique prefix and manages folder connections with granular method control.

Path Parameters

Name
:env
Type
string
Description
Unique identifier of the environment
Name
:api
Type
string
Description
Unique identifier of the API (the key field)
Name
:folder
Type
string
Description
Unique identifier of the folder (the key field)

Flux API Object

Name
key
Type
string
Description
Unique identifier for the API, automatically generated by the system.
Name
name
Type
string
Description
Display name of the API.
Name
description
Type
string
Description
Optional description of the API's purpose and functionality.
Name
environment
Type
string
Description
Key of the environment this API belongs to.
Name
prefix
Type
string
Description
URL prefix for the API endpoints. Must be unique within the environment.
Name
version
Type
string
Description
API version. Currently only "1" is supported.
Name
is_auth_required
Type
boolean
Description
When true, Flux API requests for this prefix require API key authentication.
Name
mcp_enabled
Type
boolean
Description
When true (default), the MCP Server endpoint (/{api_prefix}/_mcp) is exposed for this API prefix. Set to false to hide it from agents and clients.
Name
router_introspection_enabled
Type
boolean
Description
When true (default), the Router Introspection endpoint (/{api_prefix}/_router) is exposed for this API prefix. Set to false to hide it from agents and clients.
Name
created_at
Type
datetime
Description
Timestamp when the API was created.

Setting is_auth_required to true forces Flux API requests under this prefix to include valid Flux API credentials. Leave it false for public read-only endpoints.

mcp_enabled and router_introspection_enabled default to true and control whether the agent-facing MCP Server (/{api_prefix}/_mcp) and Router Introspection (/{api_prefix}/_router) endpoints are reachable for this API prefix. Disable them when you want the API to serve content but not advertise its tool catalog or route contract to agent integrations.

Folder Connection Object

Represents the connection between a folder and a Flux API. This object defines which folders are accessible through the API and what operations are allowed on each folder.

Name
folder
Type
string
Description
Key of the connected folder.
Name
api
Type
string
Description
Key of the API this folder is connected to.
Name
allowed_methods
Type
array
Description
Array of allowed access methods that determine what operations can be performed on this folder through the Flux API.
Available methods:
- "get_many" - Enables Search API and List Resources API endpoints for this folder. Allows retrieving multiple resources with filtering, searching, and pagination.
- "get_one" - Enables Get Resource API endpoint for this folder. Allows retrieving individual resources by their unique key.
Permission Logic:
- Both permissions (["get_many", "get_one"]) - Full access to folder data through all Flux API endpoints with complete resource content
- Only get_many (["get_many"]) - Can list and search resources, but returns only resource identifiers (keys) without actual content data. Cannot retrieve individual resources by key.
- Only get_one (["get_one"]) - Can retrieve individual resources by key with full content, but cannot list or search multiple resources
- No permissions ([]) - Folder is connected but inaccessible through Flux API (useful for URL structure without data access)
Important:
- The get_many permission is required for both Search API and List Resources API functionality
- When only get_many is enabled without get_one, API responses contain only resource keys in the _sys.key field, not the actual content data
Name
description_get_one
Type
string
Default
default:"Returns one resource by id."
Description
Optional short description (max 100 chars) for the Flux get_one endpoint of this folder.
Name
description_get_many
Type
string
Default
default:"Returns a paginated list of resources."
Description
Optional short description (max 100 chars) for the Flux get_many endpoint of this folder.
Name
description_search
Type
string
Default
default:"Searches resources by filters."
Description
Optional short description (max 100 chars) for the Flux _search endpoint of this folder.
Name
description_schema
Type
string
Default
default:"Returns JSON schema for this resource."
Description
Optional short description (max 100 chars) for the Flux /_schema endpoint of this folder.
Name
created_at
Type
datetime
Description
Timestamp when the folder was connected to the API.

POSTapi.foxnose.net/v1/:env/api/

Create API

Creates a new API in the specified environment.

Success Response: 201 Created

Attributes

Name
name
Type
string
Required
required
Description
API display name
- Minimum length: 1
- Maximum length: 255
Name
prefix
Type
string
Required
required
Description
API URL prefix
- Minimum length: 1
- Maximum length: 100
- Only lowercase letters, digits, hyphens, and underscores
- Must be unique within the environment
Name
description
Type
string
Description
API description
- Maximum length: 500
Name
version
Type
string
Default
default:1
Description
API version (currently only "1" is supported)
Name
is_auth_required
Type
boolean
Default
default:false
Description
Set to true to require Flux API key authentication for this prefix.
Name
mcp_enabled
Type
boolean
Default
default:true
Description
Whether the MCP Server endpoint (/{api_prefix}/_mcp) is exposed for this API prefix. Must be a JSON boolean — strings like "true", integers, and null are rejected.
Name
router_introspection_enabled
Type
boolean
Default
default:true
Description
Whether the Router Introspection endpoint (/{api_prefix}/_router) is exposed for this API prefix. Must be a JSON boolean — strings like "true", integers, and null are rejected.

Errors

Name
401 Unauthorized
Description
Authentication credentials are missing or invalid.
- authentication_failed - authentication credentials were not provided or are invalid
Name
403 Forbidden
Description
Insufficient permissions to create APIs.
- permission_denied - insufficient permissions to perform this action
Name
404 Not Found
Description
The specified resource could not be found. Specific codes:
- environment_not_found - the specified environment does not exist
Name
422 Unprocessable Content
Description
Validation or business logic error. Specific codes:
- validation_error - validation errors in request data
- api_prefix_exists - API with the same prefix already exists
- too_many_apis - maximum number of APIs for the environment reached

Request

POST

/v1/:env/api/

curl https://api.foxnose.net/v1/7c9h4pwu/api/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
    "name": "Blog API",
    "prefix": "blog-v1",
    "description": "API for accessing blog content"
}'

Response

{
    "key": "dw2qC5qRwxuZ",
    "name": "Blog API",
    "description": "API for accessing blog content",
    "environment": "7c9h4pwu",
    "prefix": "blog-v1",
    "version": "1",
    "is_auth_required": false,
    "mcp_enabled": true,
    "router_introspection_enabled": true,
    "created_at": "2024-01-15T10:30:00Z"
}

GETapi.foxnose.net/v1/:env/api/

List All Flux APIs

Retrieves all APIs in the specified environment. Results use standard limit/offset pagination.

Success Response: 200 OK

Query Parameters

Name
limit
Type
integer
Default
default:100
Description
Number of APIs per page.
Name
offset
Type
integer
Default
default:0
Description
Number of APIs to skip before starting the page.

Errors

Name
401 Unauthorized
Description
Authentication credentials are missing or invalid.
- authentication_failed - authentication credentials were not provided or are invalid
Name
403 Forbidden
Description
Insufficient permissions to view APIs.
- permission_denied - insufficient permissions to perform this action
Name
404 Not Found
Description
The specified resource could not be found. Specific codes:
- environment_not_found - the specified environment does not exist

Request

GET

/v1/:env/api/

curl https://api.foxnose.net/v1/7c9h4pwu/api/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "key": "dw2qC5qRwxuZ",
            "name": "Blog API",
            "description": "API for accessing blog content",
            "environment": "7c9h4pwu",
            "prefix": "blog-v1",
            "version": "1",
            "is_auth_required": false,
            "mcp_enabled": true,
            "router_introspection_enabled": true,
            "created_at": "2024-01-15T10:30:00Z"
        }
    ]
}

GETapi.foxnose.net/v1/:env/api/:api/

Retrieve Flux API

Retrieves details of a specific API.

Success Response: 200 OK

Errors

Name
401 Unauthorized
Description
Authentication credentials are missing or invalid.
- authentication_failed - authentication credentials were not provided or are invalid
Name
403 Forbidden
Description
Insufficient permissions to view this API.
- permission_denied - insufficient permissions to perform this action
Name
404 Not Found
Description
The specified resource could not be found. Specific codes:
- api_not_found - the specified API does not exist
- environment_not_found - the specified environment does not exist

Request

GET

/v1/:env/api/:api/

curl https://api.foxnose.net/v1/7c9h4pwu/api/dw2qC5qRwxuZ/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

{
    "key": "dw2qC5qRwxuZ",
    "name": "Blog API",
    "description": "API for accessing blog content",
    "environment": "7c9h4pwu",
    "prefix": "blog-v1",
    "version": "1",
    "is_auth_required": false,
    "mcp_enabled": true,
    "router_introspection_enabled": true,
    "created_at": "2024-01-15T10:30:00Z"
}

PUTapi.foxnose.net/v1/:env/api/:api/

Update Flux API

Updates an existing API.

Success Response: 200 OK

Attributes

Name
name
Type
string
Required
required
Description
API display name
- Minimum length: 1
- Maximum length: 255
Name
prefix
Type
string
Required
required
Description
API URL prefix
- Minimum length: 1
- Maximum length: 100
- Only lowercase letters, digits, hyphens, and underscores
- Must be unique within the environment
Name
description
Type
string
Description
API description
- Maximum length: 500
Name
version
Type
string
Default
default:1
Description
Keep as "1" (current supported version).
Name
is_auth_required
Type
boolean
Default
default:false
Description
Whether Flux API key authentication is enforced for this prefix.
Name
mcp_enabled
Type
boolean
Default
default:true
Description
Whether the MCP Server endpoint (/{api_prefix}/_mcp) is exposed for this API prefix. Must be a JSON boolean — strings, integers, and null are rejected. Supported on PATCH for single-field updates ({ "mcp_enabled": false }).
Name
router_introspection_enabled
Type
boolean
Default
default:true
Description
Whether the Router Introspection endpoint (/{api_prefix}/_router) is exposed for this API prefix. Must be a JSON boolean — strings, integers, and null are rejected. Supported on PATCH for single-field updates ({ "router_introspection_enabled": false }).

Errors

Name
401 Unauthorized
Description
Authentication credentials are missing or invalid.
- authentication_failed - authentication credentials were not provided or are invalid
Name
403 Forbidden
Description
Insufficient permissions to update this API.
- permission_denied - insufficient permissions to perform this action
Name
404 Not Found
Description
The specified resource could not be found. Specific codes:
- api_not_found - the specified API does not exist
- environment_not_found - the specified environment does not exist
Name
422 Unprocessable Content
Description
Validation or business logic error. Specific codes:
- validation_error - validation errors in request data
- api_prefix_exists - API with the same prefix already exists

Request

PUT

/v1/:env/api/:api/

curl -X PUT https://api.foxnose.net/v1/7c9h4pwu/api/dw2qC5qRwxuZ/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
    "name": "Updated Blog API",
    "prefix": "blog-v1",
    "description": "Updated API for accessing blog content",
    "version": "1",
    "is_auth_required": true
}'

Response

{
    "key": "dw2qC5qRwxuZ",
    "name": "Updated Blog API",
    "description": "Updated API for accessing blog content",
    "environment": "7c9h4pwu",
    "prefix": "blog-v1",
    "version": "1",
    "is_auth_required": true,
    "mcp_enabled": true,
    "router_introspection_enabled": true,
    "created_at": "2024-01-15T10:30:00Z"
}

DELETEapi.foxnose.net/v1/:env/api/:api/

Delete Flux API

Deletes an API and automatically disconnects all associated folders.

Success Response: 204 No Content

Errors

Name
401 Unauthorized
Description
Authentication credentials are missing or invalid.
- authentication_failed - authentication credentials were not provided or are invalid
Name
403 Forbidden
Description
Insufficient permissions to delete this API.
- permission_denied - insufficient permissions to perform this action
Name
404 Not Found
Description
The specified resource could not be found. Specific codes:
- api_not_found - the specified API does not exist
- environment_not_found - the specified environment does not exist

Request

DELETE

/v1/:env/api/:api/

curl -X DELETE https://api.foxnose.net/v1/7c9h4pwu/api/dw2qC5qRwxuZ/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

No response body

POSTapi.foxnose.net/v1/:env/api/:api/folders/

Connect Folder to API

Connects a folder to an API for public access.

Success Response: 201 Created

Attributes

Name
folder
Type
string
Required
required
Description
Key of the folder to connect to the API
Name
allowed_methods
Type
array
Default
default:[]
Description
Array of allowed access methods that control which Flux API endpoints are available for this folder.
Available methods:
- "get_many" - Enables listing and searching resources. Required for Search API and List Resources API
- "get_one" - Enables retrieving individual resources by key. Required for Get Resource API
Permission combinations:
- ["get_many", "get_one"] - Full access to all Flux API endpoints with complete resource content
- ["get_many"] - Can list/search resources but returns only identifiers (keys) without content data. Cannot retrieve individual resources.
- ["get_one"] - Can retrieve individual resources with full content but cannot list/search
- [] - No data access (folder appears in URL structure only)
Note: When only get_many is enabled, the API returns minimal resource information (only _sys.key and other system fields) to protect data while allowing resource discovery.
Name
description_get_one
Type
string
Default
default:"Returns one resource by id."
Description
Optional short description (max 100 chars) for get_one.
Name
description_get_many
Type
string
Default
default:"Returns a paginated list of resources."
Description
Optional short description (max 100 chars) for get_many.
Name
description_search
Type
string
Default
default:"Searches resources by filters."
Description
Optional short description (max 100 chars) for _search.
Name
description_schema
Type
string
Default
default:"Returns JSON schema for this resource."
Description
Optional short description (max 100 chars) for /_schema.

Errors

Name
401 Unauthorized
Description
Authentication credentials are missing or invalid.
- authentication_failed - authentication credentials were not provided or are invalid
Name
403 Forbidden
Description
Insufficient permissions to modify this API.
- permission_denied - insufficient permissions to perform this action
Name
404 Not Found
Description
The specified resource could not be found. Specific codes:
- api_not_found - the specified API does not exist
- folder_not_found - the specified folder does not exist
- environment_not_found - the specified environment does not exist
Name
422 Unprocessable Content
Description
Validation or business logic error. Specific codes:
- validation_error - validation errors in request data
- folder_already_connected_to_api - folder is already connected to this API

Request

POST

/v1/:env/api/:api/folders/

curl https://api.foxnose.net/v1/7c9h4pwu/api/dw2qC5qRwxuZ/folders/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
    "folder": "mK8nP3tYvBcX",
    "allowed_methods": ["get_one", "get_many"],
    "description_get_one": "Get one blog article by key",
    "description_get_many": "List blog articles",
    "description_search": "Search blog articles by filters",
    "description_schema": "Read article JSON schema"
}'

Response

{
    "folder": "mK8nP3tYvBcX",
    "api": "dw2qC5qRwxuZ",
    "allowed_methods": ["get_one", "get_many"],
    "description_get_one": "Get one blog article by key",
    "description_get_many": "List blog articles",
    "description_search": "Search blog articles by filters",
    "description_schema": "Read article JSON schema",
    "created_at": "2024-01-15T10:30:00Z"
}

GETapi.foxnose.net/v1/:env/api/:api/folders/

List Connected Folders

Retrieves all folders connected to the specified API. Results use standard limit/offset pagination.

Success Response: 200 OK

Query Parameters

Name
limit
Type
integer
Default
default:100
Description
Number of connections per page.
Name
offset
Type
integer
Default
default:0
Description
Number of connections to skip before starting the page.

Errors

Name
401 Unauthorized
Description
Authentication credentials are missing or invalid.
- authentication_failed - authentication credentials were not provided or are invalid
Name
403 Forbidden
Description
Insufficient permissions to view this API.
- permission_denied - insufficient permissions to perform this action
Name
404 Not Found
Description
The specified resource could not be found. Specific codes:
- api_not_found - the specified API does not exist
- environment_not_found - the specified environment does not exist

Request

GET

/v1/:env/api/:api/folders/

curl https://api.foxnose.net/v1/7c9h4pwu/api/dw2qC5qRwxuZ/folders/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "folder": "mK8nP3tYvBcX",
            "api": "dw2qC5qRwxuZ",
            "allowed_methods": ["get_one", "get_many"],
            "description_get_one": "Get one blog article by key",
            "description_get_many": "List blog articles",
            "description_search": "Search blog articles by filters",
            "description_schema": "Read article JSON schema",
            "created_at": "2024-01-15T10:30:00Z"
        }
    ]
}

GETapi.foxnose.net/v1/:env/api/:api/folders/:folder/

Retrieve Connected Folder

Retrieves details of a specific folder connection to an API.

Success Response: 200 OK

Errors

Name
401 Unauthorized
Description
Authentication credentials are missing or invalid.
- authentication_failed - authentication credentials were not provided or are invalid
Name
403 Forbidden
Description
Insufficient permissions to view this API.
- permission_denied - insufficient permissions to perform this action
Name
404 Not Found
Description
The specified resource could not be found. Specific codes:
- api_not_found - the specified API does not exist
- folder_not_found - the specified folder does not exist or is not connected to this API
- environment_not_found - the specified environment does not exist

Request

GET

/v1/:env/api/:api/folders/:folder/

curl https://api.foxnose.net/v1/7c9h4pwu/api/dw2qC5qRwxuZ/folders/mK8nP3tYvBcX/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

{
    "folder": "mK8nP3tYvBcX",
    "api": "dw2qC5qRwxuZ",
    "allowed_methods": ["get_one", "get_many"],
    "description_get_one": "Get one blog article by key",
    "description_get_many": "List blog articles",
    "description_search": "Search blog articles by filters",
    "description_schema": "Read article JSON schema",
    "created_at": "2024-01-15T10:30:00Z"
}

PUTapi.foxnose.net/v1/:env/api/:api/folders/:folder/

Update Connected Folder

Updates the connection settings for a folder in an API.

Success Response: 200 OK

Attributes

Name
allowed_methods
Type
array
Default
default:[]
Description
Array of allowed access methods that control which Flux API endpoints are available for this folder.
Available methods:
- "get_many" - Enables listing and searching resources. Required for Search API and List Resources API
- "get_one" - Enables retrieving individual resources by key. Required for Get Resource API
Permission combinations:
- ["get_many", "get_one"] - Full access to all Flux API endpoints with complete resource content
- ["get_many"] - Can list/search resources but returns only identifiers (keys) without content data. Cannot retrieve individual resources.
- ["get_one"] - Can retrieve individual resources with full content but cannot list/search
- [] - No data access (folder appears in URL structure only)
Note: When only get_many is enabled, the API returns minimal resource information (only _sys.key and other system fields) to protect data while allowing resource discovery.
Name
description_get_one
Type
string
Default
default:"Returns one resource by id."
Description
Optional short description (max 100 chars) for get_one.
Name
description_get_many
Type
string
Default
default:"Returns a paginated list of resources."
Description
Optional short description (max 100 chars) for get_many.
Name
description_search
Type
string
Default
default:"Searches resources by filters."
Description
Optional short description (max 100 chars) for _search.
Name
description_schema
Type
string
Default
default:"Returns JSON schema for this resource."
Description
Optional short description (max 100 chars) for /_schema.

Errors

Name
401 Unauthorized
Description
Authentication credentials are missing or invalid.
- authentication_failed - authentication credentials were not provided or are invalid
Name
403 Forbidden
Description
Insufficient permissions to modify this API.
- permission_denied - insufficient permissions to perform this action
Name
404 Not Found
Description
The specified resource could not be found. Specific codes:
- api_not_found - the specified API does not exist
- folder_not_found - the specified folder does not exist or is not connected to this API
- environment_not_found - the specified environment does not exist
Name
422 Unprocessable Content
Description
Validation or business logic error. Specific codes:
- validation_error - validation errors in request data

Request

PUT

/v1/:env/api/:api/folders/:folder/

curl -X PUT https://api.foxnose.net/v1/7c9h4pwu/api/dw2qC5qRwxuZ/folders/mK8nP3tYvBcX/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
    "allowed_methods": ["get_many"],
    "description_get_one": "",
    "description_get_many": "Public article feed",
    "description_search": "Search published articles",
    "description_schema": "Read feed schema"
}'

Response

{
    "folder": "mK8nP3tYvBcX",
    "api": "dw2qC5qRwxuZ",
    "allowed_methods": ["get_many"],
    "description_get_one": "",
    "description_get_many": "Public article feed",
    "description_search": "Search published articles",
    "description_schema": "Read feed schema",
    "created_at": "2024-01-15T10:30:00Z"
}

DELETEapi.foxnose.net/v1/:env/api/:api/folders/:folder/

Disconnect Folder

Disconnects a folder from an API.

Disconnecting a folder does not delete the folder or its resources—it only removes access to that folder through the current Flux API.

Success Response: 204 No Content

Errors

Name
401 Unauthorized
Description
Authentication credentials are missing or invalid.
- authentication_failed - authentication credentials were not provided or are invalid
Name
403 Forbidden
Description
Insufficient permissions to modify this API.
- permission_denied - insufficient permissions to perform this action
Name
404 Not Found
Description
The specified resource could not be found. Specific codes:
- api_not_found - the specified API does not exist
- folder_not_found - the specified folder does not exist or is not connected to this API
- environment_not_found - the specified environment does not exist
Name
422 Unprocessable Content
Description
Business logic error. Specific codes:
- strict_reference_error - cannot disconnect folder due to dependency constraints

Request

DELETE

/v1/:env/api/:api/folders/:folder/

curl -X DELETE https://api.foxnose.net/v1/7c9h4pwu/api/dw2qC5qRwxuZ/folders/mK8nP3tYvBcX/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

No response body