Skip to main content

API Concepts

This document outlines the core entities and their relationships within DataCovey, helping users understand how data is structured and linked.

Core Entities​

Tenant​

  • Represents a logical organization or customer using DataCovey.
  • Each user belongs to exactly one tenant.
  • Each project is owned by a single tenant.
  • Users can only access data within their tenant.

User​

  • Represents an individual user in the system.
  • Assigned a role (e.g., admin, user).
  • Always belongs to a single tenant.

Project​

  • A workspace within a tenant where datasets, tables, and queries are organized.
  • Owned by a single tenant.
  • Contains multiple datasets.
  • Users from the same tenant can collaborate on a project.

Dataset​

  • A collection of related tables in a project.
  • Owned by a single project.
  • Serves as a logical grouping for tables.

Table​

  • Represents a data structure inside a dataset.
  • Belongs to one dataset.
  • Stores structured data.
  • Can have import and export jobs associated.

Data Processing Entities​

Import Job​

  • Represents the import of data into a table.
  • Linked to one specific table.
  • Tracks the status (pending, running, completed, failed).

Export Job​

  • Represents the export of data from a table.
  • Linked to one specific table.
  • Tracks the status (pending, running, completed, failed).

Query​

  • Represents an SQL-like query executed on data within a project.
  • Belongs to a specific project.
  • Allows users to retrieve and process shared data.

Agent Gateway Entities​

Agent​

  • Represents an external AI agent that can be integrated with DataCovey.
  • Belongs to a single tenant.
  • Has a protocol (A2A or MCP) defining how it communicates.
  • Contains an endpoint URL where the agent service is hosted.
  • Has a status (active, inactive, error) indicating availability.
  • Stores capabilities and metadata as JSON.
  • Must be assigned to at least one project at all times.

Project-Agent Assignment​

  • Represents the many-to-many relationship between projects and agents.
  • Allows agents to be shared across multiple projects.
  • Can include an optional role for the agent within a project.
  • Ensures data isolation by restricting agent access to assigned projects only.

Agent Rate Limit​

  • Defines per-agent rate limiting configuration.
  • Controls maximum requests per second, minute, and hour.
  • Enforced by the Agent Gateway service to prevent abuse.
  • Each agent has exactly one rate limit configuration.

Agent Call Usage​

  • Tracks usage metrics for agent calls for billing and monitoring.
  • Records individual call details: HTTP status, request/response sizes, latency.
  • Provides daily aggregated usage for reporting and billing.
  • Belongs to a specific agent and tenant.

History Tracking​

For auditing purposes, history tables exist for all major entities, storing archival versions of records when changes occur.

History Tables​

Each of the following entities has a corresponding history table:

  • dataset_history
  • table_history
  • import_job_history
  • export_job_history
  • query_history
  • agent_history

Purpose:

  • Tracks inserts, updates, and deletions.
  • Helps with auditing and rollback.
  • Ensures data integrity over time.

Security & Access Control​

  • Every resource includes a tenant ID, ensuring strict data isolation.
  • Row-Level Security (RLS) enforces that users can only access records belonging to their tenant.
  • User roles determine their level of access.

Entity Relationship Diagram​

This diagram visually represents the relationships between core entities in DataCovey.