Skip to main content

Egret warehouses API

Embedded-catalog warehouse management: warehouses, catalog roles/grants/clients, browse, and admin ops.

This page lists 30 endpoints (OpenAPI tag control-plane-catalog). It is generated from openapi.json; see the REST API overview for authentication, CSRF and error conventions.

MethodPathOperation idNotes
DELETE/api/control-plane/clients/{id}revoke_client
DELETE/api/control-plane/grants/{grant_id}revoke_grant
DELETE/api/control-plane/roles/{role_id}delete_role
GET/api/control-plane/roles/{role_id}/grantslist_grants
POST/api/control-plane/roles/{role_id}/grantsadd_grant
GET/api/control-plane/warehouseslist_warehouses
POST/api/control-plane/warehousescreate_warehouse
GET/api/control-plane/warehouses/{id}get_warehouse
DELETE/api/control-plane/warehouses/{id}delete_warehouse
GET/api/control-plane/warehouses/{id}/clientslist_clients
POST/api/control-plane/warehouses/{id}/clientscreate_client
GET/api/control-plane/warehouses/{id}/configwarehouse_config
PUT/api/control-plane/warehouses/{id}/delete-profileset_delete_profile_route
GET/api/control-plane/warehouses/{id}/deleted-tabularsbrowse_deleted
PUT/api/control-plane/warehouses/{id}/format-policyset_format_policy
GET/api/control-plane/warehouses/{id}/namespacesbrowse_namespaces
GET/api/control-plane/warehouses/{id}/namespaces/{ns}/tablesbrowse_tables
GET/api/control-plane/warehouses/{id}/namespaces/{ns}/tables/{table}browse_schema
GET/api/control-plane/warehouses/{id}/namespaces/{ns}/views/{view}browse_view
PUT/api/control-plane/warehouses/{id}/protectionset_protection
GET/api/control-plane/warehouses/{id}/roleslist_roles
POST/api/control-plane/warehouses/{id}/rolescreate_role
GET/api/control-plane/warehouses/{id}/searchsearch_tabulars
PUT/api/control-plane/warehouses/{id}/statusset_warehouse_status
PUT/api/control-plane/warehouses/{id}/storage-credentialrotate_credential
GET/api/control-plane/warehouses/{id}/taskslist_tasks
POST/api/control-plane/warehouses/{id}/undropundrop_tabular
GET/api/control-plane/warehouses/{warehouse_id}/resource-tagslist_resource_tags
PUT/api/control-plane/warehouses/{warehouse_id}/resource-tagsassign_resource_tag
DELETE/api/control-plane/warehouses/{warehouse_id}/resource-tagsunassign_resource_tag

DELETE /api/control-plane/clients/{id}​

Operation id: revoke_client. Auth: Session cookie and X-Egret-CSRF header. Forbidden (403): Missing catalog_registry:delete permission.

ParameterInTypeRequiredDescription
idpathstring (uuid)yesCatalog Client id
StatusMeaning
204Catalog Client revoked
401Not authenticated
403Missing catalog_registry:delete permission
500Internal error

DELETE /api/control-plane/grants/{grant_id}​

Operation id: revoke_grant. Auth: Session cookie and X-Egret-CSRF header. Forbidden (403): Missing catalog_registry:delete permission.

ParameterInTypeRequiredDescription
grant_idpathstring (uuid)yesGrant id
StatusMeaning
204Grant revoked
401Not authenticated
403Missing catalog_registry:delete permission
500Internal error

DELETE /api/control-plane/roles/{role_id}​

Operation id: delete_role. Auth: Session cookie and X-Egret-CSRF header. Forbidden (403): Missing catalog_registry:delete permission.

ParameterInTypeRequiredDescription
role_idpathstring (uuid)yesCatalog role id
StatusMeaning
204Catalog role deleted
400Role is in use by one or more Catalog Clients
401Not authenticated
403Missing catalog_registry:delete permission
500Internal error

