The FoxNose Data Model

Everything you build in FoxNose lives inside a single, predictable hierarchy: Organization → Project → Environment → Collection → Resource → Revision. Each level narrows the scope, from your account down to a single versioned change to one piece of content. Understanding this chain is the fastest way to reason about where your data lives and how your APIs are shaped.

Organization (e.g., Acme Corp)
└── Project (e.g., Support Agent)
    └── Environment (e.g., Production)
        └── Collection (e.g., Articles)
            └── Resource (e.g., "getting-started")
                └── Revision (draft → published)

Organization

The Organization is the top-level container. It holds your projects and your billing information. When you sign up, a personal organization is created for you.

What it is: Your account boundary — everything you own rolls up here.
Key properties: Projects, subscription and billing.
When you create one: Automatically, on sign-up. An organization is single-owner today: it is managed by the account that created it. Role-scoped API keys grant limited access to services and agents; team member invitations are on the roadmap.

See Understanding Your Workspace for how organizations, projects, and environments fit together.

Project

A Project contains all the data and configuration for a single application — a public website, a mobile app, or an internal knowledge base.

What it is: The unit that maps to one application or product.
Key properties: A set of environments and a chosen geographic data region.
When you create one: When you start a new application. You pick the region where its data is stored at creation time.

Environment

An Environment is a complete, isolated container for a project's data — think production, staging, or development. Each environment gets its own unique host, so all of its APIs live on a distinct domain.

What it is: An isolated deployment stage of your project's content.
Key properties: An independent set of Collections, Resources, and Revisions; its own host.
When you create one: Every project starts with a Production environment. Add more for testing, previewing, or development. A new environment starts empty — it does not inherit data from other environments.

Reference: Management API — Environments.

Collection

A Collection is a typed set of Resources governed by its own versioned schema. It is the blueprint for your data model and, automatically, for your API — a Collection's alias becomes a segment in your Flux API URL.

What it is: A group of same-shaped Resources plus the schema that defines their fields.
Key properties: A versioned schema, an alias, and optional parent-child relationships with other Collections.
When you create one: For each distinct content type — articles, products, authors. Design the schema first; connect it to a Flux API last.

Concepts: Organizing Content with Collections and Schema & Fields. Reference: Management API — Collections.

Resource

A Resource is a single item inside a Collection — one article, one product, one record. Every Resource in a Collection follows that Collection's schema, which is what makes content predictable and easy to query.

What it is: An individual content record within a Collection.
Key properties: A key, and field values conforming to the Collection's schema.
When you create one: Whenever you add a new item to a Collection.

Reference: Management API — Resources.

Revision

A Revision is a specific version of a Resource's content. You create or update a Revision, it moves through validation, vectorization, and indexing, and then you publish it. The Flux API only ever serves published content, so Revisions give you a safe draft-then-publish workflow.

What it is: A versioned change to a single Resource's content.
Key properties: Draft or published state; its content is what powers records, embeddings, and indexes once published.
When you create one: Every time you write or edit a Resource's content.

For the full publish pipeline, see How Writes Work. Reference: Management API — Revisions.

Components: reusable schema, live-linked

Sitting alongside your Collections are Components — reusable, versioned schema fragments. A Collection embeds a Component through a nested field and then chooses how to follow it going forward:

component / component_version — the Component and the specific version the field is pinned to.
sync_component — an explicit call that advances a pinned field to a newer Component version when you decide to.
auto_update — when true, publishing a new Component version automatically advances the Collection to a fresh published schema version with the new pin; when false (the default), the pin only moves on an explicit sync.

This is a live-link model: Components are shared schema, and each Collection controls whether it tracks their evolution automatically or on demand. For the full model — pinning modes, compatibility rules, and sync behavior — see Components.

Wire naming. For backward compatibility, JSON request and response bodies still use folder and folder_key (and _sys.folder) where prose says Collection. The terms refer to the same thing — the wire field names are intentionally preserved, so you will see folder in API examples throughout the reference.