Skip to main content
This page provides a complete reference for all core objects in Veratrace, organized by persona use case. Understanding these objects is essential for effectively using and administering Veratrace. Related: Source: Feature Inventory

​
Purpose

This concept page defines all core data objects in Veratrace, their fields, and how different personas (end users, administrators, developers) interact with them.

​
Scope

This page covers:
  • All core objects (Instance, TWU Model, Agent, Integration, User, Work Ledger Entry)
  • Object fields and data types
  • Persona-specific use cases
  • UI routes for each object
  • API endpoints for each object
This page does not cover:

​
Instance

​
Definition

Multi-tenant configuration container. Each instance has isolated data and authentication. Multi-tenant configuration container. Each instance has isolated data and authentication. Fields:
  • id (string) - Instance identifier
  • userPoolId (string) - AWS Cognito User Pool ID (format: region_xxxxxxxx)
  • clientId (string) - Cognito OIDC client ID
  • region (string) - AWS region (extracted from userPoolId)
Admin Use: Configure instance authentication and isolation Developer Use: Instance ID is required for all API calls: /instances/:instanceId/{resource} Source: Source: Feature Inventory

​
Use Cases

Admin Use: Configure instance authentication and isolation Developer Use: Instance ID is required for all API calls: /instances/:instanceId/{resource} Source: Source: Feature Inventory

​
TWU Model

​
Definition

Defines the structure for Trusted Work Units. Models have versions with statuses. Fields:
  • id / modelId (string) - Model identifier
  • name (string) - Model name
  • description (string) - Model description
  • status (string) - Model status: DRAFT, PUBLISHED, ARCHIVED
  • entities (array) - List of entity definitions
  • actions (array) - List of action definitions
  • events (array) - List of event definitions
  • outcomes (array) - List of outcome definitions with expressions
  • version (number) - Version number
  • createdAt (timestamp) - Creation timestamp
  • updatedAt (timestamp) - Last update timestamp

​
Use Cases

End User Use: View published models to understand work structure Admin Use: Create and manage models, publish versions Developer Use: Create models via API, manage versions programmatically UI Routes:
  • /twu-models - List models
  • /twu-models/create - Create model
  • /twu-models/:modelId/versions/:version/edit - Edit version
Source: Source: Feature Inventory

​
Agent

​
Definition

AI or human agent that performs work operations. Fields:
  • id (string) - Agent identifier
  • name (string) - Agent name
  • type (string) - Agent type: “AI” or “HUMAN”
  • active (boolean) - Whether agent is active
  • capabilities (array) - Agent capabilities (varies by type)
  • model (string, AI only) - AI model identifier (e.g., “gpt-4”, “gpt-3.5-turbo”, “claude-3”)
  • priority (string) - Priority level: “high”, “medium”, “low”
  • metadata (object) - Additional agent metadata

​
Use Cases

End User Use: View available agents and their capabilities Admin Use: Create and configure agents, set priorities Developer Use: Manage agents via API, configure AI models programmatically UI Routes:
  • /agents - List agents
  • /agents/create - Create agent
  • /agents/:agentId/edit - Edit agent
Source: Source: Feature Inventory

​
Integration

​
Definition

Connection to external systems for evidence ingestion. Fields:
  • id (string) - Integration identifier
  • name (string) - Integration name
  • type (string) - Integration type (40+ types supported)
  • status (string) - Status: “active”, “inactive”, “connecting”, “error”
  • metadata (object) - Integration-specific configuration
  • health (object) - Health check information
    • isHealthy (boolean)
    • lastHealthCheck (timestamp)
    • metrics (object)

​
Use Cases

End User Use: Monitor integration health and status Admin Use: Create and configure integrations, test connections Developer Use: Manage integrations via API, implement custom integrations UI Routes:
  • /integrations - List integrations
  • /integrations/create - Create integration
  • /integrations/:integrationId/edit - Edit integration
Source: Source: Feature Inventory

​
User

​
Definition

User account within an instance. Fields:
  • id (string) - User identifier
  • username (string) - Username
  • email (string) - Email address
  • name (string) - First name
  • middleName (string, optional) - Middle name
  • familyName (string, optional) - Family name
  • enabled (boolean) - Whether user is enabled
  • temporaryPassword (string, optional) - Temporary password for new users
  • roles (array, inferred) - User roles (structure not found in code)

​
Use Cases

Admin Use: Create and manage users, assign roles, enable/disable accounts Developer Use: Manage users via API, integrate with identity providers UI Routes:
  • /users - List users
  • /users/create - Create user
  • /users/:userId/edit - Edit user
Source: Source: Feature Inventory

​
Work Ledger Entry

​
Definition

Record of a TWU execution/work operation. Fields:
  • id (string) - Entry identifier
  • title (string) - Entry title
  • description (string) - Entry description
  • type (string) - Entry type (e.g., “TWU”)
  • status (string) - Execution status (e.g., “completed”, “in_progress”)
  • createdAt (timestamp) - Creation timestamp
  • updatedAt (timestamp) - Last update timestamp
  • entityId (string) - Related entity identifier
  • relatedEntity (string) - Related entity display name
  • actors (array) - Actor types: [“AI”], [“HUMAN”], or [“AI”, “HUMAN”]
  • activeTime (number) - Active time in seconds
  • cost (number) - Cost in dollars
  • policyStatus (string) - Policy compliance status: “compliant”, “non_compliant”, “review_required”
  • modelName (string) - TWU model name used

​
Use Cases

End User Use: View work executions, monitor compliance, analyze metrics Admin Use: Review policy compliance, audit work operations Developer Use: Query work ledger via API, build analytics dashboards UI Route:
  • /ledger - View work ledger entries
Source: Source: Feature Inventory

​
Troubleshooting

​
Object Not Found

Cause: Object ID is invalid or object doesn’t exist Solution:
  • Verify object ID is correct
  • Check if object exists in the instance
  • Ensure you have access to the instance
Source: Source: Feature Inventory

​
Cannot Access Object

Cause: Insufficient permissions or wrong instance Solution:
  • Verify you have appropriate role (Administrator, Manager, Editor, or Viewer)
  • Check you’re accessing the correct instance
  • Ensure object belongs to your instance
Source: Source: Feature Inventory