# Eddytor API Reference
Version: 1.0
Base URL: https://app.eddytor.com/api

## Description
Eddytor is a Master Data Management (MDM) platform that lets you create, configure, query, and govern Delta Lake tables across any object store (S3, Azure Blob, GCS).

## Authentication

Most endpoints require a **Bearer token** in the `Authorization` header. Eddytor supports two token types:

- **JWT** — obtained via the sign-up / onboard flow through Supabase Auth.
- **API key** — created at `POST /v1/api-keys` for programmatic access. Prefix: `eak_`.

## Getting started

1. **Onboard** — `POST /v1/auth/onboard` with your email to create an account and organisation.
2. **Connect storage** — `POST /v1/storages/s3` or `/v1/storages/az` to register a bucket or container.
3. **Browse tables** — `GET /v1/storages/tables` to list discovered Delta tables.
4. **Query data** — Use the gRPC `StreamData` RPC or the REST table endpoints.

## Rate limiting

All API endpoints are rate-limited. If you receive a `429 Too Many Requests` response, back off and retry with exponential delay.

## Authentication

Eddytor supports two authentication methods, both sent as a Bearer token in the Authorization header:

  Authorization: Bearer <jwt_token_or_api_key>

### JWT Tokens
For interactive users (web/desktop). Issued by Supabase after sign-in.
Access is determined by the user's organisation role.

### API Keys
For programmatic/service access. Created via the API with fine-grained scope restrictions.
Format: edd_live_<40 hex characters>
Example: edd_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8
The full key is only returned once at creation time. Only a hashed version is stored.
Expiration options: 7d, 30d, 90d, 1y, or never.

Management Endpoints:
  POST   /v1/api-keys/    — Create a new API key
  GET    /v1/api-keys/    — List all API keys
  GET    /v1/api-keys/:id — Get a specific API key
  PATCH  /v1/api-keys/:id — Update name, scopes, or expiration
  DELETE /v1/api-keys/:id — Revoke an API key (permanent)

### Scopes

Presets:
  - read  — Read-only access (viewer scopes)
  - write — Read + write access (viewer + editor + builder scopes)
  - admin — Full access (all scopes)

Granular scopes:
  Tables: tables:query, tables:read, tables:create, tables:modify, tables:import
  Rows: rows:insert, rows:update, rows:delete
  Domains: domains:read, domains:write
  Connections: connections:read, connections:create, connections:delete
  Storage: storage:read, objects:read, objects:download, objects:delete
  AI: ai:query, ai:credentials:read, ai:credentials:write
  API Keys: apikeys:read, apikeys:create, apikeys:update, apikeys:revoke
  Organisation: org:read, org:update

An API key can only be granted scopes that the creating user's role permits.
AI scopes require a Full or Premium seat.

### Permission Model
  - JWT users: Full access based on their organisation role
  - API key users: Intersection of the user's role permissions and the key's scopes

### Security
  - Keys are hashed with HMAC-SHA256 before storage — the plaintext key is never persisted
  - Revoked keys cannot be un-revoked
  - last_used_at is tracked for auditing

### Rate Limiting
  - Default: 60 requests/minute per IP
  - Auth endpoints: 10 requests/minute per IP
  - When exceeded: 429 Too Many Requests with Retry-After header

## Error Handling

All errors follow a consistent JSON format with statusCode, error, and message fields.

### 400 Bad Request
The request body or query parameters are invalid. Check field types, required fields, and value constraints.
Retry guidance: Do not retry without fixing the request. Inspect the error details to correct validation issues.
Example: {"statusCode":400,"error":"Bad Request","message":"Validation failed","details":[{"field":"name","message":"name is required"}]}

### 401 Unauthorized
The Authorization header is missing, malformed, or the token has expired.
Retry guidance: Refresh your JWT token or generate a new API key before retrying.
Example: {"statusCode":401,"error":"Unauthorized","message":"Invalid or expired token"}

### 403 Forbidden
Your token is valid but lacks the required scopes or role permissions for this action.
Retry guidance: Verify the API key scopes or the user role. Request additional permissions if needed.
Example: {"statusCode":403,"error":"Forbidden","message":"Insufficient permissions","requiredScope":"tables:create"}

### 404 Not Found
The requested resource does not exist. Verify the ID or path.
Retry guidance: Check the resource ID and ensure it exists. This error is not transient.
Example: {"statusCode":404,"error":"Not Found","message":"Resource not found"}

### 429 Too Many Requests
You have exceeded the rate limit. The response includes a Retry-After header.
Retry guidance: Wait for the duration specified in the Retry-After header, then retry. Implement exponential backoff.
Example: {"statusCode":429,"error":"Too Many Requests","message":"Rate limit exceeded","retryAfter":30}

### 500 Internal Server Error
An unexpected error occurred on the server. This is not caused by your request.
Retry guidance: Retry with exponential backoff. If the issue persists, contact support@eddytor.com.
Example: {"statusCode":500,"error":"Internal Server Error","message":"An unexpected error occurred"}

## Webhook Events

Configure webhook endpoints to receive real-time notifications for these events.
All payloads include a signature header for verification.

### table.created
Fired when a new Delta Lake table is created in any connected storage.
Suggested action: Sync metadata, update internal catalogs, or notify downstream systems.

### table.updated
Fired when a table schema or configuration is modified.
Suggested action: Refresh cached schemas, trigger re-validation of dependent pipelines.

### table.deleted
Fired when a table is permanently deleted.
Suggested action: Clean up references, archive audit logs, remove from dashboards.

### row.batch_inserted
Fired after a batch of rows is successfully inserted into a table.
Suggested action: Trigger ETL pipelines, update materialized views, send notifications.

### apikey.revoked
Fired when an API key is revoked.
Suggested action: Invalidate cached credentials, alert security team, update access logs.

---

## AI Credentials
Store and manage per-user credentials for external AI providers
(OpenAI, Anthropic, Gemini, Mistral). Used by the Magic Dust analysis feature.

### GET /v1/ai/credentials
List AI credentials
Auth: None

Responses:
  200:  → AiCredentialsListResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### PUT /v1/ai/credentials
Upsert an AI credential
Auth: None

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: CreateAiCredentialBody
    - provider: any (required) - The AI provider (e.g. `OpenAI`, `Claude`, `Gemini`, `Mistral`).
    - api_key: string (required) - The secret API key issued by the provider. Stored encrypted and never returned.
    - base_url: string  - Custom base URL for self-hosted or proxy endpoints (e.g. Azure OpenAI).
Leave `null` to use the provider's default endpoint.

Responses:
  200:  → AiCredentialResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### DELETE /v1/ai/credentials/{provider}
Delete an AI credential
Auth: None

Responses:
  200:  → DeleteCredentialResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

---

## API Keys
Create, list, update, and revoke API keys for programmatic access.
API keys use the `eak_` prefix and support granular scope control.

