> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orca-klavest.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Endpoint reference

> Complete list of all ORCA API endpoints organized by category.

## Files & jobs

| Method   | Endpoint                             | Description                               | Auth |
| -------- | ------------------------------------ | ----------------------------------------- | ---- |
| `POST`   | `/jobs`                              | Create a new job                          | JWT  |
| `POST`   | `/jobs/sample`                       | Create sample job with pre-seeded results | JWT  |
| `POST`   | `/jobs/{job_id}/start`               | Start job after files uploaded            | JWT  |
| `GET`    | `/jobs`                              | List all jobs (paginated, filterable)     | JWT  |
| `GET`    | `/jobs/{job_id}`                     | Get job details with progress             | JWT  |
| `GET`    | `/jobs/{job_id}/cost-estimate`       | Estimate processing cost                  | JWT  |
| `GET`    | `/jobs/compare`                      | Compare two jobs side-by-side             | JWT  |
| `POST`   | `/jobs/{job_id}/files/presigned-url` | Get S3 presigned URL for upload           | JWT  |
| `GET`    | `/jobs/{job_id}/files`               | List files in a job                       | JWT  |
| `DELETE` | `/jobs/{job_id}/files/{file_id}`     | Delete a file                             | JWT  |
| `POST`   | `/jobs/{job_id}/files/bulk-upload`   | Bulk upload files                         | JWT  |
| `POST`   | `/files/prescan`                     | Validate headers for prohibited content   | None |

## Results & analysis

| Method  | Endpoint                                   | Description                        | Auth |
| ------- | ------------------------------------------ | ---------------------------------- | ---- |
| `GET`   | `/jobs/{job_id}/results`                   | Classification and quality results | JWT  |
| `PATCH` | `/jobs/{job_id}/columns/{column_name}`     | Correct column classification      | JWT  |
| `GET`   | `/jobs/{job_id}/files/{file_id}/schema`    | Inferred file schema               | JWT  |
| `GET`   | `/jobs/{job_id}/files/{file_id}/profile`   | Data profiling analysis            | JWT  |
| `GET`   | `/jobs/{job_id}/files/{file_id}/drift`     | Drift detection                    | JWT  |
| `GET`   | `/jobs/{job_id}/files/{file_id}/anomalies` | Anomaly detection                  | JWT  |
| `POST`  | `/jobs/{job_id}/files/{file_id}/diff`      | Data diffing between files         | JWT  |

## AI readiness & assessment

| Method | Endpoint                                       | Description                               | Auth |
| ------ | ---------------------------------------------- | ----------------------------------------- | ---- |
| `GET`  | `/files/{file_id}/ai-readiness`                | AI readiness score for file               | JWT  |
| `GET`  | `/ai-readiness/org`                            | Org-level aggregate AI readiness          | JWT  |
| `GET`  | `/ai-readiness/history/{file_id}`              | Historical score trends                   | JWT  |
| `GET`  | `/files/{file_id}/fix-priorities`              | Prioritized fix actions with ROI          | JWT  |
| `GET`  | `/files/{file_id}/fix-waterfall`               | Cumulative score improvement waterfall    | JWT  |
| `GET`  | `/files/{file_id}/usecase-readiness`           | Readiness for all 8 ML use cases          | JWT  |
| `GET`  | `/files/{file_id}/usecase-readiness/{usecase}` | Readiness for specific use case           | JWT  |
| `GET`  | `/usecase-readiness/available`                 | List available ML use cases               | JWT  |
| `POST` | `/files/{file_id}/ai-readiness/assess`         | Generate assessment report (requires 75+) | JWT  |
| `GET`  | `/ai-readiness/certificates`                   | List org assessment reports               | JWT  |
| `GET`  | `/certificates/{certificate_id}/verify`        | Public report verification                | None |

## Remediation & corrections

