{"openapi":"3.1.0","info":{"title":"RoboSystems API","description":"RoboSystems is a knowledge graph platform for enterprise financial and operational data. The platform powers [RoboLedger](https://roboledger.ai) for accounting analytics and [RoboInvestor](https://roboinvestor.ai) for investment research, while the knowledge graphs are managed using the [RoboSystems](https://robosystems.ai) app. Build financial knowledge graphs, integrate accounting systems, analyze SEC filings, and leverage AI-powered insights with enterprise-grade security.\n\n## Core Features\n\n- **Graph Database**: Build knowledge graphs with LadybugDB for modeling financial relationships and multi-dimensional analytics\n- **Multi-Tenant Architecture**: Isolated database instances with tier-based resource allocation\n- **AI Agent Integration**: MCP (Model Context Protocol) support enables AI agents to query and analyze your knowledge graphs\n- **DuckDB Staging**: High-performance data validation and bulk ingestion pipeline with Parquet optimization\n- **Data Integration**: Connect QuickBooks and SEC XBRL filings in a unified graph\n- **Shared Repositories**: Access to curated SEC filing data and other shared knowledge graphs\n\n## API Modules\n\n### Graph Operations\n\n- **Create**: Initialize knowledge graphs with customizable schemas and extensions\n- **Query**: Execute Cypher queries with NDJSON streaming for large results\n- **Tables**: DuckDB staging tables for data ingestion with file upload, query, and import workflows\n- **Schema**: View and analyze node types, relationship types, and property definitions\n- **Backup**: Encrypted backups with retention policies and download support\n- **Analytics**: Graph analytics for understanding contents and usage\n\n### MCP & Agents\n\n- **MCP**: Model Context Protocol for AI agent graph tools and queries\n- **Agents**: Claude-powered financial analysis and report generation\n\n### Data Synchronization\n\n- **SEC Filings**: Process XBRL documents and build filing knowledge graphs\n- **QuickBooks**: Sync transactions, accounts, and financial reports\n\n\n### Extensions Surface\n\nDomain extensions (RoboLedger, RoboInvestor) are graph-scoped under\n`/extensions/{graph_id}/...` with a clear split between reads, writes,\nand analytical view operations:\n\n- **Reads** → GraphQL at `POST /extensions/{graph_id}/graphql`. The\n  schema is composed dynamically from the domains enabled on a given\n  deployment — a ledger-only deployment exposes only ledger fields,\n  and introspection reflects the actual available shape. GraphiQL\n  playground is served at the same URL in development.\n- **Writes** → named command operations at\n  `POST /extensions/{roboledger|roboinvestor}/{graph_id}/operations/{operation_name}`.\n  Every write returns a typed `OperationEnvelope` with an\n  `operationId`, supports `Idempotency-Key` for safe retries, and is\n  audit-logged. Long-running commands return `status: \"pending\"` and\n  stream progress via the existing\n  `/v1/operations/{operation_id}/stream` SSE endpoint.\n- **Analytical view operations** → graph-backed read-only operations\n  at `POST /extensions/{domain}/{graph_id}/operations/{view_name}`.\n  These query LadybugDB rather than the extensions OLTP database and\n  share the same envelope contract as command writes. Gated\n  independently so deployments without the corresponding OLTP domain\n  can still use them.\n\n### RoboLedger\n\n- **Chart of Accounts**: View accounts and hierarchical account trees synced from connected systems\n- **Transactions**: List and inspect transactions with entries and line items\n- **Trial Balance**: Generate trial balances with optional date filtering\n- **Taxonomies**: US GAAP reporting taxonomy with structures, elements, and associations\n- **Mappings**: Map chart of accounts to GAAP reporting concepts with AI auto-mapping\n- **Reports**: Create, view, and share multi-period financial statements (income statement, balance sheet)\n- **Schedules**: Depreciation, amortization, and accrual schedules with monthly fact generation and period close workflow\n- **Fiscal Calendar**: Track close cadence with `closed_through` / `close_target` pointers, period close gates, and reopen workflow\n- **Publish Lists**: Share reports to other graphs via managed distribution lists\n\n### RoboInvestor\n\n- **Portfolios**: Create and manage investment portfolios with metadata and classification\n- **Securities**: Track securities with optional entity linking for cross-graph research\n- **Positions**: Record holdings with cost basis, quantity, and date tracking\n- **Holdings**: Aggregate portfolio holdings grouped by entity with current valuations\n\n### User & Access\n\n- **Authentication**: JWT tokens and API key management\n- **User Management**: Manage user account settings and profile\n- **Subscriptions**: Shared repository subscription access & AI credits\n- **Limits**: Rate limiting and usage tracking for shared repositories\n- **Organizations**: Team collaboration and permission management\n\n## MCP Client\n\nModel Context Protocol client for AI agent integration - [@robosystems/mcp](https://www.npmjs.com/package/@robosystems/mcp)\n\n**Usage**: `npx -y @robosystems/mcp`\n\n```\n{\n  \"mcpServers\": {\n    \"robosystems\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@robosystems/mcp\"],\n      \"env\": {\n        \"ROBOSYSTEMS_API_URL\": \"https://api.robosystems.ai\",\n        \"ROBOSYSTEMS_API_KEY\": \"rfs*\",\n        \"ROBOSYSTEMS_GRAPH_ID\": \"kg*\"\n      }\n    }\n  }\n}\n```\n\n## Clients\n\nRoboSystems provides official Clients for easy integration with the API in popular languages:\n\n### Python Client\n\nFull-featured Python client library for all API operations - [robosystems-client](https://pypi.org/project/robosystems-client/)\n\n**Installation**: `pip install robosystems-client`\n\n### TypeScript/JavaScript Client\n\nTypeScript client for Node.js and browser applications - [@robosystems/client](https://www.npmjs.com/package/@robosystems/client)\n\n**Installation**: `npm install @robosystems/client`\n\n## Authentication\n\nAll API endpoints require authentication using API keys. Include your API key in the request headers:\n\n```\nX-API-Key: rfs*\n```\n","version":"1.4.64"},"paths":{"/v1/auth/register":{"post":{"tags":["Auth"],"summary":"Register New User","description":"Register a new user account with email and password.\n\n**Organization Creation**: RoboSystems is an org-centric platform. When you register, a personal organization is automatically created for you. All resources (graphs, subscriptions, billing) belong to organizations, not individual users. You can later upgrade your personal org to a team or enterprise organization.\n\n**Security Controls**: CAPTCHA and email verification are disabled in development for API testing, but required in production.","operationId":"registerUser","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"409":{"description":"Email already registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Invalid request data or missing CAPTCHA token (production only)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Registration temporarily disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/auth/login":{"post":{"tags":["Auth"],"summary":"User Login","description":"Authenticate user with email and password.","operationId":"loginUser","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/auth/logout":{"post":{"tags":["Auth"],"summary":"User Logout","description":"Logout user and invalidate session.","operationId":"logoutUser","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Logoutuser"}}}}}}},"/v1/auth/me":{"get":{"tags":["Auth"],"summary":"Get Current User","description":"Get the currently authenticated user.","operationId":"getCurrentAuthUser","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Getcurrentauthuser"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/auth/refresh":{"post":{"tags":["Auth"],"summary":"Refresh Session","description":"Refresh authentication session with a new JWT token.","operationId":"refreshAuthSession","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/auth/email/resend":{"post":{"tags":["Auth"],"summary":"Resend Email Verification","description":"Resend verification email to the authenticated user. Rate limited to 3 per hour.","operationId":"resendVerificationEmail","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Resendverificationemail"}}}},"400":{"description":"Email already verified","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Email service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/auth/email/verify":{"post":{"tags":["Auth"],"summary":"Verify Email","description":"Verify email address with token from email link. Returns JWT for auto-login.","operationId":"verifyEmail","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailVerificationRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"400":{"description":"Invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/auth/password/policy":{"get":{"tags":["Auth"],"summary":"Get Password Policy","description":"Get current password policy requirements for frontend validation","operationId":"getPasswordPolicy","responses":{"200":{"description":"Password policy requirements","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordPolicyResponse"},"example":{"policy":{"min_length":12,"require_uppercase":true,"require_lowercase":true,"require_digits":true,"require_special":true}}}}}}}},"/v1/auth/password/check":{"post":{"tags":["Auth"],"summary":"Check Password Strength","description":"Check password strength and get validation feedback","operationId":"checkPasswordStrength","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordCheckRequest"}}},"required":true},"responses":{"200":{"description":"Password strength analysis","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordCheckResponse"},"example":{"is_valid":true,"strength":"good","score":75,"errors":[],"suggestions":["Consider adding more special characters"],"character_types":{"uppercase":true,"lowercase":true,"digits":true,"special":true}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/auth/password/forgot":{"post":{"tags":["Auth"],"summary":"Forgot Password","description":"Request password reset email. Always returns success to prevent email enumeration.","operationId":"forgotPassword","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForgotPasswordRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Forgotpassword"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/auth/password/reset/validate":{"get":{"tags":["Auth"],"summary":"Validate Reset Token","description":"Check if a password reset token is valid without consuming it.","operationId":"validateResetToken","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string","description":"Password reset token","title":"Token"},"description":"Password reset token"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResetPasswordValidateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/auth/password/reset":{"post":{"tags":["Auth"],"summary":"Reset Password","description":"Reset password with token from email. Returns JWT for auto-login.","operationId":"resetPassword","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResetPasswordRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"400":{"description":"Invalid token or password","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/auth/sso-token":{"post":{"tags":["Auth"],"summary":"Generate SSO Token","description":"Generate a temporary SSO token for cross-app authentication.","operationId":"generateSSOToken","parameters":[{"name":"auth-token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Auth-Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SSOTokenResponse"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/auth/sso-exchange":{"post":{"tags":["Auth"],"summary":"SSO Token Exchange","description":"Exchange SSO token for secure session handoff to target application.","operationId":"ssoTokenExchange","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SSOExchangeRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SSOExchangeResponse"}}}},"401":{"description":"Invalid SSO token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/auth/sso-complete":{"post":{"tags":["Auth"],"summary":"Complete SSO Authentication","description":"Complete SSO authentication using session ID from secure handoff.","operationId":"completeSSOAuth","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SSOCompleteRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"Invalid session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/auth/captcha/config":{"get":{"tags":["Auth"],"summary":"Get CAPTCHA Configuration","description":"Get CAPTCHA configuration including site key and whether CAPTCHA is required.","operationId":"getCaptchaConfig","responses":{"200":{"description":"CAPTCHA configuration","content":{"application/json":{"schema":{},"example":{"required":true,"site_key":"0x4AAAAAAA...","provider":"turnstile"}}}}}}},"/v1/status":{"get":{"tags":["Status"],"summary":"Health Check","description":"Service health check endpoint for monitoring and load balancers","operationId":"getServiceStatus","responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthStatus"}}}}}}},"/v1/user":{"get":{"tags":["User"],"summary":"Get Current User","description":"Returns information about the currently authenticated user.","operationId":"getCurrentUser","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"}}}}},"security":[{"APIKeyHeader":[]},{"BearerAuth":[]}]},"put":{"tags":["User"],"summary":"Update User Profile","description":"Update the current user's profile information.","operationId":"updateUser","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUserRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/user/password":{"put":{"tags":["User"],"summary":"Update Password","description":"Update the current user's password.","operationId":"updateUserPassword","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePasswordRequest"}}},"required":true},"responses":{"200":{"description":"Password updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid password or validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"User not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error updating password","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/user/api-keys":{"get":{"tags":["User"],"summary":"List API Keys","description":"Get all API keys for the current user.","operationId":"listUserAPIKeys","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIKeysResponse"}}}}},"security":[{"APIKeyHeader":[]},{"BearerAuth":[]}]},"post":{"tags":["User"],"summary":"Create API Key","description":"Create a new API key for the current user.","operationId":"createUserAPIKey","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAPIKeyRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAPIKeyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/user/api-keys/{api_key_id}":{"put":{"tags":["User"],"summary":"Update API Key","description":"Update an API key's name or description.","operationId":"updateUserAPIKey","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"api_key_id","in":"path","required":true,"schema":{"type":"string","title":"Api Key Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAPIKeyRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIKeyInfo"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["User"],"summary":"Revoke API Key","description":"Revoke (deactivate) an API key.","operationId":"revokeUserAPIKey","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"api_key_id","in":"path","required":true,"schema":{"type":"string","title":"Api Key Id"}}],"responses":{"200":{"description":"API key revoked successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"404":{"description":"API key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error revoking API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/orgs":{"get":{"tags":["Org"],"summary":"List User's Organizations","description":"Get all organizations the current user belongs to, with their role in each.","operationId":"listUserOrgs","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgListResponse"}}}}},"security":[{"APIKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/orgs/{org_id}":{"get":{"tags":["Org"],"summary":"Get Organization","description":"Get detailed information about an organization.","operationId":"getOrg","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","title":"Org Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgDetailResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["Org"],"summary":"Update Organization","description":"Update organization information. Requires admin or owner role.","operationId":"updateOrg","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","title":"Org Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOrgRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgDetailResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/orgs/{org_id}/graphs":{"get":{"tags":["Org"],"summary":"List Organization Graphs","description":"Get all graphs belonging to an organization.","operationId":"listOrgGraphs","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","title":"Org Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true},"title":"Response Listorggraphs"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/orgs/{org_id}/members":{"get":{"tags":["Org Members"],"summary":"List Organization Members","description":"Get all members of an organization with their roles.","operationId":"listOrgMembers","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","title":"Org Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgMemberListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Org Members"],"summary":"Invite Member","description":"Invite a user to join the organization. Requires admin or owner role.\n\n  **⚠️ FEATURE NOT READY**: This endpoint is disabled by default (ORG_MEMBER_INVITATIONS_ENABLED=false).\n  Returns 501 NOT IMPLEMENTED when disabled. See endpoint implementation for TODO list before enabling.","operationId":"inviteOrgMember","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","title":"Org Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteMemberRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgMemberResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/orgs/{org_id}/members/{user_id}":{"put":{"tags":["Org Members"],"summary":"Update Member Role","description":"Update a member's role in the organization. Requires admin or owner role.","operationId":"updateOrgMemberRole","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","title":"Org Id"}},{"name":"user_id","in":"path","required":true,"schema":{"type":"string","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMemberRoleRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgMemberResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Org Members"],"summary":"Remove Member","description":"Remove a member from the organization. Requires admin or owner role.","operationId":"removeOrgMember","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","title":"Org Id"}},{"name":"user_id","in":"path","required":true,"schema":{"type":"string","title":"User Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/orgs/{org_id}/limits":{"get":{"tags":["Org Usage"],"summary":"Get Organization Limits","description":"Get the current limits and quotas for an organization.","operationId":"getOrgLimits","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","title":"Org Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgLimitsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/orgs/{org_id}/usage":{"get":{"tags":["Org Usage"],"summary":"Get Organization Usage","description":"Get detailed usage statistics for an organization aggregated across all graphs.","operationId":"getOrgUsage","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","title":"Org Id"}},{"name":"days","in":"query","required":false,"schema":{"type":"integer","default":30,"title":"Days"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgUsageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/agent":{"get":{"tags":["Agent"],"summary":"List available agents","description":"Get a comprehensive list of all available agents with their metadata.\n\n**Returns:**\n- Agent types and names\n- Capabilities and supported modes\n- Version information\n- Credit requirements\n\nUse the optional `capability` filter to find agents with specific capabilities.","operationId":"listAgents","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}},{"name":"capability","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by capability (e.g., 'financial_analysis', 'rag_search')","title":"Capability"},"description":"Filter by capability (e.g., 'financial_analysis', 'rag_search')"}],"responses":{"200":{"description":"List of agents retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentListResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Agent"],"summary":"Auto-select agent for query","description":"Automatically select the best agent for your query with intelligent execution strategy.\n\n**Agent Selection Process:**\n\nThe orchestrator intelligently routes your query by:\n1. Analyzing query intent and complexity\n2. Enriching context with RAG if enabled\n3. Evaluating all available agents against selection criteria\n4. Selecting the best match based on confidence scores\n5. Choosing execution strategy (sync/SSE/async) based on expected time\n6. Executing the query with the selected agent\n\n**Available Agent Types:**\n- `financial`: Financial analysis, SEC filings, company metrics\n- `research`: General research, data exploration, trend analysis\n- `rag`: Knowledge base search using RAG enrichment\n\n**Execution Modes:**\n- `quick`: Fast responses (~2-5s), suitable for simple queries\n- `standard`: Balanced approach (~5-15s), default mode\n- `extended`: Comprehensive analysis (~15-60s), deep research\n- `streaming`: Real-time response streaming\n\n**Execution Strategies (automatic):**\n- Fast operations (<5s): Immediate synchronous response\n- Medium operations (5-30s): SSE streaming with progress updates\n- Long operations (>30s): Background queue with operation tracking\n\n**Response Mode Override:**\nUse query parameter `?mode=sync|async` to override automatic strategy selection.\n\n**Confidence Score Interpretation:**\n- `0.9-1.0`: High confidence, agent is ideal match\n- `0.7-0.9`: Good confidence, agent is suitable\n- `0.5-0.7`: Moderate confidence, agent can handle but may not be optimal\n- `0.3-0.5`: Low confidence, fallback agent used\n- `<0.3`: Very low confidence, consider using specific agent endpoint\n\n**Credit Costs:**\n- Quick mode: 5-10 credits per query\n- Standard mode: 15-25 credits per query\n- Extended mode: 30-75 credits per query\n- RAG enrichment: +5-15 credits (if enabled)\n\n**Use Cases:**\n- Ask questions without specifying agent type\n- Get intelligent routing for complex multi-domain queries\n- Leverage conversation history for contextual understanding\n- Enable RAG for knowledge base enrichment\n\n**Subgraph Support:**\nThis endpoint accepts both parent graph IDs and subgraph IDs.\n- Parent graph: Use `graph_id` like `kg0123456789abcdef`\n- Subgraph: Use full subgraph ID like `kg0123456789abcdef_dev`\nAgents operate on the specified graph/subgraph's data independently. RAG enrichment\nand knowledge base search are scoped to the specific graph/subgraph.\n\nSee request/response examples in the \"Examples\" dropdown below.","operationId":"autoSelectAgent","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}},{"name":"mode","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/ResponseMode"},{"type":"null"}],"description":"Override execution mode: sync, async, stream, or auto","title":"Mode"},"description":"Override execution mode: sync, async, stream, or auto"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRequest"}}}},"responses":{"200":{"description":"Query successfully processed by selected agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}},"202":{"description":"Query queued for async processing with operation tracking"},"400":{"description":"Invalid request parameters"},"402":{"description":"Insufficient credits for selected agent"},"429":{"description":"Rate limit exceeded"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/agent/{agent_type}":{"get":{"tags":["Agent"],"summary":"Get agent metadata","description":"Get comprehensive metadata for a specific agent type.\n\n**Returns:**\n- Agent name and description\n- Version information\n- Supported capabilities and modes\n- Credit requirements\n- Author and tags\n- Configuration options\n\nUse this to understand agent capabilities before execution.","operationId":"getAgentMetadata","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}},{"name":"agent_type","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-zA-Z][a-zA-Z0-9_]{2,32}$","description":"Agent type identifier (e.g., 'financial', 'research', 'rag')","title":"Agent Type"},"description":"Agent type identifier (e.g., 'financial', 'research', 'rag')"}],"responses":{"200":{"description":"Agent metadata retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentMetadataResponse"}}}},"404":{"description":"Agent type not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Agent"],"summary":"Execute specific agent","description":"Execute a specific agent type directly with intelligent execution strategy.\n\nAvailable agents:\n- **financial**: Financial analysis, SEC filings, accounting data\n- **research**: Deep research and comprehensive analysis\n- **rag**: Fast retrieval without AI (no credits required)\n\n**Execution Strategies (automatic):**\n- Fast operations (<5s): Immediate synchronous response\n- Medium operations (5-30s): SSE streaming with progress updates\n- Long operations (>30s): Background queue with operation tracking\n\n**Response Mode Override:**\nUse query parameter `?mode=sync|async` to override automatic strategy selection.\n\nUse this endpoint when you know which agent you want to use.","operationId":"executeSpecificAgent","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"agent_type","in":"path","required":true,"schema":{"type":"string","title":"Agent Type"}},{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}},{"name":"mode","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/ResponseMode"},{"type":"null"}],"description":"Override execution mode: sync, async, stream, or auto","title":"Mode"},"description":"Override execution mode: sync, async, stream, or auto"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRequest"}}}},"responses":{"200":{"description":"Query successfully processed by specified agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}},"202":{"description":"Query queued for async processing with operation tracking"},"400":{"description":"Invalid agent type or request parameters"},"402":{"description":"Insufficient credits for specified agent"},"404":{"description":"Agent type not found"},"429":{"description":"Rate limit exceeded"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/agent/batch":{"post":{"tags":["Agent"],"summary":"Batch process multiple queries","description":"Process multiple queries either sequentially or in parallel.\n\n**Features:**\n- Process up to 10 queries in a single request\n- Sequential or parallel execution modes\n- Automatic error handling per query\n- Credit checking before execution\n\n**Use Cases:**\n- Bulk analysis of multiple entities\n- Comparative analysis across queries\n- Automated report generation\n\nReturns individual results for each query with execution metrics.","operationId":"batchProcessQueries","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchAgentRequest"}}}},"responses":{"200":{"description":"Batch processing completed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchAgentResponse"}}}},"400":{"description":"Invalid batch request or too many queries"},"402":{"description":"Insufficient credits for batch processing"},"500":{"description":"Internal server error during batch processing"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/agent/recommend":{"post":{"tags":["Agent"],"summary":"Get agent recommendations","description":"Get intelligent agent recommendations for a specific query.\n\n**How it works:**\n1. Analyzes query content and structure\n2. Evaluates agent capabilities\n3. Calculates confidence scores\n4. Returns ranked recommendations\n\n**Use this when:**\n- Unsure which agent to use\n- Need to understand agent suitability\n- Want confidence scores for decision making\n\nReturns top agents ranked by confidence with explanations.","operationId":"recommendAgent","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRecommendationRequest"}}}},"responses":{"200":{"description":"Recommendations generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRecommendationResponse"}}}},"400":{"description":"Invalid recommendation request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/mcp/tools":{"get":{"tags":["MCP"],"summary":"List MCP Tools","description":"Get available Model Context Protocol tools for graph analysis.\n\nThis endpoint returns a comprehensive list of MCP tools optimized for AI agents:\n- Tool schemas with detailed parameter documentation\n- Context-aware descriptions based on graph type\n- Capability indicators for streaming and progress\n\nThe tool list is customized based on:\n- Graph type (shared repository vs user graph)\n- User permissions and subscription tier\n- Available graph capabilities for the selected graph\n\n**Subgraph Support:**\nThis endpoint accepts both parent graph IDs and subgraph IDs.\n- Parent graph: Use `graph_id` like `kg0123456789abcdef`\n- Subgraph: Use full subgraph ID like `kg0123456789abcdef_dev`\nThe returned tool list is identical for parent graphs and subgraphs, as all\nMCP tools work uniformly across graph boundaries.\n\n**Note:**\nMCP tool listing is included - no credit consumption required.","operationId":"listMcpTools","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}}],"responses":{"200":{"description":"MCP tools retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MCPToolsResponse"}}}},"403":{"description":"Access denied to graph","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Failed to retrieve MCP tools","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/mcp/call-tool":{"post":{"tags":["MCP"],"summary":"Execute MCP Tool","description":"Execute an MCP tool with intelligent response optimization.\n\nThis endpoint automatically selects the best execution strategy based on:\n- Tool type and estimated complexity\n- Client capabilities (AI agent detection)\n- System load and queue status\n- Graph type (shared repository vs user graph)\n\n**Response Formats:**\n- **JSON**: Direct response for small/fast operations\n- **SSE**: Server-Sent Events for progress monitoring\n- **NDJSON**: Newline-delimited JSON for streaming\n- **Queued**: Asynchronous execution with status monitoring\n\n**SSE Streaming Support:**\n- Maximum 5 concurrent SSE connections per user\n- Rate limited to 10 new connections per minute\n- Automatic circuit breaker for Redis failures\n- Graceful degradation to direct response if SSE unavailable\n- Progress events for long-running operations\n\n**AI Agent Optimization:**\nThe Node.js MCP client transparently handles all response formats,\npresenting a unified interface to AI agents. Streaming responses are\nautomatically aggregated for seamless consumption.\n\n**Error Handling:**\n- `429 Too Many Requests`: Connection limit or rate limit exceeded\n- `503 Service Unavailable`: SSE system temporarily disabled\n- `408 Request Timeout`: Tool execution exceeded timeout\n- Clients should implement exponential backoff on errors\n\n**Subgraph Support:**\nThis endpoint accepts both parent graph IDs and subgraph IDs.\n- Parent graph: Use `graph_id` like `kg0123456789abcdef`\n- Subgraph: Use full subgraph ID like `kg0123456789abcdef_dev`\nMCP tools operate on the specified graph/subgraph independently. Each subgraph\nhas its own schema, data, and can be queried separately via MCP.\n\n**Credit Model:**\nMCP tool execution is included - no credit consumption required. Database\noperations (queries, schema inspection, analytics) are completely free.\nOnly AI operations that invoke Claude or other LLM APIs consume credits,\nwhich happens at the AI agent layer, not the MCP tool layer.","operationId":"callMcpTool","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}},{"name":"format","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Response format override (json, sse, ndjson)","title":"Format"},"description":"Response format override (json, sse, ndjson)"},{"name":"test_mode","in":"query","required":false,"schema":{"type":"boolean","description":"Enable test mode for debugging","default":false,"title":"Test Mode"},"description":"Enable test mode for debugging"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MCPToolCall"},"examples":{"cypher_query":{"summary":"Execute Cypher Query","description":"Query companies by ticker symbol with parameters","value":{"name":"read-graph-cypher","arguments":{"query":"MATCH (c:Company {ticker: $ticker})-[:FILED]->(f:Filing) RETURN c.name, f.form_type, f.filing_date LIMIT 10","parameters":{"ticker":"AAPL"}}}},"get_schema":{"summary":"Get Graph Schema","description":"Retrieve the complete schema of the graph database","value":{"name":"get-graph-schema","arguments":{}}},"get_info":{"summary":"Get Graph Info","description":"Get statistics and metadata about the graph","value":{"name":"get-graph-info","arguments":{}}}}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{}}}},"202":{"description":"Tool queued for execution"},"400":{"description":"Invalid tool call","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"408":{"description":"Execution timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/backups":{"get":{"tags":["Backup"],"summary":"List graph database backups","description":"List all backups for the specified graph database","operationId":"listBackups","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of backups to return","default":50,"title":"Limit"},"description":"Maximum number of backups to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of backups to skip","default":0,"title":"Offset"},"description":"Number of backups to skip"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BackupListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Backup"],"summary":"Create Backup","description":"Create a backup of the graph database.\n\nCreates a complete backup of the graph database (.lbug file) with:\n- **Format**: Full database backup only (complete .lbug file)\n- **Compression**: Always enabled for optimal storage\n- **Encryption**: Optional AES-256 encryption for security\n- **Retention**: Configurable retention period (1-2555 days)\n\n**Backup Features:**\n- **Complete Backup**: Full database file backup\n- **Consistency**: Point-in-time consistent snapshot\n- **Download Support**: Unencrypted backups can be downloaded\n- **Restore Support**: Future support for encrypted backup restoration\n\n**Operation State Machine:**\n```\npending → processing → completed\n                    ↘ failed\n```\n- **pending**: Backup queued, waiting to start\n- **processing**: Actively backing up database\n- **completed**: Backup successfully created and stored\n- **failed**: Backup failed (check error message)\n\n**Expected Durations:**\nOperation times vary by database size:\n- **Small** (<1GB): 30 seconds - 2 minutes\n- **Medium** (1-10GB): 2-10 minutes\n- **Large** (10-100GB): 10-30 minutes\n- **Very Large** (>100GB): 30+ minutes\n\n**Progress Monitoring:**\nUse the returned operation_id to connect to the SSE stream:\n```javascript\nconst eventSource = new EventSource('/v1/operations/{operation_id}/stream');\neventSource.addEventListener('operation_progress', (event) => {\n  const data = JSON.parse(event.data);\n  console.log('Backup progress:', data.progress_percent + '%');\n  console.log('Status:', data.status); // pending, processing, completed, failed\n});\n```\n\n**SSE Connection Limits:**\n- Maximum 5 concurrent SSE connections per user\n- Rate limited to 10 new connections per minute\n- Automatic circuit breaker for Redis failures\n- Graceful degradation if event system unavailable\n\n**Important Notes:**\n- Only full_dump format is supported (no CSV/JSON exports)\n- Compression is always enabled\n- Encrypted backups cannot be downloaded (security measure)\n- All backups are stored securely in cloud storage\n\n**Credit Consumption:**\n- Base cost: 25.0 credits\n- Large databases (>10GB): 50.0 credits\n- Multiplied by graph tier\n\nReturns operation details for SSE monitoring.","operationId":"createBackup","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BackupCreateRequest"}}}},"responses":{"202":{"description":"Backup creation started","content":{"application/json":{"schema":{}}}},"400":{"description":"Invalid backup configuration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied - admin role required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Graph not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Failed to initiate backup","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/backups/{backup_id}/download":{"get":{"tags":["Backup"],"summary":"Get temporary download URL for backup","description":"Generate a temporary download URL for a backup (unencrypted, compressed .lbug files only)","operationId":"getBackupDownloadUrl","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"backup_id","in":"path","required":true,"schema":{"type":"string","description":"Backup identifier","title":"Backup Id"},"description":"Backup identifier"},{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}},{"name":"expires_in","in":"query","required":false,"schema":{"type":"integer","maximum":86400,"minimum":300,"description":"URL expiration time in seconds","default":3600,"title":"Expires In"},"description":"URL expiration time in seconds"}],"responses":{"200":{"description":"Download URL generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BackupDownloadUrlResponse"}}}},"403":{"description":"Access denied or backup is encrypted"},"404":{"description":"Backup not found"},"500":{"description":"Failed to generate download URL"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/backups/{backup_id}/restore":{"post":{"tags":["Backup"],"summary":"Restore Encrypted Backup","description":"Restore a graph database from an encrypted backup.\n\nRestores a complete graph database from an encrypted backup:\n- **Format**: Only full_dump backups can be restored\n- **Encryption**: Only encrypted backups can be restored (security requirement)\n- **System Backup**: Creates automatic backup of existing database before restore\n- **Verification**: Optionally verifies database integrity after restore\n\n**Restore Features:**\n- **Atomic Operation**: Complete replacement of database\n- **Rollback Protection**: System backup created before restore\n- **Data Integrity**: Verification ensures successful restore\n- **Security**: Only encrypted backups to prevent data tampering\n\n**Operation State Machine:**\n```\npending → backing_up_current → downloading → restoring → verifying → completed\n                                                                   ↘ failed\n```\n- **pending**: Restore queued, waiting to start\n- **backing_up_current**: Creating safety backup of existing database\n- **downloading**: Downloading backup from storage\n- **restoring**: Replacing database with backup contents\n- **verifying**: Verifying database integrity (if enabled)\n- **completed**: Restore successful, database operational\n- **failed**: Restore failed (rollback may be available)\n\n**Expected Durations:**\nOperation times vary by database size (includes backup + restore):\n- **Small** (<1GB): 1-3 minutes\n- **Medium** (1-10GB): 5-15 minutes\n- **Large** (10-100GB): 20-45 minutes\n- **Very Large** (>100GB): 45+ minutes\n\nNote: Restore operations take longer than backups due to safety backup step.\n\n**Progress Monitoring:**\nUse the returned operation_id to connect to the SSE stream:\n```javascript\nconst eventSource = new EventSource('/v1/operations/{operation_id}/stream');\neventSource.addEventListener('operation_progress', (event) => {\n  const data = JSON.parse(event.data);\n  console.log('Restore progress:', data.message);\n  console.log('Status:', data.status); // Shows current state\n});\n```\n\n**SSE Connection Limits:**\n- Maximum 5 concurrent SSE connections per user\n- Rate limited to 10 new connections per minute\n- Automatic circuit breaker for Redis failures\n- Graceful degradation if event system unavailable\n\n**Important Notes:**\n- Only encrypted backups can be restored (security measure)\n- Existing database is backed up to S3 before restore\n- Restore is a destructive operation - existing data is replaced\n- System backups are stored separately for recovery\n\n**Credit Consumption:**\n- Base cost: 100.0 credits\n- Large databases (>10GB): 200.0 credits\n- Multiplied by graph tier\n\nReturns operation details for SSE monitoring.","operationId":"restoreBackup","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"backup_id","in":"path","required":true,"schema":{"type":"string","description":"Backup identifier","title":"Backup Id"},"description":"Backup identifier"},{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BackupRestoreRequest"}}}},"responses":{"202":{"description":"Restore started","content":{"application/json":{"schema":{}}}},"400":{"description":"Invalid restore configuration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied - admin role required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Backup not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Failed to initiate restore","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/backups/stats":{"get":{"tags":["Backup"],"summary":"Get backup statistics","description":"Get comprehensive backup statistics for the specified graph database","operationId":"getBackupStats","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BackupStatsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/analytics":{"get":{"tags":["Usage"],"summary":"Get Graph Metrics","description":"Get comprehensive metrics for the graph database.\n\nProvides detailed analytics including:\n- **Node Statistics**: Counts by type (Entity, Report, Account, Transaction)\n- **Relationship Metrics**: Connection counts and patterns\n- **Data Quality**: Completeness scores and validation results\n- **Performance Metrics**: Query response times and database health\n- **Storage Analytics**: Database size and growth trends\n\nThis data helps with:\n- Monitoring data completeness\n- Identifying data quality issues\n- Capacity planning\n- Performance optimization\n\nNote:\nThis operation is included - no credit consumption required.","operationId":"getGraphMetrics","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}}],"responses":{"200":{"description":"Graph metrics retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GraphMetricsResponse"}}}},"403":{"description":"Access denied to graph","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Graph not found or metrics unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Failed to retrieve metrics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/analytics/usage":{"get":{"tags":["Usage"],"summary":"Get Graph Usage Analytics","description":"Get comprehensive usage analytics tracked by the GraphUsage model.\n\nProvides temporal usage patterns including:\n- **Storage Analytics**: GB-hours for billing, breakdown by type (files, tables, graphs, subgraphs)\n- **Credit Analytics**: Consumption patterns, operation breakdown, cached vs billable\n- **Performance Insights**: Operation stats, slow queries, performance scoring\n- **Recent Events**: Latest usage events with full details\n\nTime ranges available:\n- `24h` - Last 24 hours (hourly breakdown)\n- `7d` - Last 7 days (daily breakdown)\n- `30d` - Last 30 days (daily breakdown)\n- `current_month` - Current billing month\n- `last_month` - Previous billing month\n\nInclude options:\n- `storage` - Storage usage summary (GB-hours, averages, peaks)\n- `credits` - Credit consumption analytics\n- `performance` - Performance insights and optimization opportunities\n- `events` - Recent usage events (last 50)\n\nUseful for:\n- Billing and cost analysis\n- Capacity planning\n- Performance optimization\n- Usage trend analysis\n\nNote:\nThis operation is included - no credit consumption required.","operationId":"getGraphUsageAnalytics","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}},{"name":"time_range","in":"query","required":false,"schema":{"type":"string","pattern":"^(24h|7d|30d|current_month|last_month)$","description":"Time range: 24h, 7d, 30d, current_month, last_month","default":"30d","title":"Time Range"},"description":"Time range: 24h, 7d, 30d, current_month, last_month"},{"name":"include_storage","in":"query","required":false,"schema":{"type":"boolean","description":"Include storage usage summary","default":true,"title":"Include Storage"},"description":"Include storage usage summary"},{"name":"include_credits","in":"query","required":false,"schema":{"type":"boolean","description":"Include credit consumption summary","default":true,"title":"Include Credits"},"description":"Include credit consumption summary"},{"name":"include_performance","in":"query","required":false,"schema":{"type":"boolean","description":"Include performance insights (may be slower)","default":false,"title":"Include Performance"},"description":"Include performance insights (may be slower)"},{"name":"include_events","in":"query","required":false,"schema":{"type":"boolean","description":"Include recent usage events","default":false,"title":"Include Events"},"description":"Include recent usage events"}],"responses":{"200":{"description":"Usage analytics retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GraphUsageResponse"}}}},"403":{"description":"Access denied to graph","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Failed to retrieve usage analytics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/query":{"post":{"tags":["Query"],"summary":"Execute Cypher Query","description":"Execute a Cypher query with intelligent response optimization.\n\n**IMPORTANT: Write operations depend on graph type:**\n- **Main Graphs**: READ-ONLY. Write operations (CREATE, MERGE, SET, DELETE) are not allowed.\n- **Subgraphs**: WRITE-ENABLED. Full Cypher write operations are supported for development and report creation.\n\nTo load data into main graphs, use the staging pipeline:\n1. Create file upload: `POST /v1/graphs/{graph_id}/tables/{table_name}/files`\n2. Ingest to graph: `POST /v1/graphs/{graph_id}/tables/ingest`\n\n**Security Best Practice - Use Parameterized Queries:**\nALWAYS use query parameters instead of string interpolation to prevent injection attacks:\n- ✅ SAFE: `MATCH (n:Entity {type: $entity_type}) RETURN n` with `parameters: {\"entity_type\": \"Company\"}`\n- ❌ UNSAFE: `MATCH (n:Entity {type: \"Company\"}) RETURN n` with user input concatenated into query string\n\nQuery parameters provide automatic escaping and type safety. All examples in this API use parameterized queries.\n\nThis endpoint automatically selects the best execution strategy based on:\n- Query characteristics (size, complexity)\n- Client capabilities (SSE, NDJSON, JSON)\n- System load (queue status, concurrent queries)\n- User preferences (mode parameter, headers)\n\n**Response Modes:**\n- `auto` (default): Intelligent automatic selection\n- `sync`: Force synchronous JSON response (best for testing)\n- `async`: Force queued response with SSE monitoring endpoints (no polling needed)\n- `stream`: Force streaming response (SSE or NDJSON)\n\n**Client Detection:**\n- Automatically detects testing tools (Postman, Swagger UI)\n- Adjusts behavior for better interactive experience\n- Respects Accept and Prefer headers for capabilities\n\n**Streaming Support (SSE):**\n- Real-time events with progress updates\n- Maximum 5 concurrent SSE connections per user\n- Rate limited to 10 new connections per minute\n- Automatic circuit breaker for Redis failures\n- Graceful degradation if event system unavailable\n- 30-second keepalive to prevent timeouts\n\n**Streaming Support (NDJSON):**\n- Efficient line-delimited JSON for large results\n- Automatic chunking (configurable 10-10000 rows)\n- No connection limits (stateless streaming)\n\n**Queue Management:**\n- Automatic queuing under high load\n- Real-time monitoring via SSE events (no polling needed)\n- Priority based on subscription tier\n- Queue position and progress updates pushed via SSE\n- Connect to returned `/v1/operations/{id}/stream` endpoint for updates\n\n**Error Handling:**\n- `429 Too Many Requests`: Rate limit or connection limit exceeded\n- `503 Service Unavailable`: Circuit breaker open or SSE disabled\n- Clients should implement exponential backoff\n\n**Subgraph Support:**\nThis endpoint accepts both parent graph IDs and subgraph IDs.\n- Parent graph: Use `graph_id` like `kg0123456789abcdef`\n- Subgraph: Use full subgraph ID like `kg0123456789abcdef_dev`\nSubgraphs share the same instance as their parent graph and have independent data.\n\n**Note:**\nQuery operations are included - no credit consumption required.\nQueue position is based on subscription tier for priority.","operationId":"executeCypherQuery","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}},{"name":"mode","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/ResponseMode"},{"type":"null"}],"description":"Response mode override","title":"Mode"},"description":"Response mode override"},{"name":"chunk_size","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10000,"minimum":10},{"type":"null"}],"description":"Rows per chunk for streaming","title":"Chunk Size"},"description":"Rows per chunk for streaming"},{"name":"test_mode","in":"query","required":false,"schema":{"type":"boolean","description":"Enable test mode for better debugging","default":false,"title":"Test Mode"},"description":"Enable test mode for better debugging"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CypherQueryRequest"}}}},"responses":{"200":{"description":"Query executed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object"}},"columns":{"type":"array","items":{"type":"string"}},"row_count":{"type":"integer"},"execution_time_ms":{"type":"number"},"graph_id":{"type":"string"},"timestamp":{"type":"string"}}}},"application/x-ndjson":{"schema":{"type":"string","description":"Newline-delimited JSON chunks with streaming results"}},"text/event-stream":{"schema":{"type":"string","description":"Server-Sent Events stream with real-time progress updates"}}}},"202":{"description":"Query queued for execution"},"400":{"description":"Invalid query or parameters"},"403":{"description":"Access denied"},"408":{"description":"Query timeout"},"429":{"description":"Rate limit exceeded"},"500":{"description":"Internal error"},"503":{"description":"Service unavailable"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/schema":{"get":{"tags":["Schema"],"summary":"Get Runtime Graph Schema","description":"Get runtime schema information for the specified graph database.\n\n## What This Returns\n\nThis endpoint inspects the **actual current state** of the graph database and returns:\n- **Node Labels**: All node types currently in the database\n- **Relationship Types**: All relationship types currently in the database\n- **Node Properties**: Properties discovered from actual data (up to 10 properties per node type)\n\n## Runtime vs Declared Schema\n\n**Use this endpoint** (`/schema`) when you need to know:\n- What data is ACTUALLY in the database right now\n- What properties exist on real nodes\n- What relationships have been created\n- Current database structure for querying\n\n**Use `/schema/export` instead** when you need:\n- The original schema definition used to create the graph\n- Schema in a specific format (JSON, YAML, Cypher DDL)\n- Schema for documentation or version control\n- Schema to replicate in another graph\n\n## Example Use Cases\n\n- **Building queries**: See what node labels and properties exist to write accurate Cypher\n- **Data exploration**: Discover what's in an unfamiliar graph\n- **Schema drift detection**: Compare runtime vs declared schema\n- **API integration**: Dynamically adapt to current graph structure\n\n## Performance Note\n\nProperty discovery is limited to 10 properties per node type for performance.\nFor complete schema definitions, use `/schema/export`.\n\n## Subgraph Support\n\nThis endpoint accepts both parent graph IDs and subgraph IDs.\n- Parent graph: Use `graph_id` like `kg0123456789abcdef`\n- Subgraph: Use full subgraph ID like `kg0123456789abcdef_dev`\nEach subgraph has independent schema and data. The returned schema reflects\nonly the specified graph/subgraph's actual structure.\n\nThis operation is included - no credit consumption required.","operationId":"getGraphSchema","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}}],"responses":{"200":{"description":"Schema information retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchemaInfoResponse"}}}},"403":{"description":"Access denied to graph"},"500":{"description":"Failed to retrieve schema"},"504":{"description":"Schema operation timed out"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/schema/export":{"get":{"tags":["Schema"],"summary":"Export Declared Graph Schema","description":"Export the declared schema definition of an existing graph.\n\n## What This Returns\n\nThis endpoint returns the **original schema definition** that was used to create the graph:\n- The schema as it was **declared** during graph creation\n- Complete node and relationship definitions\n- Property types and constraints\n- Schema metadata (name, version, type)\n\n## Runtime vs Declared Schema\n\n**Use this endpoint** (`/schema/export`) when you need:\n- The original schema definition used to create the graph\n- Schema in a specific format (JSON, YAML, Cypher DDL)\n- Schema for documentation or version control\n- Schema to replicate in another graph\n\n**Use `/schema` instead** when you need:\n- What data is ACTUALLY in the database right now\n- What properties exist on real nodes (discovered from data)\n- Current runtime database structure for querying\n\n## Export Formats\n\n### JSON Format (`format=json`)\nReturns structured JSON with nodes, relationships, and properties.\nBest for programmatic access and API integration.\n\n### YAML Format (`format=yaml`)\nReturns human-readable YAML with comments.\nBest for documentation and configuration management.\n\n### Cypher DDL Format (`format=cypher`)\nReturns Cypher CREATE statements for recreating the schema.\nBest for database migration and replication.\n\n## Data Statistics\n\nSet `include_data_stats=true` to include:\n- Node counts by label\n- Relationship counts by type\n- Total nodes and relationships\n\nThis combines declared schema with runtime statistics.\n\nThis operation is included - no credit consumption required.","operationId":"exportGraphSchema","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","pattern":"^(json|yaml|cypher)$","description":"Export format: json, yaml, or cypher","default":"json","title":"Format"},"description":"Export format: json, yaml, or cypher","examples":{"json":{"summary":"JSON Format","description":"Structured JSON format for programmatic access","value":"json"},"yaml":{"summary":"YAML Format","description":"Human-readable YAML format for documentation","value":"yaml"},"cypher":{"summary":"Cypher DDL","description":"Cypher CREATE statements for database migration","value":"cypher"}}},{"name":"include_data_stats","in":"query","required":false,"schema":{"type":"boolean","description":"Include statistics about actual data in the graph (node counts, relationship counts)","default":false,"title":"Include Data Stats"},"description":"Include statistics about actual data in the graph (node counts, relationship counts)","examples":{"without_stats":{"summary":"Schema Only","description":"Export schema definition without data statistics","value":false},"with_stats":{"summary":"Schema + Statistics","description":"Export schema with node and relationship counts","value":true}}}],"responses":{"200":{"description":"Schema exported successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchemaExportResponse"}}}},"403":{"description":"Access denied to graph"},"404":{"description":"Schema not found for graph"},"500":{"description":"Failed to export schema"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/schema/validate":{"post":{"tags":["Schema"],"summary":"Validate Schema","description":"Validate a custom schema definition before deployment.\n\nThis endpoint performs comprehensive validation including:\n- **Structure Validation**: Ensures proper JSON/YAML format\n- **Type Checking**: Validates data types (STRING, INT, DOUBLE, etc.)\n- **Constraint Verification**: Checks primary keys and unique constraints\n- **Relationship Integrity**: Validates node references in relationships\n- **Naming Conventions**: Ensures valid identifiers\n- **Compatibility**: Checks against existing extensions if specified\n\nSupported formats:\n- JSON schema definitions\n- YAML schema definitions\n- Direct dictionary format\n\nValidation helps prevent:\n- Schema deployment failures\n- Data integrity issues\n- Performance problems\n- Naming conflicts\n\n**Subgraph Support:**\nThis endpoint accepts both parent graph IDs and subgraph IDs.\n- Parent graph: Use `graph_id` like `kg0123456789abcdef`\n- Subgraph: Use full subgraph ID like `kg0123456789abcdef_dev`\nSchema validation is performed against the specified graph/subgraph's current\nschema and data structure.\n\nThis operation is included - no credit consumption required.","operationId":"validateSchema","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchemaValidationRequest","description":"Schema definition to validate"},"examples":{"valid_schema":{"summary":"Valid Schema with Relationships","description":"A complete valid schema with nodes and relationships","value":{"schema_definition":{"name":"financial_analysis","version":"1.0.0","description":"Schema for SEC financial data","nodes":[{"name":"Company","properties":[{"name":"cik","type":"STRING","is_primary_key":true},{"name":"name","type":"STRING","is_required":true},{"name":"ticker","type":"STRING"}]},{"name":"Filing","properties":[{"name":"accession_number","type":"STRING","is_primary_key":true},{"name":"form_type","type":"STRING"}]}],"relationships":[{"name":"FILED","from_node":"Company","to_node":"Filing"}]},"format":"json"}},"schema_with_warnings":{"summary":"Schema with Warnings","description":"Valid schema but with isolated nodes","value":{"schema_definition":{"name":"warehouse_schema","version":"1.0.0","nodes":[{"name":"Product","properties":[{"name":"sku","type":"STRING","is_primary_key":true}]},{"name":"Location","properties":[{"name":"id","type":"STRING","is_primary_key":true}]}],"relationships":[]},"format":"json"}},"invalid_schema":{"summary":"Invalid Schema","description":"Schema with validation errors (invalid type, missing node)","value":{"schema_definition":{"name":"invalid_example","version":"1.0.0","nodes":[{"name":"Company","properties":[{"name":"name","type":"INVALID_TYPE"}]}],"relationships":[{"name":"RELATES_TO","from_node":"Company","to_node":"NonExistentNode"}]},"format":"json"}},"yaml_format":{"summary":"YAML Format Schema","description":"Schema validation using YAML format","value":{"schema_definition":"name: inventory_schema\nversion: '1.0.0'\nnodes:\n  - name: Product\n    properties:\n      - name: sku\n        type: STRING\n        is_primary_key: true\n      - name: name\n        type: STRING\nrelationships:\n  - name: IN_CATEGORY\n    from_node: Product\n    to_node: Category","format":"yaml"}},"compatibility_check":{"summary":"Compatibility Check","description":"Validate schema and check compatibility with existing extensions","value":{"schema_definition":{"name":"custom_extension","version":"1.0.0","nodes":[{"name":"Transaction","properties":[{"name":"id","type":"STRING","is_primary_key":true},{"name":"amount","type":"DOUBLE"}]}]},"format":"json","check_compatibility":["roboledger"]}}}}}},"responses":{"200":{"description":"Schema validation completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchemaValidationResponse"}}}},"400":{"description":"Invalid schema format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied to graph","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Schema validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/graphs/{graph_id}/credits":{"get":{"tags":["Credits"],"summary":"Get Credit Summary","description":"Retrieve comprehensive credit usage summary for the specified graph.\n\nThis endpoint provides:\n- Current credit balance and monthly allocation\n- Credit consumption metrics for the current month\n- Graph tier and credit multiplier information\n- Usage percentage to help monitor credit consumption\n\nNo credits are consumed for checking credit status.","operationId":"getCreditSummary","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","pattern":"^(kg[a-f0-9]{16,}(?:_[a-zA-Z0-9]{1,20})?|sec(?:_[a-zA-Z0-9]{1,20})?)$","description":"Graph database identifier","title":"Graph Id"},"description":"Graph database identifier"}],"responses":{"200":{"description":"Credit summary retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditSummaryResponse"}}}},"403":{"description":"Access denied to graph","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Credit pool not found for graph","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Failed to retrieve credit summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/credits/transactions":{"get":{"tags":["Credits"],"summary":"List Credit Transactions","description":"Retrieve detailed credit transaction history for the specified graph.\n\nThis enhanced endpoint provides:\n- Detailed transaction records with idempotency information\n- Summary by operation type to identify high-consumption operations\n- Date range filtering for analysis\n- Metadata search capabilities\n\nTransaction types include:\n- ALLOCATION: Monthly credit allocations\n- CONSUMPTION: Credit usage for operations\n- BONUS: Bonus credits added by admins\n- REFUND: Credit refunds\n\nNo credits are consumed for viewing transaction history.","operationId":"listCreditTransactions","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","pattern":"^(kg[a-f0-9]{16,}(?:_[a-zA-Z0-9]{1,20})?|sec(?:_[a-zA-Z0-9]{1,20})?)$","description":"Graph database identifier","title":"Graph Id"},"description":"Graph database identifier"},{"name":"transaction_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by transaction type (allocation, consumption, bonus, refund)","title":"Transaction Type"},"description":"Filter by transaction type (allocation, consumption, bonus, refund)","example":"consumption"},{"name":"operation_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by operation type (e.g., entity_lookup, cypher_query)","title":"Operation Type"},"description":"Filter by operation type (e.g., entity_lookup, cypher_query)"},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Start date for filtering (ISO format: YYYY-MM-DD)","title":"Start Date"},"description":"Start date for filtering (ISO format: YYYY-MM-DD)"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"End date for filtering (ISO format: YYYY-MM-DD)","title":"End Date"},"description":"End date for filtering (ISO format: YYYY-MM-DD)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Maximum number of transactions to return","default":100,"title":"Limit"},"description":"Maximum number of transactions to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of transactions to skip","default":0,"title":"Offset"},"description":"Number of transactions to skip"}],"responses":{"200":{"description":"Transaction history retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedTransactionsResponse"}}}},"400":{"description":"Invalid transaction type filter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied to graph","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Failed to retrieve transactions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/health":{"get":{"tags":["Graph Health"],"summary":"Database Health Check","description":"Get comprehensive health information for the graph database.\n\nReturns detailed health metrics including:\n- **Connection Status**: Database connectivity and responsiveness\n- **Performance Metrics**: Query execution times and throughput\n- **Resource Usage**: Memory and storage utilization\n- **Error Monitoring**: Recent error rates and patterns\n- **Uptime Statistics**: Service availability metrics\n\nHealth indicators:\n- **Status**: healthy, degraded, or unhealthy\n- **Query Performance**: Average execution times\n- **Error Rates**: Recent failure percentages\n- **Resource Usage**: Memory and storage consumption\n- **Alerts**: Active warnings or issues\n\n**Subgraph Support:**\nThis endpoint accepts both parent graph IDs and subgraph IDs.\n- Parent graph: Use `graph_id` like `kg0123456789abcdef`\n- Subgraph: Use full subgraph ID like `kg0123456789abcdef_dev`\nHealth metrics are specific to the requested graph/subgraph. Subgraphs share the\nsame physical instance as their parent but have independent health indicators.\n\nThis endpoint provides essential monitoring data for operational visibility.","operationId":"getDatabaseHealth","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}}],"responses":{"200":{"description":"Database health retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatabaseHealthResponse"}}}},"403":{"description":"Access denied to graph"},"404":{"description":"Graph not found"},"500":{"description":"Failed to retrieve health information"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/info":{"get":{"tags":["Graph Info"],"summary":"Database Information","description":"Get comprehensive database information and statistics.\n\nReturns detailed database metrics including:\n- **Database Metadata**: Name, path, size, and timestamps\n- **Schema Information**: Node labels, relationship types, and counts\n- **Storage Statistics**: Database size and usage metrics\n- **Data Composition**: Node and relationship counts\n- **Backup Information**: Available backups and last backup date\n- **Configuration**: Read-only status and schema version\n\nDatabase statistics:\n- **Size**: Storage usage in bytes and MB\n- **Content**: Node and relationship counts\n- **Schema**: Available labels and relationship types\n- **Backup Status**: Backup availability and recency\n- **Timestamps**: Creation and modification dates\n\n**Subgraph Support:**\nThis endpoint accepts both parent graph IDs and subgraph IDs.\n- Parent graph: Use `graph_id` like `kg0123456789abcdef`\n- Subgraph: Use full subgraph ID like `kg0123456789abcdef_dev`\nReturned metrics are specific to the requested graph/subgraph. Subgraphs have\nindependent size, node/relationship counts, and backup status.\n\nThis endpoint provides essential database information for capacity planning and monitoring.","operationId":"getDatabaseInfo","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}}],"responses":{"200":{"description":"Database information retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatabaseInfoResponse"}}}},"403":{"description":"Access denied to graph"},"404":{"description":"Graph not found"},"500":{"description":"Failed to retrieve database information"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/limits":{"get":{"tags":["Graph Limits"],"summary":"Get Graph Operational Limits","description":"Get comprehensive operational limits for the graph database.\n\nReturns all operational limits that apply to this graph including:\n- **Storage Limits**: Maximum storage size and current usage\n- **Query Limits**: Timeouts, complexity, row limits\n- **Copy/Ingestion Limits**: File sizes, timeouts, concurrent operations\n- **Backup Limits**: Frequency, retention, size limits\n- **Rate Limits**: Requests per minute/hour based on tier\n- **Credit Limits**: AI operation credits (if applicable)\n- **Content Limits**: Per-operation materialization limits (if applicable)\n- **Instance Usage**: Aggregate storage across parent + subgraphs (user graphs only)\n\n**Note**: Limits vary based on subscription tier (ladybug-standard, ladybug-large, ladybug-xlarge).","operationId":"getGraphLimits","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}}],"responses":{"200":{"description":"Limits retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GraphLimitsResponse"}}}},"403":{"description":"Access denied to graph"},"404":{"description":"Graph not found"},"500":{"description":"Failed to retrieve limits"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/subgraphs":{"get":{"tags":["Subgraphs"],"summary":"List Subgraphs","description":"List all subgraphs for a parent graph.\n\n**Requirements:**\n- Valid authentication\n- Parent graph must exist and be accessible to the user\n- User must have at least 'read' permission on the parent graph\n\n**Returns:**\n- List of all subgraphs for the parent graph\n- Each subgraph includes its ID, name, description, type, status, and creation date","operationId":"listSubgraphs","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListSubgraphsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Subgraphs"],"summary":"Create Subgraph","description":"Create a new subgraph within a parent graph, with optional data forking.\n\n**Requirements:**\n- Valid authentication\n- Parent graph must exist and be accessible to the user\n- User must have 'admin' permission on the parent graph\n- Parent graph tier must support subgraphs (LadybugDB Large/XLarge)\n- Must be within subgraph quota limits\n- Subgraph name must be unique within the parent graph\n\n**Fork Mode:**\nWhen `fork_parent=true`, the operation:\n- Returns immediately with an operation_id for SSE monitoring\n- Copies data from parent graph to the new subgraph\n- Supports selective forking via metadata.fork_options\n- Tracks progress in real-time via SSE\n\n**Returns:**\n- Without fork: Immediate SubgraphResponse with created subgraph details\n- With fork: Operation response with SSE monitoring endpoint\n\n**Subgraph ID format:** `{parent_id}_{subgraph_name}` (e.g., kg1234567890abcdef_dev)\n\n**Usage:**\n- Subgraphs share parent's credit pool\n- Subgraph ID can be used in all standard `/v1/graphs/{graph_id}/*` endpoints\n- Permissions inherited from parent graph","operationId":"createSubgraph","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubgraphRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/subgraphs/{subgraph_name}":{"delete":{"tags":["Subgraphs"],"summary":"Delete Subgraph","description":"Delete a subgraph database.\n\n**Requirements:**\n- Must be a valid subgraph (not parent graph)\n- User must have admin access to parent graph\n- Subgraph name must be alphanumeric (1-20 characters)\n- Optional backup before deletion\n\n**Deletion Options:**\n- `force`: Delete even if contains data\n- `backup_first`: Create backup before deletion\n\n**Warning:**\nDeletion is permanent unless backup is created.\nAll data in the subgraph will be lost.\n\n**Backup Location:**\nIf backup requested, stored in S3 graph database bucket at:\n`s3://{graph_s3_bucket}/{instance_id}/{database_name}_{timestamp}.backup`\n\n**Notes:**\n- Use the subgraph name (e.g., 'dev', 'staging') not the full subgraph ID\n- Deletion does not affect parent graph's credit pool or permissions\n- Backup creation consumes credits from parent graph's allocation","operationId":"deleteSubgraph","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}},{"name":"subgraph_name","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-zA-Z0-9]{1,20}$","description":"Subgraph name to delete (e.g., 'dev', 'staging')","title":"Subgraph Name"},"description":"Subgraph name to delete (e.g., 'dev', 'staging')"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteSubgraphRequest"}}}},"responses":{"200":{"description":"Subgraph deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteSubgraphResponse"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Insufficient permissions"},"404":{"description":"Subgraph not found"},"400":{"description":"Invalid subgraph identifier"},"409":{"description":"Subgraph contains data (use force=true)"},"500":{"description":"Internal server error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/subgraphs/{subgraph_name}/info":{"get":{"tags":["Subgraphs"],"summary":"Get Subgraph Details","description":"Get detailed information about a specific subgraph.\n\n**Requirements:**\n- User must have read access to parent graph\n- Subgraph name must be alphanumeric (1-20 characters)\n\n**Response includes:**\n- Full subgraph metadata\n- Database statistics (nodes, edges)\n- Size information\n- Schema configuration\n- Creation/modification timestamps\n- Last access time (when available)\n\n**Statistics:**\nReal-time statistics queried from LadybugDB:\n- Node count\n- Edge count\n- Database size on disk\n- Schema information\n\n**Note:**\nUse the subgraph name (e.g., 'dev', 'staging') not the full subgraph ID.\nThe full ID is returned in the response (e.g., 'kg0123456789abcdef_dev').","operationId":"getSubgraphInfo","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}},{"name":"subgraph_name","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-zA-Z0-9]{1,20}$","description":"Subgraph name (e.g., 'dev', 'staging')","title":"Subgraph Name"},"description":"Subgraph name (e.g., 'dev', 'staging')"}],"responses":{"200":{"description":"Subgraph information retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubgraphResponse"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied"},"404":{"description":"Subgraph not found"},"400":{"description":"Not a valid subgraph"},"500":{"description":"Internal server error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/subgraphs/quota":{"get":{"tags":["Subgraphs"],"summary":"Get Subgraph Quota","description":"Get subgraph quota and usage information for a parent graph.\n\n**Shows:**\n- Current subgraph count\n- Maximum allowed subgraphs per tier\n- Remaining capacity\n- Total size usage across all subgraphs\n\n**Tier Limits:**\n- Standard: Up to 3 subgraphs (dedicated m7g.large instance)\n- Large: Up to 10 subgraphs (dedicated r7g.large instance)\n- XLarge: Up to 25 subgraphs (dedicated r7g.xlarge instance)\n- Limits are defined in graph.yml deployment configuration\n\n**Size Tracking:**\nProvides aggregate size metrics when available.\nIndividual subgraph sizes shown in list endpoint.","operationId":"getSubgraphQuota","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}}],"responses":{"200":{"description":"Quota information retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubgraphQuotaResponse"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied to parent graph"},"404":{"description":"Parent graph not found"},"500":{"description":"Internal server error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/subscriptions":{"get":{"tags":["Subscriptions"],"summary":"Get Graph and Shared Repository Subscription","description":"Get subscription details for a graph or shared repository.\n\nFor user graphs (kg*): Returns the graph's subscription (owned by graph creator)\nFor shared repositories (sec, industry, etc.): Returns user's personal subscription to that repository\n\nThis unified endpoint automatically detects the resource type and returns the appropriate subscription.","operationId":"getGraphSubscription","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","pattern":"^(kg[a-f0-9]{16,}(?:_[a-zA-Z0-9]{1,20})?|sec(?:_[a-zA-Z0-9]{1,20})?)$","description":"Graph ID or repository name","title":"Graph Id"},"description":"Graph ID or repository name"}],"responses":{"200":{"description":"Subscription retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GraphSubscriptionResponse"},"examples":{"user_graph":{"summary":"User Graph Subscription","value":{"id":"bsub_abc123","resource_type":"graph","resource_id":"kg1a2b3c","plan_name":"ladybug-standard","billing_interval":"monthly","status":"active","base_price_cents":4999,"started_at":"2024-01-15T10:30:00Z"}},"repository":{"summary":"Repository Subscription","value":{"id":"bsub_xyz789","resource_type":"repository","resource_id":"sec","plan_name":"sec-advanced","billing_interval":"monthly","status":"active","base_price_cents":9999,"started_at":"2024-01-15T10:30:00Z"}}}}}},"404":{"description":"No subscription found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Subscriptions"],"summary":"Create Repository Subscription","description":"Create a new subscription to a shared repository.\n\nThis endpoint is ONLY for shared repositories (sec, industry, economic).\nUser graph subscriptions are created automatically when the graph is provisioned.\n\nThe subscription will be created in ACTIVE status immediately and credits will be allocated.","operationId":"createRepositorySubscription","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","pattern":"^(kg[a-f0-9]{16,}(?:_[a-zA-Z0-9]{1,20})?|sec(?:_[a-zA-Z0-9]{1,20})?)$","description":"Repository name (e.g., 'sec', 'industry')","title":"Graph Id"},"description":"Repository name (e.g., 'sec', 'industry')"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRepositorySubscriptionRequest"}}}},"responses":{"201":{"description":"Repository subscription created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GraphSubscriptionResponse"}}}},"400":{"description":"Invalid request - cannot create subscription for user graphs"},"409":{"description":"User already has a subscription to this repository"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["Subscriptions"],"summary":"Change Subscription Plan","description":"Change the plan on an existing subscription.\n\n**For shared repositories** (sec, industry, etc.): Changes access tier (e.g., starter -> advanced).\nSynchronous — takes effect immediately.\n\n**For user graphs** (kg*): Changes infrastructure tier (e.g., ladybug-standard -> ladybug-large).\nAsynchronous — returns an `operation_id` for tracking the EBS volume migration via SSE.\n\nStripe handles proration automatically for both types.\n\n**Requirements:**\n- User must be an OWNER of their organization\n- Subscription must be active\n- New plan must be valid for the resource type\n\n**Downgrade restrictions (graphs only):**\n- Subgraph count must fit the target tier's limit\n- Storage usage must fit the target tier's limit","operationId":"changeSubscriptionPlan","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","pattern":"^(kg[a-f0-9]{16,}(?:_[a-zA-Z0-9]{1,20})?|sec(?:_[a-zA-Z0-9]{1,20})?)$","description":"Graph ID or repository name","title":"Graph Id"},"description":"Graph ID or repository name"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpgradeSubscriptionRequest"}}}},"responses":{"200":{"description":"Plan changed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GraphSubscriptionResponse"}}}},"400":{"description":"Invalid plan, validation failure, or status conflict"},"404":{"description":"No subscription found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/tables":{"get":{"tags":["Tables"],"summary":"List Staging Tables","description":"List all DuckDB staging tables with comprehensive metrics and status.\n\nGet a complete inventory of all staging tables for a graph, including\nfile counts, storage sizes, and row estimates. Essential for monitoring\nthe data pipeline and determining which tables are ready for ingestion.\n\n**Returned Metrics:**\n- Table name and type (node/relationship)\n- File count per table\n- Total storage size in bytes\n- Estimated row count\n- S3 location pattern\n- Ready-for-ingestion status\n\n**Use Cases:**\n- Monitor data upload progress\n- Check which tables have files ready\n- Track storage consumption\n- Validate pipeline before ingestion\n- Capacity planning\n\n**Workflow:**\n1. List tables to see current state\n2. Upload files to empty tables\n3. Re-list to verify uploads\n4. Check file counts and sizes\n5. Ingest when ready\n\n**Important Notes:**\n- Tables with `file_count > 0` have data ready\n- Check `total_size_bytes` for storage monitoring\n- Use `s3_location` to verify upload paths\n- Empty tables (file_count=0) are skipped during ingestion\n- Table queries are included - no credit consumption","operationId":"listTables","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}}],"responses":{"200":{"description":"Tables retrieved successfully with full metrics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TableListResponse"},"example":{"tables":[{"table_name":"Entity","row_count":5000,"file_count":3,"total_size_bytes":2457600,"s3_location":"s3://bucket/staging/Entity/**/*.parquet"}],"total_count":1}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied - insufficient permissions for this graph","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Graph not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/tables/query":{"post":{"tags":["Tables"],"summary":"Query Staging Tables with SQL","description":"Execute SQL queries on DuckDB staging tables for data inspection and validation.\n\nQuery raw staging data directly with SQL before ingestion into the graph database.\nUseful for data quality checks, validation, and exploratory analysis.\n\n**Security Best Practice - Use Parameterized Queries:**\nALWAYS use query parameters instead of string concatenation to prevent SQL injection:\n- ✅ SAFE: `SELECT * FROM Entity WHERE type = ? LIMIT ?` with `parameters: [\"Company\", 100]`\n- ❌ UNSAFE: `SELECT * FROM Entity WHERE type = 'Company' LIMIT 100` with user input concatenated into SQL string\n\nQuery parameters provide automatic escaping and type safety. Use `?` placeholders with parameters array.\n\n**Use Cases:**\n- Validate data quality before graph ingestion\n- Inspect row-level data for debugging\n- Run analytics on staging tables\n- Check for duplicates, nulls, or data issues\n- Preview data transformations\n\n**Workflow:**\n1. Upload data files via `POST /tables/{table_name}/files`\n2. Query staging tables to validate: `POST /tables/query`\n3. Fix any data issues by re-uploading\n4. Ingest validated data: `POST /tables/ingest`\n\n**Supported SQL:**\n- Full DuckDB SQL syntax\n- SELECT, JOIN, WHERE, GROUP BY, ORDER BY\n- Aggregations, window functions, CTEs\n- Multiple table joins across staging area\n\n**Common Operations:**\n- Count rows: `SELECT COUNT(*) FROM Entity`\n- Filter by type: `SELECT * FROM Entity WHERE entity_type = ? LIMIT ?` with `parameters: [\"Company\", 100]`\n- Check for nulls: `SELECT * FROM Entity WHERE name IS NULL LIMIT 10`\n- Find duplicates: `SELECT identifier, COUNT(*) as cnt FROM Entity GROUP BY identifier HAVING COUNT(*) > 1`\n- Filter amounts: `SELECT * FROM Transaction WHERE amount > ? AND date >= ?` with `parameters: [1000, \"2024-01-01\"]`\n\n**Limits:**\n- Query timeout: 30 seconds\n- Result limit: 10,000 rows (use LIMIT clause)\n- Read-only: No INSERT, UPDATE, DELETE\n- User's tables only: Cannot query other users' data\n\n**Subgraph Support:**\nThis endpoint accepts both parent graph IDs and subgraph IDs.\n- Parent graph: Use `graph_id` like `kg0123456789abcdef`\n- Subgraph: Use full subgraph ID like `kg0123456789abcdef_dev`\nEach subgraph has its own independent staging tables.\n\n**Shared Repositories:**\nShared repositories (SEC, etc.) do not allow direct SQL queries.\nUse the graph query endpoint instead: `POST /v1/graphs/{graph_id}/query`\n\n**Note:**\nStaging table queries are included - no credit consumption","operationId":"queryTables","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TableQueryRequest","description":"SQL query request"}}}},"responses":{"200":{"description":"Query executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TableQueryResponse"},"example":{"success":true,"data":[{"name":"Acme Corp","count":150},{"name":"TechCo","count":89}],"columns":["name","count"],"row_count":2,"execution_time_ms":45.2}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied - shared repositories or insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Graph not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Invalid SQL query syntax or execution error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"408":{"description":"Query timeout exceeded"},"500":{"description":"Internal server error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/search":{"post":{"tags":["Search"],"summary":"Search Documents","description":"Search filing narratives and text content within a graph.","operationId":"search_documents","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/search/{document_id}":{"get":{"tags":["Search"],"summary":"Get Document Section","description":"Retrieve the full text of a document section by ID.","operationId":"get_document_section","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}},{"name":"document_id","in":"path","required":true,"schema":{"type":"string","title":"Document Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentSection"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/documents":{"get":{"tags":["Documents"],"summary":"List Documents","description":"List documents for a graph from PostgreSQL.","operationId":"list_documents","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}},{"name":"source_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Type"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Documents"],"summary":"Upload Document","description":"Upload a markdown document. Stored in PostgreSQL, synced to OpenSearch.","operationId":"upload_document","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUploadRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUploadResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/documents/{document_id}":{"get":{"tags":["Documents"],"summary":"Get Document","description":"Get a document with full content from PostgreSQL.","operationId":"get_document","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}},{"name":"document_id","in":"path","required":true,"schema":{"type":"string","title":"Document Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentDetailResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["Documents"],"summary":"Update Document","description":"Update a document's content and/or metadata. Re-syncs to OpenSearch.","operationId":"update_document","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}},{"name":"document_id","in":"path","required":true,"schema":{"type":"string","title":"Document Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUpdateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUploadResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Documents"],"summary":"Delete Document","description":"Delete a document from PostgreSQL and OpenSearch.","operationId":"delete_document","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}},{"name":"document_id","in":"path","required":true,"schema":{"type":"string","title":"Document Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/documents/bulk":{"post":{"tags":["Documents"],"summary":"Upload Documents Bulk","description":"Upload multiple markdown documents (max 50).","operationId":"upload_documents_bulk","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkDocumentUploadRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkDocumentUploadResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/materialize":{"get":{"tags":["Materialize"],"summary":"Get Materialization Status","description":"Get current materialization status for the graph.\n\nShows whether the graph is stale (DuckDB has changes not yet in graph database),\nwhen it was last materialized, and how long since last materialization.\n\n**Status Information:**\n- Whether graph is currently stale\n- Reason for staleness if applicable\n- When graph became stale\n- When graph was last materialized\n- Total materialization count\n- Hours since last materialization\n\n**Use Cases:**\n- Decide if materialization is needed\n- Monitor graph freshness\n- Track materialization history\n- Understand data pipeline state\n\n**Important Notes:**\n- Stale graph means DuckDB has changes not in graph\n- Graph becomes stale after file deletions\n- Materialization clears staleness\n- Status retrieval is included - no credit consumption","operationId":"getMaterializationStatus","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}}],"responses":{"200":{"description":"Materialization status retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaterializeStatusResponse"},"example":{"graph_id":"kg_abc123","is_stale":true,"stale_reason":"file_deleted: data.parquet from tables Fact","stale_since":"2025-01-20T14:30:00Z","last_materialized_at":"2025-01-20T10:00:00Z","materialization_count":5,"hours_since_materialization":4.5,"message":"Graph is stale - materialization recommended. Last materialized 4.5 hours ago."}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Graph not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Materialize"],"summary":"Materialize Graph from DuckDB","description":"Rebuild entire graph from DuckDB staging tables (materialized view pattern).\n\nThis endpoint rebuilds the complete graph database from the current state of DuckDB\nstaging tables. It automatically discovers all tables, ingests them in the correct\norder (nodes before relationships), and clears the staleness flag.\n\n**When to Use:**\n- After batch uploads (files uploaded with ingest_to_graph=false)\n- After cascade file deletions (graph marked stale)\n- To ensure graph consistency with DuckDB state\n- Periodic full refresh\n\n**What Happens:**\n1. Discovers all tables for the graph from PostgreSQL registry\n2. Sorts tables (nodes before relationships)\n3. Ingests all tables from DuckDB to graph in order\n4. Clears staleness flag on success\n5. Returns detailed materialization report\n\n**Staleness Check:**\nBy default, only materializes if graph is stale (after deletions or missed ingestions).\nUse `force=true` to rebuild regardless of staleness.\n\n**Rebuild Feature:**\nSetting `rebuild=true` regenerates the entire graph database from scratch:\n- Deletes existing graph database\n- Recreates with fresh schema from active GraphSchema\n- Ingests all data files\n- Safe operation - DuckDB is source of truth\n- Useful for schema changes or data corrections\n- Graph marked as 'rebuilding' during process\n\n**Table Ordering:**\nNode tables (PascalCase) are ingested before relationship tables (UPPERCASE) to\nensure referential integrity.\n\n**Error Handling:**\nWith `ignore_errors=true` (default), continues materializing even if individual\nrows fail. Failed rows are logged but don't stop the process.\n\n**Concurrency Control:**\nOnly one materialization can run per graph at a time. If another materialization is in progress,\nyou'll receive a 409 Conflict error. The distributed lock automatically expires after\nthe configured TTL (default: 1 hour) to prevent deadlocks from failed materializations.\n\n**Performance:**\nFull graph materialization can take minutes for large datasets. Consider running\nduring off-peak hours for production systems.\n\n**Dry Run:**\nSet `dry_run=true` to validate limits without executing. Returns current usage, tier limits,\nand any warnings or errors. No lock is acquired, no SSE operation is created.\n\n**Credits:**\nMaterialization is included - no credit consumption","operationId":"materializeGraph","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaterializeRequest"}}}},"responses":{"200":{"description":"Graph materialized successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaterializeResponse"},"example":{"status":"success","graph_id":"kg_abc123","was_stale":true,"stale_reason":"file_deleted: data.parquet from tables Fact","tables_materialized":["Entity","Fact","ENTITY_HAS_FACT"],"total_rows":125000,"execution_time_ms":3456.78,"message":"Graph materialized successfully from 3 tables"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied - shared repositories or insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Graph not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Graph not stale and force=false","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict - another materialization is already in progress for this graph","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Graph content limit exceeded - data too large for current tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/files":{"get":{"tags":["Files"],"summary":"List Files in Graph","description":"List all files in the graph with optional filtering.\n\nGet a complete inventory of files across all tables or filtered by table name,\nstatus, or other criteria. Files are first-class resources with independent lifecycle.\n\n**Query Parameters:**\n- `table_name` (optional): Filter by table name\n- `status` (optional): Filter by upload status (uploaded, pending, failed, etc.)\n\n**Use Cases:**\n- Monitor file upload progress across all tables\n- Verify files are ready for ingestion\n- Check file metadata and sizes\n- Track storage usage per graph\n- Identify failed or incomplete uploads\n- Audit file provenance\n\n**Returned Metadata:**\n- File ID, name, and format (parquet, csv, json)\n- Size in bytes and row count (if available)\n- Upload status and timestamps\n- DuckDB and graph ingestion status\n- Table association\n\n**File Lifecycle Tracking:**\nMulti-layer status across S3 → DuckDB → Graph pipeline\n\n**Important Notes:**\n- Files are graph-scoped, not table-scoped\n- Use table_name parameter to filter by table\n- File listing is included - no credit consumption","operationId":"listFiles","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}},{"name":"table_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by table name (optional)","title":"Table Name"},"description":"Filter by table name (optional)"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by upload status (optional)","title":"Status"},"description":"Filter by upload status (optional)"}],"responses":{"200":{"description":"Files retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListTableFilesResponse"},"example":{"graph_id":"kg123","files":[{"file_id":"f123","file_name":"data.parquet","file_format":"parquet","size_bytes":1048576,"row_count":5000,"upload_status":"uploaded","table_name":"Entity","created_at":"2025-10-28T10:00:00Z","uploaded_at":"2025-10-28T10:01:30Z"}],"total_files":1,"total_size_bytes":1048576}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Graph not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Files"],"summary":"Create File Upload","description":"Generate presigned S3 URL for file upload.\n\nInitiate file upload by generating a secure, time-limited presigned S3 URL.\nFiles are first-class resources uploaded directly to S3.\n\n**Request Body:**\n- `file_name`: Name of the file (1-255 characters)\n- `file_format`: Format (parquet, csv, json)\n- `table_name`: Table to associate file with\n\n**Upload Workflow:**\n1. Call this endpoint to get presigned URL\n2. PUT file directly to S3 URL\n3. Call PATCH /files/{file_id} with status='uploaded'\n4. Backend validates and stages in DuckDB immediately\n5. Background task ingests to graph\n\n**Supported Formats:**\n- Parquet, CSV, JSON\n\n**Auto-Table Creation:**\nTables are automatically created if they don't exist.\n\n**Important Notes:**\n- Presigned URLs expire (default: 1 hour)\n- Files are graph-scoped, independent resources\n- Upload URL generation is included - no credit consumption","operationId":"createFileUpload","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileUploadRequest","description":"Upload request with table_name"}}}},"responses":{"200":{"description":"Upload URL generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileUploadResponse"},"example":{"upload_url":"https://bucket.s3.amazonaws.com/path?signature","expires_in":3600,"file_id":"f123","s3_key":"user-staging/user123/kg123/Entity/data.parquet"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied - shared repositories or insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Graph not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Invalid file format or parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/{graph_id}/files/{file_id}":{"get":{"tags":["Files"],"summary":"Get File Information","description":"Get detailed information about a specific file.\n\nRetrieve comprehensive metadata for a single file by file_id, independent of\ntable context. Files are first-class resources with complete lifecycle tracking.\n\n**Returned Information:**\n- File ID, name, format, size\n- Upload status and timestamps\n- **Enhanced Multi-Layer Status** (new in this version):\n  - S3 layer: upload_status, uploaded_at, size_bytes, row_count\n  - DuckDB layer: duckdb_status, duckdb_staged_at, duckdb_row_count\n  - Graph layer: graph_status, graph_ingested_at\n- Table association\n- S3 location\n\n**Multi-Layer Pipeline Visibility:**\nThe `layers` object provides independent status tracking across the three-tier\ndata pipeline:\n- **S3 (Immutable Source)**: File upload and validation\n- **DuckDB (Mutable Staging)**: Immediate queryability with file provenance\n- **Graph (Immutable View)**: Optional graph database materialization\n\nEach layer shows its own status, timestamp, and row count (where applicable),\nenabling precise debugging and monitoring of the data ingestion flow.\n\n**Use Cases:**\n- Validate file upload completion\n- Monitor multi-layer ingestion progress in real-time\n- Debug upload or staging issues at specific layers\n- Verify file metadata and row counts\n- Track file provenance through the pipeline\n- Identify bottlenecks in the ingestion process\n\n**Note:**\nFile info retrieval is included - no credit consumption","operationId":"getFile","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}},{"name":"file_id","in":"path","required":true,"schema":{"type":"string","description":"File ID","title":"File Id"},"description":"File ID"}],"responses":{"200":{"description":"File information retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetFileInfoResponse"},"example":{"file_id":"f123","graph_id":"kg123","table_id":"t456","table_name":"Entity","file_name":"data.parquet","file_format":"parquet","size_bytes":1048576,"row_count":5000,"upload_status":"uploaded","created_at":"2025-10-28T10:00:00Z","uploaded_at":"2025-10-28T10:01:30Z","layers":{"s3":{"status":"uploaded","timestamp":"2025-10-28T10:01:30Z","row_count":5000,"size_bytes":1048576},"duckdb":{"status":"staged","timestamp":"2025-10-28T10:02:15Z","row_count":5000},"graph":{"status":"ingested","timestamp":"2025-10-28T10:05:45Z"}}}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"File not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Files"],"summary":"Delete File","description":"Delete file from all layers.\n\nRemove file from S3, database tracking, and optionally from DuckDB and graph.\nFiles are deleted by file_id, independent of table context.\n\n**Query Parameters:**\n- `cascade` (optional, default=false): Delete from all layers including DuckDB\n\n**What Happens (cascade=false):**\n1. File deleted from S3\n2. Database record removed\n3. Table statistics updated\n\n**What Happens (cascade=true):**\n1. File data deleted from all DuckDB tables (by file_id)\n2. Graph marked as stale\n3. File deleted from S3\n4. Database record removed\n5. Table statistics updated\n\n**Use Cases:**\n- Remove incorrect or duplicate files\n- Clean up failed uploads\n- Delete files before graph ingestion\n- Surgical data removal with cascade\n\n**Security:**\n- Write access required\n- Shared repositories block deletions\n- Full audit trail\n\n**Important:**\n- Use cascade=true for immediate DuckDB cleanup\n- Graph rebuild recommended after cascade deletion\n- File deletion is included - no credit consumption","operationId":"deleteFile","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}},{"name":"file_id","in":"path","required":true,"schema":{"type":"string","description":"File ID","title":"File Id"},"description":"File ID"},{"name":"cascade","in":"query","required":false,"schema":{"type":"boolean","description":"If true, delete from all layers including DuckDB and mark graph stale","default":false,"title":"Cascade"},"description":"If true, delete from all layers including DuckDB and mark graph stale"}],"responses":{"200":{"description":"File deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteFileResponse"},"example":{"status":"deleted","file_id":"f123","file_name":"data.parquet","message":"File deleted successfully. Removed data from 2 DuckDB table(s). Graph marked as stale - rebuild recommended.","cascade_deleted":true,"tables_affected":["Fact","Element"],"graph_marked_stale":true}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied - shared repositories or insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"File not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["Files"],"summary":"Update File Status","description":"Update file status and trigger processing.\n\nUpdate file status after upload completion. Setting status='uploaded' triggers\nimmediate DuckDB staging and optional graph ingestion.\n\n**Request Body:**\n- `status`: New status (uploaded, disabled, failed)\n- `ingest_to_graph` (optional): If true, auto-ingest to graph after DuckDB staging\n\n**What Happens (status='uploaded'):**\n1. File validated in S3\n2. Row count calculated\n3. DuckDB staging triggered immediately (background task)\n4. If ingest_to_graph=true, graph ingestion queued\n5. File queryable in DuckDB within seconds\n\n**Use Cases:**\n- Signal upload completion\n- Trigger immediate DuckDB staging\n- Enable/disable files\n- Mark failed uploads\n\n**Important:**\n- Files must exist in S3 before marking uploaded\n- DuckDB staging happens asynchronously\n- Graph ingestion is optional (ingest_to_graph flag)","operationId":"updateFile","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}},{"name":"file_id","in":"path","required":true,"schema":{"type":"string","description":"File ID","title":"File Id"},"description":"File ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileStatusUpdate","description":"Status update request"}}}},"responses":{"200":{"description":"File status updated successfully","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Updatefile"},"example":{"file_id":"f123","status":"uploaded","message":"File uploaded and queued for DuckDB staging","operation_id":"op_abc123","monitor_url":"/v1/operations/op_abc123/stream"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"File not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Invalid status or file not in S3","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs":{"get":{"tags":["Graphs"],"summary":"Get User Graphs and Repositories","description":"List all graph databases and shared repositories accessible to the current user.\n\nReturns a unified list of both user-created graphs and shared repositories (like SEC data)\nthat the user has access to, including their role/access level and selection status.\n\n**Returned Information:**\n- Graph/Repository ID and display name\n- User's role/access level (admin/member for graphs, read/write/admin for repositories)\n- Selection status (only user graphs can be selected)\n- Creation timestamp\n- Repository type indicator (isRepository: true for shared repositories)\n\n**User Graphs (isRepository: false):**\n- Collaborative workspaces that can be shared with other users\n- Roles: `admin` (full access, can invite users) or `member` (read/write access)\n- Can be selected as active workspace\n- Graphs you create or have been invited to\n\n**Shared Repositories (isRepository: true):**\n- Read-only data repositories (e.g., SEC filings)\n- Access levels: `read`, `write` (for data contributions), `admin`\n- Cannot be selected (each has separate subscription)\n- Require separate subscriptions (personal, cannot be shared)\n\n**Selected Graph Concept:**\nThe \"selected\" graph is the user's currently active workspace (user graphs only).\nMany API operations default to the selected graph if no graph_id is provided.\nUsers can change their selected graph via `POST /v1/graphs/{graph_id}/select`.\n\n**Use Cases:**\n- Display unified graph/repository selector in UI\n- Show all accessible data sources (both owned graphs and subscribed repositories)\n- Identify currently active workspace\n- Filter by type (user graphs vs repositories)\n\n**Empty Response:**\nNew users receive an empty list with `selectedGraphId: null`. Users should create\na graph or subscribe to a repository.\n\n**Note:**\nGraph listing is included - no credit consumption required.","operationId":"getGraphs","responses":{"200":{"description":"Graphs retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserGraphsResponse"},"examples":{"with_graphs_and_repositories":{"summary":"User with graphs and repository subscriptions","value":{"graphs":[{"graphId":"kg1a2b3c4d5","graphName":"Acme Consulting LLC","role":"admin","isSelected":true,"createdAt":"2024-01-15T10:00:00Z","isRepository":false},{"graphId":"kg9z8y7x6w5","graphName":"TechCorp Enterprises","role":"member","isSelected":false,"createdAt":"2024-02-20T14:30:00Z","isRepository":false},{"graphId":"sec","graphName":"SEC","role":"read","isSelected":false,"createdAt":"2024-03-01T09:00:00Z","isRepository":true,"repositoryType":"sec"}],"selectedGraphId":"kg1a2b3c4d5"}},"empty":{"summary":"New user without graphs","value":{"graphs":[]}}}}}},"500":{"description":"Error retrieving graphs"}},"security":[{"APIKeyHeader":[]},{"BearerAuth":[]}]},"post":{"tags":["Graphs"],"summary":"Create New Graph Database","description":"Create a new graph database with specified schema and optionally an initial entity.\n\nThis endpoint starts an asynchronous graph creation operation and returns\nconnection details for monitoring progress via Server-Sent Events (SSE).\n\n**Graph Creation Options:**\n\n1. **Entity Graph with Initial Entity** (`initial_entity` provided, `create_entity=True`):\n   - Creates graph structure with entity schema extensions\n   - Populates an initial entity node with provided data\n   - Useful when you want a pre-configured entity to start with\n   - Example: Creating a company graph with the company already populated\n\n2. **Entity Graph without Initial Entity** (`initial_entity=None`, `create_entity=False`):\n   - Creates graph structure with entity schema extensions\n   - Graph starts empty, ready for data import\n   - Useful for bulk data imports or custom workflows\n   - Example: Creating a graph structure before importing from CSV/API\n\n3. **Generic Graph** (no `initial_entity` provided):\n   - Creates empty graph with custom schema extensions\n   - General-purpose knowledge graph\n   - Example: Analytics graphs, custom data models\n\n**Required Fields:**\n- `metadata.graph_name`: Unique name for the graph\n- `instance_tier`: Resource tier (ladybug-standard, ladybug-large, ladybug-xlarge)\n\n**Optional Fields:**\n- `metadata.description`: Human-readable description of the graph's purpose\n- `metadata.schema_extensions`: List of schema extensions (roboledger, roboinvestor, etc.)\n- `tags`: Organizational tags (max 10)\n- `initial_entity`: Entity data (required for entity graphs with initial data)\n- `create_entity`: Whether to populate initial entity (default: true when initial_entity provided)\n\n**Monitoring Progress:**\nUse the returned `operation_id` to connect to the SSE stream:\n```javascript\nconst eventSource = new EventSource('/v1/operations/{operation_id}/stream');\neventSource.onmessage = (event) => {\n  const data = JSON.parse(event.data);\n  console.log('Progress:', data.progress_percent + '%');\n};\n```\n\n**SSE Connection Limits:**\n- Maximum 5 concurrent SSE connections per user\n- Rate limited to 10 new connections per minute\n- Automatic circuit breaker for Redis failures\n- Graceful degradation if event system unavailable\n\n**Events Emitted:**\n- `operation_started`: Graph creation begins\n- `operation_progress`: Schema loading, database setup, etc.\n- `operation_completed`: Graph ready with connection details\n- `operation_error`: Creation failed with error details\n\n**Error Handling:**\n- `429 Too Many Requests`: SSE connection limit exceeded\n- `503 Service Unavailable`: SSE system temporarily disabled\n- Clients should implement exponential backoff on errors\n\n**Response includes:**\n- `operation_id`: Unique identifier for monitoring\n- `_links.stream`: SSE endpoint for real-time updates\n- `_links.status`: Point-in-time status check endpoint","operationId":"createGraph","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGraphRequest"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/graphs/extensions":{"get":{"tags":["Graphs"],"summary":"Get Available Schema Extensions","description":"List all available schema extensions for graph creation.\n\nSchema extensions provide pre-built industry-specific data models that extend\nthe base graph schema with specialized nodes, relationships, and properties.\n\n**Available Extensions:**\n- **RoboLedger**: Complete accounting system with XBRL reporting, general ledger, and financial statements\n- **RoboInvestor**: Investment portfolio management with securities tracking, trade execution, and risk analysis\n- **RoboSCM**: Supply chain management and logistics\n- **RoboFO**: Front office operations and CRM\n- **RoboHRM**: Human resources management\n- **RoboEPM**: Enterprise performance management\n- **RoboReport**: Business intelligence and reporting\n\n**Extension Information:**\nEach extension includes:\n- Display name and description\n- Node and relationship counts\n- Context-aware capabilities (e.g., SEC repositories get different features than entity graphs)\n\n**Use Cases:**\n- Browse available extensions before creating a graph\n- Understand extension capabilities and data models\n- Plan graph schema based on business requirements\n- Combine multiple extensions for comprehensive data modeling\n\n**Note:**\nExtension listing is included - no credit consumption required.","operationId":"getAvailableExtensions","responses":{"200":{"description":"Extensions retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailableExtensionsResponse"},"example":{"extensions":[{"name":"roboledger","description":"Complete accounting system with XBRL reporting and GL transactions","enabled":false},{"name":"roboinvestor","description":"Investment portfolio management with securities tracking, trade execution, and risk analysis.","enabled":false}]}}}},"500":{"description":"Failed to retrieve extensions"}},"security":[{"APIKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/graphs/tiers":{"get":{"tags":["Graphs"],"summary":"Get Available Graph Tiers","description":"List all available graph database tier configurations.\n\nThis endpoint provides comprehensive technical specifications for each available\ngraph database tier, including instance types, resource limits, and features.\n\n**Tier Information:**\nEach tier includes:\n- Technical specifications (instance type, memory, storage)\n- Resource limits (subgraphs, credits, rate limits)\n- Feature list with capabilities\n- Availability status\n\n**Available Tiers:**\n- **ladybug-standard**: Dedicated entry-level tier\n- **ladybug-large**: Dedicated professional tier with subgraph support\n- **ladybug-xlarge**: Enterprise tier with maximum resources\n\n**Use Cases:**\n- Display tier options in graph creation UI\n- Show technical specifications for tier selection\n- Validate tier availability before graph creation\n- Display feature comparisons\n\n**Note:**\nTier listing is included - no credit consumption required.","operationId":"getAvailableGraphTiers","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"include_disabled","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Disabled"}}],"responses":{"200":{"description":"Tiers retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailableGraphTiersResponse"},"example":{"tiers":[{"tier":"ladybug-standard","name":"ladybug-standard","display_name":"LadybugDB Standard","description":"Dedicated m7g.large instance for entry-level workloads","backend":"ladybug","enabled":true,"max_subgraphs":3,"monthly_credits":8000,"api_rate_multiplier":1.0,"monthly_price":100.0,"features":["5M node limit","8,000 AI credits per month","Up to 3 subgraphs","Dedicated large instance","6GB RAM","7-day backup retention"],"instance":{"type":"m7g.large","memory_mb":6144,"is_multitenant":false},"limits":{"monthly_credits":8000,"max_subgraphs":3,"copy_operations":{"max_file_size_gb":1.0,"timeout_seconds":300,"concurrent_operations":1,"max_files_per_operation":100,"daily_copy_operations":10},"backup":{"max_backup_size_gb":10,"backup_retention_days":7,"max_backups_per_day":2}}}]}}}},"500":{"description":"Failed to retrieve tiers"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/graphs/capacity":{"get":{"tags":["Graphs"],"summary":"Get Graph Tier Capacity","description":"Check current infrastructure capacity for each graph database tier.\n\nReturns a status per tier indicating whether instances are immediately available,\ncan be provisioned on demand, or are at capacity.\n\n**Status Values:**\n- `ready` — An instance slot is available; graph creation will succeed immediately\n- `scalable` — No slots right now, but a new instance can be provisioned (3-5 min)\n- `at_capacity` — Tier is full and cannot auto-scale; contact support\n\n**Use Cases:**\n- Pre-flight check before entering the graph creation wizard\n- Show availability badges on tier selection cards\n- Gate tier selection and show contact form for at-capacity tiers\n\n**Caching:**\nResults are cached for 60 seconds to avoid excessive infrastructure queries.\n\n**Note:**\nNo credit consumption required. Does not expose instance counts or IPs.","operationId":"getGraphCapacity","responses":{"200":{"description":"Capacity status retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GraphCapacityResponse"},"example":{"tiers":[{"tier":"ladybug-standard","display_name":"LadybugDB Standard","status":"ready","message":"Available"},{"tier":"ladybug-large","display_name":"LadybugDB Large","status":"scalable","message":"Available — provisioning takes 3-5 minutes"},{"tier":"ladybug-xlarge","display_name":"LadybugDB XLarge","status":"at_capacity","message":"Currently at capacity — contact us for access"}]}}}},"500":{"description":"Failed to check capacity"}},"security":[{"APIKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/graphs/{graph_id}/select":{"post":{"tags":["Graphs"],"summary":"Select Graph","description":"Select a specific graph as the active workspace for the user.\n\nThe selected graph becomes the default context for operations in client applications\nand can be used to maintain user workspace preferences across sessions.\n\n**Functionality:**\n- Sets the specified graph as the user's currently selected graph\n- Deselects any previously selected graph (only one can be selected at a time)\n- Persists selection across sessions until changed\n- Returns confirmation with the selected graph ID\n\n**Requirements:**\n- User must have access to the graph (as admin or member)\n- Graph must exist and not be deleted\n- User can only select graphs they have permission to access\n\n**Use Cases:**\n- Switch between multiple graphs in a multi-graph environment\n- Set default workspace after creating a new graph\n- Restore user's preferred workspace on login\n- Support graph context switching in client applications\n\n**Client Integration:**\nMany client operations can default to the selected graph, simplifying API calls\nby eliminating the need to specify graph_id repeatedly. Check the selected\ngraph with `GET /v1/graphs` which returns `selectedGraphId`.\n\n**Note:**\nGraph selection is included - no credit consumption required.","operationId":"selectGraph","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}}],"responses":{"200":{"description":"Graph selected successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"},"example":{"success":true,"message":"Graph selected successfully","data":{"selectedGraphId":"kg1a2b3c4d5"}}}}},"403":{"description":"Access denied to graph","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Graph not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Error selecting graph","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/offering":{"get":{"tags":["Service Offerings"],"summary":"Get Service Offerings","description":"Get comprehensive information about all subscription offerings.\n\nThis endpoint provides complete information about both graph database subscriptions\nand shared repository subscriptions. This is the primary endpoint for frontend\napplications to display subscription options.\n\n**Pricing Model:**\n- Graph subscriptions are **per-graph** with infrastructure-based pricing\n- Each graph you create has its own monthly subscription\n- Organizations can have multiple graphs with different infrastructure tiers\n- Credits are allocated per-graph, not shared across organization\n\nIncludes:\n- Graph infrastructure tiers (ladybug-standard, ladybug-large, ladybug-xlarge) - per-graph pricing\n- Shared repository subscriptions - org-level\n- Operation costs and credit information\n- Features and capabilities for each tier\n- Enabled/disabled status for repositories\n\nAll data comes from the config-based systems to ensure accuracy with backend behavior.\n\nNo authentication required - this is public service information.","operationId":"getServiceOfferings","responses":{"200":{"description":"Complete service offerings retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceOfferingsResponse"},"example":{"graph_subscriptions":{"tiers":[{"name":"ladybug-standard","display_name":"LadybugDB Standard","monthly_price":99.0,"monthly_credits":8000,"infrastructure":"Dedicated m7g.large (2 vCPU, 8 GB RAM)","features":["8,000 AI credits per graph","7-day backup retention","Priority support"]}]},"repository_subscriptions":{"repositories":[{"type":"sec","name":"SEC Data","enabled":true,"plans":[{"plan":"starter","monthly_price":29,"monthly_credits":5000}]}]},"operation_costs":{"token_pricing":{"claude_4_sonnet":{"input_per_1k_tokens":3,"output_per_1k_tokens":15}}}}}}},"500":{"description":"Failed to retrieve service offerings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/operations/{operation_id}/stream":{"get":{"tags":["Operations"],"summary":"Stream Operation Events","description":"Stream real-time events for an operation using Server-Sent Events (SSE).\n\nThis endpoint provides real-time monitoring for all non-immediate operations including:\n- Graph creation and management\n- Agent analysis processing\n- Database backups and restores\n- Data synchronization tasks\n\n**Event Types:**\n- `operation_started`: Operation began execution\n- `operation_progress`: Progress update with details\n- `operation_completed`: Operation finished successfully\n- `operation_error`: Operation failed with error details\n- `operation_cancelled`: Operation was cancelled\n\n**Features:**\n- **Event Replay**: Use `from_sequence` parameter to replay missed events\n- **Automatic Reconnection**: Client can reconnect and resume from last seen event\n- **Real-time Updates**: Live progress updates during execution\n- **Timeout Handling**: 30-second keepalive messages prevent connection timeouts\n- **Graceful Degradation**: Automatic fallback if Redis is unavailable\n\n**Connection Limits:**\n- Maximum 5 concurrent SSE connections per user\n- Rate limited to 10 new connections per minute\n- Automatic cleanup of stale connections\n- Circuit breaker protection for Redis failures\n\n**Client Usage:**\n```javascript\nconst eventSource = new EventSource('/v1/operations/abc123/stream');\neventSource.onmessage = (event) => {\n  const data = JSON.parse(event.data);\n  console.log('Progress:', data);\n};\neventSource.onerror = (error) => {\n  // Handle connection errors or rate limits\n  console.error('SSE Error:', error);\n};\n```\n\n**Error Handling:**\n- `429 Too Many Requests`: Connection limit or rate limit exceeded\n- `503 Service Unavailable`: SSE system temporarily disabled\n- Clients should implement exponential backoff on errors\n\n**No credits are consumed for SSE connections.**","operationId":"streamOperationEvents","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"operation_id","in":"path","required":true,"schema":{"type":"string","pattern":"^(op_[0-9A-Z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$","description":"Operation identifier from initial submission","title":"Operation Id"},"description":"Operation identifier from initial submission"},{"name":"from_sequence","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Start streaming from this sequence number (0 = from beginning)","default":0,"title":"From Sequence"},"description":"Start streaming from this sequence number (0 = from beginning)"},{"name":"token","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"JWT token for SSE authentication","title":"Token"},"description":"JWT token for SSE authentication"},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"SSE stream of operation events","content":{"application/json":{"schema":{}}},"headers":{"Content-Type":{"schema":{"type":"string","enum":["text/event-stream"]}},"Cache-Control":{"schema":{"type":"string","enum":["no-cache"]}},"Connection":{"schema":{"type":"string","enum":["keep-alive"]}}}},"403":{"description":"Access denied to operation"},"404":{"description":"Operation not found"},"500":{"description":"Failed to create event stream"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/operations/{operation_id}/status":{"get":{"tags":["Operations"],"summary":"Get Operation Status","description":"Get current status and metadata for an operation.\n\nReturns detailed information including:\n- Current status (pending, running, completed, failed, cancelled)\n- Creation and update timestamps\n- Operation type and associated graph\n- Result data (for completed operations)\n- Error details (for failed operations)\n\nThis endpoint provides a point-in-time status check, while the `/stream` endpoint\nprovides real-time updates. Use this for polling or initial status checks.\n\n**No credits are consumed for status checks.**","operationId":"getOperationStatus","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"operation_id","in":"path","required":true,"schema":{"type":"string","pattern":"^(op_[0-9A-Z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$","description":"Operation identifier","title":"Operation Id"},"description":"Operation identifier"}],"responses":{"200":{"description":"Operation status retrieved successfully","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Getoperationstatus"},"example":{"operation_id":"abc123","operation_type":"graph_creation","status":"running","created_at":"2024-01-01T12:00:00Z","updated_at":"2024-01-01T12:01:30Z","graph_id":"kg1a2b3c4d5e6f7g8","_links":{"stream":"/v1/operations/abc123/stream","cancel":"/v1/operations/abc123"}}}}},"403":{"description":"Access denied to operation"},"404":{"description":"Operation not found"},"500":{"description":"Failed to retrieve operation status"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/operations/{operation_id}":{"delete":{"tags":["Operations"],"summary":"Cancel Operation","description":"Cancel a pending or running operation.\n\nCancels the specified operation if it's still in progress. Once cancelled,\nthe operation cannot be resumed and will emit a cancellation event to any\nactive SSE connections.\n\n**Note**: Completed or already failed operations cannot be cancelled.\n\n**No credits are consumed for cancellation requests.**","operationId":"cancelOperation","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"operation_id","in":"path","required":true,"schema":{"type":"string","pattern":"^(op_[0-9A-Z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$","description":"Operation identifier","title":"Operation Id"},"description":"Operation identifier"}],"responses":{"200":{"description":"Operation cancelled successfully","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Canceloperation"}}}},"403":{"description":"Access denied to operation"},"404":{"description":"Operation not found"},"409":{"description":"Operation cannot be cancelled (already completed)"},"500":{"description":"Failed to cancel operation"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/billing/customer/{org_id}":{"get":{"tags":["Billing"],"summary":"Get Organization Customer Info","description":"Get billing customer information for an organization including payment methods on file.\n\nReturns customer details, payment methods, and whether invoice billing is enabled.\n\n**Requirements:**\n- User must be a member of the organization\n- Sensitive payment details are only visible to owners","operationId":"getOrgBillingCustomer","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","title":"Org Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingCustomer"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/billing/customer/{org_id}/portal":{"post":{"tags":["Billing"],"summary":"Create Customer Portal Session","description":"Create a Stripe Customer Portal session for managing payment methods.\n\nThe portal allows users to:\n- Add new payment methods\n- Remove existing payment methods\n- Update default payment method\n- View billing history\n\nThe user will be redirected to Stripe's hosted portal page and returned to the billing page when done.\n\n**Requirements:**\n- User must be an OWNER of the organization\n- Organization must have a Stripe customer ID (i.e., has gone through checkout at least once)","operationId":"createPortalSession","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","title":"Org Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalSessionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/billing/subscriptions/{org_id}":{"get":{"tags":["Billing"],"summary":"List Organization Subscriptions","description":"List all active and past subscriptions for an organization.\n\nIncludes both graph and repository subscriptions with their status, pricing, and billing information.\n\n**Requirements:**\n- User must be a member of the organization","operationId":"listOrgSubscriptions","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","title":"Org Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/GraphSubscriptionResponse"},"title":"Response Listorgsubscriptions"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/billing/subscriptions/{org_id}/subscription/{subscription_id}":{"get":{"tags":["Billing"],"summary":"Get Organization Subscription Details","description":"Get detailed information about a specific subscription.\n\n**Requirements:**\n- User must be a member of the organization","operationId":"getOrgSubscription","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","title":"Org Id"}},{"name":"subscription_id","in":"path","required":true,"schema":{"type":"string","title":"Subscription Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GraphSubscriptionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/billing/subscriptions/{org_id}/subscription/{subscription_id}/cancel":{"post":{"tags":["Billing"],"summary":"Cancel Organization Subscription","description":"Cancel an organization subscription.\n\nThe subscription will remain active until the end of the current billing period.\n\n**Requirements:**\n- User must be an OWNER of the organization","operationId":"cancelOrgSubscription","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","title":"Org Id"}},{"name":"subscription_id","in":"path","required":true,"schema":{"type":"string","title":"Subscription Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GraphSubscriptionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/billing/invoices/{org_id}":{"get":{"tags":["Billing"],"summary":"List Organization Invoices","description":"List payment history and invoices for an organization.\n\nReturns past invoices with payment status, amounts, and line items.\n\n**Requirements:**\n- User must be a member of the organization\n- Full invoice details are only visible to owners and admins","operationId":"listOrgInvoices","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","title":"Org Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of invoices to return","default":10,"title":"Limit"},"description":"Number of invoices to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoicesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/billing/invoices/{org_id}/upcoming":{"get":{"tags":["Billing"],"summary":"Get Organization Upcoming Invoice","description":"Get preview of the next invoice for an organization.\n\nReturns estimated charges for the next billing period.\n\n**Requirements:**\n- User must be a member of the organization\n- Full invoice details are only visible to owners and admins","operationId":"getOrgUpcomingInvoice","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","title":"Org Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UpcomingInvoice"},{"type":"null"}],"title":"Response Getorgupcominginvoice"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/billing/checkout":{"post":{"tags":["Billing"],"summary":"Create Payment Checkout Session","description":"Create a Stripe checkout session for collecting payment method.\n\nThis endpoint is used when an organization owner needs to add a payment method before\nprovisioning resources. It creates a pending subscription and redirects\nto Stripe Checkout to collect payment details.\n\n**Flow:**\n1. Owner tries to create a graph but org has no payment method\n2. Frontend calls this endpoint with graph configuration\n3. Backend creates a subscription in PENDING_PAYMENT status for the user's org\n4. Returns Stripe Checkout URL\n5. User completes payment on Stripe\n6. Webhook activates subscription and provisions resource\n\n**Requirements:**\n- User must be an OWNER of their organization\n- Enterprise customers (with invoice_billing_enabled) should not call this endpoint.","operationId":"createCheckoutSession","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCheckoutRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/billing/checkout/{session_id}/status":{"get":{"tags":["Billing"],"summary":"Get Checkout Session Status","description":"Poll the status of a checkout session.\n\nFrontend should poll this endpoint after user returns from Stripe Checkout\nto determine when the resource is ready.\n\n**Status Values:**\n- `pending_payment`: Waiting for payment to complete\n- `provisioning`: Payment confirmed, resource being created\n- `active`: Resource is ready (resource_id will be set)\n- `failed`: Something went wrong (error field will be set)\n- `canceled`: Payment was canceled\n\n**When status is 'active':**\n- For graphs: `resource_id` will be the graph_id, and `operation_id` can be used to monitor SSE progress\n- For repositories: `resource_id` will be the repository name and access is immediately available","operationId":"getCheckoutStatus","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/extensions/roboledger/{graph_id}/operations/build-fact-grid":{"post":{"tags":["Extensions: RoboLedger"],"summary":"Build Fact Grid","description":"Build a multi-dimensional fact grid against the graph schema.\n\nQueries `Fact` nodes by element qnames or canonical concepts with\noptional filters for periods, entities, filing form, fiscal context,\nand period type. Returns a deduplicated pivot table plus optional\nsummary statistics.\n\nThis is a graph-database read — the query runs against LadybugDB,\nnot the extensions OLTP database. The same operation works for\nroboledger tenant graphs (post-materialization) and the SEC shared\nrepository (which uses the same XBRL hypercube schema).\n\n**Idempotency**: supply an `Idempotency-Key` header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.","operationId":"opBuildFactGrid","security":[{"APIKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"graph_id","in":"path","required":true,"schema":{"type":"string","title":"Graph Id"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateViewRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationEnvelope"}}},"headers":{"X-Rate-Limit-Remaining":{"description":"Requests remaining in the current rate-limit window","schema":{"type":"integer"}},"X-Rate-Limit-Reset":{"description":"Unix epoch seconds at which the current window resets","schema":{"type":"integer"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"400":{"description":"Invalid request payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationError"}}}},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden — caller cannot access this graph"},"404":{"description":"Resource not found (graph, ledger, report, etc.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationError"}}}},"409":{"description":"Idempotency-Key reused with a different request body, or other operation-level conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationError"}}}},"429":{"description":"Rate limit exceeded"},"500":{"description":"Internal error"}}}}},"components":{"schemas":{"APIKeyInfo":{"properties":{"id":{"type":"string","title":"Id","description":"API key ID"},"name":{"type":"string","title":"Name","description":"API key name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"API key description"},"prefix":{"type":"string","title":"Prefix","description":"API key prefix for identification"},"is_active":{"type":"boolean","title":"Is Active","description":"Whether the key is active"},"last_used_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Used At","description":"Last used timestamp"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At","description":"Expiration timestamp"},"created_at":{"type":"string","title":"Created At","description":"Creation timestamp"}},"type":"object","required":["id","name","prefix","is_active","created_at"],"title":"APIKeyInfo","description":"API key information response model."},"APIKeysResponse":{"properties":{"api_keys":{"items":{"$ref":"#/components/schemas/APIKeyInfo"},"type":"array","title":"Api Keys","description":"List of user's API keys"}},"type":"object","required":["api_keys"],"title":"APIKeysResponse","description":"Response model for listing API keys."},"AccountInfo":{"properties":{"provider":{"type":"string","title":"Provider","description":"Authentication provider ID (e.g., 'github', 'google')"},"provider_type":{"type":"string","title":"Provider Type","description":"Type of provider"},"provider_account_id":{"type":"string","title":"Provider Account Id","description":"Account ID at the provider"}},"type":"object","required":["provider","provider_type","provider_account_id"],"title":"AccountInfo","description":"Provider account information.","example":{"provider":"github","provider_account_id":"12345","provider_type":"oauth"}},"AgentListResponse":{"properties":{"agents":{"additionalProperties":{"additionalProperties":true,"type":"object"},"type":"object","title":"Agents","description":"Dictionary of available agents with metadata"},"total":{"type":"integer","title":"Total","description":"Total number of agents"}},"type":"object","required":["agents","total"],"title":"AgentListResponse","description":"Response for listing available agents."},"AgentMessage":{"properties":{"role":{"type":"string","title":"Role","description":"Message role (user/assistant)"},"content":{"type":"string","title":"Content","description":"Message content"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Timestamp","description":"Message timestamp"}},"type":"object","required":["role","content"],"title":"AgentMessage","description":"Message in conversation history."},"AgentMetadataResponse":{"properties":{"name":{"type":"string","title":"Name","description":"Agent name"},"description":{"type":"string","title":"Description","description":"Agent description"},"version":{"type":"string","title":"Version","description":"Agent version"},"capabilities":{"items":{"type":"string"},"type":"array","title":"Capabilities","description":"Agent capabilities"},"supported_modes":{"items":{"type":"string"},"type":"array","title":"Supported Modes","description":"Supported execution modes"},"requires_credits":{"type":"boolean","title":"Requires Credits","description":"Whether agent requires credits"},"author":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author","description":"Agent author"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Agent tags"}},"type":"object","required":["name","description","version","capabilities","supported_modes","requires_credits"],"title":"AgentMetadataResponse","description":"Response for agent metadata."},"AgentMode":{"type":"string","enum":["quick","standard","extended","streaming"],"title":"AgentMode","description":"Agent execution modes."},"AgentRecommendation":{"properties":{"agent_type":{"type":"string","title":"Agent Type","description":"Agent type identifier"},"agent_name":{"type":"string","title":"Agent Name","description":"Agent display name"},"confidence":{"type":"number","title":"Confidence","description":"Confidence score (0-1)"},"capabilities":{"items":{"type":"string"},"type":"array","title":"Capabilities","description":"Agent capabilities"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Reason for recommendation"}},"type":"object","required":["agent_type","agent_name","confidence","capabilities"],"title":"AgentRecommendation","description":"Single agent recommendation."},"AgentRecommendationRequest":{"properties":{"query":{"type":"string","title":"Query","description":"Query to analyze"},"context":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Context","description":"Additional context"}},"type":"object","required":["query"],"title":"AgentRecommendationRequest","description":"Request for agent recommendations."},"AgentRecommendationResponse":{"properties":{"recommendations":{"items":{"$ref":"#/components/schemas/AgentRecommendation"},"type":"array","title":"Recommendations","description":"List of agent recommendations sorted by confidence"},"query":{"type":"string","title":"Query","description":"The analyzed query"}},"type":"object","required":["recommendations","query"],"title":"AgentRecommendationResponse","description":"Response for agent recommendations."},"AgentRequest":{"properties":{"message":{"type":"string","title":"Message","description":"The query or message to process"},"history":{"items":{"$ref":"#/components/schemas/AgentMessage"},"type":"array","title":"History","description":"Conversation history"},"context":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Context","description":"Additional context for analysis (e.g., enable_rag, include_schema)"},"mode":{"anyOf":[{"$ref":"#/components/schemas/AgentMode"},{"type":"null"}],"description":"Execution mode","default":"standard"},"agent_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Type","description":"Specific agent type to use (optional)"},"selection_criteria":{"anyOf":[{"$ref":"#/components/schemas/SelectionCriteria"},{"type":"null"}],"description":"Criteria for agent selection"},"force_extended_analysis":{"type":"boolean","title":"Force Extended Analysis","description":"Force extended analysis mode with comprehensive research","default":false},"enable_rag":{"type":"boolean","title":"Enable Rag","description":"Enable RAG context enrichment","default":true},"stream":{"type":"boolean","title":"Stream","description":"Enable streaming response","default":false}},"type":"object","required":["message"],"title":"AgentRequest","description":"Request model for agent interactions.","examples":[{"description":"Basic query letting the system choose the best agent","summary":"Simple query with auto-selection","value":{"enable_rag":true,"message":"What was Apple's revenue in Q4 2023?"}},{"description":"Follow-up question using conversation context","summary":"Query with conversation history","value":{"enable_rag":true,"history":[{"content":"What was Apple's revenue in Q4 2023?","role":"user"},{"content":"Apple's Q4 2023 revenue was $89.5 billion, representing a 1% year-over-year decline.","role":"assistant"}],"message":"How did that compare to the previous quarter?"}},{"description":"Complex query with specific agent requirements and extended analysis","summary":"Advanced query with selection criteria","value":{"context":{"focus_areas":["market_share","growth_trends"],"industry":"technology","time_period":"2023-2024"},"enable_rag":true,"force_extended_analysis":true,"message":"Analyze the competitive landscape in cloud computing, focusing on market share and growth trends","mode":"extended","selection_criteria":{"max_response_time":45.0,"min_confidence":0.7,"preferred_mode":"extended","required_capabilities":["financial_analysis","market_research"]}}}]},"AgentResponse":{"properties":{"content":{"type":"string","title":"Content","description":"The agent's response content"},"agent_used":{"type":"string","title":"Agent Used","description":"The agent type that handled the request"},"mode_used":{"$ref":"#/components/schemas/AgentMode","description":"The execution mode used"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Response metadata including routing info"},"tokens_used":{"anyOf":[{"additionalProperties":{"type":"integer"},"type":"object"},{"type":"null"}],"title":"Tokens Used","description":"Token usage statistics"},"confidence_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence Score","description":"Confidence score of the response (0.0-1.0 scale)"},"operation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Operation Id","description":"Operation ID for SSE monitoring"},"is_partial":{"type":"boolean","title":"Is Partial","description":"Whether this is a partial response","default":false},"error_details":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Error Details","description":"Error details if any"},"execution_time":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Execution Time","description":"Execution time in seconds"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"Response timestamp"}},"type":"object","required":["content","agent_used","mode_used"],"title":"AgentResponse","description":"Response model for agent interactions.","examples":[{"description":"Auto-selected financial agent with high confidence","summary":"Successful financial analysis","value":{"agent_used":"financial","confidence_score":0.92,"content":"Apple's Q4 2023 revenue was $89.5 billion, representing a 1% year-over-year decline. This was driven by strong iPhone sales offset by weakness in the Mac and iPad segments. Services revenue grew 16% to $22.3 billion, continuing its strong growth trajectory.","execution_time":3.45,"metadata":{"rag_enrichment":{"documents_retrieved":5,"sources":["Apple 10-Q Q4 2023","Earnings Call Transcript Oct 2023"]},"routing_info":{"candidates_evaluated":3,"confidence_scores":{"financial":0.92,"rag":0.23,"research":0.45},"selection_reason":"Financial query with revenue and metrics keywords"}},"mode_used":"standard","timestamp":"2024-01-15T10:30:45Z","tokens_used":{"completion_tokens":320,"prompt_tokens":450,"total_tokens":770}}},{"description":"Research agent with comprehensive market analysis","summary":"Research query with extended analysis","value":{"agent_used":"research","confidence_score":0.88,"content":"The cloud computing market is dominated by three major players: AWS (32% market share), Microsoft Azure (23%), and Google Cloud (10%). Over the past year, growth rates have been: AWS 12%, Azure 27%, Google Cloud 28%. The market shows clear consolidation trends...","execution_time":12.3,"metadata":{"analysis_depth":"comprehensive","routing_info":{"candidates_evaluated":3,"selection_reason":"Market research query requiring comprehensive analysis"},"sources_consulted":15},"mode_used":"extended","timestamp":"2024-01-15T10:35:22Z","tokens_used":{"completion_tokens":850,"prompt_tokens":1200,"total_tokens":2050}}}]},"AuthResponse":{"properties":{"user":{"additionalProperties":true,"type":"object","title":"User","description":"User information"},"org":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Org","description":"Organization information (personal org created automatically on registration)"},"message":{"type":"string","title":"Message","description":"Success message"},"token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token","description":"JWT authentication token (optional for cookie-based auth)"},"expires_in":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires In","description":"Token expiry time in seconds from now"},"refresh_threshold":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Refresh Threshold","description":"Recommended refresh threshold in seconds before expiry"}},"type":"object","required":["user","message"],"title":"AuthResponse","description":"Authentication response model."},"AvailableExtension":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"enabled":{"type":"boolean","title":"Enabled","default":false}},"type":"object","required":["name","description"],"title":"AvailableExtension"},"AvailableExtensionsResponse":{"properties":{"extensions":{"items":{"$ref":"#/components/schemas/AvailableExtension"},"type":"array","title":"Extensions"}},"type":"object","required":["extensions"],"title":"AvailableExtensionsResponse"},"AvailableGraphTiersResponse":{"properties":{"tiers":{"items":{"$ref":"#/components/schemas/GraphTierInfo"},"type":"array","title":"Tiers","description":"List of available tiers"}},"type":"object","required":["tiers"],"title":"AvailableGraphTiersResponse","description":"Response containing available graph tiers."},"BackupCreateRequest":{"properties":{"backup_format":{"type":"string","pattern":"^full_dump$","title":"Backup Format","description":"Backup format - only 'full_dump' is supported (complete .lbug database file)","default":"full_dump"},"backup_type":{"type":"string","pattern":"^full$","title":"Backup Type","description":"Backup type - only 'full' is supported","default":"full"},"retention_days":{"type":"integer","maximum":2555.0,"minimum":1.0,"title":"Retention Days","description":"Retention period in days","default":30},"compression":{"type":"boolean","title":"Compression","description":"Enable compression (always enabled for optimal storage)","default":true},"encryption":{"type":"boolean","title":"Encryption","description":"Enable encryption (encrypted backups cannot be downloaded)","default":false},"schedule":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schedule","description":"Optional cron schedule for automated backups"}},"type":"object","title":"BackupCreateRequest","description":"Request model for creating a backup."},"BackupDownloadUrlResponse":{"properties":{"download_url":{"type":"string","title":"Download Url","description":"Pre-signed S3 URL for downloading the backup file","examples":["https://s3.amazonaws.com/robosystems-backups/kg1a2b3c4d5/backup.lbug.tar.gz?X-Amz-Credential=..."]},"expires_in":{"type":"integer","maximum":86400.0,"minimum":300.0,"title":"Expires In","description":"URL expiration time in seconds from now","examples":[3600]},"expires_at":{"type":"number","title":"Expires At","description":"Unix timestamp when the URL expires","examples":[1705315200.0]},"backup_id":{"type":"string","title":"Backup Id","description":"Backup identifier","examples":["bk1a2b3c4d5"]},"graph_id":{"type":"string","title":"Graph Id","description":"Graph database identifier","examples":["kg1a2b3c4d5"]}},"type":"object","required":["download_url","expires_in","expires_at","backup_id","graph_id"],"title":"BackupDownloadUrlResponse","description":"Response model for backup download URL generation.","examples":[{"description":"Generated pre-signed URL for downloading a backup with 1 hour expiration","summary":"Download URL for recent backup","value":{"backup_id":"bk1a2b3c4d5","download_url":"https://s3.amazonaws.com/robosystems-backups/kg1a2b3c4d5/backup_20240115_100000.lbug.tar.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...","expires_at":1705315200.0,"expires_in":3600,"graph_id":"kg1a2b3c4d5"}},{"description":"Download URL with 24-hour expiration for large backup files","summary":"Extended expiration download URL","value":{"backup_id":"bk9f8e7d6c5","download_url":"https://s3.amazonaws.com/robosystems-backups/kg9f8e7d6c5/backup_20240114_183000.lbug.tar.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...","expires_at":1705401600.0,"expires_in":86400,"graph_id":"kg9f8e7d6c5"}},{"description":"Download URL with minimum 5-minute expiration for immediate download","summary":"Short-lived download URL","value":{"backup_id":"bksec123456","download_url":"https://s3.amazonaws.com/robosystems-backups/sec/backup_20240115_120000.lbug.tar.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...","expires_at":1705314900.0,"expires_in":300,"graph_id":"sec"}}]},"BackupLimits":{"properties":{"max_backup_size_gb":{"type":"number","title":"Max Backup Size Gb","description":"Maximum backup size in GB"},"backup_retention_days":{"type":"integer","title":"Backup Retention Days","description":"Backup retention period in days"},"max_backups_per_day":{"type":"integer","title":"Max Backups Per Day","description":"Maximum backups per day"}},"type":"object","required":["max_backup_size_gb","backup_retention_days","max_backups_per_day"],"title":"BackupLimits","description":"Backup operation limits."},"BackupListResponse":{"properties":{"backups":{"items":{"$ref":"#/components/schemas/BackupResponse"},"type":"array","title":"Backups"},"total_count":{"type":"integer","title":"Total Count"},"graph_id":{"type":"string","title":"Graph Id"},"is_shared_repository":{"type":"boolean","title":"Is Shared Repository","description":"Whether this is a shared repository (limits apply)","default":false},"download_quota":{"anyOf":[{"$ref":"#/components/schemas/DownloadQuota"},{"type":"null"}],"description":"Download quota for shared repositories"}},"type":"object","required":["backups","total_count","graph_id"],"title":"BackupListResponse","description":"Response model for backup list."},"BackupResponse":{"properties":{"backup_id":{"type":"string","title":"Backup Id"},"graph_id":{"type":"string","title":"Graph Id"},"backup_format":{"type":"string","title":"Backup Format"},"backup_type":{"type":"string","title":"Backup Type"},"status":{"type":"string","title":"Status"},"original_size_bytes":{"type":"integer","title":"Original Size Bytes"},"compressed_size_bytes":{"type":"integer","title":"Compressed Size Bytes"},"compression_ratio":{"type":"number","title":"Compression Ratio"},"node_count":{"type":"integer","title":"Node Count"},"relationship_count":{"type":"integer","title":"Relationship Count"},"backup_duration_seconds":{"type":"number","title":"Backup Duration Seconds"},"encryption_enabled":{"type":"boolean","title":"Encryption Enabled"},"compression_enabled":{"type":"boolean","title":"Compression Enabled"},"allow_export":{"type":"boolean","title":"Allow Export"},"created_at":{"type":"string","title":"Created At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"}},"type":"object","required":["backup_id","graph_id","backup_format","backup_type","status","original_size_bytes","compressed_size_bytes","compression_ratio","node_count","relationship_count","backup_duration_seconds","encryption_enabled","compression_enabled","allow_export","created_at","completed_at","expires_at"],"title":"BackupResponse","description":"Response model for backup information."},"BackupRestoreRequest":{"properties":{"create_system_backup":{"type":"boolean","title":"Create System Backup","description":"Create a system backup of existing database before restore","default":true},"verify_after_restore":{"type":"boolean","title":"Verify After Restore","description":"Verify database integrity after restore","default":true}},"type":"object","title":"BackupRestoreRequest","description":"Request model for restoring from a backup."},"BackupStatsResponse":{"properties":{"graph_id":{"type":"string","title":"Graph Id"},"total_backups":{"type":"integer","title":"Total Backups"},"successful_backups":{"type":"integer","title":"Successful Backups"},"failed_backups":{"type":"integer","title":"Failed Backups"},"success_rate":{"type":"number","title":"Success Rate"},"total_original_size_bytes":{"type":"integer","title":"Total Original Size Bytes"},"total_compressed_size_bytes":{"type":"integer","title":"Total Compressed Size Bytes"},"storage_saved_bytes":{"type":"integer","title":"Storage Saved Bytes"},"average_compression_ratio":{"type":"number","title":"Average Compression Ratio"},"latest_backup_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Latest Backup Date"},"backup_formats":{"additionalProperties":{"type":"integer"},"type":"object","title":"Backup Formats"}},"type":"object","required":["graph_id","total_backups","successful_backups","failed_backups","success_rate","total_original_size_bytes","total_compressed_size_bytes","storage_saved_bytes","average_compression_ratio","latest_backup_date","backup_formats"],"title":"BackupStatsResponse","description":"Response model for backup statistics."},"BatchAgentRequest":{"properties":{"queries":{"items":{"$ref":"#/components/schemas/AgentRequest"},"type":"array","title":"Queries","description":"List of queries to process (max 10)"},"parallel":{"type":"boolean","title":"Parallel","description":"Process queries in parallel","default":false}},"type":"object","required":["queries"],"title":"BatchAgentRequest","description":"Request for batch processing multiple queries.","examples":[{"description":"Process multiple company queries sequentially","summary":"Sequential batch processing","value":{"parallel":false,"queries":[{"enable_rag":true,"message":"What was Apple's Q4 2023 revenue?"},{"enable_rag":true,"message":"What was Microsoft's Q4 2023 revenue?"},{"enable_rag":true,"message":"What was Google's Q4 2023 revenue?"}]}},{"description":"Process multiple queries in parallel for faster results","summary":"Parallel batch processing","value":{"parallel":true,"queries":[{"enable_rag":true,"message":"Analyze Tesla's financial performance","mode":"extended"},{"enable_rag":true,"message":"Analyze Ford's financial performance","mode":"extended"},{"enable_rag":true,"message":"Compare EV market trends","mode":"standard"}]}}]},"BatchAgentResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/AgentResponse"},"type":"array","title":"Results","description":"List of agent responses (includes successes and failures)"},"total_execution_time":{"type":"number","title":"Total Execution Time","description":"Total execution time in seconds"},"parallel_processed":{"type":"boolean","title":"Parallel Processed","description":"Whether queries were processed in parallel"}},"type":"object","required":["results","total_execution_time","parallel_processed"],"title":"BatchAgentResponse","description":"Response for batch processing.","examples":[{"description":"All queries processed successfully in sequence","summary":"Successful sequential batch","value":{"parallel_processed":false,"results":[{"agent_used":"financial","confidence_score":0.92,"content":"Apple's Q4 2023 revenue was $89.5 billion...","execution_time":3.2,"mode_used":"standard","timestamp":"2024-01-15T10:30:00Z"},{"agent_used":"financial","confidence_score":0.89,"content":"Microsoft's Q4 2023 revenue was $62.0 billion...","execution_time":3.5,"mode_used":"standard","timestamp":"2024-01-15T10:30:03Z"},{"agent_used":"financial","confidence_score":0.91,"content":"Google's Q4 2023 revenue was $86.3 billion...","execution_time":3.1,"mode_used":"standard","timestamp":"2024-01-15T10:30:07Z"}],"total_execution_time":9.8}},{"description":"Some queries succeed, one fails due to insufficient credits","summary":"Parallel batch with partial failure","value":{"parallel_processed":true,"results":[{"agent_used":"financial","confidence_score":0.88,"content":"Tesla's financial performance shows strong revenue growth...","execution_time":12.3,"mode_used":"extended","timestamp":"2024-01-15T10:35:12Z"},{"agent_used":"financial","content":"","error_details":{"available_credits":25,"code":"insufficient_credits","message":"Insufficient credits for extended analysis","required_credits":50},"execution_time":0.1,"mode_used":"extended","timestamp":"2024-01-15T10:35:00Z"},{"agent_used":"research","confidence_score":0.85,"content":"EV market trends show continued growth with 45% YoY increase...","execution_time":8.7,"mode_used":"standard","timestamp":"2024-01-15T10:35:09Z"}],"total_execution_time":12.5}}]},"BillingCustomer":{"properties":{"org_id":{"type":"string","title":"Org Id","description":"Organization ID"},"has_payment_method":{"type":"boolean","title":"Has Payment Method","description":"Whether organization has a payment method on file"},"invoice_billing_enabled":{"type":"boolean","title":"Invoice Billing Enabled","description":"Whether invoice billing is enabled (enterprise customers)"},"payment_methods":{"items":{"$ref":"#/components/schemas/PaymentMethod"},"type":"array","title":"Payment Methods","description":"List of payment methods on file"},"stripe_customer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stripe Customer Id","description":"Stripe customer ID if applicable"},"created_at":{"type":"string","title":"Created At","description":"Customer creation timestamp (ISO format)"}},"type":"object","required":["org_id","has_payment_method","invoice_billing_enabled","payment_methods","created_at"],"title":"BillingCustomer","description":"Billing customer information for an organization."},"BulkDocumentUploadRequest":{"properties":{"documents":{"items":{"$ref":"#/components/schemas/DocumentUploadRequest"},"type":"array","maxItems":50,"title":"Documents","description":"Documents to upload (max 50)"}},"type":"object","required":["documents"],"title":"BulkDocumentUploadRequest","description":"Bulk upload multiple markdown documents."},"BulkDocumentUploadResponse":{"properties":{"total_documents":{"type":"integer","title":"Total Documents"},"total_sections_indexed":{"type":"integer","title":"Total Sections Indexed"},"results":{"items":{"$ref":"#/components/schemas/DocumentUploadResponse"},"type":"array","title":"Results"},"errors":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Errors"}},"type":"object","required":["total_documents","total_sections_indexed","results"],"title":"BulkDocumentUploadResponse","description":"Response from bulk document upload."},"CheckoutResponse":{"properties":{"checkout_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Checkout Url","description":"URL to redirect user to for payment"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id","description":"Checkout session ID for status polling"},"subscription_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subscription Id","description":"Internal subscription ID"},"requires_checkout":{"type":"boolean","title":"Requires Checkout","description":"Whether checkout is required","default":true},"billing_disabled":{"type":"boolean","title":"Billing Disabled","description":"Whether billing is disabled on this instance","default":false}},"type":"object","title":"CheckoutResponse","description":"Response from checkout session creation."},"CheckoutStatusResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Checkout status: 'pending_payment', 'provisioning', 'active', 'failed', 'canceled'"},"subscription_id":{"type":"string","title":"Subscription Id","description":"Internal subscription ID"},"resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Id","description":"Resource ID (graph_id for both graphs and repositories) once provisioned. For repositories, this is the repository slug (e.g., 'sec')"},"operation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Operation Id","description":"SSE operation ID for monitoring provisioning progress"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if checkout failed"}},"type":"object","required":["status","subscription_id"],"title":"CheckoutStatusResponse","description":"Status of a checkout session."},"ContentLimits":{"properties":{"max_rows_per_copy":{"type":"integer","title":"Max Rows Per Copy","description":"Maximum rows per copy/materialization operation"},"max_single_table_rows":{"type":"integer","title":"Max Single Table Rows","description":"Maximum rows per staging table"},"chunk_size_rows":{"type":"integer","title":"Chunk Size Rows","description":"Rows per materialization chunk"}},"type":"object","required":["max_rows_per_copy","max_single_table_rows","chunk_size_rows"],"title":"ContentLimits","description":"Per-operation materialization limits."},"CopyOperationLimits":{"properties":{"max_file_size_gb":{"type":"number","title":"Max File Size Gb","description":"Maximum file size in GB"},"timeout_seconds":{"type":"integer","title":"Timeout Seconds","description":"Operation timeout in seconds"},"concurrent_operations":{"type":"integer","title":"Concurrent Operations","description":"Maximum concurrent operations"},"max_files_per_operation":{"type":"integer","title":"Max Files Per Operation","description":"Maximum files per operation"},"daily_copy_operations":{"type":"integer","title":"Daily Copy Operations","description":"Daily operation limit"},"supported_formats":{"items":{"type":"string"},"type":"array","title":"Supported Formats","description":"Supported file formats"}},"type":"object","required":["max_file_size_gb","timeout_seconds","concurrent_operations","max_files_per_operation","daily_copy_operations","supported_formats"],"title":"CopyOperationLimits","description":"Copy/ingestion operation limits."},"CreateAPIKeyRequest":{"properties":{"name":{"type":"string","maxLength":100,"minLength":1,"title":"Name","description":"Name for the API key"},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description","description":"Optional description"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At","description":"Optional expiration date in ISO format (e.g. 2024-12-31T23:59:59Z)"}},"type":"object","required":["name"],"title":"CreateAPIKeyRequest","description":"Request model for creating a new API key."},"CreateAPIKeyResponse":{"properties":{"api_key":{"$ref":"#/components/schemas/APIKeyInfo","description":"API key information"},"key":{"type":"string","title":"Key","description":"The actual API key (only shown once)"}},"type":"object","required":["api_key","key"],"title":"CreateAPIKeyResponse","description":"Response model for creating a new API key."},"CreateCheckoutRequest":{"properties":{"plan_name":{"type":"string","title":"Plan Name","description":"Billing plan name (e.g., 'ladybug-standard')"},"resource_type":{"type":"string","title":"Resource Type","description":"Resource type ('graph' or 'repository')"},"resource_config":{"additionalProperties":true,"type":"object","title":"Resource Config","description":"Configuration for the resource to be provisioned. For repositories: {'repository_name': 'graph_id'} where graph_id is the repository slug (e.g., 'sec')"}},"type":"object","required":["plan_name","resource_type","resource_config"],"title":"CreateCheckoutRequest","description":"Request to create a checkout session for payment collection."},"CreateGraphRequest":{"properties":{"metadata":{"$ref":"#/components/schemas/GraphMetadata","description":"Graph metadata including name, description, and schema extensions"},"instance_tier":{"type":"string","pattern":"^(ladybug-standard|ladybug-large|ladybug-xlarge)$","title":"Instance Tier","description":"Instance tier: ladybug-standard, ladybug-large, ladybug-xlarge","default":"ladybug-standard"},"custom_schema":{"anyOf":[{"$ref":"#/components/schemas/CustomSchemaDefinition"},{"type":"null"}],"description":"Custom schema definition to apply. If provided, creates a generic custom graph. If omitted, creates an entity graph using schema_extensions."},"initial_entity":{"anyOf":[{"$ref":"#/components/schemas/InitialEntityData"},{"type":"null"}],"description":"Optional initial entity to create in the graph. If provided with entity graph, populates the first entity node."},"create_entity":{"type":"boolean","title":"Create Entity","description":"Whether to create the entity node and upload initial data. Only applies when initial_entity is provided. Set to False to create graph without populating entity data (useful for file-based ingestion workflows).","default":true},"tags":{"items":{"type":"string"},"type":"array","maxItems":10,"title":"Tags","description":"Optional tags for organization"}},"type":"object","required":["metadata"],"title":"CreateGraphRequest","description":"Request model for creating a new graph.\n\nUse this to create either:\n- **Entity graphs**: Standard graphs with entity schema and optional extensions\n- **Custom graphs**: Generic graphs with fully custom schema definitions","examples":[{"description":"Create a graph with initial entity data for a specific company/organization","summary":"Entity graph with initial entity","value":{"create_entity":true,"initial_entity":{"cik":"0001234567","ein":"12-3456789","name":"Acme Consulting LLC","state_of_incorporation":"Delaware","uri":"https://acmeconsulting.com"},"instance_tier":"ladybug-standard","metadata":{"description":"Professional consulting services with full accounting integration","graph_name":"Acme Consulting LLC","schema_extensions":["roboledger"]},"tags":["consulting","professional-services","production"]}},{"description":"Create an entity graph structure without populating initial data (useful for bulk data imports)","summary":"Entity graph without initial entity","value":{"create_entity":false,"instance_tier":"ladybug-standard","metadata":{"description":"Knowledge graph for tracking investment portfolios and holdings","graph_name":"Investment Portfolio Graph","schema_extensions":["roboinvestor"]},"tags":["investments","portfolio-management"]}},{"description":"Create a generic graph with custom schema from custom_graph_demo","summary":"Custom graph with people and companies","value":{"custom_schema":{"description":"People, companies, and projects schema","extends":"base","metadata":{"domain":"custom_graph_demo"},"name":"custom_graph_demo","nodes":[{"name":"Person","properties":[{"name":"identifier","type":"STRING","is_primary_key":true},{"name":"name","type":"STRING","is_required":true},{"name":"title","type":"STRING"}]},{"name":"Company","properties":[{"name":"identifier","type":"STRING","is_primary_key":true},{"name":"name","type":"STRING","is_required":true},{"name":"industry","type":"STRING"}]}],"relationships":[{"from_node":"Person","name":"PERSON_WORKS_FOR_COMPANY","properties":[{"name":"role","type":"STRING"}],"to_node":"Company"}],"version":"1.0.0"},"instance_tier":"ladybug-standard","metadata":{"description":"Custom graph demo with people, companies, and projects","graph_name":"custom_graph_demo_1234","schema_extensions":[]},"tags":["custom","demo","generic"]}},{"description":"Create a custom graph for inventory tracking","summary":"Inventory management custom graph","value":{"custom_schema":{"description":"Inventory tracking with products and warehouses","metadata":{"industry":"retail"},"name":"inventory_management","nodes":[{"name":"Product","properties":[{"name":"sku","type":"STRING","is_primary_key":true},{"name":"name","type":"STRING","is_required":true},{"name":"price","type":"DOUBLE"},{"name":"quantity","type":"INT64"}]},{"name":"Warehouse","properties":[{"name":"identifier","type":"STRING","is_primary_key":true},{"name":"location","type":"STRING","is_required":true}]}],"relationships":[{"from_node":"Product","name":"STORED_IN","properties":[{"name":"quantity","type":"INT64"}],"to_node":"Warehouse"}],"version":"1.0.0"},"instance_tier":"ladybug-standard","metadata":{"description":"Inventory management system","graph_name":"warehouse_inventory","schema_extensions":[]},"tags":["inventory","retail"]}},{"description":"Create an empty graph for general-purpose use without custom schema","summary":"Generic empty graph","value":{"instance_tier":"ladybug-standard","metadata":{"description":"Graph database for customer relationship and behavior analysis","graph_name":"Customer Analytics Graph","schema_extensions":[]},"tags":["analytics","customers","marketing"]}}]},"CreateRepositorySubscriptionRequest":{"properties":{"plan_name":{"type":"string","title":"Plan Name","description":"Plan name for the repository subscription","examples":["sec-starter"]}},"type":"object","required":["plan_name"],"title":"CreateRepositorySubscriptionRequest","description":"Request to create a repository subscription."},"CreateSubgraphRequest":{"properties":{"name":{"type":"string","maxLength":20,"minLength":1,"title":"Name","description":"Alphanumeric name for the subgraph (e.g., dev, staging, prod1)","examples":["dev","staging","prod","test1"]},"display_name":{"type":"string","maxLength":100,"minLength":1,"title":"Display Name","description":"Human-readable display name for the subgraph","examples":["Development Environment","Staging Environment","Production"]},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description","description":"Optional description of the subgraph's purpose","examples":["Development environment for testing new features"]},"schema_extensions":{"items":{"type":"string"},"type":"array","title":"Schema Extensions","description":"Schema extensions to include (inherits from parent by default)","examples":[["roboledger","roboinvestor"]]},"subgraph_type":{"$ref":"#/components/schemas/SubgraphType","description":"Type of subgraph (currently only 'static' is supported)","default":"static"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Additional metadata for the subgraph","examples":[{"environment":"development","team":"engineering"}]},"fork_parent":{"type":"boolean","title":"Fork Parent","description":"If true, copy all data from parent graph to create a 'fork'","default":false}},"type":"object","required":["name","display_name"],"title":"CreateSubgraphRequest","description":"Request model for creating a subgraph."},"CreateViewRequest":{"properties":{"elements":{"items":{"type":"string"},"type":"array","title":"Elements","description":"Element qnames (e.g., 'us-gaap:Assets'). Can combine with canonical_concepts."},"canonical_concepts":{"items":{"type":"string"},"type":"array","title":"Canonical Concepts","description":"Canonical concept names (e.g., 'revenue', 'net_income'). Matches all mapped qnames."},"periods":{"items":{"type":"string"},"type":"array","title":"Periods","description":"Period end dates (YYYY-MM-DD format)"},"entity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity","description":"Filter by entity ticker, CIK, or name"},"entities":{"items":{"type":"string"},"type":"array","title":"Entities","description":"Filter by multiple entity tickers (e.g., ['NVDA', 'AAPL'])"},"form":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Form","description":"Filter by SEC filing form type (e.g., '10-K', '10-Q')"},"fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fiscal Year","description":"Filter by fiscal year (e.g., 2024)"},"fiscal_period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fiscal Period","description":"Filter by fiscal period (e.g., 'FY', 'Q1', 'Q2', 'Q3')"},"period_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period Type","description":"Filter by period type: 'annual', 'quarterly', or 'instant'"},"include_summary":{"type":"boolean","title":"Include Summary","description":"Include summary statistics per element","default":false},"view_config":{"$ref":"#/components/schemas/ViewConfig","description":"View/pivot configuration"}},"type":"object","title":"CreateViewRequest"},"CreditLimits":{"properties":{"monthly_ai_credits":{"type":"integer","title":"Monthly Ai Credits","description":"Monthly AI credits allocation"},"current_balance":{"type":"integer","title":"Current Balance","description":"Current credit balance"}},"type":"object","required":["monthly_ai_credits","current_balance"],"title":"CreditLimits","description":"AI credit limits (optional)."},"CreditSummary":{"properties":{"graph_tier":{"type":"string","title":"Graph Tier","description":"Subscription tier"},"total_credits_consumed":{"type":"number","title":"Total Credits Consumed","description":"Total credits consumed"},"total_base_cost":{"type":"number","title":"Total Base Cost","description":"Total base cost before multipliers"},"operation_breakdown":{"additionalProperties":true,"type":"object","title":"Operation Breakdown","description":"Credit usage by operation type"},"cached_operations":{"type":"integer","title":"Cached Operations","description":"Number of cached operations"},"billable_operations":{"type":"integer","title":"Billable Operations","description":"Number of billable operations"},"transaction_count":{"type":"integer","title":"Transaction Count","description":"Total transaction count"}},"type":"object","required":["graph_tier","total_credits_consumed","total_base_cost","operation_breakdown","cached_operations","billable_operations","transaction_count"],"title":"CreditSummary","description":"Credit consumption summary."},"CreditSummaryResponse":{"properties":{"graph_id":{"type":"string","title":"Graph Id"},"graph_tier":{"type":"string","title":"Graph Tier"},"current_balance":{"type":"number","title":"Current Balance"},"monthly_allocation":{"type":"number","title":"Monthly Allocation"},"consumed_this_month":{"type":"number","title":"Consumed This Month"},"transaction_count":{"type":"integer","title":"Transaction Count"},"usage_percentage":{"type":"number","title":"Usage Percentage"},"last_allocation_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Allocation Date"}},"type":"object","required":["graph_id","graph_tier","current_balance","monthly_allocation","consumed_this_month","transaction_count","usage_percentage"],"title":"CreditSummaryResponse","description":"Credit summary response model."},"CustomSchemaDefinition":{"properties":{"name":{"type":"string","title":"Name","description":"Schema name"},"version":{"type":"string","title":"Version","description":"Schema version","default":"1.0.0"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Schema description"},"extends":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Extends","description":"Base schema to extend (e.g., 'base' for common utilities)"},"nodes":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Nodes","description":"List of node definitions with properties"},"relationships":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Relationships","description":"List of relationship definitions"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Additional schema metadata"}},"type":"object","required":["name"],"title":"CustomSchemaDefinition","description":"Custom schema definition for generic graphs.\n\nThis model allows you to define custom node types, relationship types, and properties\nfor graphs that don't fit the standard entity-based schema. Perfect for domain-specific\napplications like inventory systems, org charts, project management, etc.","examples":[{"description":"Custom schema from custom_graph_demo showing organizational structure","summary":"People, companies, and projects schema","value":{"description":"People, companies, and projects schema for the custom graph demo","extends":"base","metadata":{"domain":"custom_graph_demo"},"name":"custom_graph_demo","nodes":[{"name":"Company","properties":[{"name":"identifier","type":"STRING","is_primary_key":true},{"name":"name","type":"STRING","is_required":true},{"name":"industry","type":"STRING"},{"name":"location","type":"STRING"},{"name":"founded_year","type":"INT64"}]},{"name":"Project","properties":[{"name":"identifier","type":"STRING","is_primary_key":true},{"name":"name","type":"STRING","is_required":true},{"name":"status","type":"STRING"},{"name":"budget","type":"DOUBLE"},{"name":"start_date","type":"STRING"},{"name":"end_date","type":"STRING"}]},{"name":"Person","properties":[{"name":"identifier","type":"STRING","is_primary_key":true},{"name":"name","type":"STRING","is_required":true},{"name":"age","type":"INT64"},{"name":"title","type":"STRING"},{"name":"interests","type":"STRING"}]}],"relationships":[{"from_node":"Person","name":"PERSON_WORKS_FOR_COMPANY","properties":[{"name":"role","type":"STRING"},{"name":"started_on","type":"STRING"}],"to_node":"Company"},{"from_node":"Person","name":"PERSON_WORKS_ON_PROJECT","properties":[{"name":"hours_per_week","type":"INT64"},{"name":"contribution","type":"STRING"}],"to_node":"Project"},{"from_node":"Company","name":"COMPANY_SPONSORS_PROJECT","properties":[{"name":"sponsorship_level","type":"STRING"},{"name":"budget_committed","type":"DOUBLE"}],"to_node":"Project"}],"version":"1.0.0"}},{"description":"Simple schema for tracking products and warehouses","summary":"Inventory management schema","value":{"description":"Inventory tracking system with products, warehouses, and suppliers","metadata":{"created_by":"inventory_team","industry":"retail"},"name":"inventory_management","nodes":[{"name":"Product","properties":[{"name":"sku","type":"STRING","is_primary_key":true},{"name":"name","type":"STRING","is_required":true},{"name":"price","type":"DOUBLE"},{"name":"quantity","type":"INT64"},{"name":"category","type":"STRING"}]},{"name":"Warehouse","properties":[{"name":"identifier","type":"STRING","is_primary_key":true},{"name":"location","type":"STRING","is_required":true},{"name":"capacity","type":"INT64"}]},{"name":"Supplier","properties":[{"name":"id","type":"STRING","is_primary_key":true},{"name":"name","type":"STRING","is_required":true},{"name":"contact","type":"STRING"}]}],"relationships":[{"from_node":"Product","name":"STORED_IN","properties":[{"name":"since","type":"DATE"},{"name":"quantity","type":"INT64"}],"to_node":"Warehouse"},{"from_node":"Product","name":"SUPPLIED_BY","properties":[{"name":"cost","type":"DOUBLE"}],"to_node":"Supplier"}],"version":"1.0.0"}},{"description":"Simplest custom schema with just two node types","summary":"Minimal schema","value":{"description":"Basic graph with just two node types","metadata":{},"name":"simple_graph","nodes":[{"name":"Item","properties":[{"name":"id","type":"STRING","is_primary_key":true},{"name":"name","type":"STRING","is_required":true}]},{"name":"Category","properties":[{"name":"id","type":"STRING","is_primary_key":true},{"name":"name","type":"STRING","is_required":true}]}],"relationships":[{"from_node":"Item","name":"BELONGS_TO","properties":[],"to_node":"Category"}],"version":"1.0.0"}}]},"CypherQueryRequest":{"properties":{"query":{"type":"string","maxLength":50000,"minLength":1,"title":"Query","description":"The Cypher query to execute. Use parameters ($param_name) for all dynamic values to prevent injection attacks.","examples":["MATCH (n:Entity {type: $entity_type}) RETURN n LIMIT $limit","MATCH (e:Entity)-[r:TRANSACTION]->(t:Entity) WHERE r.amount >= $min_amount AND e.name = $entity_name RETURN e, r, t LIMIT $limit","MATCH (n:Entity) WHERE n.identifier = $identifier RETURN n","MATCH (n) RETURN n LIMIT 10"]},"parameters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Parameters","description":"Query parameters for safe value substitution. ALWAYS use parameters instead of string interpolation.","examples":[{"entity_type":"Company","limit":100},{"entity_name":"Acme Corp","limit":50,"min_amount":1000},{"identifier":"ENT123456"},null]},"timeout":{"anyOf":[{"type":"integer","maximum":300.0,"minimum":1.0},{"type":"null"}],"title":"Timeout","description":"Query timeout in seconds (1-300)","default":60,"examples":[30,60,120,300]}},"additionalProperties":false,"type":"object","required":["query"],"title":"CypherQueryRequest","description":"Request model for Cypher query execution.","examples":[{"description":"Find entities by type with parameterized values","summary":"Simple entity lookup","value":{"parameters":{"entity_type":"Company","limit":100},"query":"MATCH (n:Entity {type: $entity_type}) RETURN n LIMIT $limit","timeout":60}},{"description":"Find transactions between entities with amount filtering","summary":"Relationship traversal query","value":{"parameters":{"entity_name":"Acme Corp","limit":50,"min_amount":1000},"query":"MATCH (e:Entity)-[r:TRANSACTION]->(t:Entity) WHERE r.amount >= $min_amount AND e.name = $entity_name RETURN e, r, t LIMIT $limit","timeout":120}},{"description":"Find specific entity using unique identifier","summary":"Lookup by identifier","value":{"parameters":{"identifier":"ENT123456"},"query":"MATCH (n:Entity) WHERE n.identifier = $identifier RETURN n","timeout":30}},{"description":"Aggregation query for financial metrics","summary":"Company financial query","value":{"parameters":{"form":"10-K","limit":20},"query":"MATCH (c:Company)-[:FILED]->(f:Filing) WHERE f.form_type = $form RETURN c.ticker, c.name, COUNT(f) as filing_count ORDER BY filing_count DESC LIMIT $limit","timeout":60}},{"description":"Simple query without parameters to explore graph structure","summary":"Explore all nodes","value":{"query":"MATCH (n) RETURN n LIMIT 10","timeout":30}}]},"DatabaseHealthResponse":{"properties":{"graph_id":{"type":"string","title":"Graph Id","description":"Graph database identifier","examples":["kg1a2b3c4d5"]},"status":{"type":"string","title":"Status","description":"Overall health status","examples":["healthy"]},"connection_status":{"type":"string","title":"Connection Status","description":"Database connection status","examples":["connected"]},"uptime_seconds":{"type":"number","title":"Uptime Seconds","description":"Database uptime in seconds","examples":[3600.5]},"last_query_time":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Query Time","description":"Timestamp of last query execution","examples":["2024-01-15T10:30:00Z"]},"query_count_24h":{"type":"integer","title":"Query Count 24H","description":"Number of queries executed in last 24 hours","examples":[150]},"avg_query_time_ms":{"type":"number","title":"Avg Query Time Ms","description":"Average query execution time in milliseconds","examples":[45.2]},"error_rate_24h":{"type":"number","title":"Error Rate 24H","description":"Error rate in last 24 hours (percentage)","examples":[0.5]},"memory_usage_mb":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Memory Usage Mb","description":"Memory usage in MB","examples":[512.3]},"storage_usage_mb":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Storage Usage Mb","description":"Storage usage in MB","examples":[1024.7]},"alerts":{"items":{"type":"string"},"type":"array","title":"Alerts","description":"Active alerts or warnings","examples":[["High memory usage detected"]]}},"type":"object","required":["graph_id","status","connection_status","uptime_seconds","query_count_24h","avg_query_time_ms","error_rate_24h"],"title":"DatabaseHealthResponse","description":"Response model for database health check."},"DatabaseInfoResponse":{"properties":{"graph_id":{"type":"string","title":"Graph Id","description":"Graph database identifier","examples":["kg1a2b3c4d5"]},"database_name":{"type":"string","title":"Database Name","description":"Database name","examples":["kg1a2b3c4d5"]},"database_size_bytes":{"type":"integer","title":"Database Size Bytes","description":"Database size in bytes","examples":[1048576]},"database_size_mb":{"type":"number","title":"Database Size Mb","description":"Database size in MB","examples":[1.0]},"node_count":{"type":"integer","title":"Node Count","description":"Total number of nodes","examples":[1250]},"relationship_count":{"type":"integer","title":"Relationship Count","description":"Total number of relationships","examples":[2340]},"node_labels":{"items":{"type":"string"},"type":"array","title":"Node Labels","description":"List of node labels","examples":[["Entity","Report","Fact"]]},"relationship_types":{"items":{"type":"string"},"type":"array","title":"Relationship Types","description":"List of relationship types","examples":[["HAS_REPORT","REPORTED_IN","HAS_ELEMENT"]]},"created_at":{"type":"string","title":"Created At","description":"Database creation timestamp","examples":["2024-01-15T10:00:00Z"]},"last_modified":{"type":"string","title":"Last Modified","description":"Last modification timestamp","examples":["2024-01-15T10:30:00Z"]},"schema_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schema Version","description":"Schema version","examples":["1.0.0"]},"read_only":{"type":"boolean","title":"Read Only","description":"Whether database is read-only","examples":[false]},"backup_count":{"type":"integer","title":"Backup Count","description":"Number of available backups","examples":[5]},"last_backup_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Backup Date","description":"Date of last backup","examples":["2024-01-15T09:00:00Z"]}},"type":"object","required":["graph_id","database_name","database_size_bytes","database_size_mb","node_count","relationship_count","node_labels","relationship_types","created_at","last_modified","read_only","backup_count"],"title":"DatabaseInfoResponse","description":"Response model for database information and statistics."},"DatabaseStorageEntry":{"properties":{"graph_id":{"type":"string","title":"Graph Id","description":"Database identifier"},"is_parent":{"type":"boolean","title":"Is Parent","description":"Whether this is the parent graph","default":false},"size_mb":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Size Mb","description":"Database size in MB"}},"type":"object","required":["graph_id"],"title":"DatabaseStorageEntry","description":"Storage for a single database on the instance."},"DeleteFileResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Deletion status"},"file_id":{"type":"string","title":"File Id","description":"Deleted file ID"},"file_name":{"type":"string","title":"File Name","description":"Deleted file name"},"message":{"type":"string","title":"Message","description":"Operation message"},"cascade_deleted":{"type":"boolean","title":"Cascade Deleted","description":"Whether cascade deletion was performed","default":false},"tables_affected":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tables Affected","description":"Tables from which file data was deleted (if cascade=true)"},"graph_marked_stale":{"type":"boolean","title":"Graph Marked Stale","description":"Whether graph was marked as stale","default":false}},"type":"object","required":["status","file_id","file_name","message"],"title":"DeleteFileResponse"},"DeleteSubgraphRequest":{"properties":{"force":{"type":"boolean","title":"Force","description":"Force deletion even if subgraph contains data","default":false},"backup_first":{"type":"boolean","title":"Backup First","description":"Create a backup before deletion","default":true},"backup_location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Backup Location","description":"S3 location for backup (uses default if not specified)","examples":["s3://my-bucket/backups/"]}},"type":"object","title":"DeleteSubgraphRequest","description":"Request model for deleting a subgraph."},"DeleteSubgraphResponse":{"properties":{"graph_id":{"type":"string","title":"Graph Id","description":"Deleted subgraph identifier"},"status":{"type":"string","title":"Status","description":"Deletion status","examples":["deleted","deletion_scheduled"]},"backup_location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Backup Location","description":"Location of backup if created"},"deleted_at":{"type":"string","format":"date-time","title":"Deleted At","description":"When deletion occurred"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Additional information about the deletion"}},"type":"object","required":["graph_id","status","deleted_at"],"title":"DeleteSubgraphResponse","description":"Response model for subgraph deletion."},"DetailedTransactionsResponse":{"properties":{"transactions":{"items":{"$ref":"#/components/schemas/EnhancedCreditTransactionResponse"},"type":"array","title":"Transactions"},"summary":{"additionalProperties":{"$ref":"#/components/schemas/TransactionSummaryResponse"},"type":"object","title":"Summary"},"total_count":{"type":"integer","title":"Total Count"},"filtered_count":{"type":"integer","title":"Filtered Count"},"date_range":{"additionalProperties":{"type":"string"},"type":"object","title":"Date Range"}},"type":"object","required":["transactions","summary","total_count","filtered_count","date_range"],"title":"DetailedTransactionsResponse","description":"Detailed response for transaction queries."},"DocumentDetailResponse":{"properties":{"id":{"type":"string","title":"Id"},"graph_id":{"type":"string","title":"Graph Id"},"user_id":{"type":"string","title":"User Id"},"title":{"type":"string","title":"Title"},"content":{"type":"string","title":"Content"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags"},"folder":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Folder"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id"},"source_type":{"type":"string","title":"Source Type"},"source_provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Provider"},"sections_indexed":{"type":"integer","title":"Sections Indexed"},"created_at":{"type":"string","title":"Created At"},"updated_at":{"type":"string","title":"Updated At"}},"type":"object","required":["id","graph_id","user_id","title","content","source_type","sections_indexed","created_at","updated_at"],"title":"DocumentDetailResponse","description":"Full document detail with raw content."},"DocumentListItem":{"properties":{"id":{"type":"string","title":"Id"},"document_title":{"type":"string","title":"Document Title"},"section_count":{"type":"integer","title":"Section Count"},"source_type":{"type":"string","title":"Source Type"},"folder":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Folder"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags"},"created_at":{"type":"string","title":"Created At"},"updated_at":{"type":"string","title":"Updated At"}},"type":"object","required":["id","document_title","section_count","source_type","created_at","updated_at"],"title":"DocumentListItem","description":"A document in the document list."},"DocumentListResponse":{"properties":{"total":{"type":"integer","title":"Total"},"documents":{"items":{"$ref":"#/components/schemas/DocumentListItem"},"type":"array","title":"Documents"},"graph_id":{"type":"string","title":"Graph Id"}},"type":"object","required":["total","documents","graph_id"],"title":"DocumentListResponse","description":"Response from listing indexed documents."},"DocumentSection":{"properties":{"document_id":{"type":"string","title":"Document Id"},"graph_id":{"type":"string","title":"Graph Id"},"source_type":{"type":"string","title":"Source Type"},"entity_ticker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Ticker"},"entity_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Name"},"entity_cik":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Cik"},"section_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Section Label"},"section_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Section Id"},"element_qname":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Element Qname"},"filing_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filing Date"},"fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fiscal Year"},"fiscal_period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fiscal Period"},"form_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Form Type"},"accession_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accession Number"},"xbrl_elements":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Xbrl Elements"},"content":{"type":"string","title":"Content"},"content_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Url"},"content_length":{"type":"integer","title":"Content Length","default":0},"document_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Title"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags"},"folder":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Folder"}},"type":"object","required":["document_id","graph_id","source_type","content"],"title":"DocumentSection","description":"Full document section retrieved by ID."},"DocumentUpdateRequest":{"properties":{"title":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Title"},"content":{"anyOf":[{"type":"string","maxLength":500000},{"type":"null"}],"title":"Content"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags"},"folder":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Folder"}},"type":"object","title":"DocumentUpdateRequest","description":"Update a document's metadata and/or content."},"DocumentUploadRequest":{"properties":{"title":{"type":"string","maxLength":500,"title":"Title","description":"Document title"},"content":{"type":"string","maxLength":500000,"title":"Content","description":"Markdown content"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags","description":"Optional tags for filtering"},"folder":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Folder","description":"Optional folder/category"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id","description":"Optional external identifier for upsert (e.g., Google Drive file ID)"}},"type":"object","required":["title","content"],"title":"DocumentUploadRequest","description":"Upload a markdown document for text indexing."},"DocumentUploadResponse":{"properties":{"id":{"type":"string","title":"Id"},"document_id":{"type":"string","title":"Document Id"},"sections_indexed":{"type":"integer","title":"Sections Indexed"},"total_content_length":{"type":"integer","title":"Total Content Length"},"section_ids":{"items":{"type":"string"},"type":"array","title":"Section Ids"}},"type":"object","required":["id","document_id","sections_indexed","total_content_length","section_ids"],"title":"DocumentUploadResponse","description":"Response from document upload."},"DownloadQuota":{"properties":{"limit_per_month":{"type":"integer","title":"Limit Per Month","description":"Maximum downloads allowed per month"},"used_this_month":{"type":"integer","title":"Used This Month","description":"Number of downloads used this month"},"remaining":{"type":"integer","title":"Remaining","description":"Downloads remaining this month"},"resets_at":{"type":"string","format":"date-time","title":"Resets At","description":"When the monthly limit resets (UTC)"}},"type":"object","required":["limit_per_month","used_this_month","remaining","resets_at"],"title":"DownloadQuota","description":"Download quota information for shared repository backups."},"EmailVerificationRequest":{"properties":{"token":{"type":"string","title":"Token","description":"Email verification token from email link"}},"type":"object","required":["token"],"title":"EmailVerificationRequest","description":"Email verification request model."},"EnhancedCreditTransactionResponse":{"properties":{"id":{"type":"string","title":"Id"},"type":{"type":"string","title":"Type"},"amount":{"type":"number","title":"Amount"},"description":{"type":"string","title":"Description"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"created_at":{"type":"string","title":"Created At"},"operation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Operation Id"},"idempotency_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency Key"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id"}},"type":"object","required":["id","type","amount","description","metadata","created_at"],"title":"EnhancedCreditTransactionResponse","description":"Enhanced credit transaction response with more details."},"EnhancedFileStatusLayers":{"properties":{"s3":{"$ref":"#/components/schemas/FileLayerStatus","description":"S3 layer status (immutable source)"},"duckdb":{"$ref":"#/components/schemas/FileLayerStatus","description":"DuckDB layer status (mutable staging)"},"graph":{"$ref":"#/components/schemas/FileLayerStatus","description":"Graph layer status (immutable materialized view)"}},"type":"object","required":["s3","duckdb","graph"],"title":"EnhancedFileStatusLayers"},"ErrorResponse":{"properties":{"detail":{"type":"string","title":"Detail","description":"Human-readable error message explaining what went wrong","examples":["Insufficient credits for operation"]},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code","description":"Machine-readable error code for programmatic handling","examples":["INSUFFICIENT_CREDITS"]},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id","description":"Unique request ID for tracking and debugging","examples":["req_1234567890abcdef"]},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Timestamp","description":"Timestamp when the error occurred","examples":["2024-01-01T00:00:00Z"]}},"type":"object","required":["detail"],"title":"ErrorResponse","description":"Standard error response format used across all API endpoints.\n\nThis model ensures consistent error responses for SDK generation\nand client error handling.","example":{"code":"RESOURCE_NOT_FOUND","detail":"Resource not found","request_id":"req_1234567890abcdef","timestamp":"2024-01-01T00:00:00Z"}},"FileInfo":{"properties":{"file_id":{"type":"string","title":"File Id","description":"Unique file identifier"},"file_name":{"type":"string","title":"File Name","description":"Original file name"},"file_format":{"type":"string","title":"File Format","description":"File format (parquet, csv, etc.)"},"size_bytes":{"type":"integer","title":"Size Bytes","description":"File size in bytes"},"row_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Row Count","description":"Estimated row count"},"upload_status":{"type":"string","title":"Upload Status","description":"Current upload status"},"upload_method":{"type":"string","title":"Upload Method","description":"Upload method used"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At","description":"File creation timestamp"},"uploaded_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Uploaded At","description":"File upload completion timestamp"},"s3_key":{"type":"string","title":"S3 Key","description":"S3 object key"}},"type":"object","required":["file_id","file_name","file_format","size_bytes","upload_status","upload_method","s3_key"],"title":"FileInfo"},"FileLayerStatus":{"properties":{"status":{"type":"string","title":"Status","description":"Layer status"},"timestamp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Timestamp","description":"Status timestamp"},"row_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Row Count","description":"Row count (if available)"},"size_bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Size Bytes","description":"Size in bytes (S3 layer only)"}},"type":"object","required":["status"],"title":"FileLayerStatus"},"FileStatusUpdate":{"properties":{"status":{"type":"string","title":"Status","description":"File status: 'uploaded' (ready for ingest), 'disabled' (exclude from ingest), 'archived' (soft deleted)","examples":["uploaded","disabled","archived"]},"ingest_to_graph":{"type":"boolean","title":"Ingest To Graph","description":"Auto-ingest to graph after DuckDB staging. Default=false (batch mode). Set to true for real-time incremental updates.","default":false}},"additionalProperties":false,"type":"object","required":["status"],"title":"FileStatusUpdate","examples":[{"status":"uploaded"},{"ingest_to_graph":true,"status":"uploaded"},{"status":"disabled"}]},"FileUploadRequest":{"properties":{"file_name":{"type":"string","title":"File Name","description":"File name to upload","examples":["entities.parquet","transactions.csv","data.json"]},"content_type":{"type":"string","title":"Content Type","description":"File MIME type","default":"application/x-parquet","examples":["application/x-parquet","text/csv","application/json"]},"table_name":{"anyOf":[{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_]*$"},{"type":"null"}],"title":"Table Name","description":"Table name to associate file with (required for first-class /files endpoint)","examples":["Entity","Fact","PERSON_WORKS_FOR_COMPANY"]}},"additionalProperties":false,"type":"object","required":["file_name"],"title":"FileUploadRequest","examples":[{"content_type":"application/x-parquet","file_name":"entities.parquet","table_name":"Entity"},{"content_type":"text/csv","file_name":"transactions.csv","table_name":"Fact"}]},"FileUploadResponse":{"properties":{"upload_url":{"type":"string","title":"Upload Url","description":"Presigned S3 upload URL"},"expires_in":{"type":"integer","title":"Expires In","description":"URL expiration time in seconds"},"file_id":{"type":"string","title":"File Id","description":"File tracking ID"},"s3_key":{"type":"string","title":"S3 Key","description":"S3 object key"}},"type":"object","required":["upload_url","expires_in","file_id","s3_key"],"title":"FileUploadResponse"},"ForgotPasswordRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email","description":"Email address to send reset link"}},"type":"object","required":["email"],"title":"ForgotPasswordRequest","description":"Forgot password request model."},"GetFileInfoResponse":{"properties":{"file_id":{"type":"string","title":"File Id","description":"Unique file identifier"},"graph_id":{"type":"string","title":"Graph Id","description":"Graph database identifier"},"table_id":{"type":"string","title":"Table Id","description":"Table identifier"},"table_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Table Name","description":"Table name"},"file_name":{"type":"string","title":"File Name","description":"Original file name"},"file_format":{"type":"string","title":"File Format","description":"File format (parquet, csv, etc.)"},"size_bytes":{"type":"integer","title":"Size Bytes","description":"File size in bytes"},"row_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Row Count","description":"Estimated row count"},"upload_status":{"type":"string","title":"Upload Status","description":"Current upload status"},"upload_method":{"type":"string","title":"Upload Method","description":"Upload method used"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At","description":"File creation timestamp"},"uploaded_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Uploaded At","description":"File upload completion timestamp"},"s3_key":{"type":"string","title":"S3 Key","description":"S3 object key"},"layers":{"anyOf":[{"$ref":"#/components/schemas/EnhancedFileStatusLayers"},{"type":"null"}],"description":"Multi-layer pipeline status (S3 → DuckDB → Graph). Shows status, timestamps, and row counts for each layer independently."}},"type":"object","required":["file_id","graph_id","table_id","file_name","file_format","size_bytes","upload_status","upload_method","s3_key"],"title":"GetFileInfoResponse"},"GraphCapacityResponse":{"properties":{"tiers":{"items":{"$ref":"#/components/schemas/TierCapacity"},"type":"array","title":"Tiers","description":"Capacity status per tier"}},"type":"object","required":["tiers"],"title":"GraphCapacityResponse","description":"Response containing capacity status for all customer-facing tiers."},"GraphInfo":{"properties":{"graphId":{"type":"string","title":"Graphid","description":"Graph database identifier","examples":["kg1a2b3c4d5","sec"]},"graphName":{"type":"string","title":"Graphname","description":"Display name for the graph","examples":["Acme Consulting LLC","SEC EDGAR Filings"]},"role":{"type":"string","title":"Role","description":"User's role/access level","examples":["admin","member","read"]},"isSelected":{"type":"boolean","title":"Isselected","description":"Whether this is the currently selected graph","examples":[true,false]},"createdAt":{"type":"string","title":"Createdat","description":"Creation timestamp","examples":["2024-01-15T10:00:00Z"]},"isRepository":{"type":"boolean","title":"Isrepository","description":"Whether this is a shared repository (vs user graph)","default":false,"examples":[false,true]},"repositoryType":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Repositorytype","description":"Repository type if isRepository=true","examples":[null,"sec","industry","economic"]},"schemaExtensions":{"items":{"type":"string"},"type":"array","title":"Schemaextensions","description":"List of schema extensions installed on this graph","examples":[[],["roboledger"],["roboledger","roboinvestor"]]},"isSubgraph":{"type":"boolean","title":"Issubgraph","description":"Whether this is a subgraph (vs a main graph)","default":false,"examples":[false,true]},"parentGraphId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parentgraphid","description":"Parent graph ID if this is a subgraph","examples":[null,"kg1a2b3c4d5"]},"graphType":{"type":"string","title":"Graphtype","description":"Type of graph: generic, entity, or repository","default":"entity","examples":["entity","generic","repository"]},"status":{"type":"string","title":"Status","description":"Graph lifecycle status: active, suspended, deprovisioned","default":"active","examples":["active","suspended"]}},"type":"object","required":["graphId","graphName","role","isSelected","createdAt"],"title":"GraphInfo","description":"Graph information for user.","examples":[{"createdAt":"2024-01-15T10:00:00Z","graphId":"kg1a2b3c4d5","graphName":"Acme Consulting LLC","graphType":"entity","isRepository":false,"isSelected":true,"isSubgraph":false,"role":"admin","schemaExtensions":["roboledger"],"status":"active"},{"createdAt":"2024-02-20T14:30:00Z","graphId":"kg9z8y7x6w5_dev","graphName":"TechCorp Enterprises - Dev","graphType":"entity","isRepository":false,"isSelected":false,"isSubgraph":true,"parentGraphId":"kg9z8y7x6w5","role":"member","schemaExtensions":["roboledger","roboinvestor"],"status":"active"},{"createdAt":"2024-01-01T00:00:00Z","graphId":"sec","graphName":"SEC EDGAR Filings","graphType":"repository","isRepository":true,"isSelected":false,"isSubgraph":false,"repositoryType":"sec","role":"read","schemaExtensions":[],"status":"active"}]},"GraphLimitsResponse":{"properties":{"graph_id":{"type":"string","title":"Graph Id","description":"Graph database identifier"},"subscription_tier":{"type":"string","title":"Subscription Tier","description":"User's subscription tier"},"graph_tier":{"type":"string","title":"Graph Tier","description":"Graph's database tier"},"is_shared_repository":{"type":"boolean","title":"Is Shared Repository","description":"Whether this is a shared repository"},"storage":{"$ref":"#/components/schemas/StorageLimits","description":"Storage limits and usage"},"queries":{"$ref":"#/components/schemas/QueryLimits","description":"Query operation limits"},"copy_operations":{"$ref":"#/components/schemas/CopyOperationLimits","description":"Copy/ingestion operation limits"},"backups":{"$ref":"#/components/schemas/BackupLimits","description":"Backup operation limits"},"rate_limits":{"$ref":"#/components/schemas/RateLimits","description":"API rate limits"},"credits":{"anyOf":[{"$ref":"#/components/schemas/CreditLimits"},{"type":"null"}],"description":"AI credit limits (if applicable)"},"content":{"anyOf":[{"$ref":"#/components/schemas/ContentLimits"},{"type":"null"}],"description":"Per-operation materialization limits (if applicable)"},"instance":{"anyOf":[{"$ref":"#/components/schemas/InstanceUsage"},{"type":"null"}],"description":"Aggregate instance storage usage (user graphs only)"}},"type":"object","required":["graph_id","subscription_tier","graph_tier","is_shared_repository","storage","queries","copy_operations","backups","rate_limits"],"title":"GraphLimitsResponse","description":"Response model for comprehensive graph operational limits.","examples":[{"description":"Operational limits for a ladybug-standard tier user graph","summary":"Standard tier user graph limits","value":{"backups":{"backup_retention_days":7,"max_backup_size_gb":10,"max_backups_per_day":2},"content":{"chunk_size_rows":1000000,"max_rows_per_copy":2000000,"max_single_table_rows":5000000},"copy_operations":{"concurrent_operations":1,"daily_copy_operations":25,"max_file_size_gb":1.0,"max_files_per_operation":100,"supported_formats":["parquet","csv","json","delta","iceberg"],"timeout_seconds":900},"credits":{"current_balance":7500,"monthly_ai_credits":8000},"graph_id":"kg1a2b3c4d5","graph_tier":"ladybug-standard","instance":{"databases":[{"graph_id":"kg1a2b3c4d5","is_parent":true,"size_mb":2150.0},{"graph_id":"kg1a2b3c4d5_dev","is_parent":false,"size_mb":360.0}],"limit_gb":20,"node_count":150000,"status":"healthy","total_storage_gb":2.45,"usage_percentage":12.3},"is_shared_repository":false,"queries":{"chunk_size":1000,"concurrent_queries":1,"max_rows_per_query":10000,"max_timeout_seconds":30},"rate_limits":{"burst_capacity":10,"requests_per_hour":1000,"requests_per_minute":60},"storage":{"approaching_limit":false,"current_usage_gb":2.45,"max_storage_gb":10},"subscription_tier":"ladybug-standard"}},{"description":"Operational limits for SEC shared repository (no instance usage tracking)","summary":"Shared repository limits (SEC)","value":{"backups":{"backup_retention_days":30,"max_backup_size_gb":50,"max_backups_per_day":4},"copy_operations":{"concurrent_operations":2,"daily_copy_operations":50,"max_file_size_gb":5.0,"max_files_per_operation":200,"supported_formats":["parquet","csv","json","delta","iceberg"],"timeout_seconds":600},"graph_id":"sec","graph_tier":"ladybug-shared","is_shared_repository":true,"queries":{"chunk_size":2000,"concurrent_queries":1,"max_rows_per_query":10000,"max_timeout_seconds":120},"rate_limits":{"burst_capacity":20,"requests_per_hour":2000,"requests_per_minute":120},"storage":{"approaching_limit":false,"current_usage_gb":125.3,"max_storage_gb":100},"subscription_tier":"ladybug-standard"}}]},"GraphMetadata":{"properties":{"graph_name":{"type":"string","title":"Graph Name","description":"Display name for the graph","examples":["Acme Consulting LLC"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Optional description","examples":["Professional consulting services with full accounting integration"]},"schema_extensions":{"items":{"type":"string"},"type":"array","title":"Schema Extensions","description":"Schema extensions to enable","examples":[["roboledger"]]},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Tags for organizing graphs","examples":[["consulting","professional-services"]]}},"type":"object","required":["graph_name"],"title":"GraphMetadata","description":"Metadata for graph creation."},"GraphMetricsResponse":{"properties":{"graph_id":{"type":"string","title":"Graph Id","description":"Graph database identifier"},"graph_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Graph Name","description":"Display name for the graph"},"user_role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Role","description":"User's role in this graph"},"timestamp":{"type":"string","title":"Timestamp","description":"Metrics collection timestamp"},"total_nodes":{"type":"integer","title":"Total Nodes","description":"Total number of nodes"},"total_relationships":{"type":"integer","title":"Total Relationships","description":"Total number of relationships"},"node_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Node Counts","description":"Node counts by label"},"relationship_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Relationship Counts","description":"Relationship counts by type"},"estimated_size":{"additionalProperties":true,"type":"object","title":"Estimated Size","description":"Database size estimates"},"health_status":{"additionalProperties":true,"type":"object","title":"Health Status","description":"Database health information"}},"type":"object","required":["graph_id","timestamp","total_nodes","total_relationships","node_counts","relationship_counts","estimated_size","health_status"],"title":"GraphMetricsResponse","description":"Response model for graph metrics."},"GraphSubscriptionResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Subscription ID"},"resource_type":{"type":"string","title":"Resource Type","description":"Resource type (graph or repository)"},"resource_id":{"type":"string","title":"Resource Id","description":"Resource identifier"},"plan_name":{"type":"string","title":"Plan Name","description":"Current plan name"},"plan_display_name":{"type":"string","title":"Plan Display Name","description":"Human-readable plan name for UI display"},"billing_interval":{"type":"string","title":"Billing Interval","description":"Billing interval"},"status":{"type":"string","title":"Status","description":"Subscription status"},"base_price_cents":{"type":"integer","title":"Base Price Cents","description":"Base price in cents"},"current_period_start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Period Start","description":"Current billing period start"},"current_period_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Period End","description":"Current billing period end"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Started At","description":"Subscription start date"},"canceled_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canceled At","description":"Cancellation date"},"ends_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ends At","description":"Subscription end date (when access will be revoked, especially relevant for cancelled subscriptions)"},"created_at":{"type":"string","title":"Created At","description":"Creation timestamp"},"operation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Operation Id","description":"Operation ID for tracking async tier changes via SSE"}},"type":"object","required":["id","resource_type","resource_id","plan_name","plan_display_name","billing_interval","status","base_price_cents","created_at"],"title":"GraphSubscriptionResponse","description":"Response for graph or repository subscription details."},"GraphSubscriptionTier":{"properties":{"name":{"type":"string","title":"Name","description":"Infrastructure tier identifier (e.g., ladybug-standard)"},"display_name":{"type":"string","title":"Display Name","description":"Display name for UI"},"description":{"type":"string","title":"Description","description":"Tier description"},"monthly_price_per_graph":{"type":"number","title":"Monthly Price Per Graph","description":"Monthly price in USD per graph"},"monthly_credits_per_graph":{"type":"integer","title":"Monthly Credits Per Graph","description":"Monthly AI credits per graph"},"infrastructure":{"type":"string","title":"Infrastructure","description":"Infrastructure description"},"features":{"items":{"type":"string"},"type":"array","title":"Features","description":"List of features"},"backup_retention_days":{"type":"integer","title":"Backup Retention Days","description":"Backup retention in days"},"priority_support":{"type":"boolean","title":"Priority Support","description":"Whether priority support is included"},"max_subgraphs":{"type":"integer","title":"Max Subgraphs","description":"Maximum subgraphs supported","default":0},"api_rate_multiplier":{"type":"number","title":"Api Rate Multiplier","description":"API rate multiplier"},"backend":{"type":"string","title":"Backend","description":"Database backend identifier"},"instance_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Instance Type","description":"Instance type"}},"type":"object","required":["name","display_name","description","monthly_price_per_graph","monthly_credits_per_graph","infrastructure","features","backup_retention_days","priority_support","api_rate_multiplier","backend"],"title":"GraphSubscriptionTier","description":"Information about a graph infrastructure tier.\n\nEach tier represents a per-graph subscription option with specific\ninfrastructure, performance, and pricing characteristics."},"GraphSubscriptions":{"properties":{"description":{"type":"string","title":"Description","description":"Description of graph subscriptions"},"pricing_model":{"type":"string","title":"Pricing Model","description":"Pricing model type (per_graph or per_organization)"},"tiers":{"items":{"$ref":"#/components/schemas/GraphSubscriptionTier"},"type":"array","title":"Tiers","description":"Available infrastructure tiers"},"notes":{"items":{"type":"string"},"type":"array","title":"Notes","description":"Important notes"}},"type":"object","required":["description","pricing_model","tiers","notes"],"title":"GraphSubscriptions","description":"Graph subscription offerings.\n\nGraph subscriptions are per-graph, not per-organization. Each graph\ncreated by an organization has its own subscription with its own\ninfrastructure tier, pricing, and credit allocation."},"GraphTierBackup":{"properties":{"max_backup_size_gb":{"type":"integer","title":"Max Backup Size Gb","description":"Maximum backup size in GB"},"backup_retention_days":{"type":"integer","title":"Backup Retention Days","description":"Backup retention period in days"},"max_backups_per_day":{"type":"integer","title":"Max Backups Per Day","description":"Maximum backups per day"}},"type":"object","required":["max_backup_size_gb","backup_retention_days","max_backups_per_day"],"title":"GraphTierBackup","description":"Backup configuration for a tier."},"GraphTierCopyOperations":{"properties":{"max_file_size_gb":{"type":"number","title":"Max File Size Gb","description":"Maximum file size in GB"},"timeout_seconds":{"type":"integer","title":"Timeout Seconds","description":"Operation timeout in seconds"},"concurrent_operations":{"type":"integer","title":"Concurrent Operations","description":"Maximum concurrent operations"},"max_files_per_operation":{"type":"integer","title":"Max Files Per Operation","description":"Maximum files per operation"},"daily_copy_operations":{"type":"integer","title":"Daily Copy Operations","description":"Daily operation limit"}},"type":"object","required":["max_file_size_gb","timeout_seconds","concurrent_operations","max_files_per_operation","daily_copy_operations"],"title":"GraphTierCopyOperations","description":"Copy operation limits for a tier."},"GraphTierInfo":{"properties":{"tier":{"type":"string","title":"Tier","description":"Tier identifier"},"name":{"type":"string","title":"Name","description":"Tier name"},"display_name":{"type":"string","title":"Display Name","description":"Display name for UI"},"description":{"type":"string","title":"Description","description":"Tier description"},"backend":{"type":"string","title":"Backend","description":"Database backend identifier"},"enabled":{"type":"boolean","title":"Enabled","description":"Whether tier is available"},"max_subgraphs":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Subgraphs","description":"Maximum subgraphs allowed"},"monthly_credits":{"type":"integer","title":"Monthly Credits","description":"Monthly AI credits"},"api_rate_multiplier":{"type":"number","title":"Api Rate Multiplier","description":"API rate limit multiplier"},"monthly_price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Monthly Price","description":"Monthly price in USD"},"features":{"items":{"type":"string"},"type":"array","title":"Features","description":"List of tier features"},"instance":{"$ref":"#/components/schemas/GraphTierInstance","description":"Instance specifications"},"limits":{"$ref":"#/components/schemas/GraphTierLimits","description":"Resource limits"}},"type":"object","required":["tier","name","display_name","description","backend","enabled","max_subgraphs","monthly_credits","api_rate_multiplier","features","instance","limits"],"title":"GraphTierInfo","description":"Complete information about a graph database tier."},"GraphTierInstance":{"properties":{"type":{"type":"string","title":"Type","description":"Instance type identifier"},"memory_mb":{"type":"integer","title":"Memory Mb","description":"Memory allocated to your graph in megabytes"},"is_multitenant":{"type":"boolean","title":"Is Multitenant","description":"Whether this tier shares infrastructure with other graphs"}},"type":"object","required":["type","memory_mb","is_multitenant"],"title":"GraphTierInstance","description":"Instance specifications for a tier."},"GraphTierLimits":{"properties":{"monthly_credits":{"type":"integer","title":"Monthly Credits","description":"Monthly credit allocation"},"max_subgraphs":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Subgraphs","description":"Maximum subgraphs (null for unlimited)"},"copy_operations":{"$ref":"#/components/schemas/GraphTierCopyOperations","description":"Copy operation limits"},"backup":{"$ref":"#/components/schemas/GraphTierBackup","description":"Backup configuration"}},"type":"object","required":["monthly_credits","max_subgraphs","copy_operations","backup"],"title":"GraphTierLimits","description":"Resource limits for a tier."},"GraphUsageResponse":{"properties":{"graph_id":{"type":"string","title":"Graph Id","description":"Graph database identifier"},"time_range":{"type":"string","title":"Time Range","description":"Time range for usage data"},"storage_summary":{"anyOf":[{"$ref":"#/components/schemas/StorageSummary"},{"type":"null"}],"description":"Storage usage summary"},"credit_summary":{"anyOf":[{"$ref":"#/components/schemas/CreditSummary"},{"type":"null"}],"description":"Credit consumption summary"},"performance_insights":{"anyOf":[{"$ref":"#/components/schemas/PerformanceInsights"},{"type":"null"}],"description":"Performance analytics"},"recent_events":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Recent Events","description":"Recent usage events"},"timestamp":{"type":"string","title":"Timestamp","description":"Usage collection timestamp"}},"type":"object","required":["graph_id","time_range","timestamp"],"title":"GraphUsageResponse","description":"Response model for graph usage statistics."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthStatus":{"properties":{"status":{"type":"string","pattern":"^(healthy|degraded|unhealthy)$","title":"Status","description":"Current health status","examples":["healthy"]},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"Time of health check","examples":["2024-01-01T00:00:00Z"]},"details":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Details","description":"Additional health check details"}},"type":"object","required":["status","timestamp"],"title":"HealthStatus","description":"Health check status information."},"InitialEntityData":{"properties":{"name":{"type":"string","maxLength":255,"minLength":1,"title":"Name","description":"Entity name"},"uri":{"type":"string","minLength":1,"title":"Uri","description":"Entity website or URI"},"ticker":{"anyOf":[{"type":"string","maxLength":10,"minLength":1},{"type":"null"}],"title":"Ticker","description":"Entity symbol/ticker (e.g., 'HARB', 'NVDA'). Auto-generated from name if not provided."},"cik":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cik","description":"CIK number for SEC filings"},"sic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sic","description":"SIC code"},"sic_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sic Description","description":"SIC description"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"Business category"},"state_of_incorporation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State Of Incorporation","description":"State of incorporation"},"fiscal_year_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fiscal Year End","description":"Fiscal year end (MMDD)"},"ein":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ein","description":"Employer Identification Number"}},"type":"object","required":["name","uri"],"title":"InitialEntityData","description":"Initial entity data for entity-focused graph creation.\n\nWhen creating an entity graph with an initial entity node, this model defines\nthe entity's identifying information and metadata.","examples":[{"description":"Initial entity data for a publicly-traded company with SEC information","summary":"Public company entity","value":{"cik":"0000320193","ein":"94-2404110","fiscal_year_end":"0930","name":"Apple Inc.","sic":"3571","sic_description":"Electronic Computers","state_of_incorporation":"California","uri":"https://www.apple.com"}},{"description":"Initial entity data for a private company with minimal information","summary":"Private company entity","value":{"category":"Professional Services","ein":"12-3456789","name":"Acme Consulting LLC","state_of_incorporation":"Delaware","uri":"https://acmeconsulting.com"}},{"description":"Simplest entity with just required fields","summary":"Minimal entity","value":{"name":"Startup Inc","uri":"https://startup.io"}}]},"InstanceUsage":{"properties":{"node_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Node Count","description":"Current node count (informational, no limit enforced)"},"total_storage_gb":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Storage Gb","description":"Total storage used across all databases in GB"},"limit_gb":{"type":"number","title":"Limit Gb","description":"Soft storage limit for this tier in GB"},"usage_percentage":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Usage Percentage","description":"Storage usage as percentage of limit (e.g. 105.2)"},"status":{"type":"string","title":"Status","description":"Instance status: 'healthy' (<80%), 'approaching' (80-100%), 'over_limit' (>100%)"},"databases":{"items":{"$ref":"#/components/schemas/DatabaseStorageEntry"},"type":"array","title":"Databases","description":"Per-database storage breakdown"}},"type":"object","required":["limit_gb","status"],"title":"InstanceUsage","description":"Aggregate storage usage across the dedicated instance.\n\nCovers the parent graph, all subgraphs, DuckDB staging, and\nfuture LanceDB vector indexes."},"InviteMemberRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email"},"role":{"anyOf":[{"$ref":"#/components/schemas/OrgRole"},{"type":"null"}],"default":"member"}},"type":"object","required":["email"],"title":"InviteMemberRequest","description":"Request to invite a member to an organization."},"Invoice":{"properties":{"id":{"type":"string","title":"Id","description":"Invoice ID"},"number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Number","description":"Invoice number"},"status":{"type":"string","title":"Status","description":"Invoice status (paid, open, void, uncollectible)"},"amount_due":{"type":"integer","title":"Amount Due","description":"Amount due in cents"},"amount_paid":{"type":"integer","title":"Amount Paid","description":"Amount paid in cents"},"currency":{"type":"string","title":"Currency","description":"Currency code (usd)"},"created":{"type":"string","title":"Created","description":"Invoice creation date (ISO format)"},"due_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Due Date","description":"Invoice due date (ISO format)"},"paid_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Paid At","description":"Payment date (ISO format)"},"invoice_pdf":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Invoice Pdf","description":"PDF download URL"},"hosted_invoice_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hosted Invoice Url","description":"Hosted invoice URL"},"line_items":{"items":{"$ref":"#/components/schemas/InvoiceLineItem"},"type":"array","title":"Line Items","description":"Invoice line items"},"subscription_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subscription Id","description":"Associated subscription ID"}},"type":"object","required":["id","status","amount_due","amount_paid","currency","created","line_items"],"title":"Invoice","description":"Invoice information."},"InvoiceLineItem":{"properties":{"description":{"type":"string","title":"Description","description":"Line item description"},"amount":{"type":"integer","title":"Amount","description":"Amount in cents"},"quantity":{"type":"integer","title":"Quantity","description":"Quantity"},"period_start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period Start","description":"Billing period start"},"period_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period End","description":"Billing period end"}},"type":"object","required":["description","amount","quantity"],"title":"InvoiceLineItem","description":"Invoice line item."},"InvoicesResponse":{"properties":{"invoices":{"items":{"$ref":"#/components/schemas/Invoice"},"type":"array","title":"Invoices","description":"List of invoices"},"total_count":{"type":"integer","title":"Total Count","description":"Total number of invoices"},"has_more":{"type":"boolean","title":"Has More","description":"Whether more invoices are available"}},"type":"object","required":["invoices","total_count","has_more"],"title":"InvoicesResponse","description":"Response for invoice list."},"ListSubgraphsResponse":{"properties":{"parent_graph_id":{"type":"string","title":"Parent Graph Id","description":"Parent graph identifier","examples":["kg5f2e5e0da65d45d69645"]},"parent_graph_name":{"type":"string","title":"Parent Graph Name","description":"Parent graph name","examples":["My Company Graph"]},"parent_graph_tier":{"type":"string","title":"Parent Graph Tier","description":"Parent graph tier","examples":["ladybug-large","ladybug-xlarge"]},"subgraphs_enabled":{"type":"boolean","title":"Subgraphs Enabled","description":"Whether subgraphs are enabled for this tier (requires LadybugDB Large/XLarge)"},"subgraph_count":{"type":"integer","minimum":0.0,"title":"Subgraph Count","description":"Total number of subgraphs"},"max_subgraphs":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Subgraphs","description":"Maximum allowed subgraphs for this tier (None = unlimited)"},"total_size_mb":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Size Mb","description":"Combined size of all subgraphs in megabytes"},"subgraphs":{"items":{"$ref":"#/components/schemas/SubgraphSummary"},"type":"array","title":"Subgraphs","description":"List of subgraphs"}},"type":"object","required":["parent_graph_id","parent_graph_name","parent_graph_tier","subgraphs_enabled","subgraph_count","subgraphs"],"title":"ListSubgraphsResponse","description":"Response model for listing subgraphs."},"ListTableFilesResponse":{"properties":{"graph_id":{"type":"string","title":"Graph Id","description":"Graph database identifier"},"table_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Table Name","description":"Table name (null if listing all files in graph)"},"files":{"items":{"$ref":"#/components/schemas/FileInfo"},"type":"array","title":"Files","description":"List of files in the table"},"total_files":{"type":"integer","title":"Total Files","description":"Total number of files"},"total_size_bytes":{"type":"integer","title":"Total Size Bytes","description":"Total size of all files in bytes"}},"type":"object","required":["graph_id","files","total_files","total_size_bytes"],"title":"ListTableFilesResponse"},"LoginRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email","description":"User's email address"},"password":{"type":"string","minLength":8,"title":"Password","description":"User's password"}},"type":"object","required":["email","password"],"title":"LoginRequest","description":"Login request model."},"MCPToolCall":{"properties":{"name":{"type":"string","minLength":1,"title":"Name","description":"Name of the MCP tool to execute"},"arguments":{"additionalProperties":true,"type":"object","title":"Arguments","description":"Arguments to pass to the tool"}},"type":"object","required":["name"],"title":"MCPToolCall","description":"Request model for MCP tool execution.","examples":[{"description":"Execute a simple aggregation query to count nodes by label","summary":"Count nodes by type","value":{"arguments":{"parameters":{},"query":"MATCH (n) RETURN label(n) AS type, count(n) AS count ORDER BY count DESC"},"name":"read-graph-cypher"}},{"description":"Execute accounting query with parameterized period to calculate trial balance","summary":"Trial balance calculation","value":{"arguments":{"parameters":{},"query":"MATCH (li:LineItem)-[:LINE_ITEM_RELATES_TO_ELEMENT]->(e:Element) WITH e.name AS account, e.classification AS type, sum(li.debit_amount) AS total_debits, sum(li.credit_amount) AS total_credits RETURN account, type, total_debits, total_credits, total_debits - total_credits AS net_balance ORDER BY account"},"name":"read-graph-cypher"}},{"description":"Retrieve the complete graph schema without any arguments","summary":"Get schema information","value":{"arguments":{},"name":"get-graph-schema"}},{"description":"Retrieve high-level statistics and metadata about the graph","summary":"Get graph statistics","value":{"arguments":{},"name":"get-graph-info"}},{"description":"Execute time-series query with parameterized month for revenue analysis","summary":"Revenue trends with date filter","value":{"arguments":{"parameters":{"classification":"revenue","month":"2025-09"},"query":"MATCH (t:Transaction)-[:TRANSACTION_HAS_ENTRY]->(en:Entry)-[:ENTRY_HAS_LINE_ITEM]->(li:LineItem)-[:LINE_ITEM_RELATES_TO_ELEMENT]->(e:Element) WHERE e.classification = $classification AND substring(t.date, 1, 7) = $month RETURN sum(li.credit_amount) AS total_revenue","timeout_override":60},"name":"read-graph-cypher"}}]},"MCPToolsResponse":{"properties":{"tools":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Tools","description":"List of available MCP tools with their schemas"}},"type":"object","required":["tools"],"title":"MCPToolsResponse","description":"Response model for MCP tools listing.","examples":[{"description":"Full list of available MCP tools with schemas and capabilities for an entity-based knowledge graph","summary":"Complete tool listing for entity graph","value":{"tools":[{"capabilities":{"cacheable":false,"progress":true,"streaming":true,"timeout_seconds":300},"description":"Execute a read-only Cypher query against the graph database. Supports parameterized queries for safety and streaming for large result sets.","inputSchema":{"properties":{"query":{"description":"Cypher query to execute (read-only). Use $param syntax for parameters.","type":"string"},"parameters":{"description":"Query parameters as key-value pairs","type":"object"},"timeout_override":{"description":"Override default timeout (max 300 seconds)","type":"integer"}},"required":["query"],"type":"object"},"name":"read-graph-cypher"},{"capabilities":{"cache_ttl_seconds":3600,"cacheable":true,"progress":true,"streaming":false,"timeout_seconds":60},"description":"Get the complete schema of the graph database including node labels, relationship types, and property definitions","inputSchema":{"properties":{},"type":"object"},"name":"get-graph-schema"},{"capabilities":{"cache_ttl_seconds":300,"cacheable":true,"progress":false,"streaming":false,"timeout_seconds":30},"description":"Get high-level statistics and metadata about the graph database","inputSchema":{"properties":{},"type":"object"},"name":"get-graph-info"}]}},{"description":"Basic tool set available for a newly created empty graph","summary":"Minimal tool listing","value":{"tools":[{"capabilities":{"cache_ttl_seconds":3600,"cacheable":true,"progress":true,"streaming":false,"timeout_seconds":60},"description":"Get the complete schema of the graph database","inputSchema":{"properties":{},"type":"object"},"name":"get-graph-schema"},{"capabilities":{"cache_ttl_seconds":300,"cacheable":true,"progress":false,"streaming":false,"timeout_seconds":30},"description":"Get statistics about the graph database","inputSchema":{"properties":{},"type":"object"},"name":"get-graph-info"}]}},{"description":"Tool listing for a graph with advanced analysis features enabled","summary":"Tools with extended capabilities","value":{"tools":[{"capabilities":{"cacheable":false,"progress":true,"streaming":true,"timeout_seconds":300},"description":"Execute a read-only Cypher query with streaming support","inputSchema":{"properties":{"query":{"type":"string"},"parameters":{"type":"object"}},"required":["query"],"type":"object"},"name":"read-graph-cypher"},{"capabilities":{"cacheable":false,"progress":false,"streaming":false,"timeout_seconds":60},"description":"Specialized tool for analyzing financial statement relationships and metrics","inputSchema":{"properties":{"company_identifier":{"description":"Ticker symbol or CIK","type":"string"},"analysis_type":{"enum":["revenue_trends","expense_analysis","ratios"],"type":"string"}},"required":["company_identifier"],"type":"object"},"name":"analyze-financial-statements"}]}}]},"MaterializeRequest":{"properties":{"force":{"type":"boolean","title":"Force","description":"Force materialization even if graph is not stale","default":false},"rebuild":{"type":"boolean","title":"Rebuild","description":"Delete and recreate graph database before materialization","default":false},"ignore_errors":{"type":"boolean","title":"Ignore Errors","description":"Continue ingestion on row errors","default":true},"dry_run":{"type":"boolean","title":"Dry Run","description":"Validate limits without executing materialization. Returns usage, limits, and warnings.","default":false},"source":{"anyOf":[{"type":"string","pattern":"^(staged|extensions)$"},{"type":"null"}],"title":"Source","description":"Data source for materialization. Auto-detected from graph type if not specified. 'staged' materializes from uploaded files (generic graphs). 'extensions' materializes from the extensions OLTP database (entity graphs)."},"materialize_embeddings":{"type":"boolean","title":"Materialize Embeddings","description":"Include embedding columns in materialization and build HNSW vector indexes in the graph database. When false (default), embedding columns are NULLed out to save space. Set to true for graphs that need vector search.","default":false}},"additionalProperties":false,"type":"object","title":"MaterializeRequest"},"MaterializeResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Operation status","default":"queued"},"graph_id":{"type":"string","title":"Graph Id","description":"Graph database identifier"},"operation_id":{"type":"string","title":"Operation Id","description":"SSE operation ID for progress tracking"},"message":{"type":"string","title":"Message","description":"Human-readable status message"},"limit_check":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Limit Check","description":"Limit check results (only present for dry_run requests)"}},"type":"object","required":["graph_id","operation_id","message"],"title":"MaterializeResponse","description":"Response for queued materialization operation.","example":{"graph_id":"kg_abc123","message":"Materialization queued. Monitor via SSE stream.","operation_id":"550e8400-e29b-41d4-a716-446655440000","status":"queued"}},"MaterializeStatusResponse":{"properties":{"graph_id":{"type":"string","title":"Graph Id","description":"Graph database identifier"},"is_stale":{"type":"boolean","title":"Is Stale","description":"Whether graph is currently stale"},"stale_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stale Reason","description":"Reason for staleness if applicable"},"stale_since":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stale Since","description":"When graph became stale (ISO timestamp)"},"last_materialized_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Materialized At","description":"When graph was last materialized (ISO timestamp)"},"materialization_count":{"type":"integer","title":"Materialization Count","description":"Total number of materializations performed","default":0},"hours_since_materialization":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Hours Since Materialization","description":"Hours since last materialization"},"message":{"type":"string","title":"Message","description":"Human-readable status summary"}},"type":"object","required":["graph_id","is_stale","message"],"title":"MaterializeStatusResponse"},"OfferingRepositoryPlan":{"properties":{"plan":{"type":"string","title":"Plan","description":"Plan identifier"},"name":{"type":"string","title":"Name","description":"Plan name"},"monthly_price":{"type":"number","title":"Monthly Price","description":"Monthly price in USD"},"monthly_credits":{"type":"integer","title":"Monthly Credits","description":"Monthly credit allocation"},"access_level":{"type":"string","title":"Access Level","description":"Access level"},"features":{"items":{"type":"string"},"type":"array","title":"Features","description":"List of features"},"rate_limits":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"integer"},{"type":"null"}]},"type":"object"},{"type":"null"}],"title":"Rate Limits","description":"Rate limits for this plan"}},"type":"object","required":["plan","name","monthly_price","monthly_credits","access_level","features"],"title":"OfferingRepositoryPlan","description":"Information about a repository plan."},"OperationCosts":{"properties":{"description":{"type":"string","title":"Description","description":"Description of operation costs"},"ai_operations":{"additionalProperties":{"type":"number"},"type":"object","title":"Ai Operations","description":"Base costs for AI operations"},"token_pricing":{"additionalProperties":{"$ref":"#/components/schemas/TokenPricing"},"type":"object","title":"Token Pricing","description":"Token pricing by model"},"included_operations":{"items":{"type":"string"},"type":"array","title":"Included Operations","description":"Operations that don't consume credits"},"notes":{"items":{"type":"string"},"type":"array","title":"Notes","description":"Important notes about costs"}},"type":"object","required":["description","ai_operations","token_pricing","included_operations","notes"],"title":"OperationCosts","description":"Operation cost information."},"OperationEnvelope":{"properties":{"operation":{"type":"string","title":"Operation","description":"Kebab-case operation name"},"operationId":{"type":"string","title":"Operationid","description":"op_-prefixed ULID for audit and SSE correlation"},"status":{"type":"string","enum":["completed","pending","failed"],"title":"Status","description":"Operation lifecycle state"},"result":{"anyOf":[{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"null"}],"title":"Result","description":"Command-specific result payload"},"at":{"type":"string","title":"At","description":"ISO-8601 UTC timestamp"},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Createdby","description":"User ID that initiated the operation (null for legacy callers)"},"idempotentReplay":{"type":"boolean","title":"Idempotentreplay","description":"True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions.","default":false}},"type":"object","required":["operation","operationId","status","at"],"title":"OperationEnvelope","description":"Uniform response shape for every extensions operation endpoint.\n\nEvery dispatch through `/extensions/{domain}/{graph_id}/operations/{op}`\nreturns an envelope carrying an `op_<ULID>` operation_id. That id is the\nbridge to the platform's monitoring surface: pass it to\n`GET /v1/operations/{operation_id}/stream` (see `routers/operations.py`)\nto subscribe to SSE progress events. Sync commands complete in the\nenvelope itself; async commands (`status: \"pending\"`, HTTP 202) hand off\nto a background worker and stream their tail through the same SSE\nendpoint until completion. Failed dispatches still mint an `operation_id`\nso the audit log and any partial SSE events stay correlatable.\n\nFields:\n- `operation`: kebab-case command name (e.g. `close-period`)\n- `operation_id`: `op_`-prefixed ULID; always present, usable for audit\n  correlation and — for async commands — SSE subscription via\n  `/v1/operations/{operation_id}/stream`\n- `status`: `\"completed\"` (sync, HTTP 200), `\"pending\"` (async, HTTP 202),\n  or `\"failed\"` (error responses)\n- `result`: the domain-specific payload (the original Pydantic response)\n  or `None` for async/failed cases\n- `at`: ISO-8601 UTC timestamp of when the envelope was minted (for sync\n  ops this is the completion time; for async/pending it's the enqueue time)\n- `created_by`: user ID of the caller who initiated this operation, for\n  audit correlation without having to cross-reference the audit log.\n  Always populated for dispatcher-routed calls; may be `None` for legacy\n  direct `wrap_completed(...)` callers.\n- `idempotent_replay`: `True` when the dispatcher returned this envelope\n  from the idempotency cache (the underlying command did NOT execute\n  again). `False` on every fresh execution. Clients can use this to\n  distinguish \"my retry succeeded\" from \"the server re-ran the command\"\n  without having to track their own request identity. The metrics\n  decorator also reads this attribute to suppress business-event counter\n  increments on replays so dashboards stay honest."},"OrgDetailResponse":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"org_type":{"$ref":"#/components/schemas/OrgType"},"user_role":{"$ref":"#/components/schemas/OrgRole"},"members":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Members"},"graphs":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Graphs"},"limits":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Limits"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","name","org_type","user_role","members","graphs","limits","created_at","updated_at"],"title":"OrgDetailResponse","description":"Detailed organization response."},"OrgLimitsResponse":{"properties":{"org_id":{"type":"string","title":"Org Id"},"max_graphs":{"type":"integer","title":"Max Graphs"},"current_usage":{"additionalProperties":true,"type":"object","title":"Current Usage"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings"},"can_create_graph":{"type":"boolean","title":"Can Create Graph"}},"type":"object","required":["org_id","max_graphs","current_usage","warnings","can_create_graph"],"title":"OrgLimitsResponse","description":"Organization limits response."},"OrgListResponse":{"properties":{"orgs":{"items":{"$ref":"#/components/schemas/OrgResponse"},"type":"array","title":"Orgs"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["orgs","total"],"title":"OrgListResponse","description":"List of organizations response."},"OrgMemberListResponse":{"properties":{"members":{"items":{"$ref":"#/components/schemas/OrgMemberResponse"},"type":"array","title":"Members"},"total":{"type":"integer","title":"Total"},"org_id":{"type":"string","title":"Org Id"}},"type":"object","required":["members","total","org_id"],"title":"OrgMemberListResponse","description":"List of organization members response."},"OrgMemberResponse":{"properties":{"user_id":{"type":"string","title":"User Id"},"name":{"type":"string","title":"Name"},"email":{"type":"string","title":"Email"},"role":{"$ref":"#/components/schemas/OrgRole"},"joined_at":{"type":"string","format":"date-time","title":"Joined At"},"is_active":{"type":"boolean","title":"Is Active"}},"type":"object","required":["user_id","name","email","role","joined_at","is_active"],"title":"OrgMemberResponse","description":"Organization member response."},"OrgResponse":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"org_type":{"$ref":"#/components/schemas/OrgType"},"role":{"$ref":"#/components/schemas/OrgRole"},"member_count":{"type":"integer","title":"Member Count"},"graph_count":{"type":"integer","title":"Graph Count"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"joined_at":{"type":"string","format":"date-time","title":"Joined At"}},"type":"object","required":["id","name","org_type","role","member_count","graph_count","created_at","joined_at"],"title":"OrgResponse","description":"Organization summary response."},"OrgRole":{"type":"string","enum":["owner","admin","member"],"title":"OrgRole"},"OrgType":{"type":"string","enum":["personal","team","enterprise"],"title":"OrgType"},"OrgUsageResponse":{"properties":{"org_id":{"type":"string","title":"Org Id"},"period_days":{"type":"integer","title":"Period Days"},"start_date":{"type":"string","format":"date-time","title":"Start Date"},"end_date":{"type":"string","format":"date-time","title":"End Date"},"summary":{"$ref":"#/components/schemas/OrgUsageSummary"},"graph_details":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Graph Details"},"daily_trend":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Daily Trend"}},"type":"object","required":["org_id","period_days","start_date","end_date","summary","graph_details","daily_trend"],"title":"OrgUsageResponse","description":"Organization usage response."},"OrgUsageSummary":{"properties":{"total_credits_used":{"type":"number","title":"Total Credits Used"},"total_ai_operations":{"type":"integer","title":"Total Ai Operations"},"total_storage_gb":{"type":"number","title":"Total Storage Gb"},"total_api_calls":{"type":"integer","title":"Total Api Calls"},"daily_avg_credits":{"type":"number","title":"Daily Avg Credits"},"daily_avg_api_calls":{"type":"number","title":"Daily Avg Api Calls"},"projected_monthly_credits":{"type":"number","title":"Projected Monthly Credits"},"projected_monthly_api_calls":{"type":"integer","title":"Projected Monthly Api Calls"},"credits_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Credits Limit"},"api_calls_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Api Calls Limit"},"storage_limit_gb":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Storage Limit Gb"}},"type":"object","required":["total_credits_used","total_ai_operations","total_storage_gb","total_api_calls","daily_avg_credits","daily_avg_api_calls","projected_monthly_credits","projected_monthly_api_calls","credits_limit","api_calls_limit","storage_limit_gb"],"title":"OrgUsageSummary","description":"Organization usage summary."},"PasswordCheckRequest":{"properties":{"password":{"type":"string","title":"Password","description":"Password to check"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"User email for personalization checks"}},"type":"object","required":["password"],"title":"PasswordCheckRequest","description":"Password strength check request model."},"PasswordCheckResponse":{"properties":{"is_valid":{"type":"boolean","title":"Is Valid","description":"Whether password meets requirements"},"strength":{"type":"string","title":"Strength","description":"Password strength level"},"score":{"type":"integer","title":"Score","description":"Password strength score (0-100)"},"errors":{"items":{"type":"string"},"type":"array","title":"Errors","description":"Validation errors"},"suggestions":{"items":{"type":"string"},"type":"array","title":"Suggestions","description":"Improvement suggestions"},"character_types":{"additionalProperties":{"type":"boolean"},"type":"object","title":"Character Types","description":"Character type analysis"}},"type":"object","required":["is_valid","strength","score","errors","suggestions","character_types"],"title":"PasswordCheckResponse","description":"Password strength check response model."},"PasswordPolicyResponse":{"properties":{"policy":{"additionalProperties":true,"type":"object","title":"Policy","description":"Current password policy requirements"}},"type":"object","required":["policy"],"title":"PasswordPolicyResponse","description":"Password policy response model."},"PaymentMethod":{"properties":{"id":{"type":"string","title":"Id","description":"Payment method ID"},"type":{"type":"string","title":"Type","description":"Payment method type (card, bank_account, etc.)"},"brand":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand","description":"Card brand (visa, mastercard, etc.)"},"last4":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last4","description":"Last 4 digits of the card or account number"},"exp_month":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Exp Month","description":"Expiration month of the card"},"exp_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Exp Year","description":"Expiration year of the card"},"is_default":{"type":"boolean","title":"Is Default","description":"Whether this is the default payment method"}},"type":"object","required":["id","type","is_default"],"title":"PaymentMethod","description":"Payment method information."},"PerformanceInsights":{"properties":{"analysis_period_days":{"type":"integer","title":"Analysis Period Days","description":"Analysis period in days"},"total_operations":{"type":"integer","title":"Total Operations","description":"Total operations analyzed"},"operation_stats":{"additionalProperties":true,"type":"object","title":"Operation Stats","description":"Performance stats by operation type"},"slow_queries":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Slow Queries","description":"Top slow queries (over 5 seconds)"},"performance_score":{"type":"integer","title":"Performance Score","description":"Performance score (0-100)"}},"type":"object","required":["analysis_period_days","total_operations","operation_stats","slow_queries","performance_score"],"title":"PerformanceInsights","description":"Performance analytics."},"PortalSessionResponse":{"properties":{"portal_url":{"type":"string","title":"Portal Url","description":"Stripe Customer Portal URL where user can manage payment methods"}},"type":"object","required":["portal_url"],"title":"PortalSessionResponse","description":"Response for customer portal session creation."},"QueryLimits":{"properties":{"max_timeout_seconds":{"type":"integer","title":"Max Timeout Seconds","description":"Maximum query timeout in seconds"},"chunk_size":{"type":"integer","title":"Chunk Size","description":"Maximum chunk size for result streaming"},"max_rows_per_query":{"type":"integer","title":"Max Rows Per Query","description":"Maximum rows returned per query"},"concurrent_queries":{"type":"integer","title":"Concurrent Queries","description":"Maximum concurrent queries allowed"}},"type":"object","required":["max_timeout_seconds","chunk_size","max_rows_per_query","concurrent_queries"],"title":"QueryLimits","description":"Query operation limits."},"RateLimits":{"properties":{"requests_per_minute":{"type":"integer","title":"Requests Per Minute","description":"Requests per minute limit"},"requests_per_hour":{"type":"integer","title":"Requests Per Hour","description":"Requests per hour limit"},"burst_capacity":{"type":"integer","title":"Burst Capacity","description":"Burst capacity for short spikes"}},"type":"object","required":["requests_per_minute","requests_per_hour","burst_capacity"],"title":"RateLimits","description":"API rate limits."},"RegisterRequest":{"properties":{"name":{"type":"string","maxLength":100,"minLength":1,"title":"Name","description":"User's display name"},"email":{"type":"string","format":"email","title":"Email","description":"User's email address"},"password":{"type":"string","maxLength":128,"minLength":12,"title":"Password","description":"User's password (must meet security requirements)"},"captcha_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Captcha Token","description":"CAPTCHA verification token (required in production)"}},"type":"object","required":["name","email","password"],"title":"RegisterRequest","description":"Registration request model."},"RepositoryInfo":{"properties":{"type":{"type":"string","title":"Type","description":"Repository type identifier"},"name":{"type":"string","title":"Name","description":"Repository name"},"description":{"type":"string","title":"Description","description":"Repository description"},"enabled":{"type":"boolean","title":"Enabled","description":"Whether repository is enabled"},"coming_soon":{"type":"boolean","title":"Coming Soon","description":"Whether repository is coming soon"},"plans":{"items":{"$ref":"#/components/schemas/OfferingRepositoryPlan"},"type":"array","title":"Plans","description":"Available plans"}},"type":"object","required":["type","name","description","enabled","coming_soon","plans"],"title":"RepositoryInfo","description":"Information about a shared repository."},"RepositorySubscriptions":{"properties":{"description":{"type":"string","title":"Description","description":"Description of repository subscriptions"},"pricing_model":{"type":"string","title":"Pricing Model","description":"Pricing model type (per_graph or per_organization)"},"repositories":{"items":{"$ref":"#/components/schemas/RepositoryInfo"},"type":"array","title":"Repositories","description":"Available repositories"},"notes":{"items":{"type":"string"},"type":"array","title":"Notes","description":"Important notes"}},"type":"object","required":["description","pricing_model","repositories","notes"],"title":"RepositorySubscriptions","description":"Repository subscription offerings.\n\nRepository subscriptions are per-organization, not per-graph. All members\nof an organization share access to subscribed repositories."},"ResetPasswordRequest":{"properties":{"token":{"type":"string","title":"Token","description":"Password reset token from email link"},"new_password":{"type":"string","maxLength":128,"minLength":12,"title":"New Password","description":"New password (must meet security requirements)"}},"type":"object","required":["token","new_password"],"title":"ResetPasswordRequest","description":"Reset password request model."},"ResetPasswordValidateResponse":{"properties":{"valid":{"type":"boolean","title":"Valid","description":"Whether the token is valid"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Masked email address if token is valid"}},"type":"object","required":["valid"],"title":"ResetPasswordValidateResponse","description":"Password reset token validation response model."},"ResponseMode":{"type":"string","enum":["auto","sync","async","stream"],"title":"ResponseMode","description":"Response modes for execution."},"SSOCompleteRequest":{"properties":{"session_id":{"type":"string","title":"Session Id","description":"Temporary session ID from secure handoff"}},"type":"object","required":["session_id"],"title":"SSOCompleteRequest","description":"SSO completion request model."},"SSOExchangeRequest":{"properties":{"token":{"type":"string","title":"Token","description":"Temporary SSO token"},"target_app":{"type":"string","title":"Target App","description":"Target application identifier"},"return_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Return Url","description":"Optional return URL after authentication"}},"type":"object","required":["token","target_app"],"title":"SSOExchangeRequest","description":"SSO token exchange request model."},"SSOExchangeResponse":{"properties":{"session_id":{"type":"string","title":"Session Id","description":"Temporary session ID for secure handoff"},"redirect_url":{"type":"string","title":"Redirect Url","description":"URL to redirect to for authentication"},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"Session expiration time"}},"type":"object","required":["session_id","redirect_url","expires_at"],"title":"SSOExchangeResponse","description":"SSO token exchange response model."},"SSOTokenResponse":{"properties":{"token":{"type":"string","title":"Token","description":"Temporary SSO token for cross-app authentication"},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"Token expiration time"},"apps":{"items":{"type":"string"},"type":"array","title":"Apps","description":"Available apps for this user"}},"type":"object","required":["token","expires_at","apps"],"title":"SSOTokenResponse","description":"SSO token response model."},"SchemaExportResponse":{"properties":{"graph_id":{"type":"string","title":"Graph Id","description":"Graph ID","examples":["sec","kg1a2b3c4d5"]},"schema_definition":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"string"}],"title":"Schema Definition","description":"Exported schema definition (format depends on 'format' parameter)","examples":[{"description":"Schema for SEC financial data analysis","name":"financial_analysis_schema","nodes":[{"name":"Company","properties":[{"name":"cik","type":"STRING","is_primary_key":true},{"name":"name","type":"STRING","is_required":true},{"name":"ticker","type":"STRING"},{"name":"market_cap","type":"INT64"},{"name":"sector","type":"STRING"}]},{"name":"Filing","properties":[{"name":"accession_number","type":"STRING","is_primary_key":true},{"name":"form_type","type":"STRING","is_required":true},{"name":"filing_date","type":"DATE"},{"name":"fiscal_year","type":"INT32"}]}],"relationships":[{"from_node":"Company","name":"FILED","properties":[{"name":"filing_count","type":"INT32"}],"to_node":"Filing"}],"type":"custom","version":"1.0.0"},"name: financial_analysis_schema\nversion: '1.0.0'\ntype: custom\ndescription: Schema for SEC financial data analysis\nnodes:\n  - name: Company\n    properties:\n      - name: cik\n        type: STRING\n        is_primary_key: true\n      - name: name\n        type: STRING\n        is_required: true\n      - name: ticker\n        type: STRING\n      - name: market_cap\n        type: INT64\nrelationships:\n  - name: FILED\n    from_node: Company\n    to_node: Filing","CREATE NODE TABLE Company (\n  cik STRING PRIMARY KEY,\n  name STRING NOT NULL,\n  ticker STRING,\n  market_cap INT64,\n  sector STRING\n);\n\nCREATE NODE TABLE Filing (\n  accession_number STRING PRIMARY KEY,\n  form_type STRING NOT NULL,\n  filing_date DATE,\n  fiscal_year INT32\n);\n\nCREATE REL TABLE FILED (\n  FROM Company TO Filing,\n  filing_count INT32\n);"]},"format":{"type":"string","title":"Format","description":"Export format used","examples":["json","yaml","cypher"]},"exported_at":{"type":"string","title":"Exported At","description":"Export timestamp","examples":["2025-10-29T10:30:00Z"]},"data_stats":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Data Stats","description":"Data statistics if requested (only when include_data_stats=true)","examples":[{"node_counts":{"Company":8500,"Filing":125000,"Industry":1200},"node_labels_count":4,"node_properties_count":12,"relationship_types_count":3,"total_nodes":134700}]}},"type":"object","required":["graph_id","schema_definition","format","exported_at"],"title":"SchemaExportResponse","description":"Response model for schema export."},"SchemaInfoResponse":{"properties":{"graph_id":{"type":"string","title":"Graph Id","description":"Graph database identifier"},"schema":{"additionalProperties":true,"type":"object","title":"Schema","description":"Runtime schema information showing actual database structure"}},"type":"object","required":["graph_id","schema"],"title":"SchemaInfoResponse","description":"Response model for runtime schema introspection.\n\nThis model represents the actual current state of the graph database,\nshowing what node labels, relationship types, and properties exist right now.","examples":[{"description":"Runtime schema from SEC shared repository showing XBRL structures","summary":"SEC shared repository schema","value":{"graph_id":"sec","schema":{"node_labels":["Entity","Report","Fact","Element","Period","Unit","Dimension","Taxonomy","Structure","Association"],"node_properties":{"Entity":{"cik":"STRING","entity_type":"STRING","fiscal_year_end":"STRING","industry":"STRING","name":"STRING","state_of_incorporation":"STRING","ticker":"STRING"},"Fact":{"decimals":"INT64","fact_type":"STRING","numeric_value":"DOUBLE"},"Report":{"accession_number":"STRING","filing_date":"STRING","form":"STRING","name":"STRING","report_date":"STRING"}},"relationship_types":["ENTITY_HAS_REPORT","REPORT_HAS_FACT","FACT_HAS_ELEMENT","FACT_HAS_PERIOD","FACT_HAS_UNIT","FACT_HAS_DIMENSION","REPORT_USES_TAXONOMY","STRUCTURE_HAS_TAXONOMY","STRUCTURE_HAS_ASSOCIATION","ASSOCIATION_HAS_FROM_ELEMENT","ASSOCIATION_HAS_TO_ELEMENT"]}}},{"description":"Runtime schema for accounting graph showing double-entry bookkeeping structure","summary":"Accounting graph schema","value":{"graph_id":"kg1a2b3c4d5","schema":{"node_labels":["Transaction","LineItem","Element","Report","Entity","Fact","Period","Unit"],"node_properties":{"Element":{"balance":"STRING","classification":"STRING","name":"STRING"},"LineItem":{"credit_amount":"DOUBLE","debit_amount":"DOUBLE"},"Transaction":{"date":"STRING","description":"STRING","type":"STRING"}},"relationship_types":["TRANSACTION_HAS_ENTRY","ENTRY_HAS_LINE_ITEM","LINE_ITEM_RELATES_TO_ELEMENT","ENTITY_HAS_REPORT","REPORT_HAS_FACT","FACT_HAS_ELEMENT","FACT_HAS_PERIOD","FACT_HAS_UNIT"]}}},{"description":"Runtime schema from custom graph showing people, companies, and projects","summary":"Custom graph schema","value":{"graph_id":"kg9f8e7d6c5","schema":{"node_labels":["Person","Company","Project"],"node_properties":{"Company":{"identifier":"STRING","industry":"STRING","location":"STRING","name":"STRING"},"Person":{"identifier":"STRING","interests":"STRING","name":"STRING","title":"STRING"},"Project":{"budget":"DOUBLE","name":"STRING","status":"STRING"}},"relationship_types":["PERSON_WORKS_FOR_COMPANY","PERSON_WORKS_ON_PROJECT","COMPANY_SPONSORS_PROJECT"]}}},{"description":"Runtime schema from a newly created graph with no data yet","summary":"Empty graph schema","value":{"graph_id":"kg2x3y4z5a6","schema":{"node_labels":[],"node_properties":{},"relationship_types":[]}}}]},"SchemaValidationRequest":{"properties":{"schema_definition":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"string"}],"title":"Schema Definition","description":"Schema definition as JSON dict or JSON/YAML string","examples":[{"description":"Schema for financial data with companies and filings","name":"financial_analysis","nodes":[{"name":"Company","properties":[{"name":"cik","type":"STRING","is_primary_key":true},{"name":"name","type":"STRING","is_required":true},{"name":"ticker","type":"STRING"},{"name":"market_cap","type":"INT64"}]},{"name":"Filing","properties":[{"name":"accession_number","type":"STRING","is_primary_key":true},{"name":"form_type","type":"STRING","is_required":true},{"name":"filing_date","type":"DATE"}]}],"relationships":[{"from_node":"Company","name":"FILED","properties":[{"name":"filing_count","type":"INT32"}],"to_node":"Filing"}],"version":"1.0.0"},"name: inventory_management\nversion: '1.0.0'\ndescription: Inventory tracking schema\nnodes:\n  - name: Product\n    properties:\n      - name: sku\n        type: STRING\n        is_primary_key: true\n      - name: name\n        type: STRING\n        is_required: true\n      - name: quantity\n        type: INT32\n  - name: Warehouse\n    properties:\n      - name: location_id\n        type: STRING\n        is_primary_key: true\n      - name: name\n        type: STRING\nrelationships:\n  - name: STORED_IN\n    from_node: Product\n    to_node: Warehouse",{"name":"invalid_schema_example","nodes":[{"name":"Company","properties":[{"name":"name","type":"INVALID_TYPE"}]}],"relationships":[{"from_node":"Company","name":"RELATED_TO","to_node":"NonExistentNode"}],"version":"1.0.0"}]},"format":{"type":"string","title":"Format","description":"Schema format: json, yaml, or dict","default":"json","examples":["json","yaml","dict"]},"check_compatibility":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Check Compatibility","description":"List of existing schema extensions to check compatibility with","examples":[null,["roboledger"],["sec_base","industry"]]}},"type":"object","required":["schema_definition"],"title":"SchemaValidationRequest","description":"Request model for schema validation."},"SchemaValidationResponse":{"properties":{"valid":{"type":"boolean","title":"Valid","description":"Whether the schema is valid","examples":[true,false,true]},"message":{"type":"string","title":"Message","description":"Validation message","examples":["Schema is valid","Schema validation failed","Schema is valid with 2 warning(s)"]},"errors":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Errors","description":"List of validation errors (only present when valid=false)","examples":[null,["Invalid data type 'INVALID_TYPE' for property 'name' in node 'Company'","Relationship 'RELATED_TO' references non-existent node 'NonExistentNode'","Node 'Company' has no primary key defined"]]},"warnings":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Warnings","description":"List of validation warnings (schema is still valid but has potential issues)","examples":[null,["Isolated nodes with no relationships: ['Warehouse', 'Location']","Schema has no relationships defined","Property 'deprecated_field' uses deprecated type DECIMAL"]]},"stats":{"anyOf":[{"additionalProperties":{"type":"integer"},"type":"object"},{"type":"null"}],"title":"Stats","description":"Schema statistics (only present when valid=true)","examples":[{"nodes":2,"primary_keys":2,"relationships":1,"total_properties":7},{"nodes":5,"primary_keys":5,"relationships":8,"total_properties":32}]},"compatibility":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Compatibility","description":"Compatibility check results (only when check_compatibility specified)","examples":[{"checked_extensions":["roboledger"],"compatible":true,"conflicts":[]},{"checked_extensions":["roboledger","sec_base"],"compatible":false,"conflicts":["Node 'Transaction' conflicts with existing definition in 'roboledger'","Property 'amount' type mismatch: INT64 vs DOUBLE"]}]}},"type":"object","required":["valid","message"],"title":"SchemaValidationResponse","description":"Response model for schema validation."},"SearchHit":{"properties":{"document_id":{"type":"string","title":"Document Id"},"score":{"type":"number","title":"Score"},"source_type":{"type":"string","title":"Source Type"},"parent_document_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Document Id"},"entity_ticker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Ticker"},"entity_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Name"},"section_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Section Label"},"section_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Section Id"},"element_qname":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Element Qname"},"filing_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filing Date"},"fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fiscal Year"},"form_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Form Type"},"xbrl_elements":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Xbrl Elements"},"snippet":{"type":"string","title":"Snippet"},"content_length":{"type":"integer","title":"Content Length","default":0},"content_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Url"},"document_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Title"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags"},"folder":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Folder"}},"type":"object","required":["document_id","score","source_type","snippet"],"title":"SearchHit","description":"A single search result with snippet."},"SearchRequest":{"properties":{"query":{"type":"string","maxLength":500,"minLength":1,"title":"Query","description":"Search query"},"entity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity","description":"Filter by ticker, CIK, or entity name"},"form_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Form Type","description":"Filter by SEC form type (10-K, 10-Q)"},"section":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Section","description":"Filter by section ID (item_1, item_1a, item_7, etc.)"},"element":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Element","description":"Filter by XBRL element qname (e.g., us-gaap:Goodwill)"},"source_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Type","description":"Filter by source type (xbrl_textblock, narrative_section, ixbrl_disclosure, uploaded_doc, memory)"},"fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fiscal Year","description":"Filter by fiscal year"},"date_from":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"title":"Date From","description":"Filter filings on or after date (YYYY-MM-DD)"},"date_to":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"title":"Date To","description":"Filter filings on or before date (YYYY-MM-DD)"},"semantic":{"type":"boolean","title":"Semantic","description":"Enable hybrid semantic search (BM25 + KNN). Default is BM25-only for speed.","default":false},"size":{"type":"integer","maximum":50.0,"minimum":1.0,"title":"Size","description":"Max results to return","default":10},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Pagination offset","default":0}},"type":"object","required":["query"],"title":"SearchRequest","description":"Request model for document search."},"SearchResponse":{"properties":{"total":{"type":"integer","title":"Total"},"hits":{"items":{"$ref":"#/components/schemas/SearchHit"},"type":"array","title":"Hits"},"query":{"type":"string","title":"Query"},"graph_id":{"type":"string","title":"Graph Id"}},"type":"object","required":["total","hits","query","graph_id"],"title":"SearchResponse","description":"Response model for document search."},"SelectionCriteria":{"properties":{"min_confidence":{"type":"number","title":"Min Confidence","description":"Minimum confidence score","default":0.3},"required_capabilities":{"items":{"type":"string"},"type":"array","title":"Required Capabilities","description":"Required agent capabilities"},"preferred_mode":{"anyOf":[{"$ref":"#/components/schemas/AgentMode"},{"type":"null"}],"description":"Preferred execution mode"},"max_response_time":{"type":"number","title":"Max Response Time","description":"Maximum response time in seconds","default":60.0},"excluded_agents":{"items":{"type":"string"},"type":"array","title":"Excluded Agents","description":"Agents to exclude from selection"}},"type":"object","title":"SelectionCriteria","description":"Criteria for agent selection."},"ServiceOfferingSummary":{"properties":{"total_graph_tiers":{"type":"integer","title":"Total Graph Tiers","description":"Total number of graph tiers"},"total_repositories":{"type":"integer","title":"Total Repositories","description":"Total number of repositories"},"enabled_repositories":{"type":"integer","title":"Enabled Repositories","description":"Number of enabled repositories"},"coming_soon_repositories":{"type":"integer","title":"Coming Soon Repositories","description":"Number of coming soon repositories"}},"type":"object","required":["total_graph_tiers","total_repositories","enabled_repositories","coming_soon_repositories"],"title":"ServiceOfferingSummary","description":"Summary of service offerings."},"ServiceOfferingsResponse":{"properties":{"billing_enabled":{"type":"boolean","title":"Billing Enabled","description":"Whether billing and payments are enabled"},"graph_subscriptions":{"$ref":"#/components/schemas/GraphSubscriptions","description":"Graph subscription offerings"},"repository_subscriptions":{"$ref":"#/components/schemas/RepositorySubscriptions","description":"Repository subscription offerings"},"operation_costs":{"$ref":"#/components/schemas/OperationCosts","description":"Operation cost information"},"summary":{"$ref":"#/components/schemas/ServiceOfferingSummary","description":"Summary information"}},"type":"object","required":["billing_enabled","graph_subscriptions","repository_subscriptions","operation_costs","summary"],"title":"ServiceOfferingsResponse","description":"Complete service offerings response."},"StorageLimits":{"properties":{"current_usage_gb":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Current Usage Gb","description":"Current storage usage in GB"},"max_storage_gb":{"type":"number","title":"Max Storage Gb","description":"Maximum storage limit in GB"},"approaching_limit":{"type":"boolean","title":"Approaching Limit","description":"Whether approaching storage limit (>80%)"}},"type":"object","required":["max_storage_gb","approaching_limit"],"title":"StorageLimits","description":"Storage limits information."},"StorageSummary":{"properties":{"graph_tier":{"type":"string","title":"Graph Tier","description":"Subscription tier"},"avg_storage_gb":{"type":"number","title":"Avg Storage Gb","description":"Average storage in GB"},"max_storage_gb":{"type":"number","title":"Max Storage Gb","description":"Peak storage in GB"},"min_storage_gb":{"type":"number","title":"Min Storage Gb","description":"Minimum storage in GB"},"total_gb_hours":{"type":"number","title":"Total Gb Hours","description":"Total GB-hours for billing"},"measurement_count":{"type":"integer","title":"Measurement Count","description":"Number of measurements taken"}},"type":"object","required":["graph_tier","avg_storage_gb","max_storage_gb","min_storage_gb","total_gb_hours","measurement_count"],"title":"StorageSummary","description":"Storage usage summary."},"SubgraphQuotaResponse":{"properties":{"parent_graph_id":{"type":"string","title":"Parent Graph Id","description":"Parent graph identifier"},"tier":{"type":"string","title":"Tier","description":"Graph tier","examples":["ladybug-large","ladybug-xlarge"]},"current_count":{"type":"integer","minimum":0.0,"title":"Current Count","description":"Current number of subgraphs"},"max_allowed":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Allowed","description":"Maximum allowed subgraphs (None = unlimited)"},"remaining":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Remaining","description":"Remaining subgraphs that can be created"},"total_size_mb":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Size Mb","description":"Total size of all subgraphs"},"max_size_mb":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max Size Mb","description":"Maximum allowed total size"}},"type":"object","required":["parent_graph_id","tier","current_count"],"title":"SubgraphQuotaResponse","description":"Response model for subgraph quota information."},"SubgraphResponse":{"properties":{"graph_id":{"type":"string","title":"Graph Id","description":"Full subgraph identifier (e.g., kg123_dev)","examples":["kg5f2e5e0da65d45d69645_dev"]},"parent_graph_id":{"type":"string","title":"Parent Graph Id","description":"Parent graph identifier","examples":["kg5f2e5e0da65d45d69645"]},"subgraph_index":{"type":"integer","title":"Subgraph Index","description":"Numeric index of the subgraph","examples":[1,2,3]},"subgraph_name":{"type":"string","title":"Subgraph Name","description":"Alphanumeric name of the subgraph","examples":["dev","staging","prod"]},"display_name":{"type":"string","title":"Display Name","description":"Human-readable display name","examples":["Development Environment"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Description of the subgraph's purpose"},"subgraph_type":{"$ref":"#/components/schemas/SubgraphType","description":"Type of subgraph"},"status":{"type":"string","title":"Status","description":"Current status of the subgraph","examples":["active","creating","deleting","failed"]},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the subgraph was created"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When the subgraph was last updated"},"size_mb":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Size Mb","description":"Size of the subgraph database in megabytes"},"node_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Node Count","description":"Number of nodes in the subgraph"},"edge_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Edge Count","description":"Number of edges in the subgraph"},"last_accessed":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Accessed","description":"When the subgraph was last accessed"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Additional metadata for the subgraph"}},"type":"object","required":["graph_id","parent_graph_id","subgraph_index","subgraph_name","display_name","subgraph_type","status","created_at","updated_at"],"title":"SubgraphResponse","description":"Response model for a subgraph."},"SubgraphSummary":{"properties":{"graph_id":{"type":"string","title":"Graph Id","description":"Full subgraph identifier","examples":["kg5f2e5e0da65d45d69645_dev"]},"subgraph_name":{"type":"string","title":"Subgraph Name","description":"Alphanumeric name","examples":["dev"]},"display_name":{"type":"string","title":"Display Name","description":"Human-readable name","examples":["Development Environment"]},"subgraph_type":{"$ref":"#/components/schemas/SubgraphType","description":"Type of subgraph"},"status":{"type":"string","title":"Status","description":"Current status","examples":["active"]},"size_mb":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Size Mb","description":"Size in megabytes"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp"},"last_accessed":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Accessed","description":"Last access timestamp"}},"type":"object","required":["graph_id","subgraph_name","display_name","subgraph_type","status","created_at"],"title":"SubgraphSummary","description":"Summary model for listing subgraphs."},"SubgraphType":{"type":"string","enum":["static","temporal","versioned","memory"],"title":"SubgraphType","description":"Types of subgraphs."},"SuccessResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Indicates the operation completed successfully","default":true},"message":{"type":"string","title":"Message","description":"Human-readable success message","examples":["Operation completed successfully"]},"data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Data","description":"Optional additional data related to the operation"}},"type":"object","required":["message"],"title":"SuccessResponse","description":"Standard success response for operations without specific return data.","example":{"data":{"deleted_count":1},"message":"Resource deleted successfully","success":true}},"TableInfo":{"properties":{"table_name":{"type":"string","title":"Table Name","description":"Table name"},"row_count":{"type":"integer","title":"Row Count","description":"Approximate row count"},"file_count":{"type":"integer","title":"File Count","description":"Number of files","default":0},"total_size_bytes":{"type":"integer","title":"Total Size Bytes","description":"Total size in bytes","default":0},"s3_location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"S3 Location","description":"S3 location for external tables"}},"type":"object","required":["table_name","row_count"],"title":"TableInfo"},"TableListResponse":{"properties":{"tables":{"items":{"$ref":"#/components/schemas/TableInfo"},"type":"array","title":"Tables","description":"List of tables"},"total_count":{"type":"integer","title":"Total Count","description":"Total number of tables"}},"type":"object","required":["tables","total_count"],"title":"TableListResponse"},"TableQueryRequest":{"properties":{"sql":{"type":"string","title":"Sql","description":"SQL query to execute on staging tables. Use ? placeholders or $param_name for dynamic values to prevent SQL injection.","examples":["SELECT * FROM Entity WHERE entity_type = ? LIMIT ?","SELECT COUNT(*) FROM Transaction WHERE amount > ? AND date >= ?","SELECT * FROM Entity LIMIT 10"]},"parameters":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Parameters","description":"Query parameters for safe value substitution. ALWAYS use parameters instead of string concatenation.","examples":[["Company",100],[1000,"2024-01-01"],null]}},"additionalProperties":false,"type":"object","required":["sql"],"title":"TableQueryRequest","examples":[{"parameters":["Company",100],"sql":"SELECT * FROM Entity WHERE entity_type = ? LIMIT ?"},{"parameters":[1000,"2024-01-01"],"sql":"SELECT COUNT(*) FROM Transaction WHERE amount > ? AND date >= ?"},{"sql":"SELECT * FROM Entity LIMIT 10"}]},"TableQueryResponse":{"properties":{"columns":{"items":{"type":"string"},"type":"array","title":"Columns","description":"Column names"},"rows":{"items":{"items":{},"type":"array"},"type":"array","title":"Rows","description":"Query results"},"row_count":{"type":"integer","title":"Row Count","description":"Number of rows returned"},"execution_time_ms":{"type":"number","title":"Execution Time Ms","description":"Query execution time"}},"type":"object","required":["columns","rows","row_count","execution_time_ms"],"title":"TableQueryResponse"},"TierCapacity":{"properties":{"tier":{"type":"string","title":"Tier","description":"Tier identifier (e.g. ladybug-standard)"},"display_name":{"type":"string","title":"Display Name","description":"Human-readable tier name"},"status":{"type":"string","title":"Status","description":"Capacity status: ready, scalable, or at_capacity"},"message":{"type":"string","title":"Message","description":"Human-readable status message for frontend display"}},"type":"object","required":["tier","display_name","status","message"],"title":"TierCapacity","description":"Capacity status for a single tier."},"TokenPricing":{"properties":{"input_per_1k_tokens":{"type":"number","title":"Input Per 1K Tokens","description":"Credits per 1K input tokens"},"output_per_1k_tokens":{"type":"number","title":"Output Per 1K Tokens","description":"Credits per 1K output tokens"}},"type":"object","required":["input_per_1k_tokens","output_per_1k_tokens"],"title":"TokenPricing","description":"AI token pricing for a specific model."},"TransactionSummaryResponse":{"properties":{"operation_type":{"type":"string","title":"Operation Type"},"total_amount":{"type":"number","title":"Total Amount"},"transaction_count":{"type":"integer","title":"Transaction Count"},"average_amount":{"type":"number","title":"Average Amount"},"first_transaction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Transaction"},"last_transaction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Transaction"}},"type":"object","required":["operation_type","total_amount","transaction_count","average_amount"],"title":"TransactionSummaryResponse","description":"Summary of transactions by operation type."},"UpcomingInvoice":{"properties":{"amount_due":{"type":"integer","title":"Amount Due","description":"Estimated amount due in cents"},"currency":{"type":"string","title":"Currency","description":"Currency code"},"period_start":{"type":"string","title":"Period Start","description":"Billing period start"},"period_end":{"type":"string","title":"Period End","description":"Billing period end"},"line_items":{"items":{"$ref":"#/components/schemas/InvoiceLineItem"},"type":"array","title":"Line Items","description":"Estimated line items"},"subscription_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subscription Id","description":"Associated subscription ID"}},"type":"object","required":["amount_due","currency","period_start","period_end","line_items"],"title":"UpcomingInvoice","description":"Upcoming invoice preview."},"UpdateAPIKeyRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":100,"minLength":1},{"type":"null"}],"title":"Name","description":"New name for the API key"},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description","description":"New description"}},"type":"object","title":"UpdateAPIKeyRequest","description":"Request model for updating an API key."},"UpdateMemberRoleRequest":{"properties":{"role":{"$ref":"#/components/schemas/OrgRole"}},"type":"object","required":["role"],"title":"UpdateMemberRoleRequest","description":"Request to update a member's role."},"UpdateOrgRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":100,"minLength":1},{"type":"null"}],"title":"Name"},"org_type":{"anyOf":[{"$ref":"#/components/schemas/OrgType"},{"type":"null"}]}},"type":"object","title":"UpdateOrgRequest","description":"Request to update organization details."},"UpdatePasswordRequest":{"properties":{"current_password":{"type":"string","minLength":8,"title":"Current Password","description":"Current password"},"new_password":{"type":"string","minLength":8,"title":"New Password","description":"New password"},"confirm_password":{"type":"string","minLength":8,"title":"Confirm Password","description":"Confirm new password"}},"type":"object","required":["current_password","new_password","confirm_password"],"title":"UpdatePasswordRequest","description":"Request model for updating user password."},"UpdateUserRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":100,"minLength":1},{"type":"null"}],"title":"Name","description":"User's display name"},"email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"title":"Email","description":"User's email address"}},"type":"object","title":"UpdateUserRequest","description":"Request model for updating user profile."},"UpgradeSubscriptionRequest":{"properties":{"new_plan_name":{"type":"string","title":"New Plan Name","description":"New plan name to change to","examples":["advanced"]}},"type":"object","required":["new_plan_name"],"title":"UpgradeSubscriptionRequest","description":"Request to upgrade a subscription."},"UserGraphsResponse":{"properties":{"graphs":{"items":{"$ref":"#/components/schemas/GraphInfo"},"type":"array","title":"Graphs","description":"List of accessible graphs"},"selectedGraphId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Selectedgraphid","description":"Currently selected graph ID","examples":["kg1a2b3c4d5",null]}},"type":"object","required":["graphs"],"title":"UserGraphsResponse","description":"User graphs response model.","examples":[{"graphs":[{"createdAt":"2024-01-15T10:00:00Z","graphId":"kg1a2b3c4d5","graphName":"Acme Consulting LLC","isSelected":true,"role":"admin"},{"createdAt":"2024-02-20T14:30:00Z","graphId":"kg9z8y7x6w5","graphName":"TechCorp Enterprises","isSelected":false,"role":"member"}],"selectedGraphId":"kg1a2b3c4d5"},{"graphs":[]}]},"UserResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Unique identifier for the user"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"User's display name"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"User's email address"},"email_verified":{"type":"boolean","title":"Email Verified","description":"Whether user's email is verified","default":false},"accounts":{"items":{"$ref":"#/components/schemas/AccountInfo"},"type":"array","title":"Accounts","description":"User's authentication accounts"}},"type":"object","required":["id"],"title":"UserResponse","description":"User information response model.","example":{"accounts":[{"provider":"github","provider_account_id":"12345","provider_type":"oauth"},{"provider":"google","provider_account_id":"67890","provider_type":"oauth"}],"email":"john@example.com","email_verified":true,"id":"user-123","name":"johndoe"}},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ViewAxisConfig":{"properties":{"type":{"type":"string","title":"Type","description":"Axis type: 'element', 'period', 'dimension', 'entity'"},"dimension_axis":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dimension Axis","description":"Dimension axis name for dimension-type axes"},"include_null_dimension":{"type":"boolean","title":"Include Null Dimension","description":"Include facts where this dimension is NULL (default: false)","default":false},"selected_members":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Selected Members","description":"Specific members to include (e.g., ['2024-12-31', '2023-12-31'])"},"member_order":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Member Order","description":"Explicit ordering of members (overrides default sort)"},"member_labels":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Member Labels","description":"Custom labels for members (e.g., {'2024-12-31': 'Current Year'})"},"element_order":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Element Order","description":"Element ordering for hierarchy display (e.g., ['us-gaap:Assets', 'us-gaap:Cash', ...])"},"element_labels":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Element Labels","description":"Custom labels for elements (e.g., {'us-gaap:Cash': 'Cash and Cash Equivalents'})"}},"type":"object","required":["type"],"title":"ViewAxisConfig"},"ViewConfig":{"properties":{"rows":{"items":{"$ref":"#/components/schemas/ViewAxisConfig"},"type":"array","title":"Rows","description":"Row axis configuration"},"columns":{"items":{"$ref":"#/components/schemas/ViewAxisConfig"},"type":"array","title":"Columns","description":"Column axis configuration"},"values":{"type":"string","title":"Values","description":"Field to use for values (default: numeric_value)","default":"numeric_value"},"aggregation_function":{"type":"string","title":"Aggregation Function","description":"Aggregation function: sum, average, count","default":"sum"},"fill_value":{"type":"number","title":"Fill Value","description":"Value to use for missing data","default":0.0}},"type":"object","title":"ViewConfig"},"OperationError":{"type":"object","description":"Error envelope returned by extensions operation endpoints. Shape aligns with FastAPI's default error detail plus an optional `operation_id` for audit correlation.","properties":{"detail":{"oneOf":[{"type":"string"},{"type":"object"}],"description":"Human-readable error detail or structured payload"},"operation_id":{"type":"string","description":"op_-prefixed ULID if the dispatcher minted one before the failure (async ops, idempotency conflicts, etc.)"}}}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key for authentication"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT bearer token"}}},"tags":[{"name":"Graphs","description":"🏗️ Graphs - Create and manage knowledge graph tenants"},{"name":"Query","description":"🔍 Graph queries - Execute Cypher queries against graph databases"},{"name":"MCP","description":"🔌 MCP - Model Context Protocol for AI interactions with graph data"},{"name":"Agent","description":"🤖 AI Agents - Intelligent AI agents for analyzing and managing graph data"},{"name":"Documents","description":"📑 Documents - Upload, list, and manage documents for search and analysis"},{"name":"Search","description":"🔎 Search - Full-text search across filing narratives, disclosures, and XBRL text content"},{"name":"Extensions: RoboLedger","description":"📒 RoboLedger operations - Named commands for accounting & reporting writes and analytical views"},{"name":"Materialize","description":"🔄 Materialize graph - Rebuild graph from DuckDB staging tables"},{"name":"Tables","description":"🗃️ Staging tables - SQL queries and data ingestion via DuckDB staging layer"},{"name":"Files","description":"📄 File management - Upload, track, and manage data files with multi-layer status"},{"name":"Subgraphs","description":"🌳 Subgraphs - Create and manage subgraph databases for AI memory and data isolation"},{"name":"Backup","description":"💾 Graph backup - Create, restore, and manage graph database backups"},{"name":"Schema","description":"📐 Schema management - Validate and manage custom graph schemas"},{"name":"Usage","description":"📊 Usage - Monitor usage, metrics, and system performance"},{"name":"Credits","description":"🪙 Credits - Manage credit-based usage and allocation"},{"name":"Subscriptions","description":"💳 Subscriptions - Manage graph & shared repository subscriptions"},{"name":"Graph Limits","description":"📏 Graph limits - Instance storage usage, per-operation limits, and tier configuration"},{"name":"Graph Health","description":"🩺 Graph health - Monitor graph database health and performance metrics"},{"name":"Graph Info","description":"ℹ️ Graph info - Get graph database information, statistics, and metadata"},{"name":"User","description":"👤 User management - Profile, settings, and account information"},{"name":"Org","description":"🏢 Organizations - Manage organizations and team collaboration"},{"name":"Org Members","description":"👥 Organization members - Manage team members, roles, and permissions"},{"name":"Org Usage","description":"📈 Organization usage - Track organization-wide usage, limits, and analytics"},{"name":"Billing","description":"🛒 Billing - Create and manage billing checkout sessions"},{"name":"Operations","description":"⏱️ Operation monitoring - Track SSE stream status and progress"},{"name":"Auth","description":"🔐 Authentication - Login, register, and access token management"},{"name":"Service Offerings","description":"🛍️ Service offerings - View available offers and pricing"},{"name":"Status","description":"❤️ Service status - API status and monitoring"}]}