### POST /v1/api-keys
Create a new API key
Auth: None

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: CreateApiKeyRequest
    - name: string (required) - A unique name for this API key (for your reference)
    - scopes: array  - List of scopes to grant to this API key
    - expires_in: string  - Expiration duration: "7d", "30d", "90d", "1y", or "never" (recommended)
    - expires_at: string  - Optional expiration date (ISO 8601 format). Use expires_in instead for convenience.

Responses:
  200:  → CreateApiKeyResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### GET /v1/api-keys
List all API keys
Auth: None

Responses:
  200:  → ListApiKeysResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### GET /v1/api-keys/{key_id}
Get API key details
Auth: None

Parameters:
  - key_id [path] string (required)

Responses:
  200:  → ApiKeyResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### PATCH /v1/api-keys/{key_id}
Update an API key
Auth: None

Parameters:
  - key_id [path] string (required)

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: UpdateApiKeyRequest
    - name: string  - New name for the API key
    - scopes: array  - New scopes for the API key
    - expires_at: string  - New expiration date (ISO 8601 format, empty string to remove expiration)

Responses:
  200:  → ApiKeyResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### DELETE /v1/api-keys/{key_id}
Revoke an API key
Auth: None

Parameters:
  - key_id [path] string (required)

Responses:
  200:  → RevokeApiKeyResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

---

## Auth
Sign-up, sign-out, token refresh, and OAuth provider linking.
JWT-based authentication is powered by Supabase Auth.

### POST /v1/auth/providers/{provider}/tokens
Link an OAuth provider
Auth: Required (Bearer JWT)

Parameters:
  - provider [path] string (required)

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: RefreshToken
    - refreshToken: string (required) - The refresh token obtained from a previous sign-in or token refresh.

Responses:
  200:  → EmptyResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

---

## Azure
Browse Azure subscriptions, storage accounts, and blob containers
using the user's linked Azure OAuth identity.

### GET /v1/azure/storage-accounts
List Azure storage accounts
Auth: Required (Bearer JWT)

Responses:
  200:  → AzureExplorer
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

---

## Billing
Retrieve available subscription plans and manage Stripe billing.

### GET /v1/billing/plans
Get available subscription plans.
Auth: None

Responses:
  200:  → SubscriptionPlansResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### POST /v1/billing/subscriptions/create
Create or manage a subscription.
Auth: None

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: CreateSubscriptionRequest
    - step: any (required) - The step in the subscription flow
    - priceId: string  - Price ID for the subscription (required for finalize step)
    - quantity: integer  - Number of seats (optional, defaults to 1)
    - paymentMethodId: string  - Payment method ID from Stripe (required for finalize and update-payment-method steps)

Responses:
  200:  → CreateSubscriptionResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

---

## Column Domain
Define and manage column-level value constraints (domains).
Supports fixed (enum), hierarchical (parent-child), derived, table-lookup,
and cross-table reference domain types.

### GET /v1/tables/{catalog}/{schema}/{table_name}/columns/{column_name}/domain
Get column domain configuration
Auth: None

Responses:
  200:  → ColumnDomainResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### DELETE /v1/tables/{catalog}/{schema}/{table_name}/columns/{column_name}/domain
Remove a column's domain
Auth: None

Responses:
  200:  → ColumnDomainResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### PUT /v1/tables/{catalog}/{schema}/{table_name}/columns/{column_name}/domain/fixed
Set a fixed (enum) domain on a column
Auth: None

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: FixedDomainRequest
    - allowed_values: array (required) - The complete list of allowed string values for this column.

Responses:
  200:  → ColumnDomainResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### PUT /v1/tables/{catalog}/{schema}/{table_name}/columns/{column_name}/domain/hierarchical/inline
Set a hierarchical inline domain on a column
Auth: None

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: HierarchicalInlineRequest
    - parent_column: string (required) - Name of the parent column that controls which child values are valid.
    - mappings: object (required) - Map from parent value ID to the list of allowed child values.

Responses:
  200:  → ColumnDomainResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### PUT /v1/tables/{catalog}/{schema}/{table_name}/columns/{column_name}/domain/hierarchical/derived
Set a hierarchical derived domain on a column
Auth: None

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: HierarchicalDerivedRequest
    - parent_column: string (required) - Name of the parent column.

Responses:
  200:  → ColumnDomainResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### PUT /v1/tables/{catalog}/{schema}/{table_name}/columns/{column_name}/domain/hierarchical/table
Set a hierarchical table-lookup domain on a column
Auth: None

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: HierarchicalTableRequest
    - parent_column: string (required) - Name of the parent column.
    - table_name: string (required) - Name of the lookup table containing the parent-child mapping.
    - table_path: string (required) - Storage path of the lookup table (e.g. `s3://bucket/path/to/table`).
    - parent_key: string (required) - Column in the lookup table that matches the parent value.
    - child_key: string (required) - Column in the lookup table that provides the child values.

Responses:
  200:  → ColumnDomainResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### PUT /v1/tables/{catalog}/{schema}/{table_name}/columns/{column_name}/domain/reference
Set a reference domain on a column
Auth: None

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: ReferenceDomainRequest
    - table_path: string (required) - The storage path of the source table (e.g., "s3://bucket/path/to/table")
    - table_reference: any (required) - Full table reference (catalog, schema, table)
    - column: string (required) - The column name in the source table whose domain to reference

Responses:
  200:  → ColumnDomainResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### POST /v1/tables/{catalog}/{schema}/{table_name}/columns/{column_name}/domain/values
Add a value to a fixed domain
Auth: None

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: AddValueRequest
    - value: string (required) - The value to add.

Responses:
  200:  → ColumnDomainResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### PUT /v1/tables/{catalog}/{schema}/{table_name}/columns/{column_name}/domain/values
Replace all values in a fixed domain
Auth: None

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: SetValuesRequest
    - values: array (required) - The new complete list of allowed values (replaces all existing values).

Responses:
  200:  → ColumnDomainResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### DELETE /v1/tables/{catalog}/{schema}/{table_name}/columns/{column_name}/domain/values/{value}
Remove a value from a fixed domain
Auth: None

Responses:
  200:  → ColumnDomainResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### POST /v1/tables/{catalog}/{schema}/{table_name}/columns/{column_name}/domain/parents
Add a parent to a hierarchical inline domain
Auth: None

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: AddValueRequest
    - value: string (required) - The value to add.

Responses:
  200:  → ColumnDomainResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### DELETE /v1/tables/{catalog}/{schema}/{table_name}/columns/{column_name}/domain/parents/{parent}
Remove a parent from a hierarchical inline domain
Auth: None

Responses:
  200:  → ColumnDomainResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### POST /v1/tables/{catalog}/{schema}/{table_name}/columns/{column_name}/domain/parents/{parent}/children
Add a child to a parent in a hierarchical inline domain
Auth: None

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: AddChildRequest
    - child: string (required) - The child value to add.

Responses:
  200:  → ColumnDomainResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### PUT /v1/tables/{catalog}/{schema}/{table_name}/columns/{column_name}/domain/parents/{parent}/children
Replace all children for a parent in a hierarchical inline domain
Auth: None

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: SetChildrenRequest
    - children: array (required) - The new complete list of child values (replaces all existing children).

