chore: make api doc language end-user focused

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-06-17
+
+### Changed
+
+- chore: make api doc language end-user focused
+
 ## [0.4.0] - 2026-06-16
 
 ### Added

docs/ConnectionsApi.md

@@ -23,7 +23,7 @@ Method | HTTP request | Description
 
 Add managed schema
 
-Declare a new schema (and optionally its tables) on an existing managed catalog after creation. The schema is added to the connection's declaration; declared tables can then be populated via the managed-table load endpoint. Only valid against connections whose source type is `managed`. Identifiers are normalised to lowercase.
+Declare a new schema (and optionally its tables) on an existing managed catalog after creation. The schema is added to the connection's declaration; declared tables can then be populated via the managed-table load endpoint. Only valid against connections whose source type is `managed`. Identifiers are normalized to lowercase.
 
 ### Example
 
@@ -114,7 +114,7 @@ Name | Type | Description  | Notes
 
 Add managed table
 
-Declare a new table on an existing schema of a managed catalog after creation. The table is added empty (declared-but-unloaded) and can be populated via the managed-table load endpoint. Only valid against connections whose source type is `managed`. Identifiers are normalised to lowercase.
+Declare a new table on an existing schema of a managed catalog after creation. The table is added empty (declared-but-unloaded) and can be populated via the managed-table load endpoint. Only valid against connections whose source type is `managed`. Identifiers are normalized to lowercase.
 
 ### Example
 
@@ -465,7 +465,7 @@ void (empty response body)
 
 Delete managed table
 
-Delete a single managed-catalog table. The catalog row is removed and the backing parquet file (if any) is scheduled for deletion. Only valid against connections whose source type is `managed`.
+Delete a single managed-catalog table. The table and its data are removed. Only valid against connections whose source type is `managed`.
 
 ### Example
 
@@ -810,7 +810,7 @@ This endpoint does not need any parameter.
 
 Load managed table from upload
 
-Publish a previously-uploaded parquet file as the new generation of a managed table. The upload must reference a parquet file (verified by magic bytes). Only `mode = "replace"` is supported. Concurrent loads against the same upload return 409.
+Publish a previously-uploaded parquet file as the new contents of a managed table. The upload must reference a parquet file. Only `mode = "replace"` is supported. Concurrent loads against the same upload return 409.
 
 ### Example
 
@@ -979,7 +979,7 @@ void (empty response body)
 | Status code | Description | Response headers |
 |-------------|-------------|------------------|
 **204** | Cache purged |  -  |
-**400** | Managed catalogs own their parquet generations and cannot be purged |  -  |
+**400** | Managed catalogs own their data and cannot be cache-purged |  -  |
 **404** | Connection not found |  -  |
 **409** | Connection backs a database's default catalog and cannot be purged directly |  -  |
 

docs/CreateConnectionRequest.md

@@ -12,7 +12,6 @@ Name | Type | Description | Notes
 **secret_name** | **str** | Optional reference to a secret by name. If provided, this secret will be used for authentication. Mutually exclusive with `secret_id`. | [optional] 
 **skip_discovery** | **bool** | If true, skip automatic schema discovery after registering the connection. The connection will be created but no tables will be discovered. You can run discovery later via the refresh endpoint. | [optional] 
 **source_type** | **str** |  | 
-**storage_backend** | **str** | Physical storage backend for tables created under this connection. `\"parquet\"` (default) uses the versioned parquet cache. `\"ducklake\"` stores data in a DuckLake catalog in the shared metadata DB configured via `ducklake.metadata_pg_url`; accepted for any source type and requires that pool to be configured. | [optional] 
 
 ## Example
 

docs/CreateDatabaseRequest.md

@@ -9,8 +9,7 @@ Name | Type | Description | Notes
 **default_catalog** | **str** | Optional name the database's auto-created default catalog answers to inside its query scope. Must be a valid SQL identifier (`[a-z0-9_]`, not starting with a digit) and may not collide with the system catalogs `hotdata`, `datasets`, or `information_schema`. Defaults to `default` when omitted, so `default.main.<table>` keeps working. | [optional] 
 **expires_at** | **str** | When this database expires. Accepts either an RFC 3339 timestamp (e.g. `\"2026-06-01T00:00:00Z\"`) or a relative duration suffixed with `h` (hours), `m` (minutes), or `d` (days) — for example `\"24h\"`, `\"48h\"`, or `\"7d\"`. Omitted (or empty) means the database never expires. Expiry is best-effort: the database will not be deleted before `expires_at`, but cleanup may run later than the exact timestamp. | [optional] 
 **name** | **str** | Optional free-form display label (for UIs/CLIs). Not unique. Not an identifier — databases are always addressed by `id`.  Accepts the legacy `description` key as an alias so clients that predate the rename keep populating this field. | [optional] 