| Method | Endpoint                             | Description                         | Auth |
| ------ | ------------------------------------ | ----------------------------------- | ---- |
| `GET`  | `/files/{file_id}/remediation/plan`  | Generate remediation plan (preview) | JWT  |
| `POST` | `/files/{file_id}/remediation/apply` | Apply selected fixes                | JWT  |
| `POST` | `/jobs/{job_id}/apply-corrections`   | Create correction job               | JWT  |
| `GET`  | `/corrections/{id}/status`           | Correction job status               | JWT  |
| `GET`  | `/corrections/{id}/download`         | Download corrected file             | JWT  |
| `GET`  | `/correction-pipelines`              | List correction pipelines           | JWT  |
| `GET`  | `/correction-pipelines/{id}`         | Pipeline details with steps         | JWT  |
| `POST` | `/correction-pipelines/{id}/preview` | Preview pipeline execution          | JWT  |
| `POST` | `/correction-pipelines/{id}/approve` | Approve pipeline                    | JWT  |
| `POST` | `/correction-pipelines/{id}/reject`  | Reject pipeline                     | JWT  |
| `POST` | `/correction-pipelines/{id}/export`  | Export corrected file               | JWT  |

## Data sources & integrations

| Method   | Endpoint                       | Description                                              | Auth  |
| -------- | ------------------------------ | -------------------------------------------------------- | ----- |
| `POST`   | `/sources/test-connection`     | Test data source connection                              | JWT   |
| `POST`   | `/sources`                     | Create data source (PostgreSQL, BigQuery, Snowflake, S3) | JWT   |
| `GET`    | `/sources`                     | List all data sources                                    | JWT   |
| `GET`    | `/sources/{id}`                | Get data source details                                  | JWT   |
| `PATCH`  | `/sources/{id}`                | Update data source                                       | JWT   |
| `DELETE` | `/sources/{id}`                | Delete data source                                       | Admin |
| `POST`   | `/sources/{id}/tables`         | Scan tables from source                                  | JWT   |
| `PATCH`  | `/sources/{id}/tables/{table}` | Update table settings                                    | JWT   |
| `GET`    | `/sources/{id}/scan-schedule`  | Get scheduled scans                                      | JWT   |
| `POST`   | `/sources/{id}/scan-schedule`  | Create scheduled scan                                    | JWT   |

## Data contracts

| Method   | Endpoint                          | Description                    | Auth  |
| -------- | --------------------------------- | ------------------------------ | ----- |
| `POST`   | `/contracts`                      | Create data contract           | Admin |
| `GET`    | `/contracts`                      | List data contracts            | JWT   |
| `GET`    | `/contracts/{id}`                 | Contract details with rules    | JWT   |
| `PATCH`  | `/contracts/{id}`                 | Update contract                | Admin |
| `DELETE` | `/contracts/{id}`                 | Delete contract                | Admin |
| `POST`   | `/contracts/{id}/rules`           | Add rule to contract           | Admin |
| `DELETE` | `/contracts/{id}/rules/{rule_id}` | Delete contract rule           | Admin |
| `GET`    | `/contracts/{id}/violations`      | List violations (paginated)    | JWT   |
| `POST`   | `/contracts/{id}/evaluate`        | Evaluate contract against data | JWT   |

## Knowledge graph & lineage

| Method   | Endpoint                              | Description                        | Auth  |
| -------- | ------------------------------------- | ---------------------------------- | ----- |
| `GET`    | `/knowledge-graph/entities`           | List all entities                  | JWT   |
| `GET`    | `/knowledge-graph/entities/{id}`      | Entity detail with quality history | JWT   |
| `GET`    | `/knowledge-graph/relationships`      | List all relationships             | JWT   |
| `GET`    | `/knowledge-graph/relationships/{id}` | Relationship detail                | JWT   |
| `POST`   | `/lineage/nodes`                      | Create lineage node                | Admin |
| `GET`    | `/lineage/nodes`                      | List lineage nodes                 | JWT   |
| `GET`    | `/lineage/nodes/{id}`                 | Lineage node detail                | JWT   |
| `PATCH`  | `/lineage/nodes/{id}`                 | Update lineage node                | Admin |
| `DELETE` | `/lineage/nodes/{id}`                 | Delete lineage node                | Admin |
| `POST`   | `/lineage/edges`                      | Create lineage edge                | Admin |
| `GET`    | `/lineage/edges`                      | List lineage edges                 | JWT   |
| `GET`    | `/lineage/graph`                      | Full lineage graph                 | JWT   |
| `GET`    | `/lineage/impact/{node_id}`           | Impact analysis for node           | JWT   |

## Reports