Responses:
  200:  → ColumnDomainResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### DELETE /v1/tables/{catalog}/{schema}/{table_name}/columns/{column_name}/domain/parents/{parent}/children/{child}
Remove a child from a parent in a hierarchical inline domain
Auth: None

Responses:
  200:  → ColumnDomainResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### GET /v1/tables/{catalog}/{schema}/{table_name}/columns/{column_name}/allowed-values
Get allowed values for a column
Auth: None

Responses:
  200:  → AllowedValuesResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

---

## Organisation
Manage organisations, members, roles, seats, subscriptions, and invitations.

### GET /v1/organisations/me
Get current user's organisation
Auth: None

Responses:
  200:  → OrganisationResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### GET /v1/organisations/{organisation_id}
Get organisation by ID
Auth: None

Parameters:
  - organisation_id [path] string (required)

Responses:
  200:  → OrganisationResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### PUT /v1/organisations/{organisation_id}
Rename an organisation
Auth: None

Parameters:
  - organisation_id [path] string (required)

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: RenameOrganisationRequest
    - name: string (required)

Responses:
  200:  → OrganisationResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### DELETE /v1/organisations/{organisation_id}
Delete an organisation
Auth: None

Parameters:
  - organisation_id [path] string (required)

Responses:
  200:  → EmptyResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### GET /v1/organisations/{organisation_id}/users
List organisation members
Auth: None

Parameters:
  - organisation_id [path] string (required)

Responses:
  200:  → array
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### POST /v1/organisations/{organisation_id}/invite
Invite a user to the organisation
Auth: None

Parameters:
  - organisation_id [path] string (required)

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: InviteUserRequest
    - email: string (required)
    - role: string (required) - Organisation role defining what actions a user can perform.

Role hierarchy (cumulative permissions):
- **Viewer**: Read-only access (queries, exports, view schema)
- **Editor**: + write data (CRUD on rows, imports)
- **Builder**: + schema, domains, storage connections, API keys
- **Admin**: + user management, billing, org settings
    - seatType: any  - Optional seat type for the invited user (defaults to 'standard')

Responses:
  200:  → EmptyResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### POST /v1/organisations/{organisation_id}/recover
Send a password recovery email to a user
Auth: None

Parameters:
  - organisation_id [path] string (required)

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: RecoverUserRequest
    - email: string (required)

Responses:
  200:  → EmptyResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### DELETE /v1/organisations/{organisation_id}/users/{user_id}/deactivate
Deactivate a user (soft-delete)
Auth: None

Parameters:
  - organisation_id [path] string (required)
  - user_id [path] string (required)

Responses:
  200:  → EmptyResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### DELETE /v1/organisations/{organisation_id}/users/{user_id}
Permanently delete a user from the organisation
Auth: None

Parameters:
  - organisation_id [path] string (required)
  - user_id [path] string (required)

Responses:
  200:  → EmptyResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### PUT /v1/organisations/{organisation_id}/users/{user_id}/role
Update a user's role
Auth: None

Parameters:
  - organisation_id [path] string (required)
  - user_id [path] string (required)

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: EditRoleRequest
    - role: string (required) - Organisation role defining what actions a user can perform.

Role hierarchy (cumulative permissions):
- **Viewer**: Read-only access (queries, exports, view schema)
- **Editor**: + write data (CRUD on rows, imports)
- **Builder**: + schema, domains, storage connections, API keys
- **Admin**: + user management, billing, org settings

Responses:
  200:  → EmptyResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### PUT /v1/organisations/{organisation_id}/subscription
Update subscription seat quantity
Auth: None

Parameters:
  - organisation_id [path] string (required)

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: UpdateSubscriptionQuantityRequest
    - quantity: integer (required)

Responses:
  200:  → OrganisationResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### POST /v1/organisations/{organisation_id}/subscription/cancel
Cancel the subscription for an organisation.
Auth: None

Parameters:
  - organisation_id [path] string (required)

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: CancelSubscriptionRequest
    - cancelAtPeriodEnd: boolean  - If true, cancel at the end of the current billing period.
If false, cancel immediately.

Responses:
  200:  → SubscriptionResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### POST /v1/organisations/{organisation_id}/subscription/reactivate
Reactivate a subscription that was scheduled for cancellation or is paused.
Auth: None

Parameters:
  - organisation_id [path] string (required)

Responses:
  200:  → OrganisationResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### GET /v1/organisations/{organisation_id}/billing-portal
Get a billing portal URL for the organisation to manage payment methods
Auth: None

Parameters:
  - organisation_id [path] string (required)

Responses:
  200:  → BillingPortalResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### GET /v1/organisations/{organisation_id}/invoices
Get a list of invoices for the organisation
Auth: None

Parameters:
  - organisation_id [path] string (required)

Responses:
  200:  → array
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### GET /v1/organisations/{organisation_id}/invoices/{invoice_id}
Get a single invoice by ID
Auth: None

Parameters:
  - organisation_id [path] string (required)
  - invoice_id [path] string (required)

Responses:
  200:  → InvoiceResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### POST /v1/organisations/{organisation_id}/subscription/upgrade
Upgrade or change the subscription plan for an organisation.
Auth: None

Parameters:
  - organisation_id [path] string (required)

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: UpgradePlanRequest
    - priceId: string (required) - The new Stripe price ID to upgrade to
    - planType: any (required) - The plan type (individual or team)
    - quantity: integer  - Optional new quantity (for team plans, minimum 5 seats required)

Responses:
  200:  → SubscriptionResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### GET /v1/organisations/{organisation_id}/subscription/items
List subscription items (seat types) for an organisation.
Auth: None

Parameters:
  - organisation_id [path] string (required)

Responses:
  200:  → array
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### POST /v1/organisations/{organisation_id}/subscription/items
Add a new seat type to the subscription.
Auth: None

Parameters:
  - organisation_id [path] string (required)

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: AddSeatTypeRequest
    - priceId: string (required) - The Stripe price ID for the seat type to add
    - quantity: integer (required) - Initial quantity (number of seats)

Responses:
  200:  → SubscriptionItemResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### PUT /v1/organisations/{organisation_id}/subscription/items/{seat_type}
Update the quantity of a seat type.
Auth: None

Parameters:
  - organisation_id [path] string (required)
  - seat_type [path] string (required)

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: UpdateSeatTypeQuantityRequest
    - quantity: integer (required) - New quantity (number of seats)

Responses:
  200:  → SubscriptionItemResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### POST /v1/organisations/{organisation_id}/subscription/upgrade-seats
Upgrade seats from one type to another.
Auth: None

Parameters:
  - organisation_id [path] string (required)

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: UpgradeSeatTypeRequest
    - fromSeatType: any (required) - The seat type to upgrade from (e.g., "standard")
    - toSeatType: any (required) - The seat type to upgrade to (e.g., "premium")
    - toPriceId: string (required) - The Stripe price ID for the target seat type
    - quantity: integer (required) - Number of seats to upgrade

