Folders

Authentication: JWT | API Key

Folders provide hierarchical organization for content in FoxNose environments. They support two types: composite folders for mixed content and collection folders for structured data. Folders can be nested to create multi-level structures and enforce content flows (for example, strict references for single-parent hierarchies). See the Folders Guide for architecture examples.

Path Parameters

Name
:env
Type
string
Description
Unique identifier of the environment

Folder Object

Name
key
Type
string
Description
Unique identifier for the folder within the system.
Name
name
Type
string
Description
Display name of the folder for easier identification.
Name
path
Type
string
Description
Dot-delimited path of the folder within the hierarchy (e.g., blog.articles).
Name
parent
Type
string | null
Description
Path of the parent folder if nested, or null if at the root level.
Name
alias
Type
string
Description
Unique identifier used to reference the folder in API endpoints (e.g., "phones" for a folder storing phone records).
Name
folder_type
Type
string
Description
Type of folder: "composite" for mixed content or "collection" for structured data.
Name
content_type
Type
string
Description
Folder content category. The API currently returns document for folder types that store resources.
Name
strict_reference
Type
bool
Description
Whether documents require strict hierarchical references. When true, documents can only belong to one parent.
Name
auto_remove_revisions
Type
integer | null
Description
Optional auto-clean limit (5-100) for resource revisions within the folder. When null, auto-removal is disabled.
Name
auto_remove_schema_versions
Type
integer | null
Description
Optional auto-clean limit (5-100) for schema versions. Returned only for collection folders.
Name
embedding_model
Type
string | null
Description
Identifier of the embedding model configured for similarity search. Immutable after creation.
Name
embedding_dimension
Type
integer | null
Description
Vector dimension associated with the embedding model.
Name
created_at
Type
datetime
Description
Timestamp when the folder was created, in ISO 8601 format.

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

Create Folder

Creates a new folder in the specified environment.

Success Response: 201 Created

Attributes

Name
name
Type
string
Required
required
Description
Folder display name
- Minimum length: 1
- Maximum length: 255
Name
parent
Type
string
Default
default:null
Description
Parent folder path for nesting (dot-delimited, e.g., "blog.articles")
Name
alias
Type
string
Required
required
Description
Unique folder alias
- Minimum length: 1
- Maximum length: 100
- Must be alphanumeric with at least one letter
- Hyphens and underscores allowed, but not at beginning or end
- Must be unique within the same folder level
Name
folder_type
Type
string
Required
required
Description
Folder type: "composite" or "collection"
- Must match parent folder type if nested
- Cannot be changed after creation
Name
content_type
Type
string
Required
required
Description
Content type. Use "document" for all folder types.
Name
strict_reference
Type
bool
Default
default:false
Description
Enable strict reference hierarchy
- Must be true if parent has strict reference enabled
- Cannot be changed after creation
Name
auto_remove_revisions
Type
integer
Default
default:null
Description
Optional auto-clean limit (5-100) for resource revisions.
Must not exceed your plan’s resource limit. Use null to disable.
Name
auto_remove_schema_versions
Type
integer
Default
default:null
Description
Optional auto-clean limit (5-100) for schema versions (collection folders only).
Must not exceed your plan’s schema version limit. Use null to disable.
Name
embedding_model
Type
string
Default
default:null
Description
Optional embedding model identifier for semantic search. Immutable after creation.

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 folders.
- 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
- parent_folder_not_found - the specified parent folder/path does not exist
Name
422 Unprocessable Content
Description
Validation or business logic error. Specific codes:
- validation_error - validation errors in request data
- parent_folder_not_found - the specified parent path does not exist
- folder_already_exists - folder with the same alias/path already exists at this level
- folder_cannot_be_parent_of_itself - folder cannot be set as its own parent
- invalid_inheritance - folder type/content type must be compatible with the parent
- strict_reference_inheritance_mismatch - strict reference flag must match the parent when nested
- max_folder_nesting_level - folder nesting exceeds the supported depth
- root_folder_cannot_have_strict_reference - strict reference cannot be enabled on root folders
Name
429 Too Many Requests
Description
Plan usage limit reached.
- plan_limit_exceeded - current plan already uses the maximum number of folders