GET /api/control-plane/roles/{role_id}/grants​

Operation id: list_grants. Auth: Session cookie. Forbidden (403): Missing catalog_registry:read permission.

ParameterInTypeRequiredDescription
role_idpathstring (uuid)yesCatalog role id

Response 200 (application/json): array of GrantDto

FieldTypeRequiredDescription
idstring (uuid)yes
securableTypestringyes
namespacestring[], nullableno
tableNamestring, nullableno
privilegestringyes
StatusMeaning
200Grants held by the catalog role
401Not authenticated
403Missing catalog_registry:read permission
500Internal error

POST /api/control-plane/roles/{role_id}/grants​

Operation id: add_grant. Auth: Session cookie and X-Egret-CSRF header. Forbidden (403): Missing catalog_registry:create permission.

ParameterInTypeRequiredDescription
role_idpathstring (uuid)yesCatalog role id

Request body (application/json): AddGrantBody

FieldTypeRequiredDescription
securableTypestringyes
namespacestring[], nullableno
tableNamestring, nullableno
privilegestringyes
StatusMeaning
201Grant added to the catalog role
400Invalid securable/privilege
401Not authenticated
403Missing catalog_registry:create permission
500Internal error

GET /api/control-plane/warehouses​

Operation id: list_warehouses. Auth: Session cookie. Forbidden (403): Missing catalog_registry:read permission.

Response 200 (application/json): array of WarehouseDto

FieldTypeRequiredDescription
idstring (uuid)yes
namestringyes
workspaceIdstring (uuid)yes
storageConnIdstring (uuid)yes
lakekeeperWarehouseIdstring, nullableno
StatusMeaning
200Embedded-catalog warehouses (egret rows)
401Not authenticated
403Missing catalog_registry:read permission
500Internal error

POST /api/control-plane/warehouses​

Operation id: create_warehouse. Auth: Session cookie and X-Egret-CSRF header. Forbidden (403): Missing catalog_registry:create permission.

Request body (application/json): CreateWarehouseBody

FieldTypeRequiredDescription
namestringyes
workspaceIdstring (uuid)yes
storageConnectionIdstring (uuid)yes

Response 201 (application/json): WarehouseDto

FieldTypeRequiredDescription
idstring (uuid)yes
namestringyes
workspaceIdstring (uuid)yes
storageConnIdstring (uuid)yes
lakekeeperWarehouseIdstring, nullableno
StatusMeaning
201Warehouse created (egret row + lakekeeper warehouse when a provisioner is wired) with its registry catalog, assigned to the workspace
400Unknown storage connection or invalid input
401Not authenticated
403Missing catalog_registry:create permission
409A warehouse with this name already exists
500Internal error
502Embedded catalog unreachable while provisioning

GET /api/control-plane/warehouses/{id}​

Operation id: get_warehouse. Auth: Session cookie. Forbidden (403): Missing catalog_registry:read permission.

ParameterInTypeRequiredDescription
idpathstring (uuid)yesWarehouse id

Response 200 (application/json): WarehouseDto

FieldTypeRequiredDescription
idstring (uuid)yes
namestringyes
workspaceIdstring (uuid)yes
storageConnIdstring (uuid)yes
lakekeeperWarehouseIdstring, nullableno
StatusMeaning
200The warehouse
401Not authenticated
403Missing catalog_registry:read permission
404No such warehouse
500Internal error

DELETE /api/control-plane/warehouses/{id}​

Operation id: delete_warehouse. Auth: Session cookie and X-Egret-CSRF header. Forbidden (403): Missing catalog_registry:delete permission.

ParameterInTypeRequiredDescription
idpathstring (uuid)yesWarehouse id
StatusMeaning
204Warehouse deleted
401Not authenticated
403Missing catalog_registry:delete permission
409The warehouse cannot be deleted yet: its registry catalog is attached to an engine, or a concurrent engine create has just created and assigned its catalog (retry)
500Internal error