Responses:
  200:  → EmptyResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### PUT /v1/organisations/{organisation_id}/users/{user_id}/seat-type
Update a user's seat type.
Auth: None

Parameters:
  - organisation_id [path] string (required)
  - user_id [path] string (required)

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: UpdateUserSeatTypeRequest
    - seatType: string (required) - Seat type for subscription items
- Standard: Available for both Individual and Team plans (default tier)
- Full: Individual plans only (full access tier)
- Premium: Team plans only (premium seats with enhanced features)

Responses:
  200:  → EmptyResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

---

## Storage
Register, list, and remove object-store connections (S3, Azure, GCS).
Browse, upload, download, and delete objects within connected stores.

### POST /v1/storages/s3
Register an S3-compatible storage connection
Auth: None

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: RegisterS3Request
    - accessKeyId: string  - S3 access key ID
    - secretKey: string  - S3 secret access key
    - sessionToken: string  - Optional session token for temporary credentials
    - region: string (required) - AWS region (e.g., "us-east-1")
    - bucketName: string (required) - S3 bucket name
    - endpoint: string  - S3 endpoint URL (optional, only needed for S3-compatible services like MinIO)
    - basePath: string  - Base path to scan for Delta tables (optional)
    - schemaName: string  - Schema name for registering tables in DataFusion
    - discoverDelta: boolean (required) - Whether to discover Delta tables
    - discoverIceberg: boolean (required) - Whether to discover Iceberg tables

Responses:
  200:  → RegisterStorageResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### POST /v1/storages/az
Register an Azure Blob or ADLS Gen2 storage connection
Auth: None

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: RegisterAzRequest
    - accountName: string (required) - Azure object store account name. Used as catalog
    - container: string (required) - Azure object store container name. Used as schema for the registration
    - accessKey: string  - Optional Azure access key
    - sasToken: string  - Optional Azure SAS token
    - bearerToken: string  - Optional bearer token for temporary credentials
    - useFabricEndpoint: boolean (required) - Optional if fabric endpoint must be used. This includes access to onelake
    - basePath: string (required) - Base path to scan for Delta tables (optional)
    - discoverDelta: boolean (required) - Whether to discover Delta tables
    - discoverIceberg: boolean (required) - Whether to discover Iceberg tables

Responses:
  200:  → RegisterStorageResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### GET /v1/storages/tables
List registered tables
Auth: None

Parameters:
  - with_discovery [query] boolean (optional)

Responses:
  200:  → GetRegisteredTableResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### GET /v1/storages/configs
List storage configurations
Auth: None

Responses:
  200:  → GetUserConfigs
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### DELETE /v1/storages/configs/{config_id}
Delete a storage configuration
Auth: None

Parameters:
  - config_id [path] string (required)

Responses:
  200:  → DeleteStorageConfigResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### POST /v1/storages/uploads
Upload files to a storage path
Auth: None

Request Body:
  Content-Type: multipart/form-data
  Schema: object
    - path: string (required) - Destination path within the storage configuration (e.g. `"data/raw/2024/"`)
    - files: array (required) - One or more files to upload.

Responses:
  200:  → EmptyResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### GET /v1/storages/configs/{config_id}/objects
List objects from a storage configuration
Auth: None

Parameters:
  - config_id [path] string (required)
  - path [query] string (optional)
  - extensions [query] string (optional)
  - limit [query] integer (optional)
  - continuation_token [query] string (optional)
  - delimiter [query] boolean (optional)

Responses:
  200:  → ListObjectsResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### DELETE /v1/storages/configs/{config_id}/objects
Delete an object from a storage configuration
Auth: None

Parameters:
  - config_id [path] string (required)
  - path [query] string (required)

Responses:
  200:  → DeleteObjectResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### GET /v1/storages/configs/{config_id}/objects/download
Download or preview an object from a storage configuration
Auth: None

Parameters:
  - config_id [path] string (required)
  - path [query] string (required)
  - inline [query] boolean (optional)

Responses:
  200: Binary file content
  400: Bad request
  403: Forbidden
  404: Not found
  500: Internal server error

---

## Table
Inspect table metadata, version history, constraints, and field metadata.
Perform schema inference and AI-powered analysis on Delta Lake tables.

### GET /v1/tables/{catalog}/{schema}/{table_name}
Get table metadata
Auth: None

Responses:
  200:  → TableMetadata
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### POST /v1/tables/{catalog}/{schema}/{table_name}/constraints
Add table constraints
Auth: None

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: AddConstraintsRequest
    - constraints: array (required) - One or more named check constraints (SQL expressions).

Responses:
  200:  → EmptyResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### DELETE /v1/tables/{catalog}/{schema}/{table_name}/constraints/{constraint_name}
Drop a table constraint
Auth: None

Responses:
  200:  → EmptyResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### GET /v1/tables/{catalog}/{schema}/{table_name}/history
Get table version history
Auth: None

Responses:
  200:  → array
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### PUT /v1/tables/{catalog}/{schema}/{table_name}/rollback/{version_number}
Rollback table to a previous version
Auth: None

Responses:
  200:  → EmptyResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### PUT /v1/tables/{catalog}/{schema}/{table_name}/fields/metadata
Update field metadata
Auth: None

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: UpdateFieldMetadataRequest
    - fieldName: string (required) - Name of the column whose metadata should be updated.
    - metadata: object (required) - Key-value pairs to merge into the field's Arrow metadata.

Responses:
  200:  → EmptyResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### POST /v1/tables/{catalog}/{schema}/{table_name}/enums/check
Check if an enum value is in use
Auth: None

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: CheckDeleteEnumViolationRequest
    - fieldName: string (required) - Column name that has the fixed domain.
    - value: string (required) - The enum value to check for usage.

Responses:
  200:  → EmptyResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### POST /v1/tables/infer
Infer schema from a CSV file
Auth: None

Request Body:
  Content-Type: multipart/form-data
  Schema: object
    - file: string (required) - The CSV file to analyze.
    - hasHeader: boolean (required) - Whether the first row is a header row.
    - delimiter: string (required) - Column delimiter character (e.g. `","`, `";"`, `"\t"`).

Responses:
  200:  → InferSchemaResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### POST /v1/tables/{catalog}/{schema}/{table_name}/magic-dust
Execute LLM-powered analysis actions on your table data.
Auth: None

Parameters:
  - catalog [path] string (required)
  - schema [path] string (required)
  - table_name [path] string (required)

Request Body:
  Content-Type: application/json; charset=utf-8
  Schema: MagicDustRequest
    - provider: any (required) - AI provider whose model to use (e.g. `Claude`, `OpenAI`, `Gemini`, `Mistral`).
    - action: any (required) - The analysis action to perform (`summary`, `detect_anomalies`, `find_duplicates`, `fix_nulls`).
    - model: string (required) - Model identifier (e.g. `"claude-sonnet-4-5"`, `"gpt-5.2"`). Must be valid for the chosen provider.
    - max_tokens: integer  - Maximum tokens for the LLM response. Defaults to `4096`.
    - sample_size: integer  - Maximum number of rows to sample from the table. Defaults to `1000`.