Request

POST

/v1/:env/folders/tree/

curl https://api.foxnose.net/v1/7c9h4pwu/folders/tree/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
    "name": "Sample Folder",
    "parent": "content",
    "alias": "my_folder",
    "strict_reference": true,
    "folder_type": "collection",
    "content_type": "document",
    "auto_remove_revisions": 20,
    "auto_remove_schema_versions": 8,
    "embedding_model": "text-embed-3-large"
}'

Response

{
    "key": "0k96dpkn",
    "name": "Sample Folder",
    "path": "content.my_folder",
    "parent": "content",
    "alias": "my_folder",
    "strict_reference": true,
    "folder_type": "collection",
    "content_type": "document",
    "auto_remove_revisions": 20,
    "auto_remove_schema_versions": 8,
    "embedding_model": "text-embed-3-large",
    "embedding_dimension": 3072,
    "created_at": "2024-10-29T07:02:53.215453-05:00"
}

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

List Folders

Retrieves folders in the specified environment. By default returns root folders, or related folders when using query parameters. Results are paginated with the standard limit/offset parameters.

Success Response: 200 OK

Query Parameters

Name
path
Type
string
Description
Path to a specific folder (e.g., "blog.articles")
- Cannot be used together with key
- When provided, returns folders based on the mode parameter
Name
key
Type
string
Description
Key of a specific folder
- Cannot be used together with path
- When provided, returns folders based on the mode parameter
Name
mode
Type
string
Default
default:children
Description
Defines which related folders to return when path or key is specified
- children - Direct child folders
- siblings - Folders at the same level (excluding the folder itself)
- descendants - All nested folders below
- ancestors - All parent folders above
Name
scope
Type
string | integer
Default
default:1
Description
When neither path nor key is provided, controls how many levels of the tree to return:
- Integer value (1-10, e.g. 1, 2) – returns folders up to that depth (root level = 1)
- all – returns every folder in the environment
Name
created_at
Type
datetime
Description
Filter by creation date
- Operators: exact, gt, lt, gte, lte
Name
content_type
Type
string
Description
Filter by content type
- Operator: exact
Name
folder_type
Type
string
Description
Filter by folder type
- Operator: exact
Name
strict_reference
Type
bool
Description
Filter folders that enforce strict reference hierarchy
Name
key__in
Type
string
Description
Comma-separated list of folder keys to return (applies before pagination)
Name
limit
Type
integer
Description
Maximum number of results to return. Default: 100.
Name
offset
Type
integer
Description
Number of results to skip for pagination.

Ordering

Name
created_at
Type
datetime
Description
Order by creation date
- Use ?ordering=created_at for ascending
- Use ?ordering=-created_at for descending

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 folders.
- 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
- folder_not_found - the specified folder (path or key) does not exist
Name
422 Unprocessable Content
Description
Validation error. Specific codes:
- validation_error - invalid query parameters (e.g., both path and key provided)

Request

GET

/v1/:env/folders/tree/

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

Response

{
"count": 1,
"next": null,
"previous": null,
"results": [
    {
        "key": "0k96dpkn",
        "name": "Root Folder",
        "path": "root-folder",
        "parent": null,
        "alias": "root-folder",
        "strict_reference": false,
        "folder_type": "composite",
        "content_type": "document",
        "auto_remove_revisions": null,
        "auto_remove_schema_versions": null,
        "embedding_model": null,
        "embedding_dimension": null,
        "created_at": "2024-10-29T07:02:53.215453-05:00"
    }
]
}

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

Retrieve Folder

Retrieves details of a specific folder by path or key.

Success Response: 200 OK

Query Parameters

Name
path
Type
string
Description
Path to the folder (e.g., "blog.articles")
- Cannot be used together with key
- Either path or key must be provided
Name
key
Type
string
Description
Key of the folder
- Cannot be used together with path
- Either path or key must be provided

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 folder.
- 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
- folder_not_found - the specified folder does not exist
Name
422 Unprocessable Content
Description
Validation error. Specific codes:
- validation_error - invalid query parameters (missing path/key or both provided)

Request

GET

/v1/:env/folders/tree/folder/