GET /api/control-plane/warehouses/{id}/clients​

Operation id: list_clients. Auth: Session cookie. Forbidden (403): Missing catalog_registry:read permission.

ParameterInTypeRequiredDescription
idpathstring (uuid)yesWarehouse id

Response 200 (application/json): array of ClientDto

FieldTypeRequiredDescription
idstring (uuid)yes
namestringyes
consumerTypestringyes
catalogRoleIdstring (uuid)yes
clientIdstringyes
StatusMeaning
200Catalog Clients bound to the warehouse
401Not authenticated
403Missing catalog_registry:read permission
500Internal error

POST /api/control-plane/warehouses/{id}/clients​

Operation id: create_client. Auth: Session cookie and X-Egret-CSRF header. Forbidden (403): Missing catalog_registry:create permission.

ParameterInTypeRequiredDescription
idpathstring (uuid)yesWarehouse id

Request body (application/json): CreateClientBody

FieldTypeRequiredDescription
namestringyes
consumerTypestringyes
workspaceIdstring (uuid)yes
catalogRoleIdstring (uuid)yes

Response 201 (application/json): CreatedClientDto

FieldTypeRequiredDescription
idstring (uuid)yes
clientIdstringyes
clientSecretstringyesShown ONCE.
StatusMeaning
201Catalog Client created; client_secret is shown ONCE
400Unknown consumerType (engine or external)
401Not authenticated
403Missing catalog_registry:create permission
404No such warehouse or catalog role
500Internal error

GET /api/control-plane/warehouses/{id}/config​

Operation id: warehouse_config. Auth: Session cookie. Forbidden (403): Missing catalog_registry:read permission.

ParameterInTypeRequiredDescription
idpathstring (uuid)yesWarehouse id

Response 200 (application/json): WarehouseConfigDto

FieldTypeRequiredDescription
activebooleanyes
deleteProfileSecondsinteger (int64), nullableno
numTablesinteger (int64)yes
numViewsinteger (int64)yes
statsUpdatedMsinteger (int64)yes
StatusMeaning
200Warehouse admin config (status, soft-delete TTL, statistics)
401Not authenticated
403Missing catalog_registry:read permission
404No such warehouse/browser
500Internal error
502Embedded catalog unreachable

PUT /api/control-plane/warehouses/{id}/delete-profile​

Operation id: set_delete_profile_route. Auth: Session cookie and X-Egret-CSRF header. Forbidden (403): Missing catalog_registry:update permission.

ParameterInTypeRequiredDescription
idpathstring (uuid)yesWarehouse id

Request body (application/json): DeleteProfileBody

FieldTypeRequiredDescription
secondsinteger (int64), nullablenoSoft-delete retention in seconds; null = hard delete.
StatusMeaning
204Soft-delete retention updated
401Not authenticated
403Missing catalog_registry:update permission
404No such warehouse/browser
500Internal error
502Embedded catalog unreachable

GET /api/control-plane/warehouses/{id}/deleted-tabulars​

Operation id: browse_deleted. Auth: Session cookie. Forbidden (403): Missing catalog_registry:read permission.

ParameterInTypeRequiredDescription
idpathstring (uuid)yesWarehouse id

Response 200 (application/json): array of DeletedTabularDto

FieldTypeRequiredDescription
idstring (uuid)yes
namestringyes
namespacestring[]yes
kindstringyes
deletedAtstring (date-time)yes
expirationstring (date-time)yes
StatusMeaning
200Soft-deleted tables/views awaiting purge
401Not authenticated
403Missing catalog_registry:read permission
500Internal error
502Embedded catalog unreachable

PUT /api/control-plane/warehouses/{id}/format-policy​

Operation id: set_format_policy. Auth: Session cookie and X-Egret-CSRF header. Forbidden (403): Missing catalog_registry:update permission.