Responses:
  200:  → MagicDustResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

---

## User
Retrieve and update the authenticated user's profile, and manage linked identities.

### GET /v1/users/me
Get current user profile
Auth: None

Responses:
  200:  → User
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

### DELETE /v1/users/identities/{identity_id}/unlink
Unlink an identity provider
Auth: None

Parameters:
  - identity_id [path] string (required)

Responses:
  200:  → EmptyResponse
  204: 
  205: 
  400:  → ApiError
  403:  → ApiError
  404:  → ApiError
  500:  → ApiError

---

## Schemas

### AIAction
Type: string
Enum: summary, detect_anomalies, find_duplicates, fix_nulls

### AIProviderKind
Type: string
Enum: claude, gemini, mistral, ollama, openai

### AddChildRequest
Request to add a child value under a hierarchical parent.
Type: object
Properties:
  - child: string (required) - The child value to add.

### AddConstraintsRequest
Request to add check constraints to an existing table.
Type: object
Properties:
  - constraints: array (required) - One or more named check constraints (SQL expressions).

### AddSeatTypeRequest
Request to add a new seat type to a subscription
Type: object
Properties:
  - priceId: string (required) - The Stripe price ID for the seat type to add
  - quantity: integer [int32] (required) - Initial quantity (number of seats)

### AddValueRequest
Request to add a single value to a fixed or hierarchical domain.
Type: object
Properties:
  - value: string (required) - The value to add.

### AiCredentialResponse
Response representing a single AI credential (API key is never included).
Type: object
Properties:
  - id: string [uuid] (required) - Unique identifier of this credential record.
  - provider: allOf (required) - The AI provider this credential is for.
  - base_url: string  - Custom base URL, if one was configured.
  - created_at: string (required) - When the credential was first created (ISO 8601).
  - updated_at: string (required) - When the credential was last updated (ISO 8601).

### AiCredentialsListResponse
Response containing a list of the user's AI credentials.
Type: object
Properties:
  - credentials: array (required) - All credentials owned by the authenticated user.

### AllowedValuePayload
A domain value returned in read responses (ID may be absent for derived values).
Type: object
Properties:
  - id: string [uuid]  - UUID of this domain value, or `null` for values resolved from external sources.
  - value: string (required) - The string value.

### AllowedValuesResponse
Response containing the resolved allowed values for a column.
Type: object
Properties:
  - column_name: string (required) - The column whose allowed values are returned.
  - parent_value: string  - If this is a hierarchical domain, the parent value that was used to filter children.
  - allowed_values: array (required) - The list of values the column currently accepts.

### ApiError
Type: object
Properties:
  - code: integer [int32] (required) - Your internal / business error code
  - message: string (required) - Human readable message

### ApiKeyResponse
API key details (shown in list/get responses)
Type: object
Properties:
  - id: string [uuid] (required) - Unique identifier for the API key
  - name: string (required) - Name of the API key
  - key_prefix: string (required) - Key prefix for identification (first 16 characters)
  - scopes: array (required) - Scopes granted to this API key
  - expires_at: string  - Optional expiration timestamp (ISO 8601 format)
  - last_used_at: string  - When the API key was last used (ISO 8601 format)
  - created_at: string (required) - When the API key was created (ISO 8601 format)
  - is_revoked: boolean (required) - Whether the API key has been revoked

### AppMetadata
Metadata about how the user first signed up and what providers they can use.
Type: object
Properties:
  - provider: string (required) - The primary provider (e.g. `"email"`, `"github"`, etc.).
  - providers: array (required) - All linked providers for this user.

### AzureBlobContainer
A single Azure Blob Storage container.
Type: object
Properties:
  - id: string (required) - Azure resource ID of the container.
  - name: string (required) - Container name.

### AzureExplorer
Top-level response containing all Azure subscriptions visible to the user.
Type: object
Properties:
  - subscriptions: array (required) - Azure subscriptions the user has access to.

### AzureStorageAccount
An Azure Storage account and its blob containers.
Type: object
Properties:
  - id: string (required) - Azure resource ID of the storage account.
  - name: string (required) - Storage account name.
  - containers: array (required) - Blob containers within this storage account.

### AzureSubscription
An Azure subscription with its storage accounts.
Type: object
Properties:
  - id: string (required) - Azure subscription ID (GUID).
  - name: string (required) - Human-readable display name of the subscription.
  - storageAccounts: array (required) - Storage accounts within this subscription.

### BillingPortalResponse
Type: object
Properties:
  - url: string (required)

### CancelSubscriptionRequest
Type: object
Properties:
  - cancelAtPeriodEnd: boolean  - If true, cancel at the end of the current billing period.
If false, cancel immediately.

### CheckDeleteEnumViolationRequest
Request to check whether an enum (fixed-domain) value is referenced by any rows.
Type: object
Properties:
  - fieldName: string (required) - Column name that has the fixed domain.
  - value: string (required) - The enum value to check for usage.

### ColumnDomainPayload
The full domain definition for a column.
Type: object
Properties:
  - type: string (required) - Domain type: `"fixed"`, `"hierarchical"`, or `"reference"`.
  - allowed_values: array  - Allowed values (present for fixed domains).
  - parent_column: string  - Parent column name (present for hierarchical domains).
  - lookup: allOf  - Lookup source configuration (present for hierarchical domains).
  - reference_source: allOf  - Source table reference (present for reference domains).

### ColumnDomainResponse
Response describing the domain configuration for a column.
Type: object
Properties:
  - column_name: string (required) - The column name.
  - domain: allOf  - The domain configuration, or `null` if no domain is set.

### ColumnStatistic
Type: object
Properties:
  - nullCount: integer [uint64] (required) - Number of null values on column
  - distinctCount: integer [uint64] (required) - Number of distinct values

### Constraint
Type: object
Properties:
  - name: string (required)
  - expr: string (required)

### CreateAiCredentialBody
Request body for creating or updating an AI credential.
Type: object
Properties:
  - provider: allOf (required) - The AI provider (e.g. `OpenAI`, `Claude`, `Gemini`, `Mistral`).
  - api_key: string (required) - The secret API key issued by the provider. Stored encrypted and never returned.
  - base_url: string  - Custom base URL for self-hosted or proxy endpoints (e.g. Azure OpenAI).
Leave `null` to use the provider's default endpoint.

### CreateApiKeyRequest
Request to create a new API key
Type: object
Properties:
  - name: string (required) - A unique name for this API key (for your reference)
  - scopes: array  - List of scopes to grant to this API key
  - expires_in: string  - Expiration duration: "7d", "30d", "90d", "1y", or "never" (recommended)
  - expires_at: string  - Optional expiration date (ISO 8601 format). Use expires_in instead for convenience.

### CreateApiKeyResponse
Response when creating a new API key (includes the full key - only shown once!)
Type: object
Properties:
  - key: string (required) - The full API key - SAVE THIS! It will only be shown once.
  - api_key: allOf (required) - Details about the created API key

