Collections

Authentication: JWT | API Key

Collections provide hierarchical organization for content in FoxNose environments. Each Collection is backed by a single schema version that defines the shape of every resource it stores. Collections can be nested to create multi-level structures and enforce content flows (for example, strict references for single-parent hierarchies). See the Collections Guide for architecture examples.

Path deprecation

The canonical paths for this API are /v1/{env}/collections/.... A legacy alias /v1/{env}/folders/... remains available for backward compatibility: it returns identical responses, but every response carries an X-Deprecated: true header to signal that the path is deprecated. New integrations must use the /collections/ paths; the /folders/ alias may be removed in a future release.

Path Parameters

  • Name
    :env
    Type
    string
    Description

    Unique identifier of the environment

Collection Object

  • Name
    key
    Type
    string
    Description

    Unique identifier for the collection within the system.

  • Name
    name
    Type
    string
    Description

    Display name of the collection for easier identification.

  • Name
    path
    Type
    string
    Description

    Dot-delimited path of the collection within the hierarchy (e.g., blog.articles).

  • Name
    parent
    Type
    string | null
    Description

    Path of the parent collection if nested, or null if at the root level.

  • Name
    alias
    Type
    string
    Description

    Unique identifier used to reference the collection in API endpoints (e.g., "phones" for a collection storing phone records).

  • Name
    content_type
    Type
    string
    Description

    Collection content category. The API currently returns document for collection 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 collection. 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 collections.

  • 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 collection was created, in ISO 8601 format.

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

Create Collection

Creates a new collection in the specified environment.

Success Response: 201 Created