ParameterInTypeRequiredDescription
idpathstring (uuid)yesWarehouse id

Request body (application/json): FormatPolicyBody

FieldTypeRequiredDescription
versionsinteger (int32)[]yes
StatusMeaning
204Allowed Iceberg format versions updated
400At least one format version is required
401Not authenticated
403Missing catalog_registry:update permission
404No such warehouse/browser
500Internal error
502Embedded catalog unreachable

GET /api/control-plane/warehouses/{id}/namespaces​

Operation id: browse_namespaces. Auth: Session cookie. Forbidden (403): Missing catalog_registry:read permission.

ParameterInTypeRequiredDescription
idpathstring (uuid)yesWarehouse id

Response 200 (application/json): array of NamespaceDto

FieldTypeRequiredDescription
partsstring[]yes
idstring (uuid), nullableno
protectedbooleanyes
StatusMeaning
200Top-level namespaces (empty when no browser/lakekeeper warehouse is wired)
401Not authenticated
403Missing catalog_registry:read permission
500Internal error
502Embedded catalog unreachable

GET /api/control-plane/warehouses/{id}/namespaces/{ns}/tables​

Operation id: browse_tables. Auth: Session cookie. Forbidden (403): Missing catalog_registry:read permission.

ParameterInTypeRequiredDescription
idpathstring (uuid)yesWarehouse id
nspathstringyesDot-delimited namespace

Response 200 (application/json): array of TabularDto

FieldTypeRequiredDescription
namestringyes
kindstringyes
idstring (uuid), nullableno
protectedbooleanyes
StatusMeaning
200Tables and views in the namespace
401Not authenticated
403Missing catalog_registry:read permission
500Internal error
502Embedded catalog unreachable

GET /api/control-plane/warehouses/{id}/namespaces/{ns}/tables/{table}​

Operation id: browse_schema. Auth: Session cookie. Forbidden (403): Missing catalog_registry:read permission.

ParameterInTypeRequiredDescription
idpathstring (uuid)yesWarehouse id
nspathstringyesDot-delimited namespace
tablepathstringyesTable name

Response 200 (application/json): SchemaDto

FieldTypeRequiredDescription
locationstringyes
formatVersioninteger (int32)yes
lastUpdatedMsinteger (int64)yes
currentSnapshotIdinteger (int64), nullableno
snapshotCountintegeryes
columnsColumnDto[]yes
partitionFieldsPartitionDto[]yes
sortFieldsSortDto[]yes
propertiesobjectyes
snapshotsSnapshotDto[]yes
StatusMeaning
200Table detail (schema, partitioning, snapshots)
401Not authenticated
403Missing catalog_registry:read permission
404No such warehouse/browser or table
500Internal error
502Embedded catalog unreachable

GET /api/control-plane/warehouses/{id}/namespaces/{ns}/views/{view}​

Operation id: browse_view. Auth: Session cookie. Forbidden (403): Missing catalog_registry:read permission.

ParameterInTypeRequiredDescription
idpathstring (uuid)yesWarehouse id
nspathstringyesDot-delimited namespace
viewpathstringyesView name

Response 200 (application/json): array of ColumnDto

FieldTypeRequiredDescription
namestringyes
typestringyes
requiredbooleanyes
StatusMeaning
200The view's current-schema columns
401Not authenticated
403Missing catalog_registry:read permission
404No such warehouse/browser or view
500Internal error
502Embedded catalog unreachable

PUT /api/control-plane/warehouses/{id}/protection​

Operation id: set_protection. Auth: Session cookie and X-Egret-CSRF header. Forbidden (403): Missing catalog_registry:update permission.

ParameterInTypeRequiredDescription
idpathstring (uuid)yesWarehouse id

Request body (application/json): ProtectionBody

FieldTypeRequiredDescription
targetstringyes
idstring (uuid)yes
protectedbooleanyes