### CreateSubscriptionRequest
Request to create or manage a subscription
Type: object
Properties:
  - step: allOf (required) - The step in the subscription flow
  - priceId: string  - Price ID for the subscription (required for finalize step)
  - quantity: integer [int32]  - Number of seats (optional, defaults to 1)
  - paymentMethodId: string  - Payment method ID from Stripe (required for finalize and update-payment-method steps)

### CreateSubscriptionResponse
Response from subscription creation flow
Type: object
Properties:
  - step: allOf (required) - The step that was executed
  - clientSecret: string  - Client secret for SetupIntent (returned in setup step)
  - subscriptionId: string  - Subscription ID (returned in finalize step)
  - status: enum  - Current subscription status
  - isTrial: boolean  - Whether the subscription is in trial
  - message: string (required) - Success message

### DeleteCredentialResponse
Response confirming whether a credential was deleted.
Type: object
Properties:
  - deleted: boolean (required) - `true` if the credential existed and was deleted; `false` if it was not found.

### DeleteObjectResponse
Response for deleting an object from a storage configuration
Type: object
Properties:
  - path: string (required) - Path of the deleted object
  - message: string (required) - Success message

### DeleteStorageConfigResponse
Type: object
Properties:
  - configId: string [uuid] (required)
  - configName: string (required)
  - message: string (required)

### DomainValuePayload
A domain value with a stable identifier (used in write requests).
Type: object
Properties:
  - id: string [uuid] (required) - Stable UUID for this domain value, used for referencing in hierarchical mappings.
  - value: string (required) - The string value of this domain entry.

### EditRoleRequest
Type: object
Properties:
  - role: string (required) - Organisation role defining what actions a user can perform.

Role hierarchy (cumulative permissions):
- **Viewer**: Read-only access (queries, exports, view schema)
- **Editor**: + write data (CRUD on rows, imports)
- **Builder**: + schema, domains, storage connections, API keys
- **Admin**: + user management, billing, org settings

### EmptyResponse
Type: object

### FixedDomainRequest
Request to create a fixed (enum) domain on a column.
Type: object
Properties:
  - allowed_values: array (required) - The complete list of allowed string values for this column.

### GetRegisteredTableResponse
Type: object
Properties:
  - fileExplorer: object (required) - Tree structure of registered tables discovered across connected object stores

### GetUserConfigs
Type: object
Properties:
  - configs: array (required)

### HierarchicalDerivedRequest
Request to create a hierarchical derived domain.
Child values are automatically derived from existing table data.
Type: object
Properties:
  - parent_column: string (required) - Name of the parent column.

### HierarchicalInlineRequest
Request to create a hierarchical inline domain on a column.
Parent-child mappings are stored directly in the domain metadata.
Type: object
Properties:
  - parent_column: string (required) - Name of the parent column that controls which child values are valid.
  - mappings: object (required) - Map from parent value ID to the list of allowed child values.

### HierarchicalTableRequest
Request to create a hierarchical table-lookup domain.
Parent-child relationships are resolved from an external lookup table.
Type: object
Properties:
  - parent_column: string (required) - Name of the parent column.
  - table_name: string (required) - Name of the lookup table containing the parent-child mapping.
  - table_path: string (required) - Storage path of the lookup table (e.g. `s3://bucket/path/to/table`).
  - parent_key: string (required) - Column in the lookup table that matches the parent value.
  - child_key: string (required) - Column in the lookup table that provides the child values.

### InferSchemaResponse
Response from CSV schema inference.
Type: object
Properties:
  - schema: object (required) - The inferred Arrow schema.
  - fieldsWithDomains: object (required) - Columns that are candidates for fixed-domain constraints, mapped to their distinct values.
  - length: integer [uint64] (required) - Total number of data rows in the file (excluding header).

### InviteUserRequest
Type: object
Properties:
  - email: string [email] (required)
  - role: string (required) - Organisation role defining what actions a user can perform.

Role hierarchy (cumulative permissions):
- **Viewer**: Read-only access (queries, exports, view schema)
- **Editor**: + write data (CRUD on rows, imports)
- **Builder**: + schema, domains, storage connections, API keys
- **Admin**: + user management, billing, org settings
  - seatType: allOf  - Optional seat type for the invited user (defaults to 'standard')

### InvoiceResponse
Type: object
Properties:
  - id: string (required)
  - amountDue: integer [int64] (required)
  - amountPaid: integer [int64] (required)
  - currency: string (required)
  - status: string (required)
  - created: integer [int64] (required)
  - dueDate: integer [int64] 
  - hostedInvoiceUrl: string 
  - invoicePdf: string 

### ListApiKeysResponse
Response for listing API keys
Type: object
Properties:
  - api_keys: array (required) - List of API keys owned by the user

### ListObjectsResponse
Response for listing objects in a storage configuration
Type: object
Properties:
  - objects: array (required) - List of objects matching the query
  - commonPrefixes: array (required) - Virtual directories (only in delimiter mode)
  - nextContinuationToken: string  - Token for next page, null if no more results
  - hasMore: boolean (required) - Whether more results are available
  - count: integer [uint64] (required) - Number of objects in this response

### LookupSourcePayload
Configuration for how hierarchical child values are resolved.
Type: object
Properties:
  - source: string (required) - Lookup strategy: `"inline"`, `"derived"`, or `"table"`.
  - mappings: object  - Parent-ID → children mappings (present for inline lookups).
  - table_name: string  - Lookup table name (present for table lookups).
  - table_path: string  - Storage path of the lookup table (present for table lookups).
  - parent_key: string  - Column in the lookup table matching the parent value (present for table lookups).
  - child_key: string  - Column in the lookup table providing child values (present for table lookups).

### MagicDustRequest
Request body for AI-powered table analysis (Magic Dust).
Type: object
Properties:
  - provider: allOf (required) - AI provider whose model to use (e.g. `Claude`, `OpenAI`, `Gemini`, `Mistral`).
  - action: allOf (required) - The analysis action to perform (`summary`, `detect_anomalies`, `find_duplicates`, `fix_nulls`).
  - model: string (required) - Model identifier (e.g. `"claude-sonnet-4-5"`, `"gpt-5.2"`). Must be valid for the chosen provider.
  - max_tokens: integer [uint32]  - Maximum tokens for the LLM response. Defaults to `4096`.
  - sample_size: integer [uint64]  - Maximum number of rows to sample from the table. Defaults to `1000`.

### MagicDustResponse
Response from an AI-powered table analysis (Magic Dust).
Type: object
Properties:
  - action: allOf (required) - The analysis action that was performed.
  - model: string (required) - The model identifier that was used.
  - content: string (required) - The natural-language analysis result produced by the LLM.
  - usage: allOf  - Token usage breakdown, if reported by the provider.

### OauthProvider
Type: string
Enum: azure, gitHub, google

