KytheraDB -- API Reference
Complete API endpoint documentation grouped by module. All endpoints return JSON unless otherwise noted.
Base URL: http://localhost:8000
Authentication: Endpoints marked "Auth: Yes" require an Authorization: Bearer <token> header.
Table of Contents
- Health
- Auth
- Projects
- Connections
- Schema
- Data (CRUD)
- Graphs
- SQL Console
- Mass Patch
- Bridge
- Anonymization
- Seeds
- QA Templates
- Validation
- Performance
- Preflight
- GDPR
- Export
- Import
- Jobs
- Configuration
- Profiling
- Activity
- References
- Annotations
- Plans
- Teams
- Governance
Health
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| GET | /health | Health check | No | -- |
Auth
All auth routes are prefixed with /auth.
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| POST | /auth/register | Register a new user | No | -- |
| POST | /auth/login | Authenticate and get JWT token | No | -- |
| GET | /auth/me | Get current user profile | Yes | -- |
| GET | /auth/users | List all users | Yes | admin |
| PATCH | /auth/users/{user_id}/role | Update user role | Yes | admin |
| PATCH | /auth/users/{user_id}/plan | Update user plan | Yes | admin |
| PATCH | /auth/users/{user_id}/toggle-active | Toggle user active status | Yes | admin |
| POST | /auth/users/invite | Invite a new user | Yes | admin |
| PATCH | /auth/users/{user_id} | Update user details | Yes | admin |
| DELETE | /auth/users/{user_id} | Delete a user | Yes | admin |
| POST | /auth/users/{user_id}/reset-password | Reset user password | Yes | admin |
| GET | /auth/users/{user_id}/activity | Get user activity log | Yes | admin |
| GET | /auth/activity | Get platform activity log (paginated) | Yes | admin |
Projects
All project routes are prefixed with /projects.
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| POST | /projects/ | Create a new project | Yes | -- |
| GET | /projects/ | List user's projects | Yes | -- |
| GET | /projects/{project_id} | Get project details | Yes | -- |
| GET | /projects/{project_id}/check-access | Check user access to project | Yes | -- |
| PATCH | /projects/{project_id} | Update project | Yes | -- |
| DELETE | /projects/{project_id} | Delete project | Yes | -- |
Connections
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| POST | /connections/test | Test a connection config | Yes | -- |
| POST | /projects/{project_id}/connections | Create a connection | Yes | -- |
| GET | /projects/{project_id}/connections | List project connections | Yes | -- |
| GET | /connections/{connection_id} | Get connection details | Yes | -- |
| PATCH | /connections/{connection_id} | Update connection | Yes | -- |
| POST | /connections/{connection_id}/test | Test existing connection | Yes | -- |
| DELETE | /connections/{connection_id} | Delete connection | Yes | -- |
Schema
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| POST | /projects/{project_id}/schema | Introspect and snapshot schema | Yes | -- |
| GET | /projects/{project_id}/schema | Get latest schema snapshot | Yes | -- |
| GET | /projects/{project_id}/tables | List tables | Yes | -- |
| GET | /projects/{project_id}/tables/{table_name} | Get table details | Yes | -- |
| GET | /projects/{project_id}/tables/{table_name}/columns | Get table columns | Yes | -- |
| GET | /projects/{project_id}/schema/snapshots | List schema snapshots | Yes | -- |
| POST | /projects/{project_id}/health | Run schema health audit | Yes | pro |
| GET | /projects/{project_id}/schema/migration | Generate migration script | Yes | enterprise |
Data (CRUD)
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| GET | /projects/{project_id}/data/{table_name} | List rows (paginated) | Yes | -- |
| GET | /projects/{project_id}/data/{table_name}/form-schema | Get dynamic form schema | Yes | -- |
| GET | /projects/{project_id}/data/{table_name}/fk-options/{column_name} | Get FK dropdown options | Yes | -- |
| GET | /projects/{project_id}/data/{table_name}/{record_id}/360 | 360-degree entity view | Yes | -- |
| GET | /projects/{project_id}/data/{table_name}/{record_id} | Get single record | Yes | -- |
| POST | /projects/{project_id}/data/{table_name} | Create record | Yes | pro |
| PATCH | /projects/{project_id}/data/{table_name}/{record_id} | Update record | Yes | pro |
| DELETE | /projects/{project_id}/data/{table_name}/{record_id} | Delete record | Yes | pro |
Graphs
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| GET | /projects/{project_id}/graph | Get full relationship graph | Yes | -- |
| GET | /projects/{project_id}/graph/focus/{table_name} | Get focused graph for a table | Yes | -- |
| GET | /projects/{project_id}/dependencies | Get dependency order | Yes | -- |
SQL Console
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| POST | /projects/{project_id}/sql/analyze | Analyze SQL (parse, risk, guard rails) | Yes | -- |
| POST | /projects/{project_id}/sql/execute | Execute SQL statement | Yes | -- |
| POST | /projects/{project_id}/sql/preview | Preview query results (dry-run) | Yes | -- |
| POST | /projects/{project_id}/sql/explain | Run EXPLAIN on a query | Yes | -- |
Legacy playground endpoints:
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| POST | /projects/{project_id}/playground/execute | Execute SQL (legacy) | Yes | -- |
| GET | /projects/{project_id}/playground/autocomplete | Get autocomplete suggestions | Yes | -- |
Mass Patch
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| POST | /projects/{project_id}/patches | Create a new patch | Yes | pro |
| GET | /projects/{project_id}/patches | List patches | Yes | pro |
| GET | /projects/{project_id}/patches/{patch_id} | Get patch details | Yes | pro |
| PUT | /projects/{project_id}/patches/{patch_id} | Update patch | Yes | pro |
| POST | /projects/{project_id}/patches/{patch_id}/duplicate | Duplicate a patch | Yes | pro |
| DELETE | /projects/{project_id}/patches/{patch_id} | Delete patch | Yes | pro |
| POST | /projects/{project_id}/patches/{patch_id}/guard-rails | Run guard rail validation | Yes | pro |
| POST | /projects/{project_id}/patches/{patch_id}/dry-run | Execute dry-run simulation | Yes | pro |
| POST | /projects/{project_id}/patches/{patch_id}/approve | Approve patch for execution | Yes | pro |
| POST | /projects/{project_id}/patches/{patch_id}/execute | Execute patch (creates job) | Yes | pro |
| POST | /projects/{project_id}/patches/{patch_id}/rollback | Rollback executed patch | Yes | pro |
| GET | /projects/{project_id}/patches/{patch_id}/diff | Get before/after diff | Yes | pro |
| GET | /projects/{project_id}/patches/{patch_id}/progress | Get execution progress | Yes | pro |
| GET | /projects/{project_id}/patches/{patch_id}/export/{fmt} | Export patch (sql, liquibase) | Yes | pro |
| POST | /projects/{project_id}/patches/{patch_id}/test-memory | Test snapshot memory usage | Yes | pro |
| POST | /projects/{project_id}/patches/analyze-sql | Analyze SQL for a patch | Yes | pro |
| POST | /projects/{project_id}/patches/generate-sql | Generate SQL from template | Yes | pro |
| GET | /projects/{project_id}/guard-rail-policies | List guard rail policies | Yes | pro |
| POST | /projects/{project_id}/guard-rail-policies | Create guard rail policy | Yes | pro |
Bridge
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| POST | /projects/{project_id}/bridge/validate | Validate source/target connections | Yes | pro |
| POST | /projects/{project_id}/bridge/transfer | Execute data transfer | Yes | pro |
| POST | /projects/{project_id}/bridge/preview | Preview transfer (row count comparison) | Yes | pro |
| POST | /projects/{project_id}/bridge/missing-tables | Detect missing tables in target | Yes | pro |
| POST | /projects/{project_id}/bridge/clone-structure | Clone table structure to target | Yes | pro |
| POST | /projects/{project_id}/detect-hash | Detect hashed columns | Yes | pro |
| GET | /projects/{project_id}/bridge/history | Get transfer history | Yes | pro |
Anonymization
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| POST | /projects/{project_id}/anonymize/preview | Preview anonymized data | Yes | pro |
| POST | /projects/{project_id}/anonymize/execute | Execute in-place anonymization | Yes | pro |
| POST | /projects/{project_id}/anonymize/detect | Detect sensitive columns | Yes | pro |
| POST | /projects/{project_id}/anonymize/copy | Anonymize and copy to target | Yes | enterprise |
| POST | /projects/{project_id}/anonymize/config | Save anonymization configuration | Yes | pro |
| GET | /projects/{project_id}/anonymize/configs | List saved configurations | Yes | pro |
| POST | /projects/{project_id}/anonymize/config/load | Load a saved configuration | Yes | pro |
| POST | /projects/{project_id}/anonymize/bulk | Bulk anonymize multiple tables | Yes | pro |
Seeds
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| POST | /projects/{project_id}/seed/generate | Generate seed data (standard) | Yes | -- |
| POST | /projects/{project_id}/seed/insert | Insert seed data | Yes | -- |
| POST | /projects/{project_id}/seed/entity | Entity-aware seed | Yes | pro |
| GET | /projects/{project_id}/seed/history | Get seed history | Yes | -- |
| GET | /projects/{project_id}/seed/plan | Get seed plan (FK order) | Yes | -- |
| GET | /projects/{project_id}/seed/entity/config | Get entity seed configuration | Yes | pro |
| POST | /projects/{project_id}/seed/entity/preview | Preview entity seed | Yes | pro |
| POST | /projects/{project_id}/seed/entity/execute | Execute entity seed | Yes | pro |
| POST | /projects/{project_id}/seed/sql | SQL-based seed | Yes | enterprise |
| POST | /projects/{project_id}/seed/entity/full | Full entity seed pipeline | Yes | pro |
| POST | /projects/{project_id}/seed/scenario | Run seed scenario | Yes | pro |
| GET | /projects/{project_id}/seed/scenarios | List seed scenarios | Yes | pro |
| DELETE | /projects/{project_id}/seed/scenarios/{scenario_id} | Delete seed scenario | Yes | pro |
| POST | /projects/{project_id}/seed/scenario/duplicate | Duplicate scenario | Yes | pro |
QA Templates
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| POST | /projects/{project_id}/qa-templates | Create QA template | Yes | pro |
| GET | /projects/{project_id}/qa-templates | List QA templates | Yes | pro |
| GET | /projects/{project_id}/qa-templates/{template_id} | Get QA template details | Yes | pro |
| PUT | /projects/{project_id}/qa-templates/{template_id} | Update QA template | Yes | pro |
| DELETE | /projects/{project_id}/qa-templates/{template_id} | Delete QA template | Yes | pro |
| POST | /projects/{project_id}/qa-templates/{template_id}/preview | Preview template output | Yes | pro |
| POST | /projects/{project_id}/qa-templates/{template_id}/run | Execute template | Yes | pro |
| POST | /projects/{project_id}/qa-templates/{template_id}/duplicate | Duplicate template | Yes | pro |
| GET | /projects/{project_id}/qa-templates/{template_id}/runs | Get template run history | Yes | pro |
| POST | /projects/{project_id}/qa-templates/validate | Validate template definition | Yes | pro |
Validation
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| POST | /projects/{project_id}/validation/rules | Create validation rule | Yes | pro |
| GET | /projects/{project_id}/validation/rules | List validation rules | Yes | pro |
| PUT | /validation/rules/{rule_id} | Update validation rule | Yes | pro |
| DELETE | /validation/rules/{rule_id} | Delete validation rule | Yes | pro |
| POST | /projects/{project_id}/validation/validate-sql | Validate custom SQL rule | Yes | pro |
| POST | /projects/{project_id}/validation/scan | Run validation scan | Yes | pro |
| POST | /projects/{project_id}/validation/suggest | Auto-suggest rules for columns | Yes | pro |
| GET | /validation/regex-library | Get built-in regex patterns | Yes | pro |
| POST | /validation/test-regex | Test regex against sample data | Yes | pro |
| GET | /projects/{project_id}/validation/dashboard | Get validation dashboard metrics | Yes | pro |
| GET | /projects/{project_id}/validation/runs/compare | Compare two scan runs | Yes | pro |
| GET | /projects/{project_id}/validation/runs/{run_id} | Get scan run details | Yes | pro |
| GET | /projects/{project_id}/validation/runs | List scan runs | Yes | pro |
Performance
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| GET | /projects/{project_id}/performance/check/{connection_id} | Check pg_stat_statements setup | Yes | enterprise |
| GET | /projects/{project_id}/performance/{connection_id}/schemas | List available schemas | Yes | enterprise |
| GET | /projects/{project_id}/performance/{connection_id}/dashboard | Performance dashboard metrics | Yes | enterprise |
| GET | /projects/{project_id}/performance/{connection_id}/slow-queries | List slow queries | Yes | enterprise |
| GET | /projects/{project_id}/performance/{connection_id}/table-stats | Table-level statistics | Yes | enterprise |
| GET | /projects/{project_id}/performance/{connection_id}/index-recommendations | Index improvement suggestions | Yes | enterprise |
| POST | /projects/{project_id}/performance/{connection_id}/explain | Run EXPLAIN ANALYZE on a query | Yes | enterprise |
Preflight
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| POST | /projects/{project_id}/preflight/analyze | Analyze single SQL statement | Yes | enterprise |
| POST | /projects/{project_id}/preflight/analyze-batch | Analyze multiple SQL statements | Yes | enterprise |
| GET | /projects/{project_id}/preflight/environment/{connection_id} | Get environment context | Yes | enterprise |
| GET | /projects/{project_id}/preflight/history | Get analysis history | Yes | enterprise |
| GET | /projects/{project_id}/preflight/stats | Get analysis statistics | Yes | enterprise |
GDPR
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| POST | /projects/{project_id}/gdpr/scan | Run compliance scan | Yes | pro |
| GET | /gdpr/regulations | List available regulations | Yes | -- |
Export
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| GET | /projects/{project_id}/export/csv/{table_name} | Export table as CSV | Yes | -- |
| GET | /projects/{project_id}/export/csv/{table_name}/anonymized | Export table as anonymized CSV | Yes | enterprise |
| GET | /projects/{project_id}/export/full/sql | Export full database as SQL | Yes | pro |
| GET | /projects/{project_id}/export/full/csv | Export full database as CSV zip | Yes | -- |
| GET | /projects/{project_id}/export/full/sql/anonymized | Export full DB as anonymized SQL | Yes | enterprise |
| GET | /projects/{project_id}/export/schema/sql | Export schema DDL | Yes | pro |
| GET | /projects/{project_id}/export/doc/markdown | Export schema as Markdown | Yes | pro |
| GET | /projects/{project_id}/export/doc/html | Export schema as HTML | Yes | enterprise |
Import
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| POST | /projects/{project_id}/import/validate/{table_name} | Validate CSV file for import | Yes | pro |
| POST | /projects/{project_id}/import/execute/{table_name} | Execute CSV import | Yes | pro |
| POST | /projects/{project_id}/import/sql/validate | Validate SQL file for import | Yes | enterprise |
| POST | /projects/{project_id}/import/sql/execute | Execute SQL import | Yes | enterprise |
| POST | /projects/{project_id}/import/bulk/validate | Validate bulk CSV import | Yes | enterprise |
| POST | /projects/{project_id}/import/bulk/execute | Execute bulk CSV import | Yes | enterprise |
Jobs
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| GET | /projects/{project_id}/jobs | List jobs for project | Yes | -- |
| GET | /projects/{project_id}/jobs/{job_id} | Get job details | Yes | -- |
| GET | /projects/{project_id}/jobs/{job_id}/stream | SSE stream for job progress | Yes | -- |
| POST | /projects/{project_id}/jobs/{job_id}/cancel | Cancel a running job | Yes | -- |
Configuration
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| GET | /projects/{project_id}/config | Get project configuration | Yes | -- |
| POST | /projects/{project_id}/config | Update project configuration | Yes | -- |
| GET | /projects/{project_id}/config/guard-rails | Get guard rail settings | Yes | -- |
| POST | /projects/{project_id}/config/guard-rails | Update guard rail settings | Yes | -- |
| GET | /projects/{project_id}/config/environments | Get environment definitions | Yes | -- |
| POST | /projects/{project_id}/config/environments | Update environment definitions | Yes | -- |
| GET | /projects/{project_id}/config/security | Get security settings | Yes | -- |
| POST | /projects/{project_id}/config/security | Update security settings | Yes | -- |
Profiling
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| GET | /projects/{project_id}/profiling/{table_name} | Profile all columns in a table | Yes | pro |
| GET | /projects/{project_id}/profiling/{table_name}/{column_name} | Profile a specific column | Yes | pro |
Activity
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| GET | /projects/{project_id}/activity | Get project activity log | Yes | -- |
| GET | /projects/{project_id}/activity/stats | Get activity statistics | Yes | -- |
References
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| GET | /projects/{project_id}/references | List reference definitions | Yes | pro |
| POST | /projects/{project_id}/references | Create reference definition | Yes | pro |
| PATCH | /projects/{project_id}/references/{reference_id} | Update reference definition | Yes | pro |
| DELETE | /projects/{project_id}/references/{reference_id} | Delete reference definition | Yes | pro |
| GET | /projects/{project_id}/references/values/{table_name}/{column_name} | Get reference values for a column | Yes | pro |
| POST | /projects/{project_id}/detect | Auto-detect reference columns | Yes | pro |
Annotations
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| GET | /projects/{project_id}/annotations | List project annotations | Yes | pro |
| POST | /projects/{project_id}/annotations | Create annotation | Yes | pro |
| PATCH | /annotations/{annotation_id} | Update annotation | Yes | pro |
| DELETE | /annotations/{annotation_id} | Delete annotation | Yes | pro |
Plans
All plan routes are prefixed with /plans.
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| GET | /plans | List all available plans | Yes | -- |
| GET | /plans/me | Get current user's plan | Yes | -- |
| PATCH | /plans/me | Update current user's plan | Yes | -- |
| GET | /plans/me/limits | Get current plan limits | Yes | -- |
Teams
All team routes are prefixed with /teams.
| Method | Path | Description | Auth | Plan |
|---|---|---|---|---|
| POST | /teams/ | Create a team | Yes | admin |
| GET | /teams/ | List teams | Yes | admin |
| GET | /teams/{team_id} | Get team details with members | Yes | admin |
| PATCH | /teams/{team_id} | Update team | Yes | admin |
| DELETE | /teams/{team_id} | Delete team | Yes | admin |
| POST | /teams/{team_id}/members | Add member to team | Yes | admin |
| DELETE | /teams/{team_id}/members/{user_id} | Remove member from team | Yes | admin |
| PATCH | /teams/{team_id}/members/{user_id} | Update member role in team | Yes | admin |
| GET | /teams/{team_id}/projects | List team's projects | Yes | admin |
| POST | /teams/{team_id}/projects | Create project under team | Yes | admin |
Governance
All governance routes are prefixed with /governance. Requires super_admin role.
| Method | Path | Description | Auth | Role |
|---|---|---|---|---|
| GET | /governance/dashboard | DSI dashboard with aggregate metrics | Yes | super_admin |
| GET | /governance/users | List all users with details | Yes | super_admin |
| POST | /governance/users/{user_id}/block | Block a user | Yes | super_admin |
| POST | /governance/users/{user_id}/unblock | Unblock a user | Yes | super_admin |
| POST | /governance/users/{user_id}/force-logout | Force logout a user | Yes | super_admin |
| GET | /governance/teams | List all teams | Yes | super_admin |
| POST | /governance/teams | Create a team | Yes | super_admin |
| GET | /governance/teams/{team_id} | Get team details | Yes | super_admin |
| DELETE | /governance/teams/{team_id} | Delete a team | Yes | super_admin |
| GET | /governance/projects | List all projects | Yes | super_admin |
| GET | /governance/projects/{project_id}/detail | Get project audit detail | Yes | super_admin |
| GET | /governance/audit | Search audit trail (paginated) | Yes | super_admin |
| GET | /governance/audit/export | Export audit trail as CSV | Yes | super_admin |
| GET | /governance/alerts | Get governance alerts | Yes | super_admin |
| GET | /governance/sessions | List active sessions | Yes | super_admin |
| POST | /governance/sessions/{user_id}/revoke | Revoke user session | Yes | super_admin |
| GET | /governance/deleted-projects | List deleted projects | Yes | super_admin |
| POST | /governance/projects/{project_id}/permissions | Grant project permission to user | Yes | super_admin |
| GET | /governance/projects/{project_id}/permissions | List project permissions | Yes | super_admin |
| DELETE | /governance/projects/{project_id}/permissions/{user_id} | Revoke project permission | Yes | super_admin |