Response 200 (application/json): ProtectionDto

FieldTypeRequiredDescription
protectedbooleanyes
StatusMeaning
200New protected flag for the target
401Not authenticated
403Missing catalog_registry:update permission
404No such warehouse/browser or target
500Internal error
502Embedded catalog unreachable

GET /api/control-plane/warehouses/{id}/roles​

Operation id: list_roles. Auth: Session cookie. Forbidden (403): Missing catalog_registry:read permission.

ParameterInTypeRequiredDescription
idpathstring (uuid)yesWarehouse id

Response 200 (application/json): array of CatalogRoleDto

FieldTypeRequiredDescription
idstring (uuid)yes
namestringyes
consumerTypestringyes
descriptionstring, nullableno
StatusMeaning
200Catalog roles defined on the warehouse
401Not authenticated
403Missing catalog_registry:read permission
500Internal error

POST /api/control-plane/warehouses/{id}/roles​

Operation id: create_role. Auth: Session cookie and X-Egret-CSRF header. Forbidden (403): Missing catalog_registry:create permission.

ParameterInTypeRequiredDescription
idpathstring (uuid)yesWarehouse id

Request body (application/json): CreateRoleBody

FieldTypeRequiredDescription
namestringyes
consumerTypestringyes
descriptionstring, nullableno

Response 201 (application/json): CatalogRoleDto

FieldTypeRequiredDescription
idstring (uuid)yes
namestringyes
consumerTypestringyes
descriptionstring, nullableno
StatusMeaning
201Catalog role created
400Unknown consumerType (engine or external)
401Not authenticated
403Missing catalog_registry:create permission
409A role with this name already exists
500Internal error

GET /api/control-plane/warehouses/{id}/search​

Operation id: search_tabulars. Auth: Session cookie. Forbidden (403): Missing catalog_registry:read permission.

ParameterInTypeRequiredDescription
idpathstring (uuid)yesWarehouse id
qquerystringnoTable/view name search term (empty ⇒ empty result)

Response 200 (application/json): array of SearchResultDto

FieldTypeRequiredDescription
namespacestring[]yes
namestringyes
kindstringyes
StatusMeaning
200Table/view name-search matches
401Not authenticated
403Missing catalog_registry:read permission
500Internal error
502Embedded catalog unreachable

PUT /api/control-plane/warehouses/{id}/status​

Operation id: set_warehouse_status. Auth: Session cookie and X-Egret-CSRF header. Forbidden (403): Missing catalog_registry:update permission.

ParameterInTypeRequiredDescription
idpathstring (uuid)yesWarehouse id

Request body (application/json): StatusBody

FieldTypeRequiredDescription
activebooleanyes
StatusMeaning
204Warehouse activated/deactivated
401Not authenticated
403Missing catalog_registry:update permission
404No such warehouse/browser
500Internal error
502Embedded catalog unreachable

PUT /api/control-plane/warehouses/{id}/storage-credential​

Operation id: rotate_credential. Auth: Session cookie and X-Egret-CSRF header. Forbidden (403): Missing catalog_registry:update permission.

ParameterInTypeRequiredDescription
idpathstring (uuid)yesWarehouse id

Request body (application/json): RotateCredBody

FieldTypeRequiredDescription
accessKeystringyes
secretKeystringyes
StatusMeaning
204S3 storage credential rotated
401Not authenticated
403Missing catalog_registry:update permission
404No such warehouse/browser
500Internal error
502Embedded catalog unreachable

GET /api/control-plane/warehouses/{id}/tasks​

Operation id: list_tasks. Auth: Session cookie. Forbidden (403): Missing catalog_registry:read permission.

ParameterInTypeRequiredDescription
idpathstring (uuid)yesWarehouse id

Response 200 (application/json): array of TaskDto