-**schemas** | [**List[DatabaseDefaultSchemaDecl]**](DatabaseDefaultSchemaDecl.md) | Optional schemas/tables to declare on the database's auto-created default catalog. Mirrors the `config.schemas` field of a managed `POST /v1/connections`. Tables declared here can be loaded via the standard managed-table load endpoint targeting `default_connection_id`. Omitted or empty means the default catalog starts empty. | [optional] 
-**storage_backend** | **str** | Physical storage backend for the database's auto-created `default` catalog. `\"parquet\"` (default) uses the versioned parquet cache. `\"ducklake\"` stores data in a DuckLake catalog in the shared metadata DB configured via `ducklake.metadata_pg_url`, which must be configured for that value to be accepted. Omitted means `\"parquet\"`. | [optional] 
+**schemas** | [**List[DatabaseDefaultSchemaDecl]**](DatabaseDefaultSchemaDecl.md) | Optional schemas/tables to declare on the database's auto-created default catalog. Tables declared here can be loaded via the standard managed-table load endpoint targeting `default_connection_id`. Omitted or empty means the default catalog starts empty. | [optional] 
 
 ## Example
 

docs/CreateDatasetRequest.md

@@ -8,7 +8,6 @@ Name | Type | Description | Notes
 ------------ | ------------- | ------------- | -------------
 **label** | **str** |  | 
 **source** | [**DatasetSource**](DatasetSource.md) |  | 
-**storage_backend** | **str** | Optional storage backend: `\"parquet\"` (default) or `\"ducklake\"`. `\"ducklake\"` requires `ducklake.metadata_pg_url` to be configured at engine boot; the engine also rejects the combo of `storage_backend: \"ducklake\"` with a saved-query source or with explicit geometry columns (both deferred to a follow-up). | [optional] 
 **table_name** | **str** | Optional table_name - if not provided, derived from label | [optional] 
 
 ## Example

docs/DatabaseDefaultSchemaDecl.md

@@ -1,6 +1,6 @@
 # DatabaseDefaultSchemaDecl
 
-One schema declaration inside the database's default catalog at create time. Mirrors `crate::source::ManagedSchemaDecl`. Tables default to empty so callers can declare just a schema name and add tables later via the managed-tables API on the default connection.
+One schema declaration inside the database's default catalog, supplied at create time. `tables` defaults to empty, so you can declare just a schema name and add tables later.
 
 ## Properties
 

docs/DatabaseDefaultTableDecl.md

@@ -1,6 +1,6 @@
 # DatabaseDefaultTableDecl
 
-One table declaration inside a default-catalog schema at database-create time. Mirrors `crate::source::ManagedTableDecl` shape so the controller can convert with a simple `.map`.
+One table declaration inside a default-catalog schema, supplied at database-create time.
 
 ## Properties
 

docs/DatabasesApi.md

@@ -19,7 +19,7 @@ Method | HTTP request | Description
 
 Add schema to database default catalog
 
-Declare a new schema (and optionally its tables) on the database's auto-created default catalog after creation. The schema becomes reachable inside the database scope (e.g. `default.<schema>.<table>` and `information_schema.schemata`) without the caller addressing the internal default connection directly. Identifiers are normalised to lowercase.
+Declare a new schema (and optionally its tables) on the database's auto-created default catalog after creation. The schema becomes reachable inside the database scope (e.g. `default.<schema>.<table>` and `information_schema.schemata`) without the caller addressing the internal default connection directly. Identifiers are normalized to lowercase.
 
 ### Example
 
@@ -110,7 +110,7 @@ Name | Type | Description  | Notes
 
 Add table to database default catalog
 
-Declare a new table on an existing schema of the database's default catalog after creation. The table is added empty (declared-but-unloaded) and can be populated via the managed-table load endpoint targeting the default connection. Identifiers are normalised to lowercase.
+Declare a new table on an existing schema of the database's default catalog after creation. The table is added empty (declared-but-unloaded) and can be populated via the managed-table load endpoint targeting the default connection. Identifiers are normalized to lowercase.
 
 ### Example
 
@@ -291,7 +291,7 @@ void (empty response body)
 
 Create database
 
