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

    Count-based revision retention, evaluated on every write: hold a resource to at most this many live revisions (5-100). What goes is decided by age, not status — the oldest first — except the resource's current revision, which is never removed even when it is the oldest of them. When null, count-based retention is disabled. See Revision retention.

  • Name
    remove_drafts_on_publish
    Type
    bool
    Description

    Publication-based revision retention, evaluated on publish: when a revision is published, that resource’s lower-numbered draft revisions are removed. Revisions in published and unpublished status are kept. Defaults to false. Mutually exclusive with auto_remove_revisions. See Revision retention.

  • 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

    Count-based revision retention (5-100), applied on every write.
    Must not exceed your plan’s resource limit. Use null to disable.
    Cannot be combined with remove_drafts_on_publish.

  • Name
    remove_drafts_on_publish
    Type
    bool
    Default
    default:false
    Description

    Publication-based revision retention: removes a resource’s preceding drafts once a revision is published.
    Cannot be combined with auto_remove_revisions.

  • 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,
    "remove_drafts_on_publish": false,
    "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,
        "remove_drafts_on_publish": false,
        "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,
    "remove_drafts_on_publish": false,
    "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

    Count-based revision retention (5-100), applied on every write.
    Must not exceed your plan’s resource limit. Use null to disable.
    Cannot be combined with remove_drafts_on_publish.

  • Name
    remove_drafts_on_publish
    Type
    bool
    Default
    default:false
    Description

    Publication-based revision retention: removes a resource’s preceding drafts once a revision is published.
    Cannot be combined with auto_remove_revisions.

  • 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,
    "remove_drafts_on_publish": false,
    "auto_remove_schema_versions": 8,
    "embedding_model": "text-embed-3-large",
    "embedding_dimension": 3072,
    "created_at": "2024-10-29T07:02:53.215453-05:00"
}

Revision retention

A collection can trim its revision history automatically, in one of two ways. They answer different questions, and a collection may enable at most one of them.

  • Name
    auto_remove_revisions
    Type
    integer | null
    Description

    Count-based, evaluated on every write. Hold a resource to at most N live revisions; each write that pushes it past the limit removes the oldest, regardless of whether they are drafts or published. The one exception is the resource's current revision, which is never removed. Suits human editing, where only the latest version matters and the history is a safety net rather than a record.

  • Name
    remove_drafts_on_publish
    Type
    bool
    Description

    Publication-based, evaluated on publish. Nothing is removed while a resource is being worked on. When a revision is published, the revisions of that resource with draft status and a lower revision number are removed — drafts created afterwards belong to the next run and stay, as do revisions in published and unpublished status. Suits agent workflows, where the whole path matters until there is a result and only then becomes noise.

Enabling both in one request is rejected with 422 and error_code: "validation_error". The exclusivity is also enforced by a database constraint, so it holds no matter which write path is taken.

Enabling remove_drafts_on_publish on a collection that already has drafts does not remove anything retroactively. It takes effect on the next publication of each resource.

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?