Copy page

Reference

Core entity definitions

This page defines the core entities in Bevaya and how they relate. It is a compact reference; for the procedures that create and configure these entities, follow the links in each definition.

The entities fall into two groups: the structural entities that organize your account (organization, workspace, AI Agent) and the entities you build and operate inside them (flow, environment, workflow run, work item, file).

The hierarchy at a glance

Code
Organization              your company's boundary in Bevaya (tenant)
├── Users                 members of the organization, assigned roles
├── Environments          organization-level runtime contexts
└── Workspace             a grouping of related AI Agents
    └── AI Agent           where flows and their configuration live
        └── Flow           the agent's behavior you build, test, and run
            └── Workflow run   one execution of the flow against a case
                └── Work item   an exception routed for human review

Relationships and cardinality

Entity	Lives within	Contains	Defined / managed in
Organization	— (top level)	Workspaces, users, environments	Provisioned for your company
Workspace	One organization	AI Agents, workspace members	Platform hierarchy
AI Agent	One workspace	Flows and their configuration	Platform hierarchy
Flow	One AI Agent	Trigger + nodes; produces runs	Build AI Agents
Environment	One organization (shared)	Variables; selected at run time	Environments and variables reference
Workflow run	One flow	Execution steps; may create work items	Run history
Work item	One workflow run	Source documents, fields, a review	Human review
File	Uploaded into your organization	The document content for processing	Files (API)

Structural entities

Organization — the top-level boundary for your company in Bevaya and the tenant boundary: all workspaces, AI Agents, flows, users, environments, and configuration belong to your organization and are isolated from other customers. Organization-level settings apply across everything beneath them. See Platform hierarchy.

Workspace — a grouping of related AI Agents within an organization, used to separate work by line of business, team, or stage of work. Workspaces have their own members; granting workspace access controls which AI Agents and resources a user can reach inside it. See Platform hierarchy and Users and access.

AI Agent — the working area that contains flows and their related configuration, including agent-scoped variables. AI Agents are built, tested, run, and monitored here. Note: the API still refers to this entity as a project. See AI Agent reference.

Build and runtime entities

Flow — the node-based definition of an AI Agent's behavior: a trigger plus the connected nodes that process each case. A flow belongs to one AI Agent. You build it, test the draft, and publish a version to run. See Build AI Agents.

Environment — the runtime context a flow runs in. Environments are defined at the organization level and shared across its workspaces and AI Agents; you select one when you test, publish, or run a flow. Variables resolve to different values per environment, so the same flow can run against sandbox or live settings without changing the flow. See Environments and variables reference.

Workflow run — a single execution of a flow against one case (a document package, claim, submission, audit sample, or business event). A configured trigger starts a run in production; the run progresses through execution steps and completes or fails. Browse and inspect runs in Run history. For run lifecycle values, see Workflow run statuses.

Work item — a prepared exception task created when a flow needs human judgment before completing an action. It arrives with context already assembled — the source document, proposed classification, extracted fields, and a recommended match or action — for a reviewer to validate or correct. A work item belongs to the run that created it. See Human review. For item lifecycle values, see Work item statuses.

File — a document uploaded for processing, referenced throughout the platform and API by a file ID. Files enter a flow through a trigger (manual upload or email) or, programmatically, through the API. See Files (API).

Ownership and access boundaries

Access follows the hierarchy. Users are members of the organization; their assigned roles and the workspaces and AI Agents they belong to determine what they can see and do. Because access is granted at the workspace and AI Agent level, you can give a builder access only to the AI Agents where they build, give a reviewer access only to the items they review, and keep administrative control with administrators — without exposing one team's work to another. See Users and access.

Where to go next

• Platform hierarchy — choose your workspace and AI Agent structure.
• AI Agent reference — what an AI Agent does and does not decide.
• Environments and variables reference — scopes, precedence, and permissions.
• Concepts glossary — concise definitions for every term used in the docs.