Attributes

  • Name
    name
    Type
    string
    Required
    required
    Description

    Collection display name

    • Minimum length: 1
    • Maximum length: 255
  • Name
    parent
    Type
    string
    Default
    default:null
    Description

    Parent collection path for nesting (dot-delimited, e.g., "blog.articles")

  • Name
    alias
    Type
    string
    Required
    required
    Description

    Unique collection 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 collection level
  • Name
    content_type
    Type
    string
    Required
    required
    Description

    Content type. Use "document" for all collection 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 (collections 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 collections.

    • 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_collection_not_found - the specified parent collection/path does not exist
  • Name
    422 Unprocessable Content
    Description

    Validation or business logic error. Specific codes:

    • validation_error - validation errors in request data
    • parent_collection_not_found - the specified parent path does not exist
    • collection_already_exists - collection with the same alias/path already exists at this level
    • collection_cannot_be_parent_of_itself - collection cannot be set as its own parent
    • invalid_inheritance - collection type/content type must be compatible with the parent
    • strict_reference_inheritance_mismatch - strict reference flag must match the parent when nested
    • max_collection_nesting_level - collection nesting exceeds the supported depth
    • root_collection_cannot_have_strict_reference - strict reference cannot be enabled on root collections
  • Name
    403 Forbidden
    Description

    The universal safety ceiling for collections was reached. Collections are not a per-plan quota; a flat ceiling of 5000 collections applies to every plan to protect the platform from runaway automation.

    • plan_limit_exceeded - the 5000-collection safety ceiling was reached (detail: {"entity": "collections", "limit": 5000, "current": <count>})

Request

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

Response

{
    "key": "0k96dpkn",
    "name": "Sample Collection",
    "path": "content.my_collection",
    "parent": "content",
    "alias": "my_collection",
    "strict_reference": true,
    "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/collections/tree/

List Collections

Retrieves collections in the specified environment. By default returns root collections, or related collections 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 collection (e.g., "blog.articles")

    • Cannot be used together with key
    • When provided, returns collections based on the mode parameter
  • Name
    key
    Type
    string
    Description

    Key of a specific collection

    • Cannot be used together with path
    • When provided, returns collections based on the mode parameter
  • Name
    mode
    Type
    string
    Default
    default:children
    Description

    Defines which related collections to return when path or key is specified

    • children - Direct child collections
    • siblings - Collections at the same level (excluding the collection itself)
    • descendants - All nested collections below
    • ancestors - All parent collections 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 collections up to that depth (root level = 1)
    • all – returns every collection 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
    strict_reference
    Type
    bool
    Description

    Filter collections that enforce strict reference hierarchy

  • Name
    key__in
    Type
    string
    Description

    Comma-separated list of collection 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 collections.

    • 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
    • collection_not_found - the specified collection (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/collections/tree/
curl https://api.foxnose.net/v1/7c9h4pwu/collections/tree/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

{
"count": 1,
"next": null,
"previous": null,
"results": [
    {
        "key": "0k96dpkn",
        "name": "Root Collection",
        "path": "root-collection",
        "parent": null,
        "alias": "root-collection",
        "strict_reference": false,
        "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/collections/tree/collection/

Retrieve Collection

Retrieves details of a specific collection by path or key.

Success Response: 200 OK

Query Parameters

  • Name
    path
    Type
    string
    Description

    Path to the collection (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 collection

    • 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 collection.

    • 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
    • collection_not_found - the specified collection 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/collections/tree/collection/
curl "https://api.foxnose.net/v1/7c9h4pwu/collections/tree/collection/?path=blog.articles" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

{
    "key": "0k96dpkn",
    "name": "Sample Collection",
    "path": "content.my_collection",
    "parent": "content",
    "alias": "my_collection",
    "strict_reference": true,
    "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/collections/tree/collection/

Update Collection

Updates an existing collection 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 collection (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 collection

    • Cannot be used together with path
    • Either path or key must be provided

Attributes

  • Name
    name
    Type
    string
    Required
    required
    Description

    Collection display name

    • Minimum length: 1
    • Maximum length: 255
  • Name
    parent
    Type
    string
    Description

    Parent collection path for nesting (dot-delimited, e.g., "blog.articles")

  • Name
    alias
    Type
    string
    Required
    required
    Description

    Unique collection 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 collection 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 (collections 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 collection.

    • 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
    • collection_not_found - the specified collection does not exist
    • parent_collection_not_found - the specified parent collection 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
    • collection_already_exists - collection with the same alias already exists at this level
    • collection_cannot_be_parent_of_itself - collection cannot be set as its own parent
    • invalid_inheritance - collection type must match parent collection type
    • strict_reference_inheritance_mismatch - strict reference setting must be consistent with parent
    • max_collection_nesting_level - maximum collection nesting level exceeded
    • strict_reference_error - cannot modify collection with strict reference constraints

Request

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

Response

{
    "key": "0k96dpkn",
    "name": "Updated Collection Name",
    "path": "content.updated_alias",
    "parent": "content",
    "alias": "updated_alias",
    "strict_reference": true,
    "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"
}

Composing Components

Collections can embed reusable Component schemas via nested fields. Adding a nested type field to a Collection's draft schema wires in the full field structure of a published Component version. This lets you define a shared content block once (as a Component) and reference it from many Collections without duplicating fields.

auto_update vs. pinned mode

Each nested field on a Collection carries two pieces of metadata that control how the embedded Component version evolves over time:

FieldTypeDefaultMeaning
component_versionstringset on creationThe Component schema version UID that is currently embedded.
auto_updatebooleanfalseWhen true, the pin advances automatically each time the Component publishes a new version. When false (pinned mode), the pin stays frozen.

Auto-update mode (auto_update: true) is convenient for Collections that always want the latest Component structure. When the Component publishes, FoxNose fans out a new published schema version for every Collection that has an auto-update nested field pointing at that Component, and advances each Collection's current_version automatically. There is no intermediate draft and no manual publish step — the new version is live immediately.

Pinned mode (auto_update: false) gives you full control. The component_version pin does not move until you explicitly call sync_component. Use this mode when you need to review Component changes before they affect your Collection's schema or when a migration window is required.

Advancing a pinned field

To advance one or more pinned nested fields to a newer (or older) Component version, call:

POST /v1/:env/collections/:collection/sync_component/

You can target specific field paths, supply per-path version overrides, or omit the body entirely to advance all pinned fields to their Component's current published version. See the sync_component reference for the full request and response shape, conflict semantics, and required permissions.

DELETEapi.foxnose.net/v1/:env/collections/tree/collection/

Delete Collection

Deletes a collection 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 collection (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 collection

    • 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 collection.

    • 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
    • collection_not_found - the specified collection 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/collections/tree/collection/
curl -X DELETE "https://api.foxnose.net/v1/7c9h4pwu/collections/tree/collection/?path=blog.articles" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

No response body

Was this page helpful?