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 complex organizational structures with customizable access patterns and strict reference controls.

Read more about how folders work in the Folders Guide.

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
parent
Type
string | null
Description
Key of the parent folder if nested, or null if at 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
Defines allowed content types: "any" or "document". Collection folders cannot use "any".
Name
strict_reference
Type
bool
Description
Whether documents require strict hierarchical references. When true, documents can only belong to one parent.
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 identifier for nested folders
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
strict_reference
Type
bool
Default
default:false
Description
Enable strict reference hierarchy
- Cannot be changed after creation
- Must be true if parent has strict reference enabled
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: "any" or "document"
- Cannot be "any" if folder_type is "collection"
- Cannot be changed 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 does not exist
Name
422 Unprocessable Content
Description
Validation or business logic error. Specific codes:
- validation_error - validation errors in request data
- 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

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": "first_folder",
    "alias": "my_folder",
    "strict_reference": true,
    "folder_type": "collection",
    "content_type": "document"
}'

Response

{
    "key": "0k96dpkn",
    "name": "Sample Folder",
    "parent": "first_folder",
    "alias": "my_folder",
    "strict_reference": true,
    "folder_type": "collection",
    "content_type": "document",
    "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.

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
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
parent
Type
string
Description
Filter by parent folder ID
- Operator: exact

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

{
    "results": [
        {
            "key": "0k96dpkn",
            "name": "Sample Folder",
            "parent": "first_folder",
            "alias": "my_folder",
            "strict_reference": true,
            "folder_type": "collection",
            "content_type": "document",
            "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",
    "parent": "first_folder",
    "alias": "my_folder",
    "strict_reference": true,
    "folder_type": "collection",
    "content_type": "document",
    "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.

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
Description
Folder display name
- Minimum length: 1
- Maximum length: 255
Name
parent
Type
string
Description
Parent folder identifier for moving folders
Name
alias
Type
string
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

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",
    "parent": "new_parent_folder",
    "alias": "updated_alias",
    "strict_reference": true,
    "folder_type": "collection",
    "content_type": "document",
    "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