-Create a new database (a metadata-only grouping). A managed default catalog is auto-created and addressable inside the database as `default` (or the optional `default_catalog` name), with a `main` schema pre-declared so `default.main.<table>` works out of the box. The optional `name` is a free-form display label and is not required to be unique. Optional `default_catalog` overrides the name the default catalog answers to; it must be a valid SQL identifier and may not collide with the `hotdata`, `datasets`, or `information_schema` system catalogs. Optional `schemas` declares additional schemas/tables on the default catalog at create time; declared tables can be loaded via the standard managed-tables-load endpoint targeting `default_connection_id`. Optional `expires_at` sets when the database expires — accepts either an RFC 3339 timestamp or a relative duration suffixed with `h` (hours), `m` (minutes), or `d` (days), e.g. `24h`, `48h`, `90m`, `7d`. When omitted, the database never expires. Expiry is best-effort: the database will not be deleted before `expires_at`, but cleanup may run later than the exact timestamp. Optional `storage_backend` selects the physical backend for the default catalog — `parquet` (default) or `ducklake` (requires `ducklake.metadata_pg_url` to be configured).
+Create a new database (a metadata-only grouping). A managed default catalog is auto-created and addressable inside the database as `default` (or the optional `default_catalog` name), with a `main` schema pre-declared so `default.main.<table>` works out of the box. The optional `name` is a free-form display label and is not required to be unique. Optional `default_catalog` overrides the name the default catalog answers to; it must be a valid SQL identifier and may not collide with the `hotdata`, `datasets`, or `information_schema` system catalogs. Optional `schemas` declares additional schemas/tables on the default catalog at create time; declared tables can be loaded via the standard managed-tables-load endpoint targeting `default_connection_id`. Optional `expires_at` sets when the database expires — accepts either an RFC 3339 timestamp or a relative duration suffixed with `h` (hours), `m` (minutes), or `d` (days), e.g. `24h`, `48h`, `90m`, `7d`. When omitted, the database never expires. Expiry is best-effort: the database will not be deleted before `expires_at`, but cleanup may run later than the exact timestamp.
 
 ### Example
 

docs/IndexesApi.md