FieldTypeRequiredDescription
queuestringyes
entitystring, nullableno
statusstringyes
StatusMeaning
200Recent background (GC) tasks on the warehouse
401Not authenticated
403Missing catalog_registry:read permission
500Internal error
502Embedded catalog unreachable

POST /api/control-plane/warehouses/{id}/undrop​

Operation id: undrop_tabular. Auth: Session cookie and X-Egret-CSRF header. Forbidden (403): Missing catalog_registry:update permission.

ParameterInTypeRequiredDescription
idpathstring (uuid)yesWarehouse id

Request body (application/json): UndropBody

FieldTypeRequiredDescription
kindstringyes
idstring (uuid)yes
StatusMeaning
204Table/view recovered
401Not authenticated
403Missing catalog_registry:update permission
404No such warehouse/browser or tabular
409A view on a catalog whose profile has classified columns: a restored view would bypass the classification hold, so it is refused; re-create it with CREATE VIEW
500Internal error
502Embedded catalog unreachable

GET /api/control-plane/warehouses/{warehouse_id}/resource-tags​

Operation id: list_resource_tags. Auth: Session cookie. Forbidden (403): Missing catalog_registry:read permission.

ParameterInTypeRequiredDescription
warehouse_idpathstring (uuid)yesWarehouse id
schemaquerystringyesSchema name
tablequerystringyesTable name

Response 200 (application/json): array of ResourceTagDto

FieldTypeRequiredDescription
schemastringyes
tablestringyes
columnstringyes
tagTagDtoyesA classification tag carried by an object (Access P3.1). Local snake_case DTO so egret-bi does not depend on egret-controlplane. assignment_count is the tag's global assignment count (as computed by TagRepo).
StatusMeaning
200The table's tags plus its columns' tags
401Not authenticated
403Missing catalog_registry:read permission
500Internal error

PUT /api/control-plane/warehouses/{warehouse_id}/resource-tags​

Operation id: assign_resource_tag. Auth: Session cookie and X-Egret-CSRF header. Forbidden (403): Missing catalog_registry:update permission.

ParameterInTypeRequiredDescription
warehouse_idpathstring (uuid)yesWarehouse id

Request body (application/json): ResourceTagBody

FieldTypeRequiredDescription
schemastringyes
tablestringyes
columnstring, nullablenoEmpty / omitted ⇒ a table-level tag.
tag_idstring (uuid)yes

Response 200 (application/json): Ack

FieldTypeRequiredDescription
okbooleanyes
StatusMeaning
200Tag assigned to the catalog resource (idempotent)
400The coordinate cannot be stored (an empty schema or table, or */? in any level — see migration 0177), or the tag is being attached to a whole TABLE while a tag-addressed mask names it, which would make that table unreadable rather than...
401Not authenticated
403Missing catalog_registry:update permission
409A rule overlap: the assignment would make two mask (or two row-filter) policies decide one column differently (compiled rules, hand-written tag policies, or one of each), or a profile it recompiles already holds such a pair. The body adds...
500Internal error

DELETE /api/control-plane/warehouses/{warehouse_id}/resource-tags​

Operation id: unassign_resource_tag. Auth: Session cookie and X-Egret-CSRF header. Forbidden (403): Missing catalog_registry:update permission.

ParameterInTypeRequiredDescription
warehouse_idpathstring (uuid)yesWarehouse id

Request body (application/json): ResourceTagBody

FieldTypeRequiredDescription
schemastringyes
tablestringyes
columnstring, nullablenoEmpty / omitted ⇒ a table-level tag.
tag_idstring (uuid)yes

Response 200 (application/json): Ack

FieldTypeRequiredDescription
okbooleanyes
StatusMeaning
200Tag removed from the catalog resource (idempotent)
401Not authenticated
403Missing catalog_registry:update permission
409A rule overlap that the unassignment does not remove: a profile it recompiles already holds two mask (or two row-filter) rules that decide one request differently. Same body as the assignment's 409
500Internal error