@robosystems/client 0.2.14 → 0.2.16

package/sdk.gen.ts

@@ -1,7 +1,7 @@
 // This file is auto-generated by @hey-api/openapi-ts
 
 import type { Options as ClientOptions, TDataShape, Client } from './client';
-import type { RegisterUserData, RegisterUserResponses, RegisterUserErrors, LoginUserData, LoginUserResponses, LoginUserErrors, LogoutUserData, LogoutUserResponses, GetCurrentAuthUserData, GetCurrentAuthUserResponses, GetCurrentAuthUserErrors, RefreshAuthSessionData, RefreshAuthSessionResponses, RefreshAuthSessionErrors, ResendVerificationEmailData, ResendVerificationEmailResponses, ResendVerificationEmailErrors, VerifyEmailData, VerifyEmailResponses, VerifyEmailErrors, GetPasswordPolicyData, GetPasswordPolicyResponses, CheckPasswordStrengthData, CheckPasswordStrengthResponses, CheckPasswordStrengthErrors, ForgotPasswordData, ForgotPasswordResponses, ForgotPasswordErrors, ValidateResetTokenData, ValidateResetTokenResponses, ValidateResetTokenErrors, ResetPasswordData, ResetPasswordResponses, ResetPasswordErrors, GenerateSsoTokenData, GenerateSsoTokenResponses, GenerateSsoTokenErrors, SsoTokenExchangeData, SsoTokenExchangeResponses, SsoTokenExchangeErrors, CompleteSsoAuthData, CompleteSsoAuthResponses, CompleteSsoAuthErrors, GetCaptchaConfigData, GetCaptchaConfigResponses, GetServiceStatusData, GetServiceStatusResponses, GetCurrentUserData, GetCurrentUserResponses, UpdateUserData, UpdateUserResponses, UpdateUserErrors, UpdateUserPasswordData, UpdateUserPasswordResponses, UpdateUserPasswordErrors, ListUserApiKeysData, ListUserApiKeysResponses, CreateUserApiKeyData, CreateUserApiKeyResponses, CreateUserApiKeyErrors, RevokeUserApiKeyData, RevokeUserApiKeyResponses, RevokeUserApiKeyErrors, UpdateUserApiKeyData, UpdateUserApiKeyResponses, UpdateUserApiKeyErrors, ListUserOrgsData, ListUserOrgsResponses, CreateOrgData, CreateOrgResponses, CreateOrgErrors, GetOrgData, GetOrgResponses, GetOrgErrors, UpdateOrgData, UpdateOrgResponses, UpdateOrgErrors, ListOrgGraphsData, ListOrgGraphsResponses, ListOrgGraphsErrors, ListOrgMembersData, ListOrgMembersResponses, ListOrgMembersErrors, InviteOrgMemberData, InviteOrgMemberResponses, InviteOrgMemberErrors, RemoveOrgMemberData, RemoveOrgMemberResponses, RemoveOrgMemberErrors, UpdateOrgMemberRoleData, UpdateOrgMemberRoleResponses, UpdateOrgMemberRoleErrors, GetOrgLimitsData, GetOrgLimitsResponses, GetOrgLimitsErrors, GetOrgUsageData, GetOrgUsageResponses, GetOrgUsageErrors, ListConnectionsData, ListConnectionsResponses, ListConnectionsErrors, CreateConnectionData, CreateConnectionResponses, CreateConnectionErrors, GetConnectionOptionsData, GetConnectionOptionsResponses, GetConnectionOptionsErrors, ExchangeLinkTokenData, ExchangeLinkTokenResponses, ExchangeLinkTokenErrors, CreateLinkTokenData, CreateLinkTokenResponses, CreateLinkTokenErrors, InitOAuthData, InitOAuthResponses, InitOAuthErrors, OauthCallbackData, OauthCallbackResponses, OauthCallbackErrors, DeleteConnectionData, DeleteConnectionResponses, DeleteConnectionErrors, GetConnectionData, GetConnectionResponses, GetConnectionErrors, SyncConnectionData, SyncConnectionResponses, SyncConnectionErrors, ListAgentsData, ListAgentsResponses, ListAgentsErrors, AutoSelectAgentData, AutoSelectAgentResponses, AutoSelectAgentErrors, GetAgentMetadataData, GetAgentMetadataResponses, GetAgentMetadataErrors, ExecuteSpecificAgentData, ExecuteSpecificAgentResponses, ExecuteSpecificAgentErrors, BatchProcessQueriesData, BatchProcessQueriesResponses, BatchProcessQueriesErrors, RecommendAgentData, RecommendAgentResponses, RecommendAgentErrors, ListMcpToolsData, ListMcpToolsResponses, ListMcpToolsErrors, CallMcpToolData, CallMcpToolResponses, CallMcpToolErrors, ListBackupsData, ListBackupsResponses, ListBackupsErrors, CreateBackupData, CreateBackupResponses, CreateBackupErrors, GetBackupDownloadUrlData, GetBackupDownloadUrlResponses, GetBackupDownloadUrlErrors, RestoreBackupData, RestoreBackupResponses, RestoreBackupErrors, GetBackupStatsData, GetBackupStatsResponses, GetBackupStatsErrors, GetGraphMetricsData, GetGraphMetricsResponses, GetGraphMetricsErrors, GetGraphUsageAnalyticsData, GetGraphUsageAnalyticsResponses, GetGraphUsageAnalyticsErrors, ExecuteCypherQueryData, ExecuteCypherQueryResponses, ExecuteCypherQueryErrors, GetGraphSchemaData, GetGraphSchemaResponses, GetGraphSchemaErrors, ExportGraphSchemaData, ExportGraphSchemaResponses, ExportGraphSchemaErrors, ValidateSchemaData, ValidateSchemaResponses, ValidateSchemaErrors, GetCreditSummaryData, GetCreditSummaryResponses, GetCreditSummaryErrors, ListCreditTransactionsData, ListCreditTransactionsResponses, ListCreditTransactionsErrors, CheckCreditBalanceData, CheckCreditBalanceResponses, CheckCreditBalanceErrors, GetStorageUsageData, GetStorageUsageResponses, GetStorageUsageErrors, CheckStorageLimitsData, CheckStorageLimitsResponses, CheckStorageLimitsErrors, GetDatabaseHealthData, GetDatabaseHealthResponses, GetDatabaseHealthErrors, GetDatabaseInfoData, GetDatabaseInfoResponses, GetDatabaseInfoErrors, GetGraphLimitsData, GetGraphLimitsResponses, GetGraphLimitsErrors, ListSubgraphsData, ListSubgraphsResponses, ListSubgraphsErrors, CreateSubgraphData, CreateSubgraphResponses, CreateSubgraphErrors, DeleteSubgraphData, DeleteSubgraphResponses, DeleteSubgraphErrors, GetSubgraphInfoData, GetSubgraphInfoResponses, GetSubgraphInfoErrors, GetSubgraphQuotaData, GetSubgraphQuotaResponses, GetSubgraphQuotaErrors, GetGraphSubscriptionData, GetGraphSubscriptionResponses, GetGraphSubscriptionErrors, CreateRepositorySubscriptionData, CreateRepositorySubscriptionResponses, CreateRepositorySubscriptionErrors, UpgradeSubscriptionData, UpgradeSubscriptionResponses, UpgradeSubscriptionErrors, ListTablesData, ListTablesResponses, ListTablesErrors, ListTableFilesData, ListTableFilesResponses, ListTableFilesErrors, GetUploadUrlData, GetUploadUrlResponses, GetUploadUrlErrors, DeleteFileData, DeleteFileResponses, DeleteFileErrors, GetFileInfoData, GetFileInfoResponses, GetFileInfoErrors, UpdateFileStatusData, UpdateFileStatusResponses, UpdateFileStatusErrors, IngestTablesData, IngestTablesResponses, IngestTablesErrors, QueryTablesData, QueryTablesResponses, QueryTablesErrors, GetGraphsData, GetGraphsResponses, GetGraphsErrors, CreateGraphData, CreateGraphResponses, CreateGraphErrors, GetAvailableExtensionsData, GetAvailableExtensionsResponses, GetAvailableExtensionsErrors, GetAvailableGraphTiersData, GetAvailableGraphTiersResponses, GetAvailableGraphTiersErrors, SelectGraphData, SelectGraphResponses, SelectGraphErrors, GetServiceOfferingsData, GetServiceOfferingsResponses, GetServiceOfferingsErrors, StreamOperationEventsData, StreamOperationEventsResponses, StreamOperationEventsErrors, GetOperationStatusData, GetOperationStatusResponses, GetOperationStatusErrors, CancelOperationData, CancelOperationResponses, CancelOperationErrors, GetOrgBillingCustomerData, GetOrgBillingCustomerResponses, GetOrgBillingCustomerErrors, CreatePortalSessionData, CreatePortalSessionResponses, CreatePortalSessionErrors, ListOrgSubscriptionsData, ListOrgSubscriptionsResponses, ListOrgSubscriptionsErrors, GetOrgSubscriptionData, GetOrgSubscriptionResponses, GetOrgSubscriptionErrors, CancelOrgSubscriptionData, CancelOrgSubscriptionResponses, CancelOrgSubscriptionErrors, ListOrgInvoicesData, ListOrgInvoicesResponses, ListOrgInvoicesErrors, GetOrgUpcomingInvoiceData, GetOrgUpcomingInvoiceResponses, GetOrgUpcomingInvoiceErrors, CreateCheckoutSessionData, CreateCheckoutSessionResponses, CreateCheckoutSessionErrors, GetCheckoutStatusData, GetCheckoutStatusResponses, GetCheckoutStatusErrors } from './types.gen';
+import type { RegisterUserData, RegisterUserResponses, RegisterUserErrors, LoginUserData, LoginUserResponses, LoginUserErrors, LogoutUserData, LogoutUserResponses, GetCurrentAuthUserData, GetCurrentAuthUserResponses, GetCurrentAuthUserErrors, RefreshAuthSessionData, RefreshAuthSessionResponses, RefreshAuthSessionErrors, ResendVerificationEmailData, ResendVerificationEmailResponses, ResendVerificationEmailErrors, VerifyEmailData, VerifyEmailResponses, VerifyEmailErrors, GetPasswordPolicyData, GetPasswordPolicyResponses, CheckPasswordStrengthData, CheckPasswordStrengthResponses, CheckPasswordStrengthErrors, ForgotPasswordData, ForgotPasswordResponses, ForgotPasswordErrors, ValidateResetTokenData, ValidateResetTokenResponses, ValidateResetTokenErrors, ResetPasswordData, ResetPasswordResponses, ResetPasswordErrors, GenerateSsoTokenData, GenerateSsoTokenResponses, GenerateSsoTokenErrors, SsoTokenExchangeData, SsoTokenExchangeResponses, SsoTokenExchangeErrors, CompleteSsoAuthData, CompleteSsoAuthResponses, CompleteSsoAuthErrors, GetCaptchaConfigData, GetCaptchaConfigResponses, GetServiceStatusData, GetServiceStatusResponses, GetCurrentUserData, GetCurrentUserResponses, UpdateUserData, UpdateUserResponses, UpdateUserErrors, UpdateUserPasswordData, UpdateUserPasswordResponses, UpdateUserPasswordErrors, ListUserApiKeysData, ListUserApiKeysResponses, CreateUserApiKeyData, CreateUserApiKeyResponses, CreateUserApiKeyErrors, RevokeUserApiKeyData, RevokeUserApiKeyResponses, RevokeUserApiKeyErrors, UpdateUserApiKeyData, UpdateUserApiKeyResponses, UpdateUserApiKeyErrors, ListUserOrgsData, ListUserOrgsResponses, CreateOrgData, CreateOrgResponses, CreateOrgErrors, GetOrgData, GetOrgResponses, GetOrgErrors, UpdateOrgData, UpdateOrgResponses, UpdateOrgErrors, ListOrgGraphsData, ListOrgGraphsResponses, ListOrgGraphsErrors, ListOrgMembersData, ListOrgMembersResponses, ListOrgMembersErrors, InviteOrgMemberData, InviteOrgMemberResponses, InviteOrgMemberErrors, RemoveOrgMemberData, RemoveOrgMemberResponses, RemoveOrgMemberErrors, UpdateOrgMemberRoleData, UpdateOrgMemberRoleResponses, UpdateOrgMemberRoleErrors, GetOrgLimitsData, GetOrgLimitsResponses, GetOrgLimitsErrors, GetOrgUsageData, GetOrgUsageResponses, GetOrgUsageErrors, ListConnectionsData, ListConnectionsResponses, ListConnectionsErrors, CreateConnectionData, CreateConnectionResponses, CreateConnectionErrors, GetConnectionOptionsData, GetConnectionOptionsResponses, GetConnectionOptionsErrors, ExchangeLinkTokenData, ExchangeLinkTokenResponses, ExchangeLinkTokenErrors, CreateLinkTokenData, CreateLinkTokenResponses, CreateLinkTokenErrors, InitOAuthData, InitOAuthResponses, InitOAuthErrors, OauthCallbackData, OauthCallbackResponses, OauthCallbackErrors, DeleteConnectionData, DeleteConnectionResponses, DeleteConnectionErrors, GetConnectionData, GetConnectionResponses, GetConnectionErrors, SyncConnectionData, SyncConnectionResponses, SyncConnectionErrors, ListAgentsData, ListAgentsResponses, ListAgentsErrors, AutoSelectAgentData, AutoSelectAgentResponses, AutoSelectAgentErrors, GetAgentMetadataData, GetAgentMetadataResponses, GetAgentMetadataErrors, ExecuteSpecificAgentData, ExecuteSpecificAgentResponses, ExecuteSpecificAgentErrors, BatchProcessQueriesData, BatchProcessQueriesResponses, BatchProcessQueriesErrors, RecommendAgentData, RecommendAgentResponses, RecommendAgentErrors, ListMcpToolsData, ListMcpToolsResponses, ListMcpToolsErrors, CallMcpToolData, CallMcpToolResponses, CallMcpToolErrors, ListBackupsData, ListBackupsResponses, ListBackupsErrors, CreateBackupData, CreateBackupResponses, CreateBackupErrors, GetBackupDownloadUrlData, GetBackupDownloadUrlResponses, GetBackupDownloadUrlErrors, RestoreBackupData, RestoreBackupResponses, RestoreBackupErrors, GetBackupStatsData, GetBackupStatsResponses, GetBackupStatsErrors, GetGraphMetricsData, GetGraphMetricsResponses, GetGraphMetricsErrors, GetGraphUsageAnalyticsData, GetGraphUsageAnalyticsResponses, GetGraphUsageAnalyticsErrors, ExecuteCypherQueryData, ExecuteCypherQueryResponses, ExecuteCypherQueryErrors, GetGraphSchemaData, GetGraphSchemaResponses, GetGraphSchemaErrors, ExportGraphSchemaData, ExportGraphSchemaResponses, ExportGraphSchemaErrors, ValidateSchemaData, ValidateSchemaResponses, ValidateSchemaErrors, GetCreditSummaryData, GetCreditSummaryResponses, GetCreditSummaryErrors, ListCreditTransactionsData, ListCreditTransactionsResponses, ListCreditTransactionsErrors, CheckCreditBalanceData, CheckCreditBalanceResponses, CheckCreditBalanceErrors, GetStorageUsageData, GetStorageUsageResponses, GetStorageUsageErrors, CheckStorageLimitsData, CheckStorageLimitsResponses, CheckStorageLimitsErrors, GetDatabaseHealthData, GetDatabaseHealthResponses, GetDatabaseHealthErrors, GetDatabaseInfoData, GetDatabaseInfoResponses, GetDatabaseInfoErrors, GetGraphLimitsData, GetGraphLimitsResponses, GetGraphLimitsErrors, ListSubgraphsData, ListSubgraphsResponses, ListSubgraphsErrors, CreateSubgraphData, CreateSubgraphResponses, CreateSubgraphErrors, DeleteSubgraphData, DeleteSubgraphResponses, DeleteSubgraphErrors, GetSubgraphInfoData, GetSubgraphInfoResponses, GetSubgraphInfoErrors, GetSubgraphQuotaData, GetSubgraphQuotaResponses, GetSubgraphQuotaErrors, GetGraphSubscriptionData, GetGraphSubscriptionResponses, GetGraphSubscriptionErrors, CreateRepositorySubscriptionData, CreateRepositorySubscriptionResponses, CreateRepositorySubscriptionErrors, UpgradeSubscriptionData, UpgradeSubscriptionResponses, UpgradeSubscriptionErrors, ListTablesData, ListTablesResponses, ListTablesErrors, QueryTablesData, QueryTablesResponses, QueryTablesErrors, CreateViewData, CreateViewResponses, CreateViewErrors, SaveViewData, SaveViewResponses, SaveViewErrors, GetMaterializationStatusData, GetMaterializationStatusResponses, GetMaterializationStatusErrors, MaterializeGraphData, MaterializeGraphResponses, MaterializeGraphErrors, ListFilesData, ListFilesResponses, ListFilesErrors, CreateFileUploadData, CreateFileUploadResponses, CreateFileUploadErrors, DeleteFileData, DeleteFileResponses, DeleteFileErrors, GetFileData, GetFileResponses, GetFileErrors, UpdateFileData, UpdateFileResponses, UpdateFileErrors, GetGraphsData, GetGraphsResponses, GetGraphsErrors, CreateGraphData, CreateGraphResponses, CreateGraphErrors, GetAvailableExtensionsData, GetAvailableExtensionsResponses, GetAvailableExtensionsErrors, GetAvailableGraphTiersData, GetAvailableGraphTiersResponses, GetAvailableGraphTiersErrors, SelectGraphData, SelectGraphResponses, SelectGraphErrors, GetServiceOfferingsData, GetServiceOfferingsResponses, GetServiceOfferingsErrors, StreamOperationEventsData, StreamOperationEventsResponses, StreamOperationEventsErrors, GetOperationStatusData, GetOperationStatusResponses, GetOperationStatusErrors, CancelOperationData, CancelOperationResponses, CancelOperationErrors, GetOrgBillingCustomerData, GetOrgBillingCustomerResponses, GetOrgBillingCustomerErrors, CreatePortalSessionData, CreatePortalSessionResponses, CreatePortalSessionErrors, ListOrgSubscriptionsData, ListOrgSubscriptionsResponses, ListOrgSubscriptionsErrors, GetOrgSubscriptionData, GetOrgSubscriptionResponses, GetOrgSubscriptionErrors, CancelOrgSubscriptionData, CancelOrgSubscriptionResponses, CancelOrgSubscriptionErrors, ListOrgInvoicesData, ListOrgInvoicesResponses, ListOrgInvoicesErrors, GetOrgUpcomingInvoiceData, GetOrgUpcomingInvoiceResponses, GetOrgUpcomingInvoiceErrors, CreateCheckoutSessionData, CreateCheckoutSessionResponses, CreateCheckoutSessionErrors, GetCheckoutStatusData, GetCheckoutStatusResponses, GetCheckoutStatusErrors } from './types.gen';
 import { client as _heyApiClient } from './client.gen';
 
 export type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean> = ClientOptions<TData, ThrowOnError> & {
@@ -1725,11 +1725,14 @@ export const getGraphUsageAnalytics = <ThrowOnError extends boolean = false>(opt
 };
 
 /**
- * Execute Cypher Query (Read-Only)
- * Execute a read-only Cypher query with intelligent response optimization.
+ * Execute Cypher Query
+ * Execute a Cypher query with intelligent response optimization.
  *
- * **IMPORTANT: This endpoint is READ-ONLY.** Write operations (CREATE, MERGE, SET, DELETE) are not allowed.
- * To load data into your graph, use the staging pipeline:
+ * **IMPORTANT: Write operations depend on graph type:**
+ * - **Main Graphs**: READ-ONLY. Write operations (CREATE, MERGE, SET, DELETE) are not allowed.
+ * - **Subgraphs**: WRITE-ENABLED. Full Cypher write operations are supported for development and report creation.
+ *
+ * To load data into main graphs, use the staging pipeline:
  * 1. Create file upload: `POST /v1/graphs/{graph_id}/tables/{table_name}/files`
  * 2. Ingest to graph: `POST /v1/graphs/{graph_id}/tables/ingest`
  *
@@ -2306,7 +2309,7 @@ export const listSubgraphs = <ThrowOnError extends boolean = false>(options: Opt
 
 /**
  * Create Subgraph
- * Create a new subgraph within a parent graph.
+ * Create a new subgraph within a parent graph, with optional data forking.
  *
  * **Requirements:**
  * - Valid authentication
@@ -2316,9 +2319,18 @@ export const listSubgraphs = <ThrowOnError extends boolean = false>(options: Opt
  * - Must be within subgraph quota limits
  * - Subgraph name must be unique within the parent graph
  *
+ * **Fork Mode:**
+ * When `fork_parent=true`, the operation:
+ * - Returns immediately with an operation_id for SSE monitoring
+ * - Copies data from parent graph to the new subgraph
+ * - Supports selective forking via metadata.fork_options
+ * - Tracks progress in real-time via SSE
+ *
  * **Returns:**
- * - Created subgraph details including its unique ID
- * - Subgraph ID format: `{parent_id}_{subgraph_name}` (e.g., kg1234567890abcdef_dev)
+ * - Without fork: Immediate SubgraphResponse with created subgraph details
+ * - With fork: Operation response with SSE monitoring endpoint
+ *
+ * **Subgraph ID format:** `{parent_id}_{subgraph_name}` (e.g., kg1234567890abcdef_dev)
  *
  * **Usage:**
  * - Subgraphs share parent's credit pool
@@ -2614,44 +2626,66 @@ export const listTables = <ThrowOnError extends boolean = false>(options: Option
 };
 
 /**
- * List Files in Staging Table
- * List all files uploaded to a staging table with comprehensive metadata.
+ * Query Staging Tables with SQL
+ * Execute SQL queries on DuckDB staging tables for data inspection and validation.
+ *
+ * Query raw staging data directly with SQL before ingestion into the graph database.
+ * Useful for data quality checks, validation, and exploratory analysis.
+ *
+ * **Security Best Practice - Use Parameterized Queries:**
+ * ALWAYS use query parameters instead of string concatenation to prevent SQL injection:
+ * - ✅ SAFE: `SELECT * FROM Entity WHERE type = ? LIMIT ?` with `parameters: ["Company", 100]`
+ * - ❌ UNSAFE: `SELECT * FROM Entity WHERE type = 'Company' LIMIT 100` with user input concatenated into SQL string
  *
- * Get a complete inventory of all files in a staging table, including upload status,
- * file sizes, row counts, and S3 locations. Essential for monitoring upload progress
- * and validating data before ingestion.
+ * Query parameters provide automatic escaping and type safety. Use `?` placeholders with parameters array.
  *
  * **Use Cases:**
- * - Monitor file upload progress
- * - Verify files are ready for ingestion
- * - Check file formats and sizes
- * - Track storage usage per table
- * - Identify failed or incomplete uploads
- * - Pre-ingestion validation
+ * - Validate data quality before graph ingestion
+ * - Inspect row-level data for debugging
+ * - Run analytics on staging tables
+ * - Check for duplicates, nulls, or data issues
+ * - Preview data transformations
  *
- * **Returned Metadata:**
- * - File ID, name, and format (parquet, csv, json)
- * - Size in bytes and row count (if available)
- * - Upload status and method
- * - Creation and upload timestamps
- * - S3 key for reference
+ * **Workflow:**
+ * 1. Upload data files via `POST /tables/{table_name}/files`
+ * 2. Query staging tables to validate: `POST /tables/query`
+ * 3. Fix any data issues by re-uploading
+ * 4. Ingest validated data: `POST /tables/ingest`
  *
- * **Upload Status Values:**
- * - `pending`: Upload URL generated, awaiting upload
- * - `uploaded`: Successfully uploaded, ready for ingestion
- * - `disabled`: Excluded from ingestion
- * - `archived`: Soft deleted
- * - `failed`: Upload failed
+ * **Supported SQL:**
+ * - Full DuckDB SQL syntax
+ * - SELECT, JOIN, WHERE, GROUP BY, ORDER BY
+ * - Aggregations, window functions, CTEs
+ * - Multiple table joins across staging area
  *
- * **Important Notes:**
- * - Only `uploaded` files are ingested
- * - Check `row_count` to estimate data volume
- * - Use `total_size_bytes` for storage monitoring
- * - Files with `failed` status should be deleted and re-uploaded
- * - File listing is included - no credit consumption
+ * **Common Operations:**
+ * - Count rows: `SELECT COUNT(*) FROM Entity`
+ * - Filter by type: `SELECT * FROM Entity WHERE entity_type = ? LIMIT ?` with `parameters: ["Company", 100]`
+ * - Check for nulls: `SELECT * FROM Entity WHERE name IS NULL LIMIT 10`
+ * - Find duplicates: `SELECT identifier, COUNT(*) as cnt FROM Entity GROUP BY identifier HAVING COUNT(*) > 1`
+ * - Filter amounts: `SELECT * FROM Transaction WHERE amount > ? AND date >= ?` with `parameters: [1000, "2024-01-01"]`
+ *
+ * **Limits:**
+ * - Query timeout: 30 seconds
+ * - Result limit: 10,000 rows (use LIMIT clause)
+ * - Read-only: No INSERT, UPDATE, DELETE
+ * - User's tables only: Cannot query other users' data
+ *
+ * **Subgraph Support:**
+ * This endpoint accepts both parent graph IDs and subgraph IDs.
+ * - Parent graph: Use `graph_id` like `kg0123456789abcdef`
+ * - Subgraph: Use full subgraph ID like `kg0123456789abcdef_dev`
+ * Each subgraph has its own independent staging tables.
+ *
+ * **Shared Repositories:**
+ * Shared repositories (SEC, etc.) do not allow direct SQL queries.
+ * Use the graph query endpoint instead: `POST /v1/graphs/{graph_id}/query`
+ *
+ * **Note:**
+ * Staging table queries are included - no credit consumption
  */
-export const listTableFiles = <ThrowOnError extends boolean = false>(options: Options<ListTableFilesData, ThrowOnError>) => {
-    return (options.client ?? _heyApiClient).get<ListTableFilesResponses, ListTableFilesErrors, ThrowOnError>({
+export const queryTables = <ThrowOnError extends boolean = false>(options: Options<QueryTablesData, ThrowOnError>) => {
+    return (options.client ?? _heyApiClient).post<QueryTablesResponses, QueryTablesErrors, ThrowOnError>({
         security: [
             {
                 name: 'X-API-Key',
@@ -2662,56 +2696,36 @@ export const listTableFiles = <ThrowOnError extends boolean = false>(options: Op
                 type: 'http'
             }
         ],
-        url: '/v1/graphs/{graph_id}/tables/{table_name}/files',
-        ...options
+        url: '/v1/graphs/{graph_id}/tables/query',
+        ...options,
+        headers: {
+            'Content-Type': 'application/json',
+            ...options.headers
+        }
     });
 };
 
 /**
- * Get File Upload URL
- * Generate a presigned S3 URL for secure file upload.
- *
- * Initiates file upload to a staging table by generating a secure, time-limited
- * presigned S3 URL. Files are uploaded directly to S3, bypassing the API for
- * optimal performance.
- *
- * **Upload Workflow:**
- * 1. Call this endpoint to get presigned URL
- * 2. PUT file directly to S3 URL
- * 3. Call PATCH /tables/files/{file_id} with status='uploaded'
- * 4. Backend validates file and calculates metrics
- * 5. File ready for ingestion
- *
- * **Supported Formats:**
- * - Parquet (`application/x-parquet` with `.parquet` extension)
- * - CSV (`text/csv` with `.csv` extension)
- * - JSON (`application/json` with `.json` extension)
- *
- * **Validation:**
- * - File extension must match content type
- * - File name 1-255 characters
- * - No path traversal characters (.. / \)
- * - Auto-creates table if it doesn't exist
+ * Create View
+ * Generate financial report view from data source (dual-mode support).
  *
- * **Auto-Table Creation:**
- * Tables are automatically created on first file upload with type inferred from name
- * (e.g., "Transaction" → relationship) and empty schema populated during ingestion.
+ * **Mode 1: Transaction Aggregation (generate_from_transactions)**
+ * - Aggregates raw transaction data to trial balance
+ * - Creates facts on-demand
+ * - Shows real-time reporting from source of truth
  *
- * **Subgraph Support:**
- * This endpoint accepts both parent graph IDs and subgraph IDs.
- * - Parent graph: Use `graph_id` like `kg0123456789abcdef`
- * - Subgraph: Use full subgraph ID like `kg0123456789abcdef_dev`
- * Each subgraph has completely isolated S3 staging areas and tables. Files uploaded
- * to one subgraph do not appear in other subgraphs.
+ * **Mode 2: Existing Facts (pivot_existing_facts)**
+ * - Queries existing Fact nodes
+ * - Supports multi-dimensional analysis
+ * - Works with SEC filings and pre-computed facts
  *
- * **Important Notes:**
- * - Presigned URLs expire (default: 1 hour)
- * - Use appropriate Content-Type header when uploading to S3
- * - File extension must match content type
- * - Upload URL generation is included - no credit consumption
+ * Both modes:
+ * - Build FactGrid from data
+ * - Generate pivot table presentation
+ * - Return consistent response format
  */
-export const getUploadUrl = <ThrowOnError extends boolean = false>(options: Options<GetUploadUrlData, ThrowOnError>) => {
-    return (options.client ?? _heyApiClient).post<GetUploadUrlResponses, GetUploadUrlErrors, ThrowOnError>({
+export const createView = <ThrowOnError extends boolean = false>(options: Options<CreateViewData, ThrowOnError>) => {
+    return (options.client ?? _heyApiClient).post<CreateViewResponses, CreateViewErrors, ThrowOnError>({
         security: [
             {
                 name: 'X-API-Key',
@@ -2722,7 +2736,7 @@ export const getUploadUrl = <ThrowOnError extends boolean = false>(options: Opti
                 type: 'http'
             }
         ],
-        url: '/v1/graphs/{graph_id}/tables/{table_name}/files',
+        url: '/v1/graphs/{graph_id}/views',
         ...options,
         headers: {
             'Content-Type': 'application/json',
@@ -2732,41 +2746,39 @@ export const getUploadUrl = <ThrowOnError extends boolean = false>(options: Opti
 };
 
 /**
- * Delete File from Staging
- * Delete a file from S3 storage and database tracking.
+ * Save View
+ * Save or update view as materialized report in the graph.
  *
- * Remove unwanted, duplicate, or incorrect files from staging tables before ingestion.
- * The file is deleted from both S3 and database tracking, and table statistics
- * are automatically recalculated.
+ * Converts computed view results into persistent Report, Fact, and Structure nodes.
+ * This establishes what data exists in the subgraph, which then defines what
+ * needs to be exported for publishing to the parent graph.
  *
- * **Use Cases:**
- * - Remove duplicate uploads
- * - Delete files with incorrect data
- * - Clean up failed uploads
- * - Fix data quality issues before ingestion
- * - Manage storage usage
+ * **Create Mode** (no report_id provided):
+ * - Generates new report_id from entity + period + report type
+ * - Creates new Report, Facts, and Structures
  *
- * **What Happens:**
- * 1. File deleted from S3 storage
- * 2. Database tracking record removed
- * 3. Table statistics recalculated (file count, size, row count)
- * 4. DuckDB automatically excludes file from future queries
+ * **Update Mode** (report_id provided):
+ * - Deletes all existing Facts and Structures for the report
+ * - Updates Report metadata
+ * - Creates fresh Facts and Structures from current view
+ * - Useful for refreshing reports with updated data or view configurations
  *
- * **Security:**
- * - Write access required (verified via auth)
- * - Shared repositories block file deletions
- * - Full audit trail of deletion operations
- * - Cannot delete after ingestion to graph
+ * **This is NOT publishing** - it only creates nodes in the subgraph workspace.
+ * Publishing (export → parquet → parent ingest) happens separately.
  *
- * **Important Notes:**
- * - Delete files before ingestion for best results
- * - Table statistics update automatically
- * - No need to refresh DuckDB - exclusion is automatic
- * - Consider re-uploading corrected version after deletion
- * - File deletion is included - no credit consumption
+ * Creates/Updates:
+ * - Report node with metadata
+ * - Fact nodes with all aspects (period, entity, element, unit)
+ * - PresentationStructure nodes (how facts are displayed)
+ * - CalculationStructure nodes (how facts roll up)
+ *
+ * Returns:
+ * - report_id: Unique identifier used as parquet export prefix
+ * - parquet_export_prefix: Filename prefix for future exports
+ * - All created facts and structures
  */
-export const deleteFile = <ThrowOnError extends boolean = false>(options: Options<DeleteFileData, ThrowOnError>) => {
-    return (options.client ?? _heyApiClient).delete<DeleteFileResponses, DeleteFileErrors, ThrowOnError>({
+export const saveView = <ThrowOnError extends boolean = false>(options: Options<SaveViewData, ThrowOnError>) => {
+    return (options.client ?? _heyApiClient).post<SaveViewResponses, SaveViewErrors, ThrowOnError>({
         security: [
             {
                 name: 'X-API-Key',
@@ -2777,31 +2789,44 @@ export const deleteFile = <ThrowOnError extends boolean = false>(options: Option
                 type: 'http'
             }
         ],
-        url: '/v1/graphs/{graph_id}/tables/files/{file_id}',
-        ...options
+        url: '/v1/graphs/{graph_id}/views/save',
+        ...options,
+        headers: {
+            'Content-Type': 'application/json',
+            ...options.headers
+        }
     });
 };
 
 /**
- * Get File Information
- * Get detailed information about a specific file.
+ * Get Materialization Status
+ * Get current materialization status for the graph.
+ *
+ * Shows whether the graph is stale (DuckDB has changes not yet in graph database),
+ * when it was last materialized, and how long since last materialization.
  *
- * Retrieve comprehensive metadata for a single file, including upload status,
- * size, row count, and timestamps. Useful for validating individual files
- * before ingestion.
+ * **Status Information:**
+ * - Whether graph is currently stale
+ * - Reason for staleness if applicable
+ * - When graph became stale
+ * - When graph was last materialized
+ * - Total materialization count
+ * - Hours since last materialization
  *
  * **Use Cases:**
- * - Validate file upload completion
- * - Check file metadata before ingestion
- * - Debug upload issues
- * - Verify file format and size
- * - Track file lifecycle
+ * - Decide if materialization is needed
+ * - Monitor graph freshness
+ * - Track materialization history
+ * - Understand data pipeline state
  *
- * **Note:**
- * File info retrieval is included - no credit consumption
+ * **Important Notes:**
+ * - Stale graph means DuckDB has changes not in graph
+ * - Graph becomes stale after file deletions
+ * - Materialization clears staleness
+ * - Status retrieval is included - no credit consumption
  */
-export const getFileInfo = <ThrowOnError extends boolean = false>(options: Options<GetFileInfoData, ThrowOnError>) => {
-    return (options.client ?? _heyApiClient).get<GetFileInfoResponses, GetFileInfoErrors, ThrowOnError>({
+export const getMaterializationStatus = <ThrowOnError extends boolean = false>(options: Options<GetMaterializationStatusData, ThrowOnError>) => {
+    return (options.client ?? _heyApiClient).get<GetMaterializationStatusResponses, GetMaterializationStatusErrors, ThrowOnError>({
         security: [
             {
                 name: 'X-API-Key',
@@ -2812,52 +2837,67 @@ export const getFileInfo = <ThrowOnError extends boolean = false>(options: Optio
                 type: 'http'
             }
         ],
-        url: '/v1/graphs/{graph_id}/tables/files/{file_id}',
+        url: '/v1/graphs/{graph_id}/materialize/status',
         ...options
     });
 };
 
 /**
- * Update File Upload Status
- * Update file status after upload completes.
+ * Materialize Graph from DuckDB
+ * Rebuild entire graph from DuckDB staging tables (materialized view pattern).
  *
- * Marks files as uploaded after successful S3 upload. The backend validates
- * the file, calculates size and row count, enforces storage limits, and
- * registers the DuckDB table for queries.
+ * This endpoint rebuilds the complete graph database from the current state of DuckDB
+ * staging tables. It automatically discovers all tables, ingests them in the correct
+ * order (nodes before relationships), and clears the staleness flag.
  *
- * **Status Values:**
- * - `uploaded`: File successfully uploaded to S3 (triggers validation)
- * - `disabled`: Exclude file from ingestion
- * - `archived`: Soft delete file
- *
- * **What Happens on 'uploaded' Status:**
- * 1. Verify file exists in S3
- * 2. Calculate actual file size
- * 3. Enforce tier storage limits
- * 4. Calculate or estimate row count
- * 5. Update table statistics
- * 6. Register DuckDB external table
- * 7. File ready for ingestion
- *
- * **Row Count Calculation:**
- * - **Parquet**: Exact count from file metadata
- * - **CSV**: Count rows (minus header)
- * - **JSON**: Count array elements
- * - **Fallback**: Estimate from file size if reading fails
- *
- * **Storage Limits:**
- * Enforced per subscription tier. Returns HTTP 413 if limit exceeded.
- * Check current usage before large uploads.
+ * **When to Use:**
+ * - After batch uploads (files uploaded with ingest_to_graph=false)
+ * - After cascade file deletions (graph marked stale)
+ * - To ensure graph consistency with DuckDB state
+ * - Periodic full refresh
  *
- * **Important Notes:**
- * - Always call this after S3 upload completes
- * - Check response for actual row count
- * - Storage limit errors (413) mean tier upgrade needed
- * - DuckDB registration failures are non-fatal (retried later)
- * - Status updates are included - no credit consumption
+ * **What Happens:**
+ * 1. Discovers all tables for the graph from PostgreSQL registry
+ * 2. Sorts tables (nodes before relationships)
+ * 3. Ingests all tables from DuckDB to graph in order
+ * 4. Clears staleness flag on success
+ * 5. Returns detailed materialization report
+ *
+ * **Staleness Check:**
+ * By default, only materializes if graph is stale (after deletions or missed ingestions).
+ * Use `force=true` to rebuild regardless of staleness.
+ *
+ * **Rebuild Feature:**
+ * Setting `rebuild=true` regenerates the entire graph database from scratch:
+ * - Deletes existing graph database
+ * - Recreates with fresh schema from active GraphSchema
+ * - Ingests all data files
+ * - Safe operation - DuckDB is source of truth
+ * - Useful for schema changes or data corrections
+ * - Graph marked as 'rebuilding' during process
+ *
+ * **Table Ordering:**
+ * Node tables (PascalCase) are ingested before relationship tables (UPPERCASE) to
+ * ensure referential integrity.
+ *
+ * **Error Handling:**
+ * With `ignore_errors=true` (default), continues materializing even if individual
+ * rows fail. Failed rows are logged but don't stop the process.
+ *
+ * **Concurrency Control:**
+ * Only one materialization can run per graph at a time. If another materialization is in progress,
+ * you'll receive a 409 Conflict error. The distributed lock automatically expires after
+ * the configured TTL (default: 1 hour) to prevent deadlocks from failed materializations.
+ *
+ * **Performance:**
+ * Full graph materialization can take minutes for large datasets. Consider running
+ * during off-peak hours for production systems.
+ *
+ * **Credits:**
+ * Materialization is included - no credit consumption
  */
-export const updateFileStatus = <ThrowOnError extends boolean = false>(options: Options<UpdateFileStatusData, ThrowOnError>) => {
-    return (options.client ?? _heyApiClient).patch<UpdateFileStatusResponses, UpdateFileStatusErrors, ThrowOnError>({
+export const materializeGraph = <ThrowOnError extends boolean = false>(options: Options<MaterializeGraphData, ThrowOnError>) => {
+    return (options.client ?? _heyApiClient).post<MaterializeGraphResponses, MaterializeGraphErrors, ThrowOnError>({
         security: [
             {
                 name: 'X-API-Key',
@@ -2868,7 +2908,7 @@ export const updateFileStatus = <ThrowOnError extends boolean = false>(options:
                 type: 'http'
             }
         ],
-        url: '/v1/graphs/{graph_id}/tables/files/{file_id}',
+        url: '/v1/graphs/{graph_id}/materialize',
         ...options,
         headers: {
             'Content-Type': 'application/json',
@@ -2878,72 +2918,88 @@ export const updateFileStatus = <ThrowOnError extends boolean = false>(options:
 };
 
 /**
- * Ingest Tables to Graph
- * Load all files from S3 into DuckDB staging tables and ingest into Kuzu graph database.
+ * List Files in Graph
+ * List all files in the graph with optional filtering.
  *
- * Orchestrates the complete data pipeline from S3 staging files into the Kuzu graph database.
- * Processes all tables in a single bulk operation with comprehensive error handling and metrics.
+ * Get a complete inventory of files across all tables or filtered by table name,
+ * status, or other criteria. Files are first-class resources with independent lifecycle.
+ *
+ * **Query Parameters:**
+ * - `table_name` (optional): Filter by table name
+ * - `status` (optional): Filter by upload status (uploaded, pending, failed, etc.)
  *
  * **Use Cases:**
- * - Initial graph population from uploaded data
- * - Incremental data updates with new files
- * - Complete database rebuild from source files
- * - Recovery from failed ingestion attempts
+ * - Monitor file upload progress across all tables
+ * - Verify files are ready for ingestion
+ * - Check file metadata and sizes
+ * - Track storage usage per graph
+ * - Identify failed or incomplete uploads
+ * - Audit file provenance
  *
- * **Workflow:**
- * 1. Upload data files via `POST /tables/{table_name}/files`
- * 2. Files are validated and marked as 'uploaded'
- * 3. Trigger ingestion: `POST /tables/ingest`
- * 4. DuckDB staging tables created from S3 patterns
- * 5. Data copied from DuckDB to Kuzu
- * 6. Per-table results and metrics returned
+ * **Returned Metadata:**
+ * - File ID, name, and format (parquet, csv, json)
+ * - Size in bytes and row count (if available)
+ * - Upload status and timestamps
+ * - DuckDB and graph ingestion status
+ * - Table association
  *
- * **Rebuild Feature:**
- * Setting `rebuild=true` regenerates the entire graph database from scratch:
- * - Deletes existing Kuzu database
- * - Recreates with fresh schema from active GraphSchema
- * - Ingests all data files
- * - Safe operation - S3 is source of truth
- * - Useful for schema changes or data corrections
- * - Graph marked as 'rebuilding' during process
+ * **File Lifecycle Tracking:**
+ * Multi-layer status across S3 → DuckDB → Graph pipeline
  *
- * **Error Handling:**
- * - Per-table error isolation with `ignore_errors` flag
- * - Partial success support (some tables succeed, some fail)
- * - Detailed error reporting per table
- * - Graph status tracking throughout process
- * - Automatic failure recovery and cleanup
+ * **Important Notes:**
+ * - Files are graph-scoped, not table-scoped
+ * - Use table_name parameter to filter by table
+ * - File listing is included - no credit consumption
+ */
+export const listFiles = <ThrowOnError extends boolean = false>(options: Options<ListFilesData, ThrowOnError>) => {
+    return (options.client ?? _heyApiClient).get<ListFilesResponses, ListFilesErrors, ThrowOnError>({
+        security: [
+            {
+                name: 'X-API-Key',
+                type: 'apiKey'
+            },
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/v1/graphs/{graph_id}/files',
+        ...options
+    });
+};
+
+/**
+ * Create File Upload
+ * Generate presigned S3 URL for file upload.
  *
- * **Performance:**
- * - Processes all tables in sequence
- * - Each table timed independently
- * - Total execution metrics provided
- * - Scales to thousands of files
- * - Optimized for large datasets
+ * Initiate file upload by generating a secure, time-limited presigned S3 URL.
+ * Files are first-class resources uploaded directly to S3.
  *
- * **Concurrency Control:**
- * Only one ingestion can run per graph at a time. If another ingestion is in progress,
- * you'll receive a 409 Conflict error. The distributed lock automatically expires after
- * the configured TTL (default: 1 hour) to prevent deadlocks from failed ingestions.
+ * **Request Body:**
+ * - `file_name`: Name of the file (1-255 characters)
+ * - `file_format`: Format (parquet, csv, json)
+ * - `table_name`: Table to associate file with
  *
- * **Subgraph Support:**
- * This endpoint accepts both parent graph IDs and subgraph IDs.
- * - Parent graph: Use `graph_id` like `kg0123456789abcdef`
- * - Subgraph: Use full subgraph ID like `kg0123456789abcdef_dev`
- * Each subgraph has independent staging tables and graph data. Ingestion operates
- * on the specified graph/subgraph only and does not affect other subgraphs.
+ * **Upload Workflow:**
+ * 1. Call this endpoint to get presigned URL
+ * 2. PUT file directly to S3 URL
+ * 3. Call PATCH /files/{file_id} with status='uploaded'
+ * 4. Backend validates and stages in DuckDB immediately
+ * 5. Background task ingests to graph
+ *
+ * **Supported Formats:**
+ * - Parquet, CSV, JSON
+ *
+ * **Auto-Table Creation:**
+ * Tables are automatically created if they don't exist.
  *
  * **Important Notes:**
- * - Only files with 'uploaded' status are processed
- * - Tables with no uploaded files are skipped
- * - Use `ignore_errors=false` for strict validation
- * - Monitor progress via per-table results
- * - Check graph metadata for rebuild status
- * - Wait for current ingestion to complete before starting another
- * - Table ingestion is included - no credit consumption
+ * - Presigned URLs expire (default: 1 hour)
+ * - Files are graph-scoped, independent resources
+ * - Upload URL generation is included - no credit consumption
  */
-export const ingestTables = <ThrowOnError extends boolean = false>(options: Options<IngestTablesData, ThrowOnError>) => {
-    return (options.client ?? _heyApiClient).post<IngestTablesResponses, IngestTablesErrors, ThrowOnError>({
+export const createFileUpload = <ThrowOnError extends boolean = false>(options: Options<CreateFileUploadData, ThrowOnError>) => {
+    return (options.client ?? _heyApiClient).post<CreateFileUploadResponses, CreateFileUploadErrors, ThrowOnError>({
         security: [
             {
                 name: 'X-API-Key',
@@ -2954,7 +3010,7 @@ export const ingestTables = <ThrowOnError extends boolean = false>(options: Opti
                 type: 'http'
             }
         ],
-        url: '/v1/graphs/{graph_id}/tables/ingest',
+        url: '/v1/graphs/{graph_id}/files',
         ...options,
         headers: {
             'Content-Type': 'application/json',
@@ -2964,66 +3020,100 @@ export const ingestTables = <ThrowOnError extends boolean = false>(options: Opti
 };
 
 /**
- * Query Staging Tables with SQL
- * Execute SQL queries on DuckDB staging tables for data inspection and validation.
+ * Delete File
+ * Delete file from all layers.
  *
- * Query raw staging data directly with SQL before ingestion into the graph database.
- * Useful for data quality checks, validation, and exploratory analysis.
+ * Remove file from S3, database tracking, and optionally from DuckDB and graph.
+ * Files are deleted by file_id, independent of table context.
  *
- * **Security Best Practice - Use Parameterized Queries:**
- * ALWAYS use query parameters instead of string concatenation to prevent SQL injection:
- * - ✅ SAFE: `SELECT * FROM Entity WHERE type = ? LIMIT ?` with `parameters: ["Company", 100]`
- * - ❌ UNSAFE: `SELECT * FROM Entity WHERE type = 'Company' LIMIT 100` with user input concatenated into SQL string
+ * **Query Parameters:**
+ * - `cascade` (optional, default=false): Delete from all layers including DuckDB
  *
- * Query parameters provide automatic escaping and type safety. Use `?` placeholders with parameters array.
+ * **What Happens (cascade=false):**
+ * 1. File deleted from S3
+ * 2. Database record removed
+ * 3. Table statistics updated
  *
- * **Use Cases:**
- * - Validate data quality before graph ingestion
- * - Inspect row-level data for debugging
- * - Run analytics on staging tables
- * - Check for duplicates, nulls, or data issues
- * - Preview data transformations
+ * **What Happens (cascade=true):**
+ * 1. File data deleted from all DuckDB tables (by file_id)
+ * 2. Graph marked as stale
+ * 3. File deleted from S3
+ * 4. Database record removed
+ * 5. Table statistics updated
  *
- * **Workflow:**
- * 1. Upload data files via `POST /tables/{table_name}/files`
- * 2. Query staging tables to validate: `POST /tables/query`
- * 3. Fix any data issues by re-uploading
- * 4. Ingest validated data: `POST /tables/ingest`
+ * **Use Cases:**
+ * - Remove incorrect or duplicate files
+ * - Clean up failed uploads
+ * - Delete files before graph ingestion
+ * - Surgical data removal with cascade
  *
- * **Supported SQL:**
- * - Full DuckDB SQL syntax
- * - SELECT, JOIN, WHERE, GROUP BY, ORDER BY
- * - Aggregations, window functions, CTEs
- * - Multiple table joins across staging area
+ * **Security:**
+ * - Write access required
+ * - Shared repositories block deletions
+ * - Full audit trail
  *
- * **Common Operations:**
- * - Count rows: `SELECT COUNT(*) FROM Entity`
- * - Filter by type: `SELECT * FROM Entity WHERE entity_type = ? LIMIT ?` with `parameters: ["Company", 100]`
- * - Check for nulls: `SELECT * FROM Entity WHERE name IS NULL LIMIT 10`
- * - Find duplicates: `SELECT identifier, COUNT(*) as cnt FROM Entity GROUP BY identifier HAVING COUNT(*) > 1`
- * - Filter amounts: `SELECT * FROM Transaction WHERE amount > ? AND date >= ?` with `parameters: [1000, "2024-01-01"]`
+ * **Important:**
+ * - Use cascade=true for immediate DuckDB cleanup
+ * - Graph rebuild recommended after cascade deletion
+ * - File deletion is included - no credit consumption
+ */
+export const deleteFile = <ThrowOnError extends boolean = false>(options: Options<DeleteFileData, ThrowOnError>) => {
+    return (options.client ?? _heyApiClient).delete<DeleteFileResponses, DeleteFileErrors, ThrowOnError>({
+        security: [
+            {
+                name: 'X-API-Key',
+                type: 'apiKey'
+            },
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/v1/graphs/{graph_id}/files/{file_id}',
+        ...options
+    });
+};
+
+/**
+ * Get File Information
+ * Get detailed information about a specific file.
  *
- * **Limits:**
- * - Query timeout: 30 seconds
- * - Result limit: 10,000 rows (use LIMIT clause)
- * - Read-only: No INSERT, UPDATE, DELETE
- * - User's tables only: Cannot query other users' data
+ * Retrieve comprehensive metadata for a single file by file_id, independent of
+ * table context. Files are first-class resources with complete lifecycle tracking.
  *
- * **Subgraph Support:**
- * This endpoint accepts both parent graph IDs and subgraph IDs.
- * - Parent graph: Use `graph_id` like `kg0123456789abcdef`
- * - Subgraph: Use full subgraph ID like `kg0123456789abcdef_dev`
- * Each subgraph has its own independent staging tables.
+ * **Returned Information:**
+ * - File ID, name, format, size
+ * - Upload status and timestamps
+ * - **Enhanced Multi-Layer Status** (new in this version):
+ * - S3 layer: upload_status, uploaded_at, size_bytes, row_count
+ * - DuckDB layer: duckdb_status, duckdb_staged_at, duckdb_row_count
+ * - Graph layer: graph_status, graph_ingested_at
+ * - Table association
+ * - S3 location
+ *
+ * **Multi-Layer Pipeline Visibility:**
+ * The `layers` object provides independent status tracking across the three-tier
+ * data pipeline:
+ * - **S3 (Immutable Source)**: File upload and validation
+ * - **DuckDB (Mutable Staging)**: Immediate queryability with file provenance
+ * - **Graph (Immutable View)**: Optional graph database materialization
+ *
+ * Each layer shows its own status, timestamp, and row count (where applicable),
+ * enabling precise debugging and monitoring of the data ingestion flow.
  *
- * **Shared Repositories:**
- * Shared repositories (SEC, etc.) do not allow direct SQL queries.
- * Use the graph query endpoint instead: `POST /v1/graphs/{graph_id}/query`
+ * **Use Cases:**
+ * - Validate file upload completion
+ * - Monitor multi-layer ingestion progress in real-time
+ * - Debug upload or staging issues at specific layers
+ * - Verify file metadata and row counts
+ * - Track file provenance through the pipeline
+ * - Identify bottlenecks in the ingestion process
  *
  * **Note:**
- * Staging table queries are included - no credit consumption
+ * File info retrieval is included - no credit consumption
  */
-export const queryTables = <ThrowOnError extends boolean = false>(options: Options<QueryTablesData, ThrowOnError>) => {
-    return (options.client ?? _heyApiClient).post<QueryTablesResponses, QueryTablesErrors, ThrowOnError>({
+export const getFile = <ThrowOnError extends boolean = false>(options: Options<GetFileData, ThrowOnError>) => {
+    return (options.client ?? _heyApiClient).get<GetFileResponses, GetFileErrors, ThrowOnError>({
         security: [
             {
                 name: 'X-API-Key',
@@ -3034,7 +3124,53 @@ export const queryTables = <ThrowOnError extends boolean = false>(options: Optio
                 type: 'http'
             }
         ],
-        url: '/v1/graphs/{graph_id}/tables/query',
+        url: '/v1/graphs/{graph_id}/files/{file_id}',
+        ...options
+    });
+};
+
+/**
+ * Update File Status
+ * Update file status and trigger processing.
+ *
+ * Update file status after upload completion. Setting status='uploaded' triggers
+ * immediate DuckDB staging and optional graph ingestion.
+ *
+ * **Request Body:**
+ * - `status`: New status (uploaded, disabled, failed)
+ * - `ingest_to_graph` (optional): If true, auto-ingest to graph after DuckDB staging
+ *
+ * **What Happens (status='uploaded'):**
+ * 1. File validated in S3
+ * 2. Row count calculated
+ * 3. DuckDB staging triggered immediately (Celery task)
+ * 4. If ingest_to_graph=true, graph ingestion queued
+ * 5. File queryable in DuckDB within seconds
+ *
+ * **Use Cases:**
+ * - Signal upload completion
+ * - Trigger immediate DuckDB staging
+ * - Enable/disable files
+ * - Mark failed uploads
+ *
+ * **Important:**
+ * - Files must exist in S3 before marking uploaded
+ * - DuckDB staging happens asynchronously
+ * - Graph ingestion is optional (ingest_to_graph flag)
+ */
+export const updateFile = <ThrowOnError extends boolean = false>(options: Options<UpdateFileData, ThrowOnError>) => {
+    return (options.client ?? _heyApiClient).patch<UpdateFileResponses, UpdateFileErrors, ThrowOnError>({
+        security: [
+            {
+                name: 'X-API-Key',
+                type: 'apiKey'
+            },
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/v1/graphs/{graph_id}/files/{file_id}',
         ...options,
         headers: {
             'Content-Type': 'application/json',