@@ -65,7 +65,7 @@ configuration = hotdata.Configuration(
 with hotdata.ApiClient(configuration) as api_client:
     # Create an instance of the API class
     api_instance = hotdata.IndexesApi(api_client)
-    dataset_id = 'dataset_id_example' # str | Dataset identifier
+    dataset_id = 'dataset_id_example' # str | Dataset ID
     create_index_request = hotdata.CreateIndexRequest() # CreateIndexRequest | 
 
     try:
@@ -84,7 +84,7 @@ with hotdata.ApiClient(configuration) as api_client:
 
 Name | Type | Description  | Notes
 ------------- | ------------- | ------------- | -------------
- **dataset_id** | **str**| Dataset identifier | 
+ **dataset_id** | **str**| Dataset ID | 
  **create_index_request** | [**CreateIndexRequest**](CreateIndexRequest.md)|  | 
 
 ### Return type
@@ -156,7 +156,7 @@ configuration = hotdata.Configuration(
 with hotdata.ApiClient(configuration) as api_client:
     # Create an instance of the API class
     api_instance = hotdata.IndexesApi(api_client)
-    connection_id = 'connection_id_example' # str | Connection identifier
+    connection_id = 'connection_id_example' # str | Connection ID
     var_schema = 'var_schema_example' # str | Schema name
     table = 'table_example' # str | Table name
     create_index_request = hotdata.CreateIndexRequest() # CreateIndexRequest | 
@@ -177,7 +177,7 @@ with hotdata.ApiClient(configuration) as api_client:
 
 Name | Type | Description  | Notes
 ------------- | ------------- | ------------- | -------------
- **connection_id** | **str**| Connection identifier | 
+ **connection_id** | **str**| Connection ID | 
  **var_schema** | **str**| Schema name | 
  **table** | **str**| Table name | 
  **create_index_request** | [**CreateIndexRequest**](CreateIndexRequest.md)|  | 
@@ -256,7 +256,7 @@ configuration = hotdata.Configuration(
 with hotdata.ApiClient(configuration) as api_client:
     # Create an instance of the API class
     api_instance = hotdata.IndexesApi(api_client)
-    dataset_id = 'dataset_id_example' # str | Dataset identifier
+    dataset_id = 'dataset_id_example' # str | Dataset ID
     index_name = 'index_name_example' # str | Index name
 
     try:
@@ -273,7 +273,7 @@ with hotdata.ApiClient(configuration) as api_client:
 
 Name | Type | Description  | Notes
 ------------- | ------------- | ------------- | -------------
- **dataset_id** | **str**| Dataset identifier | 
+ **dataset_id** | **str**| Dataset ID | 
  **index_name** | **str**| Index name | 
 
 ### Return type
@@ -341,7 +341,7 @@ configuration = hotdata.Configuration(
 with hotdata.ApiClient(configuration) as api_client:
     # Create an instance of the API class
     api_instance = hotdata.IndexesApi(api_client)
-    connection_id = 'connection_id_example' # str | Connection identifier
+    connection_id = 'connection_id_example' # str | Connection ID
     var_schema = 'var_schema_example' # str | Schema name
     table = 'table_example' # str | Table name
     index_name = 'index_name_example' # str | Index name
@@ -360,7 +360,7 @@ with hotdata.ApiClient(configuration) as api_client:
 
 Name | Type | Description  | Notes
 ------------- | ------------- | ------------- | -------------
- **connection_id** | **str**| Connection identifier | 
+ **connection_id** | **str**| Connection ID | 
  **var_schema** | **str**| Schema name | 
  **table** | **str**| Table name | 
  **index_name** | **str**| Index name | 
@@ -439,7 +439,7 @@ configuration = hotdata.Configuration(
 with hotdata.ApiClient(configuration) as api_client:
     # Create an instance of the API class
     api_instance = hotdata.IndexesApi(api_client)
-    dataset_id = 'dataset_id_example' # str | Dataset identifier
+    dataset_id = 'dataset_id_example' # str | Dataset ID
 
     try:
         # List indexes on a dataset
@@ -457,7 +457,7 @@ with hotdata.ApiClient(configuration) as api_client:
 
 Name | Type | Description  | Notes
 ------------- | ------------- | ------------- | -------------
- **dataset_id** | **str**| Dataset identifier | 
+ **dataset_id** | **str**| Dataset ID | 
 
 ### Return type
 
@@ -525,7 +525,7 @@ configuration = hotdata.Configuration(
 with hotdata.ApiClient(configuration) as api_client:
     # Create an instance of the API class
     api_instance = hotdata.IndexesApi(api_client)
-    connection_id = 'connection_id_example' # str | Connection identifier
+    connection_id = 'connection_id_example' # str | Connection ID
     var_schema = 'var_schema_example' # str | Schema name
     table = 'table_example' # str | Table name
 
@@ -545,7 +545,7 @@ with hotdata.ApiClient(configuration) as api_client:
 
 Name | Type | Description  | Notes
 ------------- | ------------- | ------------- | -------------
- **connection_id** | **str**| Connection identifier | 
+ **connection_id** | **str**| Connection ID | 
  **var_schema** | **str**| Schema name | 
  **table** | **str**| Table name | 
 

docs/JobType.md

@@ -16,6 +16,8 @@ Background job types returned by the API.
 
 * `CREATE_DATASET_INDEX` (value: `'create_dataset_index'`)
 
+* `MANAGED_LOAD` (value: `'managed_load'`)
+
 [[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
 
 

docs/LoadManagedTableRequest.md

@@ -1,6 +1,6 @@
 # LoadManagedTableRequest
 
-Request body for `POST /v1/connections/{connection_id}/schemas/{schema}/tables/{table}/loads`.  Publishes a previously-uploaded parquet file as the new generation for the named managed table. `mode` is fixed to `\"replace\"` today; the field is kept in the request body so future modes (e.g. append) are an additive change.
+Request body for `POST /v1/connections/{connection_id}/schemas/{schema}/tables/{table}/loads`.  Publishes a previously-uploaded parquet file as the new contents of the named managed table. `mode` is fixed to `\"replace\"` today; the field is kept in the request body so future modes (e.g. append) are an additive change.
 
 ## Properties
 

docs/LoadManagedTableResponse.md

@@ -6,7 +6,7 @@ Response body for `POST /v1/connections/{connection_id}/schemas/{schema}/tables/
 
 Name | Type | Description | Notes
 ------------ | ------------- | ------------- | -------------
-**arrow_schema_json** | **str** | Arrow schema (JSON) parsed from the uploaded parquet footer. | 
+**arrow_schema_json** | **str** | Schema of the loaded table, as JSON. | 
 **connection_id** | **str** |  | 
 **row_count** | **int** | Total rows in the published parquet file. | 
 **schema_name** | **str** |  | 

docs/ManagedSchemaResponse.md

@@ -1,6 +1,6 @@
 # ManagedSchemaResponse
 
-Response body for a successful add-schema request. Echoes the normalised (lowercased) names so callers see exactly what was persisted.
+Response body for a successful add-schema request. Echoes the normalized (lowercased) names so callers see exactly what was persisted.
 
 ## Properties
 

docs/QueryApi.md

@@ -106,6 +106,7 @@ Name | Type | Description  | Notes
 **404** | Database not found |  -  |
 **429** | Too many concurrent queries; retry after the Retry-After delay |  -  |
 **500** | Internal server error |  -  |
+**503** | Result store temporarily unavailable (a truncated result could not be persisted); retry after the Retry-After delay |  -  |
 
 [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)