| Method   | Endpoint                  | Description                            | Auth  |
| -------- | ------------------------- | -------------------------------------- | ----- |
| `POST`   | `/reports/generate`       | Generate PDF report (async, 5 credits) | JWT   |
| `GET`    | `/reports`                | List reports (paginated)               | JWT   |
| `GET`    | `/reports/{id}`           | Report status + download URL           | JWT   |
| `GET`    | `/reports/{id}/download`  | Download report                        | JWT   |
| `GET`    | `/reports/schedules`      | List scheduled reports                 | Admin |
| `POST`   | `/reports/schedules`      | Create scheduled report                | Admin |
| `PATCH`  | `/reports/schedules/{id}` | Update scheduled report                | Admin |
| `DELETE` | `/reports/schedules/{id}` | Delete scheduled report                | Admin |

## Alerts & notifications

| Method | Endpoint                       | Description                         | Auth |
| ------ | ------------------------------ | ----------------------------------- | ---- |
| `GET`  | `/alerts`                      | List alerts (filterable, paginated) | JWT  |
| `GET`  | `/alerts/unacknowledged-count` | Unacknowledged alert count          | JWT  |
| `POST` | `/alerts/{id}/acknowledge`     | Mark alert as acknowledged          | JWT  |

## Chat (conversational AI)

| Method   | Endpoint                                             | Description                    | Auth |
| -------- | ---------------------------------------------------- | ------------------------------ | ---- |
| `POST`   | `/chat/conversations`                                | Create conversation            | JWT  |
| `GET`    | `/chat/conversations`                                | List conversations             | JWT  |
| `GET`    | `/chat/conversations/{id}`                           | Get conversation + messages    | JWT  |
| `POST`   | `/chat/conversations/{id}/messages`                  | Send message, get AI response  | JWT  |
| `DELETE` | `/chat/conversations/{id}`                           | Archive conversation           | JWT  |
| `GET`    | `/chat/suggestions`                                  | Contextual suggested questions | JWT  |
| `PUT`    | `/chat/conversations/{id}/messages/{mid}/edit`       | Edit user message              | JWT  |
| `POST`   | `/chat/conversations/{id}/messages/{mid}/regenerate` | Regenerate response            | JWT  |
| `GET`    | `/chat/conversations/search`                         | Search conversations           | JWT  |
| `GET`    | `/chat/credit-estimate`                              | Estimate credit cost           | JWT  |

## Authentication

| Method | Endpoint                       | Description                           | Auth   |
| ------ | ------------------------------ | ------------------------------------- | ------ |
| `POST` | `/auth/register`               | Register with invite code             | None   |
| `POST` | `/auth/login`                  | Login                                 | None   |
| `POST` | `/auth/refresh`                | Refresh access token                  | Cookie |
| `POST` | `/auth/logout`                 | Logout (invalidates session)          | JWT    |
| `GET`  | `/auth/check-sso`              | Check SSO enforcement for domain      | None   |
| `POST` | `/auth/verify-email`           | Verify email address                  | None   |
| `POST` | `/auth/password-reset`         | Request password reset                | None   |
| `POST` | `/auth/password-reset/{token}` | Complete password reset               | None   |
| `POST` | `/auth/totp/setup`             | Setup 2FA (returns QR + backup codes) | JWT    |
| `POST` | `/auth/totp/verify-setup`      | Verify 2FA setup                      | JWT    |
| `POST` | `/auth/totp/complete`          | Complete 2FA login                    | None   |
| `POST` | `/auth/totp/disable`           | Disable 2FA                           | JWT    |

## User management

| Method   | Endpoint                      | Description              | Auth  |
| -------- | ----------------------------- | ------------------------ | ----- |
| `GET`    | `/users/me`                   | Current user profile     | JWT   |
| `GET`    | `/users/me/permissions`       | Current user permissions | JWT   |
| `PATCH`  | `/users/me/alert-preferences` | Update alert preferences | JWT   |
| `POST`   | `/users/me/password`          | Change password          | JWT   |
| `GET`    | `/users`                      | List all users in org    | Admin |
| `POST`   | `/users`                      | Invite user              | Admin |
| `GET`    | `/users/{id}`                 | Get user details         | Admin |
| `PATCH`  | `/users/{id}`                 | Update user              | Admin |
| `DELETE` | `/users/{id}`                 | Delete user              | Admin |

## Teams & roles