curl "https://api.foxnose.net/v1/7c9h4pwu/folders/tree/folder/?path=blog.articles" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

{
    "key": "0k96dpkn",
    "name": "Sample Folder",
    "path": "content.my_folder",
    "parent": "content",
    "alias": "my_folder",
    "strict_reference": true,
    "folder_type": "collection",
    "content_type": "document",
    "auto_remove_revisions": 20,
    "auto_remove_schema_versions": 8,
    "embedding_model": "text-embed-3-large",
    "embedding_dimension": 3072,
    "created_at": "2024-10-29T07:02:53.215453-05:00"
}

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

Update Folder

Updates an existing folder by path or key. Supports changing the display name, alias, parent, and auto-clean thresholds.

Success Response: 200 OK

Query Parameters

Name
path
Type
string
Description
Path to the folder (e.g., "blog.articles")
- Cannot be used together with key
- Either path or key must be provided
Name
key
Type
string
Description
Key of the folder
- Cannot be used together with path
- Either path or key must be provided

Attributes

Name
name
Type
string
Required
required
Description
Folder display name
- Minimum length: 1
- Maximum length: 255
Name
parent
Type
string
Description
Parent folder path for nesting (dot-delimited, e.g., "blog.articles")
Name
alias
Type
string
Required
required
Description
Unique folder alias
- Minimum length: 1
- Maximum length: 100
- Must be alphanumeric with at least one letter
- Hyphens and underscores allowed, but not at beginning or end
- Must be unique within the same folder level
Name
auto_remove_revisions
Type
integer | null
Default
default:null
Description
Optional auto-clean limit (5-100) for resource revisions.
Must not exceed your plan’s resource limit. Use null to disable.
Name
auto_remove_schema_versions
Type
integer | null
Default
default:null
Description
Optional auto-clean limit (5-100) for schema versions (collection folders only).
Must not exceed your plan’s schema version limit. Use null to disable.

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 folder.
- 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
- folder_not_found - the specified folder does not exist
- parent_folder_not_found - the specified parent folder does not exist
Name
422 Unprocessable Content
Description
Validation or business logic error. Specific codes:
- validation_error - validation errors in request data or query parameters
- folder_already_exists - folder with the same alias already exists at this level
- folder_cannot_be_parent_of_itself - folder cannot be set as its own parent
- invalid_inheritance - folder type must match parent folder type
- strict_reference_inheritance_mismatch - strict reference setting must be consistent with parent
- max_folder_nesting_level - maximum folder nesting level exceeded
- strict_reference_error - cannot modify folder with strict reference constraints

Request

PUT

/v1/:env/folders/tree/folder/

curl -X PUT "https://api.foxnose.net/v1/7c9h4pwu/folders/tree/folder/?path=blog.articles" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
    "name": "Updated Folder Name",
    "alias": "updated_alias"
}'

Response

{
    "key": "0k96dpkn",
    "name": "Updated Folder Name",
    "path": "content.updated_alias",
    "parent": "content",
    "alias": "updated_alias",
    "strict_reference": true,
    "folder_type": "collection",
    "content_type": "document",
    "auto_remove_revisions": 15,
    "auto_remove_schema_versions": 8,
    "embedding_model": "text-embed-3-large",
    "embedding_dimension": 3072,
    "created_at": "2024-10-29T07:02:53.215453-05:00"
}

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

Delete Folder

Deletes a folder by path or key. The operation is asynchronous and returns immediately.

Success Response: 202 Accepted

Query Parameters

Name
path
Type
string
Description
Path to the folder (e.g., "blog.articles")
- Cannot be used together with key
- Either path or key must be provided
Name
key
Type
string
Description
Key of the folder
- Cannot be used together with path
- Either path or key must be provided

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 folder.
- 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
- folder_not_found - the specified folder does not exist
Name
422 Unprocessable Content
Description
Validation error. Specific codes:
- validation_error - invalid query parameters (missing path/key or both provided)

Request

DELETE

/v1/:env/folders/tree/folder/

curl -X DELETE "https://api.foxnose.net/v1/7c9h4pwu/folders/tree/folder/?path=blog.articles" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

No response body