### ObjectEntry
Individual object entry in listing response
Type: object
Properties:
  - path: string (required) - Full path/key of the object
  - name: string (required) - File name only (last component of path)
  - extension: string  - File extension without dot, if any
  - size: integer [uint64] (required) - Size in bytes
  - lastModified: string (required) - ISO 8601 timestamp of last modification
  - etag: string  - Entity tag if available
  - isDirectory: boolean (required) - True for directory entries (delimiter mode)

### OrganisationConfig
Type: object
Properties:
  - table_constraints: any 

### OrganisationResponse
Type: object
Properties:
  - id: string [uuid] (required)
  - name: string (required)
  - owner: string [uuid] (required)
  - config: object (required)
  - subscription: object 
  - userMembership: allOf  - The current user's membership details (role and seat type).
Only populated when fetching the user's own organisation (/me endpoint).
  - userCount: integer [int64] 
  - createdAt: string (required)
  - updatedAt: string (required)
  - deletedAt: string 

### OrganisationRole
Organisation role defining what actions a user can perform.

Role hierarchy (cumulative permissions):
- **Viewer**: Read-only access (queries, exports, view schema)
- **Editor**: + write data (CRUD on rows, imports)
- **Builder**: + schema, domains, storage connections, API keys
- **Admin**: + user management, billing, org settings
Type: string
Enum: admin, builder, editor, viewer

### OrganisationUserCompositionResponse
Type: object
Properties:
  - id: string [uuid] (required) - Unique user identifier (UUID).
  - aud: string (required) - Audience claim from the JWT (e.g. `"authenticated"`).
  - role: string (required) - Organisation role defining what actions a user can perform.

Role hierarchy (cumulative permissions):
- **Viewer**: Read-only access (queries, exports, view schema)
- **Editor**: + write data (CRUD on rows, imports)
- **Builder**: + schema, domains, storage connections, API keys
- **Admin**: + user management, billing, org settings
  - email: string  - Primary email address, if set.
  - email_confirmed_at: string  - Timestamp when the email was confirmed (ISO 8601).
  - phone: string  - Phone number, if set.
  - phone_confirmed_at: string  - Timestamp when the phone was confirmed (ISO 8601).
  - confirmed_at: string  - Timestamp when the account was confirmed (ISO 8601).
  - last_sign_in_at: string  - Timestamp of the most recent sign-in (ISO 8601).
  - app_metadata: allOf (required) - Provider and linked-provider information set by the auth system.
  - user_metadata: any (required) - Arbitrary JSON metadata editable by the user.
  - created_at: string (required) - Account creation timestamp (ISO 8601).
  - updated_at: string (required) - Last profile update timestamp (ISO 8601).
  - deleted_at: string  - Soft-deletion timestamp, if the account has been deleted (ISO 8601).
  - is_anonymous: boolean (required) - Whether this is an anonymous (guest) account.
  - seatType: allOf (required) - The user's seat type (standard, full, premium)

### PlanType
Plan type distinguishing between individual and team plans
Type: string
Enum: individual, team

### PricingTier
A pricing tier within a product/plan
Type: object
Properties:
  - price_id: string (required) - The price ID (use this when creating subscriptions)
  - name: string (required) - Name of this pricing tier (e.g., "Standard", "Premium")
  - unit_amount: integer [int64] (required) - Price in smallest currency unit (e.g., cents for USD)
  - currency: string (required) - Three-letter ISO currency code (e.g., "usd", "eur")
  - recurring: allOf  - Recurring billing information
  - lookup_key: string  - Optional lookup key for identifying this price

### ProductPlan
A product/plan with its pricing tiers
Type: object
Properties:
  - product_id: string (required) - Stripe product ID
  - name: string (required) - Name of the product/plan (e.g., "Team Plan", "Individual Plan")
  - description: string  - Optional description
  - plan_type: allOf (required) - Type of plan (individual or team)
  - minimum_seats: integer [int32]  - Minimum seats required (only applies to team plans)
  - pricing_tiers: array (required) - Available pricing tiers for this product

### RecoverUserRequest
Type: object
Properties:
  - email: string [email] (required)

### RecurringInfo
Recurring billing interval information
Type: object
Properties:
  - interval: string (required) - Billing interval (e.g., "month", "year")
  - interval_count: integer [int32] (required) - Number of intervals between billings (e.g., 1 for monthly, 12 for yearly)

### ReferenceDomainRequest
Request to set a reference domain on a column
Type: object
Properties:
  - table_path: string (required) - The storage path of the source table (e.g., "s3://bucket/path/to/table")
  - table_reference: allOf (required) - Full table reference (catalog, schema, table)
  - column: string (required) - The column name in the source table whose domain to reference

### ReferenceSourcePayload
Payload for reference domain source
Type: object
Properties:
  - table_path: string (required) - The storage path of the source table (e.g., "s3://bucket/path/to/table")
  - table_reference: allOf (required) - Full table reference (catalog, schema, table)
  - column: string (required) - The column name in the source table whose domain to reference

### RefreshToken
Request body containing a refresh token.
Type: object
Properties:
  - refreshToken: string (required) - The refresh token obtained from a previous sign-in or token refresh.

### RegisterAzRequest
Type: object
Properties:
  - accountName: string (required) - Azure object store account name. Used as catalog
  - container: string (required) - Azure object store container name. Used as schema for the registration
  - accessKey: string  - Optional Azure access key
  - sasToken: string  - Optional Azure SAS token
  - bearerToken: string  - Optional bearer token for temporary credentials
  - useFabricEndpoint: boolean (required) - Optional if fabric endpoint must be used. This includes access to onelake
  - basePath: string (required) - Base path to scan for Delta tables (optional)
  - discoverDelta: boolean (required) - Whether to discover Delta tables
  - discoverIceberg: boolean (required) - Whether to discover Iceberg tables

### RegisterS3Request
Type: object
Properties:
  - accessKeyId: string  - S3 access key ID
  - secretKey: string  - S3 secret access key
  - sessionToken: string  - Optional session token for temporary credentials
  - region: string (required) - AWS region (e.g., "us-east-1")
  - bucketName: string (required) - S3 bucket name
  - endpoint: string  - S3 endpoint URL (optional, only needed for S3-compatible services like MinIO)
  - basePath: string  - Base path to scan for Delta tables (optional)
  - schemaName: string  - Schema name for registering tables in DataFusion
  - discoverDelta: boolean (required) - Whether to discover Delta tables
  - discoverIceberg: boolean (required) - Whether to discover Iceberg tables

### RegisterStorageResponse
Type: object
Properties:
  - deltaTablesCount: integer [uint64] (required) - Number of Delta tables discovered
  - icebergTablesCount: integer [uint64] (required) - Number of Iceberg tables discovered
  - totalTables: integer [uint64] (required) - Total number of tables registered
  - message: string (required) - Success message
  - discoveryTimeMs: integer [uint64] (required) - Time taken for discovery in milliseconds

### RenameOrganisationRequest
Type: object
Properties:
  - name: string (required)

### RevokeApiKeyResponse
Response when deleting/revoking an API key
Type: object
Properties:
  - success: boolean (required) - Whether the API key was successfully revoked
  - message: string (required) - Message describing the result