| Method   | Endpoint                        | Description                     | Auth  |
| -------- | ------------------------------- | ------------------------------- | ----- |
| `GET`    | `/teams`                        | List teams                      | Admin |
| `POST`   | `/teams`                        | Create team                     | Admin |
| `PATCH`  | `/teams/{id}`                   | Rename team                     | Admin |
| `DELETE` | `/teams/{id}`                   | Delete team                     | Admin |
| `GET`    | `/teams/{id}`                   | Team with members + permissions | Admin |
| `POST`   | `/teams/{id}/members`           | Add user to team                | Admin |
| `DELETE` | `/teams/{id}/members/{user_id}` | Remove user from team           | Admin |
| `GET`    | `/teams/{id}/permissions`       | Get team permissions            | Admin |
| `PATCH`  | `/teams/{id}/permissions`       | Update team permissions         | Admin |
| `GET`    | `/roles`                        | List all roles                  | Admin |
| `POST`   | `/roles`                        | Create custom role              | Admin |
| `PATCH`  | `/roles/{id}`                   | Update custom role              | Admin |
| `DELETE` | `/roles/{id}`                   | Delete custom role              | Admin |

## Billing & credits

| Method  | Endpoint                 | Description                      | Auth  |
| ------- | ------------------------ | -------------------------------- | ----- |
| `GET`   | `/billing/balance`       | Credit balance and spending      | JWT   |
| `POST`  | `/billing/credits/add`   | Add credits                      | Admin |
| `GET`   | `/billing/usage-summary` | Usage summary for billing period | JWT   |
| `POST`  | `/billing/checkout`      | Create Stripe checkout session   | JWT   |
| `GET`   | `/billing/token-status`  | Token bucket status              | JWT   |
| `PATCH` | `/billing/ai-tier`       | Switch AI tier (basic/advanced)  | Admin |

## API keys & webhooks

| Method   | Endpoint              | Description                 | Auth  |
| -------- | --------------------- | --------------------------- | ----- |
| `POST`   | `/api-keys`           | Create API key (max 10/org) | Admin |
| `GET`    | `/api-keys`           | List API keys               | Admin |
| `GET`    | `/api-keys/{id}`      | API key details             | Admin |
| `PATCH`  | `/api-keys/{id}`      | Update API key              | Admin |
| `DELETE` | `/api-keys/{id}`      | Revoke API key              | Admin |
| `POST`   | `/webhooks`           | Create webhook (max 10/org) | Admin |
| `GET`    | `/webhooks`           | List webhooks               | Admin |
| `GET`    | `/webhooks/{id}`      | Webhook details             | Admin |
| `PATCH`  | `/webhooks/{id}`      | Update webhook              | Admin |
| `DELETE` | `/webhooks/{id}`      | Delete webhook              | Admin |
| `POST`   | `/webhooks/{id}/test` | Send test webhook           | Admin |

## Organisation & settings

| Method  | Endpoint                     | Description                        | Auth  |
| ------- | ---------------------------- | ---------------------------------- | ----- |
| `GET`   | `/organisations`             | Org details                        | Admin |
| `GET`   | `/settings/retention`        | Data retention settings            | Admin |
| `PATCH` | `/settings/retention`        | Update retention settings          | Admin |
| `GET`   | `/org-profile`               | Org profile and learned rules      | JWT   |
| `PATCH` | `/org-profile`               | Update org profile                 | Admin |
| `GET`   | `/org-profile/trust-history` | Trust level and approval rate      | JWT   |
| `GET`   | `/audit`                     | Audit logs (filterable, paginated) | Admin |
| `GET`   | `/analytics/org`             | Org analytics                      | JWT   |
| `GET`   | `/analytics/jobs`            | Job analytics                      | JWT   |
| `GET`   | `/analytics/quality`         | Quality metrics and trends         | JWT   |
| `GET`   | `/analytics/usage`           | Usage metrics                      | JWT   |

## SSO

| Method   | Endpoint             | Description             | Auth  |
| -------- | -------------------- | ----------------------- | ----- |
| `GET`    | `/sso/config`        | Get SSO config          | Admin |
| `POST`   | `/sso/config`        | Create SSO config       | Admin |
| `PATCH`  | `/sso/config`        | Update SSO config       | Admin |
| `DELETE` | `/sso/config`        | Delete SSO config       | Admin |
| `POST`   | `/sso/saml/login`    | SAML login initiation   | None  |
| `POST`   | `/sso/saml/acs`      | SAML assertion consumer | None  |
| `GET`    | `/sso/oidc/login`    | OIDC login initiation   | None  |
| `GET`    | `/sso/oidc/callback` | OIDC callback handler   | None  |