### SeatType
Seat type for subscription items
- Standard: Available for both Individual and Team plans (default tier)
- Full: Individual plans only (full access tier)
- Premium: Team plans only (premium seats with enhanced features)
Type: string
Enum: standard, full, premium

### SetChildrenRequest
Request to replace all children under a hierarchical parent.
Type: object
Properties:
  - children: array (required) - The new complete list of child values (replaces all existing children).

### SetValuesRequest
Request to replace all values in a fixed domain.
Type: object
Properties:
  - values: array (required) - The new complete list of allowed values (replaces all existing values).

### SubscriptionItemResponse
Response for a subscription item (seat type with quantity)
Type: object
Properties:
  - subscriptionItemId: string (required) - Stripe subscription item ID
  - priceId: string (required) - Stripe price ID
  - seatType: allOf (required) - The seat type
  - quantity: integer [int32] (required) - Number of seats purchased
  - userCount: integer [int64] (required) - Number of users actually assigned to this seat type

### SubscriptionPlansResponse
Response containing available subscription plans grouped by product
Type: object
Properties:
  - products: array (required) - List of available products with their pricing tiers

### SubscriptionResponse
Type: object
Properties:
  - id: string (required)
  - customer: string (required)
  - status: enum (required) - Subscription enum status (e.g. Trialing, Incomplete, Paid)
  - quantity: integer [int32] (required)
  - planType: string  - Plan type distinguishing between individual and team plans
  - cancelAtPeriodEnd: boolean  - Only available when fetched from Stripe (not from cached data)
  - canceledAt: integer [int64] 
  - currentPeriodStart: integer [int64] 
  - currentPeriodEnd: integer [int64] 
  - trialStart: integer [int64] 
  - trialEnd: integer [int64] 
  - billingInterval: string 
  - hasDiscounts: boolean 
  - currency: string 
  - defaultPaymentMethod: string 

### SubscriptionStep
Step in the subscription creation flow
Type: string
Enum: setup, finalize, update-payment-method

### TableHistoryItem
Type: object
Properties:
  - version: integer [int64] (required) - Version of the commit
  - timestamp: integer [int64]  - Timestamp in millis when the commit was created
  - userId: string  - Id of the user invoking the commit
  - userName: string  - Name of the user invoking the commit
  - operation: string  - The operation performed during the
  - operationParameters: object  - Parameters used for table operation
  - engineInfo: string  - Query Engine which created the commit.
  - info: object (required) - Additional provenance information for the commit
  - userMetadata: string  - User defined metadata

### TableMetadata
Type: object
Properties:
  - id: string (required)
  - description: string (required)
  - version: integer [int64] (required)
  - tableName: string (required)
  - tableType: string (required)
  - fileName: string (required)
  - filePath: string (required)
  - fileSize: integer [uint64] (required)
  - mode: string (required)
  - numRows: integer [uint64] (required)
  - schema: object  - Apache Arrow Schema definition
  - constraints: array 
  - columnStatistics: array (required)
  - createdAt: integer [int64] 

### TableReference
Type: object
Properties:
  - catalog: string (required) - The catalog (aka database) containing the table
  - schema: string (required) - The schema containing the table
  - table: string (required) - The table name

### TableType
Type: string
Enum: DELTA, ICEBERG, UNDEFINED

### TokenUsage
Token usage breakdown for an LLM request.
Type: object
Properties:
  - input_tokens: integer [uint32] (required) - Number of tokens in the prompt sent to the model.
  - output_tokens: integer [uint32] (required) - Number of tokens generated by the model.

### UpdateApiKeyRequest
Request to update an API key
Type: object
Properties:
  - name: string  - New name for the API key
  - scopes: array  - New scopes for the API key
  - expires_at: string  - New expiration date (ISO 8601 format, empty string to remove expiration)

### UpdateFieldMetadataRequest
Request to update the metadata of a single table field.
Type: object
Properties:
  - fieldName: string (required) - Name of the column whose metadata should be updated.
  - metadata: object (required) - Key-value pairs to merge into the field's Arrow metadata.

### UpdateSeatTypeQuantityRequest
Request to update the quantity of a seat type
Type: object
Properties:
  - quantity: integer [int32] (required) - New quantity (number of seats)

### UpdateSubscriptionQuantityRequest
Type: object
Properties:
  - quantity: integer [int32] (required)

### UpdateUserSeatTypeRequest
Request to update a user's seat type
Type: object
Properties:
  - seatType: string (required) - Seat type for subscription items
- Standard: Available for both Individual and Team plans (default tier)
- Full: Individual plans only (full access tier)
- Premium: Team plans only (premium seats with enhanced features)

### UpgradePlanRequest
Type: object
Properties:
  - priceId: string (required) - The new Stripe price ID to upgrade to
  - planType: allOf (required) - The plan type (individual or team)
  - quantity: integer [int32]  - Optional new quantity (for team plans, minimum 5 seats required)

### UpgradeSeatTypeRequest
Request to upgrade seats from one type to another.

This atomically reduces the source seat type and increases the target seat type,
ensuring proper proration (only the price difference is charged).
Type: object
Properties:
  - fromSeatType: allOf (required) - The seat type to upgrade from (e.g., "standard")
  - toSeatType: allOf (required) - The seat type to upgrade to (e.g., "premium")
  - toPriceId: string (required) - The Stripe price ID for the target seat type
  - quantity: integer [int32] (required) - Number of seats to upgrade

### User
The authenticated user's profile.
Type: object
Properties:
  - id: string [uuid] (required) - Unique user identifier (UUID).
  - aud: string (required) - Audience claim from the JWT (e.g. `"authenticated"`).
  - role: string (required) - Supabase role (e.g. `"authenticated"`).
  - email: string  - Primary email address, if set.
  - email_confirmed_at: string  - Timestamp when the email was confirmed (ISO 8601).
  - phone: string  - Phone number, if set.
  - phone_confirmed_at: string  - Timestamp when the phone was confirmed (ISO 8601).
  - confirmed_at: string  - Timestamp when the account was confirmed (ISO 8601).
  - last_sign_in_at: string  - Timestamp of the most recent sign-in (ISO 8601).
  - app_metadata: allOf (required) - Provider and linked-provider information set by the auth system.
  - user_metadata: any (required) - Arbitrary JSON metadata editable by the user.
  - created_at: string (required) - Account creation timestamp (ISO 8601).
  - updated_at: string (required) - Last profile update timestamp (ISO 8601).
  - deleted_at: string  - Soft-deletion timestamp, if the account has been deleted (ISO 8601).
  - is_anonymous: boolean (required) - Whether this is an anonymous (guest) account.

### UserConfig
Type: object
Properties:
  - id: string [uuid] (required)
  - name: string (required)
  - path: string (required)
  - schemeType: enum (required) - The scheme type of an object store (S3, Abfss, Gs)
  - createdAt: string (required)

### UserMembershipResponse
The current user's membership in the organisation
Type: object
Properties:
  - role: allOf (required) - The user's role in the organisation
  - seatType: allOf (required) - The user's seat type